核心型号 / 组件
注册客户端
一个RegisteredClient
是向授权服务器注册的客户端的表示形式。
客户端必须先向授权服务器注册,然后才能启动授权授予流,例如authorization_code
或client_credentials
.
在客户端注册期间,将为客户端分配一个唯一的客户端标识符、(可选)客户端密钥(取决于客户端类型)以及与客户端唯一标识符关联的元数据。 客户端的元数据范围可以从面向人的显示字符串(例如客户端名称)到特定于协议流的项目(例如有效重定向 URI 列表)。
Spring Security 的 OAuth2 客户端支持中相应的客户端注册模型是ClientRegistration。 |
客户端的主要用途是请求访问受保护的资源。 客户端首先通过向授权服务器进行身份验证并提供授权来请求访问令牌。 授权服务器对客户端和授权授权进行身份验证,如果它们有效,则颁发访问令牌。 客户端现在可以通过提供访问令牌从资源服务器请求受保护的资源。
以下示例显示如何配置RegisteredClient
允许执行 authorization_code Grant 流来请求访问令牌:
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} 表示PasswordEncoder id 的 Spring Security 的 NoOpPasswordEncoder。 |
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: http://localhost: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 . |
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 令牌的自定义设置 – 例如,访问/刷新令牌生存时间、重用刷新令牌等。 |
RegisteredClient存储库
这RegisteredClientRepository
是可以注册新客户端和查询现有客户端的中心组件。
当遵循特定协议流时,其他组件会使用它,例如客户端身份验证、授权授予处理、令牌自省、动态客户端注册等。
提供的RegisteredClientRepository
是InMemoryRegisteredClientRepository
和JdbcRegisteredClientRepository
.
这InMemoryRegisteredClientRepository
实现存储RegisteredClient
实例,建议仅在开发和测试期间使用。JdbcRegisteredClientRepository
是一个持续存在的 JDBC 实现RegisteredClient
实例JdbcOperations
.
这RegisteredClientRepository 是 REQUIRED 组件。 |
以下示例演示如何注册RegisteredClientRepository
@Bean
:
@Bean
public RegisteredClientRepository registeredClientRepository() {
List<RegisteredClient> registrations = ...
return new InMemoryRegisteredClientRepository(registrations);
}
或者,您也可以配置RegisteredClientRepository
通过OAuth2AuthorizationServerConfigurer
:
@Bean
public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception {
OAuth2AuthorizationServerConfigurer authorizationServerConfigurer =
OAuth2AuthorizationServerConfigurer.authorizationServer();
http
.securityMatcher(authorizationServerConfigurer.getEndpointsMatcher())
.with(authorizationServerConfigurer, (authorizationServer) ->
authorizationServer
.registeredClientRepository(registeredClientRepository)
)
...
return http.build();
}
这OAuth2AuthorizationServerConfigurer 在同时应用多个配置选项时非常有用。 |
OAuth2授权
一OAuth2Authorization
是 OAuth2 授权的表示形式,它包含与授予客户端的授权相关的状态,由资源所有者或自身(如果是client_credentials
授权授权类型。
Spring Security 的 OAuth2 客户端支持中相应的授权模型是 OAuth2AuthorizedClient。 |
成功完成授权授予流程后,OAuth2Authorization
创建并关联OAuth2AccessToken
、 (可选)OAuth2RefreshToken
以及特定于已执行授权授权类型的其他状态。
这OAuth2Token
实例与OAuth2Authorization
根据授权授权类型而有所不同。
对于 OAuth2 authorization_code 授权,一个OAuth2AuthorizationCode
一OAuth2AccessToken
和 (可选)OAuth2RefreshToken
关联。
对于 OpenID Connect 1.0 authorization_code授权,需要OAuth2AuthorizationCode
一OidcIdToken
一OAuth2AccessToken
和 (可选)OAuth2RefreshToken
关联。
对于 OAuth2 client_credentials 授权,只有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 . |
2 | registeredClientId :唯一标识 RegisteredClient 的 ID。 |
3 | principalName :资源所有者(或客户端)的主体名称。 |
4 | authorizationGrantType :这AuthorizationGrantType 使用。 |
5 | authorizedScopes :这Set 为客户端授权的范围。 |
6 | tokens :这OAuth2Token 实例(和关联的元数据)特定于已执行的授权授权类型。 |
7 | attributes :特定于已执行授权授权类型的附加属性 – 例如,已验证的Principal ,OAuth2AuthorizationRequest 等。 |
OAuth2Authorization
及其关联的OAuth2Token
实例具有固定的生命周期。
新发行的OAuth2Token
处于活动状态,并在过期或失效(吊销)时变为非活动状态。
这OAuth2Authorization
在全部关联的OAuth2Token
实例处于非活动状态。
每OAuth2Token
保存在OAuth2Authorization.Token
,它为isExpired()
,isInvalidated()
和isActive()
.
OAuth2Authorization.Token
还提供getClaims()
,这将返回与OAuth2Token
.
OAuth2AuthorizationService
这OAuth2AuthorizationService
是存储新授权和查询现有授权的中心组件。
当遵循特定协议流时,其他组件会使用它,例如,客户端身份验证、授权授予处理、令牌自省、令牌吊销、动态客户端注册等。
提供的OAuth2AuthorizationService
是InMemoryOAuth2AuthorizationService
和JdbcOAuth2AuthorizationService
.
这InMemoryOAuth2AuthorizationService
实现存储OAuth2Authorization
实例,建议仅在开发和测试期间使用。JdbcOAuth2AuthorizationService
是一个持续存在的 JDBC 实现OAuth2Authorization
实例JdbcOperations
.
这OAuth2AuthorizationService 是 OPTIONAL 组件,默认为InMemoryOAuth2AuthorizationService . |
以下示例演示如何注册OAuth2AuthorizationService
@Bean
:
@Bean
public OAuth2AuthorizationService authorizationService() {
return new InMemoryOAuth2AuthorizationService();
}
或者,您也可以配置OAuth2AuthorizationService
通过OAuth2AuthorizationServerConfigurer
:
@Bean
public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception {
OAuth2AuthorizationServerConfigurer authorizationServerConfigurer =
OAuth2AuthorizationServerConfigurer.authorizationServer();
http
.securityMatcher(authorizationServerConfigurer.getEndpointsMatcher())
.with(authorizationServerConfigurer, (authorizationServer) ->
authorizationServer
.authorizationService(authorizationService)
)
...
return http.build();
}
这OAuth2AuthorizationServerConfigurer 在同时应用多个配置选项时非常有用。 |
OAuth2授权同意
一OAuth2AuthorizationConsent
是来自 OAuth2 授权请求流的授权 “同意”(决策) 的表示形式,例如,authorization_code
grant,它包含资源所有者授予客户端的权限。
在授权客户端访问时,资源所有者只能授予客户端请求的权限子集。
典型的用例是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 实现OAuth2AuthorizationConsent
实例JdbcOperations
.
这OAuth2AuthorizationConsentService 是 OPTIONAL 组件,默认为InMemoryOAuth2AuthorizationConsentService . |
以下示例演示如何注册OAuth2AuthorizationConsentService
@Bean
:
@Bean
public OAuth2AuthorizationConsentService authorizationConsentService() {
return new InMemoryOAuth2AuthorizationConsentService();
}
或者,您也可以配置OAuth2AuthorizationConsentService
通过OAuth2AuthorizationServerConfigurer
:
@Bean
public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception {
OAuth2AuthorizationServerConfigurer authorizationServerConfigurer =
OAuth2AuthorizationServerConfigurer.authorizationServer();
http
.securityMatcher(authorizationServerConfigurer.getEndpointsMatcher())
.with(authorizationServerConfigurer, (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 保存 Authorization Server 运行时环境信息的对象。 |
4 | getAuthorization() :与授权授权关联的 OAuth2Authorization。 |
5 | getAuthorizedScopes() :为客户端授权的范围。 |
6 | getTokenType() :这OAuth2TokenType 生成。支持的值为code ,access_token ,refresh_token 和id_token . |
7 | getAuthorizationGrantType() :这AuthorizationGrantType 与授权授权相关联。 |
8 | getAuthorizationGrant() :这Authentication 实例AuthenticationProvider 处理授权。 |
OAuth2令牌生成器
一OAuth2TokenGenerator
负责生成OAuth2Token
从提供的 OAuth2TokenContext 中包含的信息中。
这OAuth2Token
生成主要取决于OAuth2TokenType
在OAuth2TokenContext
.
例如,当value
为OAuth2TokenType
是:
-
code
然后OAuth2AuthorizationCode
生成。 -
access_token
然后OAuth2AccessToken
生成。 -
refresh_token
然后OAuth2RefreshToken
生成。 -
id_token
然后OidcIdToken
生成。
此外,生成的OAuth2AccessToken
会有所不同,具体取决于TokenSettings.getAccessTokenFormat()
为 RegisteredClient 配置。
如果格式为OAuth2TokenFormat.SELF_CONTAINED
(默认值),则Jwt
生成。
如果格式为OAuth2TokenFormat.REFERENCE
,则会生成一个 “opaque” 令牌。
最后,如果生成的OAuth2Token
具有一组声明和实现ClaimAccessor
,则可以从 OAuth2Authorization.Token.getClaims() 访问声明。
这OAuth2TokenGenerator
主要由实现授权授权处理的组件使用,例如authorization_code
,client_credentials
和refresh_token
.
提供的实现包括OAuth2AccessTokenGenerator
,OAuth2RefreshTokenGenerator
和JwtGenerator
.
这OAuth2AccessTokenGenerator
生成一个 “opaque” (OAuth2TokenFormat.REFERENCE
) 访问令牌,而JwtGenerator
生成一个Jwt
(OAuth2TokenFormat.SELF_CONTAINED
).
这OAuth2TokenGenerator 是 OPTIONAL 组件,默认为DelegatingOAuth2TokenGenerator 由OAuth2AccessTokenGenerator 和OAuth2RefreshTokenGenerator . |
如果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);
}
或者,您也可以配置OAuth2TokenGenerator
通过OAuth2AuthorizationServerConfigurer
:
@Bean
public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception {
OAuth2AuthorizationServerConfigurer authorizationServerConfigurer =
OAuth2AuthorizationServerConfigurer.authorizationServer();
http
.securityMatcher(authorizationServerConfigurer.getEndpointsMatcher())
.with(authorizationServerConfigurer, (authorizationServer) ->
authorizationServer
.tokenGenerator(tokenGenerator)
)
...
return http.build();
}
这OAuth2AuthorizationServerConfigurer 在同时应用多个配置选项时非常有用。 |
OAuth2TokenCustomizer (OAuth2令牌自定义器)
一OAuth2TokenCustomizer
提供自定义OAuth2Token
,这些函数可以在提供的 OAuth2TokenContext 中访问。
OAuth2TokenGenerator 使用它来自定义OAuth2Token
在生成之前。
一OAuth2TokenCustomizer<OAuth2TokenClaimsContext>
使用泛型类型OAuth2TokenClaimsContext
(implements OAuth2TokenContext
) 提供了自定义 “opaque” 声明的功能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 . |
一OAuth2TokenCustomizer<JwtEncodingContext>
使用泛型类型JwtEncodingContext
(implements OAuth2TokenContext
) 提供了自定义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 . |
有关演示如何自定义 ID 令牌的示例,请参阅指南作方法:自定义 OpenID Connect 1.0 UserInfo 响应。 |
SessionRegistry (会话注册表)
如果启用了 OpenID Connect 1.0,则SessionRegistry
实例用于跟踪已验证的会话。
这SessionRegistry
由SessionAuthenticationStrategy
与 OAuth2 授权端点相关联,用于注册新的经过身份验证的会话。
如果SessionRegistry @Bean 未注册,则默认实现SessionRegistryImpl 将被使用。 |
如果SessionRegistry @Bean 已注册,并且是SessionRegistryImpl 一个HttpSessionEventPublisher @Bean 还应进行注册,因为它负责通知SessionRegistryImpl 会话生命周期事件,例如SessionDestroyedEvent ,以提供删除SessionInformation 实例。 |
当最终用户请求注销时,OpenID Connect 1.0 注销终端节点使用SessionRegistry
要查找SessionInformation
与经过身份验证的最终用户关联以执行注销。
如果正在使用 Spring Security 的并发会话控制功能,建议注册一个SessionRegistry
@Bean
以确保它在 Spring Security 的并发会话控制和 Spring 授权服务器的注销功能之间共享。
以下示例演示如何注册SessionRegistry
@Bean
和HttpSessionEventPublisher
@Bean
(需要SessionRegistryImpl
):
@Bean
public SessionRegistry sessionRegistry() {
return new SessionRegistryImpl();
}
@Bean
public HttpSessionEventPublisher httpSessionEventPublisher() {
return new HttpSessionEventPublisher();
}