对于最新的稳定版本,请使用 Spring Security 6.5.0! |
高级配置
HttpSecurity.oauth2Login()
提供了许多用于自定义 OAuth 2.0 登录的配置选项。
主要配置选项分为其协议端点对应项。
例如oauth2Login().authorizationEndpoint()
允许配置 Authorization Endpoint,而oauth2Login().tokenEndpoint()
允许配置 Token Endpoint。
下面的代码显示了一个示例:
-
Java
-
Kotlin
@Configuration
@EnableWebSecurity
public class OAuth2LoginSecurityConfig {
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http
.oauth2Login(oauth2 -> oauth2
.authorizationEndpoint(authorization -> authorization
...
)
.redirectionEndpoint(redirection -> redirection
...
)
.tokenEndpoint(token -> token
...
)
.userInfoEndpoint(userInfo -> userInfo
...
)
);
return http.build();
}
}
@Configuration
@EnableWebSecurity
class OAuth2LoginSecurityConfig {
@Bean
open fun filterChain(http: HttpSecurity): SecurityFilterChain {
http {
oauth2Login {
authorizationEndpoint {
...
}
redirectionEndpoint {
...
}
tokenEndpoint {
...
}
userInfoEndpoint {
...
}
}
}
return http.build()
}
}
主要目标oauth2Login()
DSL 将与规范中定义的命名紧密一致。
OAuth 2.0 授权框架对协议端点的定义如下:
授权过程使用两个授权服务器终端节点(HTTP 资源):
-
授权端点:由客户端用于通过用户代理重定向从资源所有者处获取授权。
-
Token Endpoint:由客户端用于交换访问Tokens的授权,通常使用客户端身份验证。
授权过程还使用一个客户端终端节点:
-
重定向终端节点:由授权服务器用于通过资源所有者用户代理将包含授权凭证的响应返回给客户端。
OpenID Connect Core 1.0 规范对 UserInfo 端点的定义如下:
UserInfo 端点是一种 OAuth 2.0 受保护的资源,它返回有关经过身份验证的最终用户的声明。 为了获取有关最终用户的请求声明,客户端使用通过 OpenID Connect 身份验证获取的访问Tokens向 UserInfo 终端节点发出请求。 这些声明通常由一个 JSON 对象表示,该对象包含声明的名称/值对集合。
以下代码显示了可用于oauth2Login()
DSL:
-
Java
-
Kotlin
@Configuration
@EnableWebSecurity
public class OAuth2LoginSecurityConfig {
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http
.oauth2Login(oauth2 -> oauth2
.clientRegistrationRepository(this.clientRegistrationRepository())
.authorizedClientRepository(this.authorizedClientRepository())
.authorizedClientService(this.authorizedClientService())
.loginPage("/login")
.authorizationEndpoint(authorization -> authorization
.baseUri(this.authorizationRequestBaseUri())
.authorizationRequestRepository(this.authorizationRequestRepository())
.authorizationRequestResolver(this.authorizationRequestResolver())
)
.redirectionEndpoint(redirection -> redirection
.baseUri(this.authorizationResponseBaseUri())
)
.tokenEndpoint(token -> token
.accessTokenResponseClient(this.accessTokenResponseClient())
)
.userInfoEndpoint(userInfo -> userInfo
.userAuthoritiesMapper(this.userAuthoritiesMapper())
.userService(this.oauth2UserService())
.oidcUserService(this.oidcUserService())
)
);
return http.build();
}
}
@Configuration
@EnableWebSecurity
class OAuth2LoginSecurityConfig {
@Bean
open fun filterChain(http: HttpSecurity): SecurityFilterChain {
http {
oauth2Login {
clientRegistrationRepository = clientRegistrationRepository()
authorizedClientRepository = authorizedClientRepository()
authorizedClientService = authorizedClientService()
loginPage = "/login"
authorizationEndpoint {
baseUri = authorizationRequestBaseUri()
authorizationRequestRepository = authorizationRequestRepository()
authorizationRequestResolver = authorizationRequestResolver()
}
redirectionEndpoint {
baseUri = authorizationResponseBaseUri()
}
tokenEndpoint {
accessTokenResponseClient = accessTokenResponseClient()
}
userInfoEndpoint {
userAuthoritiesMapper = userAuthoritiesMapper()
userService = oauth2UserService()
oidcUserService = oidcUserService()
}
}
}
return http.build()
}
}
除了oauth2Login()
还支持 DSL、XML 配置。
以下代码显示了 security 命名空间中可用的完整配置选项:
<http>
<oauth2-login client-registration-repository-ref="clientRegistrationRepository"
authorized-client-repository-ref="authorizedClientRepository"
authorized-client-service-ref="authorizedClientService"
authorization-request-repository-ref="authorizationRequestRepository"
authorization-request-resolver-ref="authorizationRequestResolver"
access-token-response-client-ref="accessTokenResponseClient"
user-authorities-mapper-ref="userAuthoritiesMapper"
user-service-ref="oauth2UserService"
oidc-user-service-ref="oidcUserService"
login-processing-url="/login/oauth2/code/*"
login-page="/login"
authentication-success-handler-ref="authenticationSuccessHandler"
authentication-failure-handler-ref="authenticationFailureHandler"
jwt-decoder-factory-ref="jwtDecoderFactory"/>
</http>
以下部分将更详细地介绍每个可用的配置选项:
OAuth 2.0 登录页面
默认情况下,OAuth 2.0 登录页面由DefaultLoginPageGeneratingFilter
.
默认登录页面显示每个已配置的 OAuth 客户端及其ClientRegistration.clientName
作为链接,该链接能够启动授权请求(或 OAuth 2.0 登录)。
为 |
每个 OAuth 客户端的链接目标默认为以下内容:
OAuth2AuthorizationRequestRedirectFilter.DEFAULT_AUTHORIZATION_REQUEST_BASE_URI + "/{registrationId}"
以下行显示了一个示例:
<a href="/oauth2/authorization/google">Google</a>
要覆盖默认登录页面,请配置oauth2Login().loginPage()
和(可选)oauth2Login().authorizationEndpoint().baseUri()
.
下面的清单显示了一个示例:
-
Java
-
Kotlin
-
Xml
@Configuration
@EnableWebSecurity
public class OAuth2LoginSecurityConfig {
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http
.oauth2Login(oauth2 -> oauth2
.loginPage("/login/oauth2")
...
.authorizationEndpoint(authorization -> authorization
.baseUri("/login/oauth2/authorization")
...
)
);
return http.build();
}
}
@Configuration
@EnableWebSecurity
class OAuth2LoginSecurityConfig {
@Bean
open fun filterChain(http: HttpSecurity): SecurityFilterChain {
http {
oauth2Login {
loginPage = "/login/oauth2"
authorizationEndpoint {
baseUri = "/login/oauth2/authorization"
}
}
}
return http.build()
}
}
<http>
<oauth2-login login-page="/login/oauth2"
...
/>
</http>
您需要提供 |
如前所述,配置 以下行显示了一个示例:
|
重定向端点
授权服务器使用重定向端点通过资源所有者用户代理将授权响应(包含授权凭证)返回给客户端。
OAuth 2.0 登录利用授权码授予。 因此,授权凭证就是授权码。 |
默认的 Authorization ResponsebaseUri
(重定向端点)为/login/oauth2/code/*
,它在OAuth2LoginAuthenticationFilter.DEFAULT_FILTER_PROCESSES_URI
.
如果要自定义授权响应baseUri
,则按如下方式进行配置:
-
Java
-
Kotlin
-
Xml
@Configuration
@EnableWebSecurity
public class OAuth2LoginSecurityConfig {
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http
.oauth2Login(oauth2 -> oauth2
.redirectionEndpoint(redirection -> redirection
.baseUri("/login/oauth2/callback/*")
...
)
);
return http.build();
}
}
@Configuration
@EnableWebSecurity
class OAuth2LoginSecurityConfig {
@Bean
open fun filterChain(http: HttpSecurity): SecurityFilterChain {
http {
oauth2Login {
redirectionEndpoint {
baseUri = "/login/oauth2/callback/*"
}
}
}
return http.build()
}
}
<http>
<oauth2-login login-processing-url="/login/oauth2/callback/*"
...
/>
</http>
您还需要确保 下面的清单显示了一个示例:
|
UserInfo 端点
UserInfo Endpoint 包括许多配置选项,如以下小节所述:
映射用户权限
在用户成功通过 OAuth 2.0 提供程序进行身份验证后,OAuth2User.getAuthorities()
(或OidcUser.getAuthorities()
) 包含从OAuth2UserRequest.getAccessToken().getScopes()
,前缀为SCOPE_
.
这些授予的权限可以映射到一组新的GrantedAuthority
实例,这些实例被提供给OAuth2AuthenticationToken
完成身份验证时。
OAuth2AuthenticationToken.getAuthorities() 用于授权请求,例如hasRole('USER') 或hasRole('ADMIN') . |
在映射用户权限时,有几个选项可供选择:
使用 GrantedAuthoritiesMapper
这GrantedAuthoritiesMapper
给定一个已授予权限列表,其中包含OAuth2UserAuthority
和权限字符串OAUTH2_USER
(或OidcUserAuthority
和权限字符串OIDC_USER
).
提供GrantedAuthoritiesMapper
并对其进行配置,如下所示:
-
Java
-
Kotlin
-
Xml
@Configuration
@EnableWebSecurity
public class OAuth2LoginSecurityConfig {
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http
.oauth2Login(oauth2 -> oauth2
.userInfoEndpoint(userInfo -> userInfo
.userAuthoritiesMapper(this.userAuthoritiesMapper())
...
)
);
return http.build();
}
private GrantedAuthoritiesMapper userAuthoritiesMapper() {
return (authorities) -> {
Set<GrantedAuthority> mappedAuthorities = new HashSet<>();
authorities.forEach(authority -> {
if (OidcUserAuthority.class.isInstance(authority)) {
OidcUserAuthority oidcUserAuthority = (OidcUserAuthority)authority;
OidcIdToken idToken = oidcUserAuthority.getIdToken();
OidcUserInfo userInfo = oidcUserAuthority.getUserInfo();
// Map the claims found in idToken and/or userInfo
// to one or more GrantedAuthority's and add it to mappedAuthorities
} else if (OAuth2UserAuthority.class.isInstance(authority)) {
OAuth2UserAuthority oauth2UserAuthority = (OAuth2UserAuthority)authority;
Map<String, Object> userAttributes = oauth2UserAuthority.getAttributes();
// Map the attributes found in userAttributes
// to one or more GrantedAuthority's and add it to mappedAuthorities
}
});
return mappedAuthorities;
};
}
}
@Configuration
@EnableWebSecurity
class OAuth2LoginSecurityConfig {
@Bean
open fun filterChain(http: HttpSecurity): SecurityFilterChain {
http {
oauth2Login {
userInfoEndpoint {
userAuthoritiesMapper = userAuthoritiesMapper()
}
}
}
return http.build()
}
private fun userAuthoritiesMapper(): GrantedAuthoritiesMapper = GrantedAuthoritiesMapper { authorities: Collection<GrantedAuthority> ->
val mappedAuthorities = emptySet<GrantedAuthority>()
authorities.forEach { authority ->
if (authority is OidcUserAuthority) {
val idToken = authority.idToken
val userInfo = authority.userInfo
// Map the claims found in idToken and/or userInfo
// to one or more GrantedAuthority's and add it to mappedAuthorities
} else if (authority is OAuth2UserAuthority) {
val userAttributes = authority.attributes
// Map the attributes found in userAttributes
// to one or more GrantedAuthority's and add it to mappedAuthorities
}
}
mappedAuthorities
}
}
<http>
<oauth2-login user-authorities-mapper-ref="userAuthoritiesMapper"
...
/>
</http>
或者,您可以注册一个GrantedAuthoritiesMapper
@Bean
将其自动应用于配置,如下所示:
-
Java
-
Kotlin
@Configuration
@EnableWebSecurity
public class OAuth2LoginSecurityConfig {
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http
.oauth2Login(withDefaults());
return http.build();
}
@Bean
public GrantedAuthoritiesMapper userAuthoritiesMapper() {
...
}
}
@Configuration
@EnableWebSecurity
class OAuth2LoginSecurityConfig {
@Bean
open fun filterChain(http: HttpSecurity): SecurityFilterChain {
http {
oauth2Login { }
}
return http.build()
}
@Bean
fun userAuthoritiesMapper(): GrantedAuthoritiesMapper {
...
}
}
使用 OAuth2UserService 的基于委托的策略
与使用GrantedAuthoritiesMapper
.但是,它也更灵活,因为它允许您访问OAuth2UserRequest
和OAuth2User
(使用 OAuth 2.0 UserService 时)或OidcUserRequest
和OidcUser
(使用 OpenID Connect 1.0 UserService 时)。
这OAuth2UserRequest
(以及OidcUserRequest
) 允许您访问关联的OAuth2AccessToken
,这在委托人需要先从受保护资源获取权限信息才能为用户映射自定义权限的情况下非常有用。
以下示例说明如何使用 OpenID Connect 1.0 UserService 实施和配置基于委派的策略:
-
Java
-
Kotlin
-
Xml
@Configuration
@EnableWebSecurity
public class OAuth2LoginSecurityConfig {
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http
.oauth2Login(oauth2 -> oauth2
.userInfoEndpoint(userInfo -> userInfo
.oidcUserService(this.oidcUserService())
...
)
);
return http.build();
}
private OAuth2UserService<OidcUserRequest, OidcUser> oidcUserService() {
final OidcUserService delegate = new OidcUserService();
return (userRequest) -> {
// Delegate to the default implementation for loading a user
OidcUser oidcUser = delegate.loadUser(userRequest);
OAuth2AccessToken accessToken = userRequest.getAccessToken();
Set<GrantedAuthority> mappedAuthorities = new HashSet<>();
// TODO
// 1) Fetch the authority information from the protected resource using accessToken
// 2) Map the authority information to one or more GrantedAuthority's and add it to mappedAuthorities
// 3) Create a copy of oidcUser but use the mappedAuthorities instead
oidcUser = new DefaultOidcUser(mappedAuthorities, oidcUser.getIdToken(), oidcUser.getUserInfo());
return oidcUser;
};
}
}
@Configuration
@EnableWebSecurity
class OAuth2LoginSecurityConfig {
@Bean
open fun filterChain(http: HttpSecurity): SecurityFilterChain {
http {
oauth2Login {
userInfoEndpoint {
oidcUserService = oidcUserService()
}
}
}
return http.build()
}
@Bean
fun oidcUserService(): OAuth2UserService<OidcUserRequest, OidcUser> {
val delegate = OidcUserService()
return OAuth2UserService { userRequest ->
// Delegate to the default implementation for loading a user
var oidcUser = delegate.loadUser(userRequest)
val accessToken = userRequest.accessToken
val mappedAuthorities = HashSet<GrantedAuthority>()
// TODO
// 1) Fetch the authority information from the protected resource using accessToken
// 2) Map the authority information to one or more GrantedAuthority's and add it to mappedAuthorities
// 3) Create a copy of oidcUser but use the mappedAuthorities instead
oidcUser = DefaultOidcUser(mappedAuthorities, oidcUser.idToken, oidcUser.userInfo)
oidcUser
}
}
}
<http>
<oauth2-login oidc-user-service-ref="oidcUserService"
...
/>
</http>
OAuth 2.0 用户服务
DefaultOAuth2UserService
是OAuth2UserService
支持标准 OAuth 2.0 提供程序的。
|
DefaultOAuth2UserService
使用RestOperations
instance。
如果需要自定义 UserInfo Request 的预处理,可以提供DefaultOAuth2UserService.setRequestEntityConverter()
使用自定义Converter<OAuth2UserRequest, RequestEntity<?>>
.
默认实现OAuth2UserRequestEntityConverter
构建一个RequestEntity
UserInfo Request 的表示形式,该请求将OAuth2AccessToken
在Authorization
标头。
另一方面,如果需要自定义 UserInfo Response 的后处理,则需要提供DefaultOAuth2UserService.setRestOperations()
使用自定义配置RestOperations
.
默认的RestOperations
配置如下:
RestTemplate restTemplate = new RestTemplate();
restTemplate.setErrorHandler(new OAuth2ErrorResponseErrorHandler());
OAuth2ErrorResponseErrorHandler
是一个ResponseErrorHandler
可以处理 OAuth 2.0 错误(400 错误请求)。
它使用OAuth2ErrorHttpMessageConverter
用于将 OAuth 2.0 错误参数转换为OAuth2Error
.
无论您是否自定义DefaultOAuth2UserService
或提供您自己的OAuth2UserService
,您需要按如下方式进行配置:
-
Java
-
Kotlin
@Configuration
@EnableWebSecurity
public class OAuth2LoginSecurityConfig {
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http
.oauth2Login(oauth2 -> oauth2
.userInfoEndpoint(userInfo -> userInfo
.userService(this.oauth2UserService())
...
)
);
return http.build();
}
private OAuth2UserService<OAuth2UserRequest, OAuth2User> oauth2UserService() {
...
}
}
@Configuration
@EnableWebSecurity
class OAuth2LoginSecurityConfig {
@Bean
open fun filterChain(http: HttpSecurity): SecurityFilterChain {
http {
oauth2Login {
userInfoEndpoint {
userService = oauth2UserService()
// ...
}
}
}
return http.build()
}
private fun oauth2UserService(): OAuth2UserService<OAuth2UserRequest, OAuth2User> {
// ...
}
}
OpenID Connect 1.0 用户服务
OidcUserService
是OAuth2UserService
支持 OpenID Connect 1.0 提供程序的。
这OidcUserService
利用DefaultOAuth2UserService
在 UserInfo Endpoint 请求 user 属性时。
如果需要自定义 UserInfo Request 的预处理或 UserInfo Response 的后处理,需要提供OidcUserService.setOauth2UserService()
使用自定义配置DefaultOAuth2UserService
.
无论您是否自定义OidcUserService
或提供您自己的OAuth2UserService
对于 OpenID Connect 1.0 提供程序,您需要按如下方式进行配置:
-
Java
-
Kotlin
@Configuration
@EnableWebSecurity
public class OAuth2LoginSecurityConfig {
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http
.oauth2Login(oauth2 -> oauth2
.userInfoEndpoint(userInfo -> userInfo
.oidcUserService(this.oidcUserService())
...
)
);
return http.build();
}
private OAuth2UserService<OidcUserRequest, OidcUser> oidcUserService() {
...
}
}
@Configuration
@EnableWebSecurity
class OAuth2LoginSecurityConfig {
@Bean
open fun filterChain(http: HttpSecurity): SecurityFilterChain {
http {
oauth2Login {
userInfoEndpoint {
oidcUserService = oidcUserService()
// ...
}
}
}
return http.build()
}
private fun oidcUserService(): OAuth2UserService<OidcUserRequest, OidcUser> {
// ...
}
}
ID Token 签名验证
OpenID Connect 1.0 身份验证引入了 ID Tokens,这是一个安全Tokens,其中包含有关客户端使用时授权服务器对最终用户进行身份验证的声明。
ID Tokens表示为 JSON Web Tokens (JWT),并且必须使用 JSON Web 签名 (JWS) 进行签名。
这OidcIdTokenDecoderFactory
提供JwtDecoder
用于OidcIdToken
签名验证。默认算法为RS256
但在客户端注册期间分配时可能会有所不同。
对于这些情况,您可以配置解析程序以返回为特定客户端分配的预期 JWS 算法。
JWS 算法解析程序是一个Function
接受ClientRegistration
并返回预期的JwsAlgorithm
对于客户端,例如SignatureAlgorithm.RS256
或MacAlgorithm.HS256
以下代码显示了如何配置OidcIdTokenDecoderFactory
@Bean
默认为MacAlgorithm.HS256
为了所有人ClientRegistration
实例:
-
Java
-
Kotlin
@Bean
public JwtDecoderFactory<ClientRegistration> idTokenDecoderFactory() {
OidcIdTokenDecoderFactory idTokenDecoderFactory = new OidcIdTokenDecoderFactory();
idTokenDecoderFactory.setJwsAlgorithmResolver(clientRegistration -> MacAlgorithm.HS256);
return idTokenDecoderFactory;
}
@Bean
fun idTokenDecoderFactory(): JwtDecoderFactory<ClientRegistration?> {
val idTokenDecoderFactory = OidcIdTokenDecoderFactory()
idTokenDecoderFactory.setJwsAlgorithmResolver { MacAlgorithm.HS256 }
return idTokenDecoderFactory
}
对于基于 MAC 的算法(例如 |
如果有多个 |
OpenID Connect 1.0 注销
OpenID Connect 会话管理 1.0 允许使用客户端在提供程序处注销最终用户。 可用的策略之一是 RP 发起的注销。
如果 OpenID Provider 同时支持 Session Management 和 Discovery,则客户端可以获取end_session_endpoint
URL
从 OpenID 提供程序的发现元数据。
为此,您可以配置ClientRegistration
使用issuer-uri
如下:
spring:
security:
oauth2:
client:
registration:
okta:
client-id: okta-client-id
client-secret: okta-client-secret
...
provider:
okta:
issuer-uri: https://dev-1234.oktapreview.com
此外,您还可以配置OidcClientInitiatedLogoutSuccessHandler
,它实施 RP 启动的注销,如下所示:
-
Java
-
Kotlin
@Configuration
@EnableWebSecurity
public class OAuth2LoginSecurityConfig {
@Autowired
private ClientRegistrationRepository clientRegistrationRepository;
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http
.authorizeHttpRequests(authorize -> authorize
.anyRequest().authenticated()
)
.oauth2Login(withDefaults())
.logout(logout -> logout
.logoutSuccessHandler(oidcLogoutSuccessHandler())
);
return http.build();
}
private LogoutSuccessHandler oidcLogoutSuccessHandler() {
OidcClientInitiatedLogoutSuccessHandler oidcLogoutSuccessHandler =
new OidcClientInitiatedLogoutSuccessHandler(this.clientRegistrationRepository);
// Sets the location that the End-User's User Agent will be redirected to
// after the logout has been performed at the Provider
oidcLogoutSuccessHandler.setPostLogoutRedirectUri("{baseUrl}");
return oidcLogoutSuccessHandler;
}
}
@Configuration
@EnableWebSecurity
class OAuth2LoginSecurityConfig {
@Autowired
private lateinit var clientRegistrationRepository: ClientRegistrationRepository
@Bean
open fun filterChain(http: HttpSecurity): SecurityFilterChain {
http {
authorizeRequests {
authorize(anyRequest, authenticated)
}
oauth2Login { }
logout {
logoutSuccessHandler = oidcLogoutSuccessHandler()
}
}
return http.build()
}
private fun oidcLogoutSuccessHandler(): LogoutSuccessHandler {
val oidcLogoutSuccessHandler = OidcClientInitiatedLogoutSuccessHandler(clientRegistrationRepository)
// Sets the location that the End-User's User Agent will be redirected to
// after the logout has been performed at the Provider
oidcLogoutSuccessHandler.setPostLogoutRedirectUri("{baseUrl}")
return oidcLogoutSuccessHandler
}
}
|