高階配置
HttpSecurity.oauth2Login()
提供了許多用於自定義 OAuth 2.0 登入的配置選項。主要配置選項按照協議端點對應關係進行分組。
例如,oauth2Login().authorizationEndpoint()
允許配置 *授權端點*,而 oauth2Login().tokenEndpoint()
允許配置 *令牌端點*。
以下程式碼展示了一個示例
-
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 資源)
-
授權端點:客戶端透過使用者代理重定向從資源所有者獲取授權時使用。
-
令牌端點:客戶端用於將授權許可交換為訪問令牌,通常伴隨客戶端認證。
授權過程還使用一個客戶端端點
-
重定向端點:授權伺服器透過資源所有者使用者代理向客戶端返回包含授權憑據的響應時使用。
OpenID Connect Core 1.0 規範將 UserInfo 端點 定義如下
UserInfo 端點是受保護的 OAuth 2.0 資源,用於返回關於認證後的終端使用者(End-User)的宣告(claims)。為了獲取關於終端使用者的請求宣告,客戶端使用透過 OpenID Connect Authentication 獲得的訪問令牌向 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 配置。
以下程式碼顯示了安全名稱空間中可用的完整配置選項
<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 Code Grant)。因此,授權憑據就是授權碼。 |
預設的授權響應 baseUri
(重定向端點)是 /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 端點包含許多配置選項,如下面的子節所述
對映使用者許可權
使用者成功透過 OAuth 2.0 Provider 認證後,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
ProviderDetails providerDetails = userRequest.getClientRegistration().getProviderDetails();
String userNameAttributeName = providerDetails.getUserInfoEndpoint().getUserNameAttributeName();
if (StringUtils.hasText(userNameAttributeName)) {
oidcUser = new DefaultOidcUser(mappedAuthorities, oidcUser.getIdToken(), oidcUser.getUserInfo(), userNameAttributeName);
} else {
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
val 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
val providerDetails = userRequest.getClientRegistration().getProviderDetails()
val userNameAttributeName = providerDetails.getUserInfoEndpoint().getUserNameAttributeName()
if (StringUtils.hasText(userNameAttributeName)) {
DefaultOidcUser(mappedAuthorities, oidcUser.idToken, oidcUser.userInfo, userNameAttributeName)
} else {
DefaultOidcUser(mappedAuthorities, oidcUser.idToken, oidcUser.userInfo)
}
}
}
}
<http>
<oauth2-login oidc-user-service-ref="oidcUserService"
...
/>
</http>
OAuth 2.0 UserService
DefaultOAuth2UserService
是 OAuth2UserService
的一個實現,支援標準的 OAuth 2.0 Provider。
|
DefaultOAuth2UserService
在 UserInfo 端點請求使用者屬性時使用 RestOperations
例項。
如果您需要自定義 UserInfo 請求的預處理,可以為 DefaultOAuth2UserService.setRequestEntityConverter()
提供一個自定義的 Converter<OAuth2UserRequest, RequestEntity<?>>
。預設實現 OAuth2UserRequestEntityConverter
構建 UserInfo 請求的 RequestEntity
表示,預設情況下在 Authorization
頭中設定 OAuth2AccessToken
。
另一方面,如果您需要自定義 UserInfo 響應的後處理,需要為 DefaultOAuth2UserService.setRestOperations()
提供一個自定義配置的 RestOperations
。預設的 RestOperations
配置如下
RestTemplate restTemplate = new RestTemplate();
restTemplate.setErrorHandler(new OAuth2ErrorResponseErrorHandler());
OAuth2ErrorResponseErrorHandler
是一個 ResponseErrorHandler
,可以處理 OAuth 2.0 錯誤(400 Bad Request)。它使用 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 UserService
OidcUserService
是 OAuth2UserService
的一個實現,支援 OpenID Connect 1.0 Provider。
OidcUserService
在 UserInfo 端點請求使用者屬性時利用了 DefaultOAuth2UserService
。
如果您需要自定義 UserInfo 請求的預處理或 UserInfo 響應的後處理,您需要為 OidcUserService.setOauth2UserService()
提供一個自定義配置的 DefaultOAuth2UserService
。
無論您是自定義 OidcUserService
還是為 OpenID Connect 1.0 Provider 提供自己的 OAuth2UserService
實現,都需要按如下方式進行配置
-
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 令牌簽名驗證
OpenID Connect 1.0 Authentication 引入了 ID 令牌,它是一個安全令牌,當由客戶端使用時,其中包含授權伺服器對終端使用者認證的宣告。
ID 令牌表示為 JSON Web Token (JWT),並且必須使用 JSON Web Signature (JWS) 進行簽名。
OidcIdTokenDecoderFactory
提供了一個用於 OidcIdToken
簽名驗證的 JwtDecoder
。預設演算法是 RS256
,但在客戶端註冊時分配的演算法可能不同。對於這些情況,您可以配置一個解析器來返回為特定客戶端分配的預期 JWS 演算法。
JWS 演算法解析器是一個 Function
,它接受一個 ClientRegistration
並返回客戶端預期的 JwsAlgorithm
,例如 SignatureAlgorithm.RS256
或 MacAlgorithm.HS256
以下程式碼展示瞭如何配置 OidcIdTokenDecoderFactory
的 @Bean
,使其對所有 ClientRegistration
例項預設為 MacAlgorithm.HS256
-
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 Authentication 配置了多個 |
然後,您可以繼續配置 登出