核心模型/组件
RegisteredClient
RegisteredClient 是一个客户端的表示,该客户端已在授权服务器上注册。客户端在启动授权授予流程(例如 authorization_code 或 client_credentials)之前,必须在授权服务器上注册。
在客户端注册期间,客户端会被分配一个唯一的客户端标识符,(可选地)一个客户端密钥(取决于客户端类型),以及与其唯一客户端标识符关联的元数据。客户端的元数据可以从面向人类的显示字符串(如客户端名称)到特定于协议流的项(如有效重定向URI列表)不等。
| Spring Security OAuth2 客户端支持中相应的客户端注册模型是 ClientRegistration。 |
客户端的主要目的是请求访问受保护的资源。客户端首先通过向授权服务器进行身份验证并提交授权授予来请求访问令牌。授权服务器对客户端和授权授予进行身份验证,如果它们有效,则颁发访问令牌。客户端现在可以通过提交访问令牌从资源服务器请求受保护的资源。
以下示例展示了如何配置一个允许执行 authorization_code 授权 流程以请求访问令牌的 RegisteredClient
RegisteredClient registeredClient = RegisteredClient.withId(UUID.randomUUID().toString())
.clientId("client-a")
.clientSecret("{noop}secret") (1)
.clientAuthenticationMethod(ClientAuthenticationMethod.CLIENT_SECRET_BASIC)
.authorizationGrantType(AuthorizationGrantType.AUTHORIZATION_CODE)
.redirectUri("http://127.0.0.1:8080/authorized")
.scope("scope-a")
.clientSettings(ClientSettings.builder().requireAuthorizationConsent(true).build())
.build();
| 1 | {noop} 代表 Spring Security 的 NoOpPasswordEncoder 的 PasswordEncoder ID。 |
Spring Security OAuth2 客户端支持 中的相应配置是
spring:
security:
oauth2:
client:
registration:
client-a:
provider: spring
client-id: client-a
client-secret: secret
authorization-grant-type: authorization_code
redirect-uri: "http://127.0.0.1:8080/authorized"
scope: scope-a
provider:
spring:
issuer-uri: https://:9000
RegisteredClient 具有与其唯一客户端标识符关联的元数据(属性),定义如下
public class RegisteredClient implements Serializable {
private String id; (1)
private String clientId; (2)
private Instant clientIdIssuedAt; (3)
private String clientSecret; (4)
private Instant clientSecretExpiresAt; (5)
private String clientName; (6)
private Set<ClientAuthenticationMethod> clientAuthenticationMethods; (7)
private Set<AuthorizationGrantType> authorizationGrantTypes; (8)
private Set<String> redirectUris; (9)
private Set<String> postLogoutRedirectUris; (10)
private Set<String> scopes; (11)
private ClientSettings clientSettings; (12)
private TokenSettings tokenSettings; (13)
...
}
| 1 | id: 唯一标识 RegisteredClient 的 ID。 |
| 2 | clientId:客户端标识符。 |
| 3 | clientIdIssuedAt: 客户端标识符的颁发时间。 |
| 4 | clientSecret: 客户端的密钥。该值应使用 Spring Security 的 PasswordEncoder 进行编码。 |
| 5 | clientSecretExpiresAt: 客户端密钥的到期时间。 |
| 6 | clientName: 用于客户端的描述性名称。该名称可在某些场景中使用,例如在同意页面显示客户端名称时。 |
| 7 | clientAuthenticationMethods: 客户端可用的身份验证方法。支持的值有 client_secret_basic、client_secret_post、private_key_jwt、client_secret_jwt 和 none (公共客户端)。 |
| 8 | authorizationGrantTypes: 客户端可使用的授权授予类型。支持的值有 authorization_code、client_credentials、refresh_token、urn:ietf:params:oauth:grant-type:device_code 和 urn:ietf:params:oauth:grant-type:token-exchange。 |
| 9 | redirectUris: 客户端可在基于重定向的流程中使用的注册重定向URI——例如,authorization_code 授权。 |
| 10 | postLogoutRedirectUris: 客户端可用于注销的注销后重定向URI。 |
| 11 | scopes: 客户端允许请求的范围。 |
| 12 | clientSettings: 客户端的自定义设置——例如,需要 PKCE、需要授权同意等。 |
| 13 | tokenSettings: 颁发给客户端的 OAuth2 令牌的自定义设置——例如,访问/刷新令牌的存活时间、刷新令牌的复用等。 |
RegisteredClientRepository
RegisteredClientRepository 是核心组件,用于注册新客户端和查询现有客户端。其他组件在遵循特定协议流程(如客户端身份验证、授权授予处理、令牌自省、动态客户端注册等)时会使用它。
RegisteredClientRepository 的提供实现包括 InMemoryRegisteredClientRepository 和 JdbcRegisteredClientRepository。InMemoryRegisteredClientRepository 实现将 RegisteredClient 实例存储在内存中,仅建议在开发和测试期间使用。JdbcRegisteredClientRepository 是一个 JDBC 实现,通过使用 JdbcOperations 持久化 RegisteredClient 实例。
RegisteredClientRepository 是一个必需组件。 |
以下示例展示了如何注册一个 RegisteredClientRepository @Bean
@Bean
public RegisteredClientRepository registeredClientRepository() {
List<RegisteredClient> registrations = ...
return new InMemoryRegisteredClientRepository(registrations);
}
或者,您可以通过 OAuth2AuthorizationServerConfigurer 配置 RegisteredClientRepository
@Bean
public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception {
http
.oauth2AuthorizationServer((authorizationServer) ->
authorizationServer
.registeredClientRepository(registeredClientRepository)
)
...
return http.build();
}
当同时应用多个配置选项时,OAuth2AuthorizationServerConfigurer 会很有用。 |
OAuth2Authorization
OAuth2Authorization 是 OAuth2 授权的表示,它保存了授予客户端的授权相关状态,由资源所有者或在 client_credentials 授权授予类型的情况下由其自身授予。
| Spring Security OAuth2 客户端支持中相应的授权模型是 OAuth2AuthorizedClient。 |
成功完成授权授予流程后,会创建一个 OAuth2Authorization,并关联一个 OAuth2AccessToken、一个(可选的)OAuth2RefreshToken 以及特定于已执行授权授予类型的附加状态。
与 OAuth2Authorization 关联的 OAuth2Token 实例因授权授予类型而异。
对于 OAuth2 授权码授权,关联了 OAuth2AuthorizationCode、OAuth2AccessToken 和(可选)OAuth2RefreshToken。
对于 OpenID Connect 1.0 授权码授权,关联了 OAuth2AuthorizationCode、OidcIdToken、OAuth2AccessToken 和(可选)OAuth2RefreshToken。
对于 OAuth2 客户端凭据授权,仅关联 OAuth2AccessToken。
OAuth2Authorization 及其属性定义如下
public class OAuth2Authorization implements Serializable {
private String id; (1)
private String registeredClientId; (2)
private String principalName; (3)
private AuthorizationGrantType authorizationGrantType; (4)
private Set<String> authorizedScopes; (5)
private Map<Class<? extends OAuth2Token>, Token<?>> tokens; (6)
private Map<String, Object> attributes; (7)
...
}
| 1 | id: 唯一标识 OAuth2Authorization 的 ID。 |
| 2 | registeredClientId: 唯一标识 RegisteredClient 的 ID。 |
| 3 | principalName: 资源所有者(或客户端)的主体名称。 |
| 4 | authorizationGrantType: 使用的 AuthorizationGrantType。 |
| 5 | authorizedScopes: 为客户端授权的范围 Set。 |
| 6 | tokens: 特定于已执行授权授予类型的 OAuth2Token 实例(及相关元数据)。 |
| 7 | attributes: 特定于已执行授权授予类型的附加属性——例如,已认证的 Principal、OAuth2AuthorizationRequest 等。 |
OAuth2Authorization 及其关联的 OAuth2Token 实例具有设定的生命周期。新颁发的 OAuth2Token 是活动的,当它过期或失效(撤销)时变为非活动状态。当所有关联的 OAuth2Token 实例均处于非活动状态时,OAuth2Authorization(隐式)处于非活动状态。每个 OAuth2Token 都保存在 OAuth2Authorization.Token 中,该对象提供 isExpired()、isInvalidated() 和 isActive() 访问器。
OAuth2Authorization.Token 还提供 getClaims(),返回与 OAuth2Token 关联的声明(如果有)。
OAuth2AuthorizationService
OAuth2AuthorizationService 是核心组件,用于存储新授权和查询现有授权。其他组件在遵循特定协议流程(例如客户端身份验证、授权授予处理、令牌自省、令牌撤销、动态客户端注册等)时会使用它。
OAuth2AuthorizationService 的提供实现包括 InMemoryOAuth2AuthorizationService 和 JdbcOAuth2AuthorizationService。InMemoryOAuth2AuthorizationService 实现将 OAuth2Authorization 实例存储在内存中,仅建议在开发和测试期间使用。JdbcOAuth2AuthorizationService 是一个 JDBC 实现,通过使用 JdbcOperations 持久化 OAuth2Authorization 实例。
OAuth2AuthorizationService 是一个可选组件,默认为 InMemoryOAuth2AuthorizationService。 |
以下示例展示了如何注册一个 OAuth2AuthorizationService @Bean
@Bean
public OAuth2AuthorizationService authorizationService() {
return new InMemoryOAuth2AuthorizationService();
}
或者,您可以通过 OAuth2AuthorizationServerConfigurer 配置 OAuth2AuthorizationService
@Bean
public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception {
http
.oauth2AuthorizationServer((authorizationServer) ->
authorizationServer
.authorizationService(authorizationService)
)
...
return http.build();
}
当同时应用多个配置选项时,OAuth2AuthorizationServerConfigurer 会很有用。 |
OAuth2AuthorizationConsent
OAuth2AuthorizationConsent 是 OAuth2 授权请求流 中的授权“同意”(决定)的表示形式——例如 authorization_code 授权,它包含资源所有者授予客户端的权限。
在授权客户端访问时,资源所有者可能只授予客户端请求权限的一个子集。典型的用例是 authorization_code 授权流程,其中客户端请求范围,资源所有者授予(或拒绝)对所请求范围的访问。
完成 OAuth2 授权请求流程后,会创建一个(或更新)OAuth2AuthorizationConsent,并将授予的权限与客户端和资源所有者关联起来。
OAuth2AuthorizationConsent 及其属性定义如下
public final class OAuth2AuthorizationConsent implements Serializable {
private final String registeredClientId; (1)
private final String principalName; (2)
private final Set<GrantedAuthority> authorities; (3)
...
}
| 1 | registeredClientId: 唯一标识 RegisteredClient 的 ID。 |
| 2 | principalName: 资源所有者的主体名称。 |
| 3 | authorities: 资源所有者授予客户端的权限。权限可以表示范围、声明、许可、角色等。 |
OAuth2AuthorizationConsentService
OAuth2AuthorizationConsentService 是核心组件,用于存储新的授权同意和查询现有授权同意。它主要由实现 OAuth2 授权请求流程(例如 authorization_code 授权)的组件使用。
OAuth2AuthorizationConsentService 的提供实现包括 InMemoryOAuth2AuthorizationConsentService 和 JdbcOAuth2AuthorizationConsentService。InMemoryOAuth2AuthorizationConsentService 实现将 OAuth2AuthorizationConsent 实例存储在内存中,仅建议用于开发和测试。JdbcOAuth2AuthorizationConsentService 是一个 JDBC 实现,通过使用 JdbcOperations 持久化 OAuth2AuthorizationConsent 实例。
OAuth2AuthorizationConsentService 是一个可选组件,默认为 InMemoryOAuth2AuthorizationConsentService。 |
以下示例展示了如何注册一个 OAuth2AuthorizationConsentService @Bean
@Bean
public OAuth2AuthorizationConsentService authorizationConsentService() {
return new InMemoryOAuth2AuthorizationConsentService();
}
或者,您可以通过 OAuth2AuthorizationServerConfigurer 配置 OAuth2AuthorizationConsentService
@Bean
public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception {
http
.oauth2AuthorizationServer((authorizationServer) ->
authorizationServer
.authorizationConsentService(authorizationConsentService)
)
...
return http.build();
}
当同时应用多个配置选项时,OAuth2AuthorizationServerConfigurer 会很有用。 |
OAuth2TokenContext
OAuth2TokenContext 是一个上下文对象,它保存与 OAuth2Token 相关的信息,并由 OAuth2TokenGenerator 和 OAuth2TokenCustomizer 使用。
OAuth2TokenContext 提供以下访问器
public interface OAuth2TokenContext extends Context {
default RegisteredClient getRegisteredClient() ... (1)
default <T extends Authentication> T getPrincipal() ... (2)
default AuthorizationServerContext getAuthorizationServerContext() ... (3)
@Nullable
default OAuth2Authorization getAuthorization() ... (4)
default Set<String> getAuthorizedScopes() ... (5)
default OAuth2TokenType getTokenType() ... (6)
default AuthorizationGrantType getAuthorizationGrantType() ... (7)
default <T extends Authentication> T getAuthorizationGrant() ... (8)
...
}
| 1 | getRegisteredClient(): 与授权授予关联的 RegisteredClient。 |
| 2 | getPrincipal(): 资源所有者(或客户端)的 Authentication 实例。 |
| 3 | getAuthorizationServerContext(): 包含授权服务器运行时环境信息的 AuthorizationServerContext 对象。 |
| 4 | getAuthorization(): 与授权授予关联的 OAuth2Authorization。 |
| 5 | getAuthorizedScopes(): 为客户端授权的范围。 |
| 6 | getTokenType(): 要生成的 OAuth2TokenType。支持的值是 code、access_token、refresh_token 和 id_token。 |
| 7 | getAuthorizationGrantType(): 与授权授予关联的 AuthorizationGrantType。 |
| 8 | getAuthorizationGrant(): 由处理授权授予的 AuthenticationProvider 使用的 Authentication 实例。 |
OAuth2TokenGenerator
OAuth2TokenGenerator 负责从提供的 OAuth2TokenContext 中包含的信息生成 OAuth2Token。
生成的 OAuth2Token 主要取决于 OAuth2TokenContext 中指定的 OAuth2TokenType 类型。
例如,当 OAuth2TokenType 的 value 是
-
code,则生成OAuth2AuthorizationCode。 -
access_token,则生成OAuth2AccessToken。 -
refresh_token,则生成OAuth2RefreshToken。 -
id_token,则生成OidcIdToken。
此外,生成的 OAuth2AccessToken 的格式取决于为 RegisteredClient 配置的 TokenSettings.getAccessTokenFormat()。如果格式为 OAuth2TokenFormat.SELF_CONTAINED(默认),则生成 Jwt。如果格式为 OAuth2TokenFormat.REFERENCE,则生成“不透明”令牌。
最后,如果生成的 OAuth2Token 包含一组声明并实现了 ClaimAccessor,则这些声明可以通过 OAuth2Authorization.Token.getClaims() 进行访问。
OAuth2TokenGenerator 主要由实现授权授予处理的组件使用——例如 authorization_code、client_credentials 和 refresh_token。
提供的实现是 OAuth2AccessTokenGenerator、OAuth2RefreshTokenGenerator 和 JwtGenerator。OAuth2AccessTokenGenerator 生成“不透明” (OAuth2TokenFormat.REFERENCE) 访问令牌,而 JwtGenerator 生成 Jwt (OAuth2TokenFormat.SELF_CONTAINED)。
OAuth2TokenGenerator 是一个可选组件,默认为由 OAuth2AccessTokenGenerator 和 OAuth2RefreshTokenGenerator 组成的 DelegatingOAuth2TokenGenerator。 |
如果注册了 JwtEncoder @Bean 或 JWKSource<SecurityContext> @Bean,则 JwtGenerator 将额外添加到 DelegatingOAuth2TokenGenerator 中。 |
OAuth2TokenGenerator 提供了极大的灵活性,因为它支持任何自定义的 access_token 和 refresh_token 令牌格式。
以下示例展示了如何注册一个 OAuth2TokenGenerator @Bean
@Bean
public OAuth2TokenGenerator<?> tokenGenerator() {
JwtEncoder jwtEncoder = ...
JwtGenerator jwtGenerator = new JwtGenerator(jwtEncoder);
OAuth2AccessTokenGenerator accessTokenGenerator = new OAuth2AccessTokenGenerator();
OAuth2RefreshTokenGenerator refreshTokenGenerator = new OAuth2RefreshTokenGenerator();
return new DelegatingOAuth2TokenGenerator(
jwtGenerator, accessTokenGenerator, refreshTokenGenerator);
}
或者,您可以通过 OAuth2AuthorizationServerConfigurer 配置 OAuth2TokenGenerator
@Bean
public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception {
http
.oauth2AuthorizationServer((authorizationServer) ->
authorizationServer
.tokenGenerator(tokenGenerator)
)
...
return http.build();
}
当同时应用多个配置选项时,OAuth2AuthorizationServerConfigurer 会很有用。 |
OAuth2TokenCustomizer
OAuth2TokenCustomizer 提供定制 OAuth2Token 属性的能力,这些属性可在提供的 OAuth2TokenContext 中访问。它由 OAuth2TokenGenerator 使用,以允许在生成 OAuth2Token 之前定制其属性。
声明为泛型类型 OAuth2TokenClaimsContext(implements OAuth2TokenContext)的 OAuth2TokenCustomizer<OAuth2TokenClaimsContext> 提供了定制“不透明” OAuth2AccessToken 声明的能力。OAuth2TokenClaimsContext.getClaims() 提供对 OAuth2TokenClaimsSet.Builder 的访问,允许添加、替换和删除声明。
以下示例展示了如何实现 OAuth2TokenCustomizer<OAuth2TokenClaimsContext> 并将其与 OAuth2AccessTokenGenerator 配置
@Bean
public OAuth2TokenGenerator<?> tokenGenerator() {
JwtEncoder jwtEncoder = ...
JwtGenerator jwtGenerator = new JwtGenerator(jwtEncoder);
OAuth2AccessTokenGenerator accessTokenGenerator = new OAuth2AccessTokenGenerator();
accessTokenGenerator.setAccessTokenCustomizer(accessTokenCustomizer());
OAuth2RefreshTokenGenerator refreshTokenGenerator = new OAuth2RefreshTokenGenerator();
return new DelegatingOAuth2TokenGenerator(
jwtGenerator, accessTokenGenerator, refreshTokenGenerator);
}
@Bean
public OAuth2TokenCustomizer<OAuth2TokenClaimsContext> accessTokenCustomizer() {
return context -> {
OAuth2TokenClaimsSet.Builder claims = context.getClaims();
// Customize claims
};
}
如果 OAuth2TokenGenerator 未作为 @Bean 提供或未通过 OAuth2AuthorizationServerConfigurer 配置,则 OAuth2TokenCustomizer<OAuth2TokenClaimsContext> @Bean 将自动与 OAuth2AccessTokenGenerator 配置。 |
声明为泛型类型 JwtEncodingContext(implements OAuth2TokenContext)的 OAuth2TokenCustomizer<JwtEncodingContext> 提供了定制 Jwt 头部和声明的能力。JwtEncodingContext.getJwsHeader() 提供对 JwsHeader.Builder 的访问,允许添加、替换和删除头部。JwtEncodingContext.getClaims() 提供对 JwtClaimsSet.Builder 的访问,允许添加、替换和删除声明。
以下示例展示了如何实现 OAuth2TokenCustomizer<JwtEncodingContext> 并将其与 JwtGenerator 配置
@Bean
public OAuth2TokenGenerator<?> tokenGenerator() {
JwtEncoder jwtEncoder = ...
JwtGenerator jwtGenerator = new JwtGenerator(jwtEncoder);
jwtGenerator.setJwtCustomizer(jwtCustomizer());
OAuth2AccessTokenGenerator accessTokenGenerator = new OAuth2AccessTokenGenerator();
OAuth2RefreshTokenGenerator refreshTokenGenerator = new OAuth2RefreshTokenGenerator();
return new DelegatingOAuth2TokenGenerator(
jwtGenerator, accessTokenGenerator, refreshTokenGenerator);
}
@Bean
public OAuth2TokenCustomizer<JwtEncodingContext> jwtCustomizer() {
return context -> {
JwsHeader.Builder headers = context.getJwsHeader();
JwtClaimsSet.Builder claims = context.getClaims();
if (context.getTokenType().equals(OAuth2TokenType.ACCESS_TOKEN)) {
// Customize headers/claims for access_token
} else if (context.getTokenType().getValue().equals(OidcParameterNames.ID_TOKEN)) {
// Customize headers/claims for id_token
}
};
}
如果 OAuth2TokenGenerator 未作为 @Bean 提供或未通过 OAuth2AuthorizationServerConfigurer 配置,则 OAuth2TokenCustomizer<JwtEncodingContext> @Bean 将自动与 JwtGenerator 配置。 |
SessionRegistry
如果启用了 OpenID Connect 1.0,则使用 SessionRegistry 实例来跟踪已认证的会话。SessionRegistry 由与 OAuth2 授权端点 关联的 SessionAuthenticationStrategy 的默认实现使用,用于注册新的已认证会话。
如果未注册 SessionRegistry @Bean,将使用默认实现 SessionRegistryImpl。 |
如果注册了 SessionRegistry @Bean 并且它是 SessionRegistryImpl 的实例,则应该同时注册 HttpSessionEventPublisher @Bean,因为它负责通知 SessionRegistryImpl 会话生命周期事件(例如 SessionDestroyedEvent),以提供删除 SessionInformation 实例的能力。 |
当最终用户请求注销时,OpenID Connect 1.0 注销端点 使用 SessionRegistry 查找与已认证最终用户关联的 SessionInformation 以执行注销。
如果正在使用 Spring Security 的 并发会话控制 功能,建议注册一个 SessionRegistry @Bean,以确保它在 Spring Security 的并发会话控制和 Spring Security 授权服务器的注销功能之间共享。
以下示例展示了如何注册 SessionRegistry @Bean 和 HttpSessionEventPublisher @Bean(SessionRegistryImpl 所需)
@Bean
public SessionRegistry sessionRegistry() {
return new SessionRegistryImpl();
}
@Bean
public HttpSessionEventPublisher httpSessionEventPublisher() {
return new HttpSessionEventPublisher();
}