核心介面 / 類

ClientRegistration

ClientRegistration 表示在 OAuth 2.0 或 OpenID Connect 1.0 Provider 註冊的客戶端。

客戶端註冊包含的資訊，例如 client id, client secret, authorization grant type, redirect URI, scope(s), authorization URI, token URI 等詳細資訊。

ClientRegistration 及其屬性定義如下

public final class ClientRegistration {
	private String registrationId;	(1)
	private String clientId;	(2)
	private String clientSecret;	(3)
	private ClientAuthenticationMethod clientAuthenticationMethod;	(4)
	private AuthorizationGrantType authorizationGrantType;	(5)
	private String redirectUri;	(6)
	private Set<String> scopes;	(7)
	private ProviderDetails providerDetails;
	private String clientName;	(8)

	public class ProviderDetails {
		private String authorizationUri;	(9)
		private String tokenUri;	(10)
		private UserInfoEndpoint userInfoEndpoint;
		private String jwkSetUri;	(11)
		private String issuerUri;	(12)
		private Map<String, Object> configurationMetadata;  (13)

		public class UserInfoEndpoint {
			private String uri;	(14)
			private AuthenticationMethod authenticationMethod;  (15)
			private String userNameAttributeName;	(16)

		}
	}
}
1 registrationId: 唯一標識 ClientRegistration 的 ID。
2 clientId: 客戶端識別符號。
3 clientSecret: 客戶端金鑰。
4 clientAuthenticationMethod: 用於客戶端向 Provider 進行認證的方法。支援的值有 client_secret_basic, client_secret_post, private_key_jwt, client_secret_jwt 和 none (公共客戶端)。
5 authorizationGrantType: OAuth 2.0 授權框架定義了四種 授權許可 (Authorization Grant) 型別。支援的值有 authorization_code, client_credentials, password，以及擴充套件許可型別 urn:ietf:params:oauth:grant-type:jwt-bearer。
6 redirectUri: 客戶端註冊的重定向 URI，在終端使用者認證並授權客戶端訪問後，授權伺服器 將終端使用者的使用者代理重定向到此 URI。
7 scopes: 在授權請求流程中客戶端請求的作用域，例如 openid, email, 或 profile。
8 clientName: 用於客戶端的描述性名稱。該名稱可以在某些場景下使用，例如在自動生成的登入頁中顯示客戶端名稱。
9 authorizationUri: 授權伺服器的授權端點 URI。
10 tokenUri: 授權伺服器的令牌端點 URI。
11 jwkSetUri: 用於從授權伺服器檢索 JSON Web Key (JWK) Set 的 URI，其中包含用於驗證 ID Token 的 JSON Web Signature (JWS) 以及可選的 UserInfo Response 的加密金鑰。
12 issuerUri: 返回 OpenID Connect 1.0 provider 或 OAuth 2.0 Authorization Server 的頒發者識別符號 URI。
13 configurationMetadata: OpenID Provider 配置資訊。只有在配置了 Spring Boot 屬性 spring.security.oauth2.client.provider.[providerId].issuerUri 時，此資訊才可用。
14 (userInfoEndpoint)uri: 用於訪問已認證終端使用者的宣告/屬性的 UserInfo 端點 URI。
15 (userInfoEndpoint)authenticationMethod: 將訪問令牌傳送到 UserInfo 端點時使用的認證方法。支援的值有 header, form 和 query。
16 userNameAttributeName: UserInfo Response 中返回的引用終端使用者名稱稱或識別符號的屬性名稱。

ClientRegistration 最初可以使用 OpenID Connect Provider 的 配置端點 或授權伺服器的 元資料端點 的發現功能進行配置。

ClientRegistrations 提供了便捷的方法來以這種方式配置 ClientRegistration，如下例所示

  • Java

  • Kotlin

ClientRegistration clientRegistration =
	ClientRegistrations.fromIssuerLocation("https://idp.example.com/issuer").build();
val clientRegistration = ClientRegistrations.fromIssuerLocation("https://idp.example.com/issuer").build()

上面的程式碼將按順序查詢 idp.example.com/issuer/.well-known/openid-configuration，然後是 idp.example.com/.well-known/openid-configuration/issuer，最後是 idp.example.com/.well-known/oauth-authorization-server/issuer，並在第一個返回 200 響應時停止。

作為替代方案，您可以使用 ClientRegistrations.fromOidcIssuerLocation() 僅查詢 OpenID Connect Provider 的配置端點。

ReactiveClientRegistrationRepository

ReactiveClientRegistrationRepository 作為 OAuth 2.0 / OpenID Connect 1.0 ClientRegistration 的倉庫。

客戶端註冊資訊最終儲存並歸相關授權伺服器所有。此倉庫提供了檢索儲存在授權伺服器中的主要客戶端註冊資訊子集的功能。

Spring Boot 自動配置將 spring.security.oauth2.client.registration.[registrationId] 下的每個屬性繫結到 ClientRegistration 例項，然後將每個 ClientRegistration 例項組合到 ReactiveClientRegistrationRepository 中。

ReactiveClientRegistrationRepository 的預設實現是 InMemoryReactiveClientRegistrationRepository。

自動配置還將 ReactiveClientRegistrationRepository 作為 @Bean 註冊到 ApplicationContext 中，以便應用程式在需要時可以進行依賴注入。

以下列表顯示了一個示例

  • Java

  • Kotlin

@Controller
public class OAuth2ClientController {

	@Autowired
	private ReactiveClientRegistrationRepository clientRegistrationRepository;

	@GetMapping("/")
	public Mono<String> index() {
		return this.clientRegistrationRepository.findByRegistrationId("okta")
				...
				.thenReturn("index");
	}
}
@Controller
class OAuth2ClientController {

    @Autowired
    private lateinit var clientRegistrationRepository: ReactiveClientRegistrationRepository

    @GetMapping("/")
    fun index(): Mono<String> {
        return this.clientRegistrationRepository.findByRegistrationId("okta")
            ...
            .thenReturn("index")
    }
}

OAuth2AuthorizedClient

OAuth2AuthorizedClient 代表一個授權客戶端。當終端使用者（資源所有者）授權客戶端訪問其受保護資源時，該客戶端被視為已授權。

OAuth2AuthorizedClient 的作用是將一個 OAuth2AccessToken（和可選的 OAuth2RefreshToken）關聯到 ClientRegistration（客戶端）和資源所有者，後者是授予授權的 Principal 終端使用者。

ServerOAuth2AuthorizedClientRepository / ReactiveOAuth2AuthorizedClientService

ServerOAuth2AuthorizedClientRepository 負責在 Web 請求之間持久化 OAuth2AuthorizedClient。而 ReactiveOAuth2AuthorizedClientService 的主要作用是在應用層面管理 OAuth2AuthorizedClient。

從開發人員的角度來看，ServerOAuth2AuthorizedClientRepository 或 ReactiveOAuth2AuthorizedClientService 提供了查詢與客戶端關聯的 OAuth2AccessToken 的功能，以便用於發起受保護資源請求。

以下列表顯示了一個示例

  • Java

  • Kotlin

@Controller
public class OAuth2ClientController {

	@Autowired
	private ReactiveOAuth2AuthorizedClientService authorizedClientService;

	@GetMapping("/")
	public Mono<String> index(Authentication authentication) {
		return this.authorizedClientService.loadAuthorizedClient("okta", authentication.getName())
				.map(OAuth2AuthorizedClient::getAccessToken)
				...
				.thenReturn("index");
	}
}
@Controller
class OAuth2ClientController {

    @Autowired
    private lateinit var authorizedClientService: ReactiveOAuth2AuthorizedClientService

    @GetMapping("/")
    fun index(authentication: Authentication): Mono<String> {
        return this.authorizedClientService.loadAuthorizedClient<OAuth2AuthorizedClient>("okta", authentication.name)
            .map { it.accessToken }
            ...
            .thenReturn("index")
    }
}

Spring Boot 自動配置會在 ApplicationContext 中註冊一個 ServerOAuth2AuthorizedClientRepository 和/或 ReactiveOAuth2AuthorizedClientService @Bean。然而，應用程式可以選擇覆蓋並註冊自定義的 ServerOAuth2AuthorizedClientRepository 或 ReactiveOAuth2AuthorizedClientService @Bean。

ReactiveOAuth2AuthorizedClientService 的預設實現是 InMemoryReactiveOAuth2AuthorizedClientService，它將 OAuth2AuthorizedClient 儲存在記憶體中。

另外，可以配置 R2DBC 實現 R2dbcReactiveOAuth2AuthorizedClientService 將 OAuth2AuthorizedClient 持久化到資料庫中。

R2dbcReactiveOAuth2AuthorizedClientService 依賴於 OAuth 2.0 Client Schema 中描述的表定義。

ReactiveOAuth2AuthorizedClientManager / ReactiveOAuth2AuthorizedClientProvider

ReactiveOAuth2AuthorizedClientManager 負責 OAuth2AuthorizedClient 的整體管理。

主要職責包括

  • 使用 ReactiveOAuth2AuthorizedClientProvider 授權（或重新授權）OAuth 2.0 客戶端。

  • 委託 OAuth2AuthorizedClient 的持久化，通常使用 ReactiveOAuth2AuthorizedClientService 或 ServerOAuth2AuthorizedClientRepository。

  • 當 OAuth 2.0 客戶端成功授權（或重新授權）時，委託給 ReactiveOAuth2AuthorizationSuccessHandler。

  • 當 OAuth 2.0 客戶端授權（或重新授權）失敗時，委託給 ReactiveOAuth2AuthorizationFailureHandler。

ReactiveOAuth2AuthorizedClientProvider 實現了一種授權（或重新授權）OAuth 2.0 客戶端的策略。實現通常會實現某種授權許可型別，例如 authorization_code, client_credentials 等。

ReactiveOAuth2AuthorizedClientManager 的預設實現是 DefaultReactiveOAuth2AuthorizedClientManager，它關聯了一個 ReactiveOAuth2AuthorizedClientProvider，該 Provider 可以使用基於委託的複合模式支援多種授權許可型別。可以使用 ReactiveOAuth2AuthorizedClientProviderBuilder 配置和構建基於委託的複合。

以下程式碼展示瞭如何配置和構建一個支援 authorization_code, refresh_token, client_credentials 和 password 授權許可型別的 ReactiveOAuth2AuthorizedClientProvider 複合

  • Java

  • Kotlin

@Bean
public ReactiveOAuth2AuthorizedClientManager authorizedClientManager(
		ReactiveClientRegistrationRepository clientRegistrationRepository,
		ServerOAuth2AuthorizedClientRepository authorizedClientRepository) {

	ReactiveOAuth2AuthorizedClientProvider authorizedClientProvider =
			ReactiveOAuth2AuthorizedClientProviderBuilder.builder()
					.authorizationCode()
					.refreshToken()
					.clientCredentials()
					.password()
					.build();

	DefaultReactiveOAuth2AuthorizedClientManager authorizedClientManager =
			new DefaultReactiveOAuth2AuthorizedClientManager(
					clientRegistrationRepository, authorizedClientRepository);
	authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider);

	return authorizedClientManager;
}
@Bean
fun authorizedClientManager(
        clientRegistrationRepository: ReactiveClientRegistrationRepository,
        authorizedClientRepository: ServerOAuth2AuthorizedClientRepository): ReactiveOAuth2AuthorizedClientManager {
    val authorizedClientProvider: ReactiveOAuth2AuthorizedClientProvider = ReactiveOAuth2AuthorizedClientProviderBuilder.builder()
            .authorizationCode()
            .refreshToken()
            .clientCredentials()
            .password()
            .build()
    val authorizedClientManager = DefaultReactiveOAuth2AuthorizedClientManager(
            clientRegistrationRepository, authorizedClientRepository)
    authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider)
    return authorizedClientManager
}

當授權嘗試成功時，DefaultReactiveOAuth2AuthorizedClientManager 將委託給 ReactiveOAuth2AuthorizationSuccessHandler，後者（預設情況下）將透過 ServerOAuth2AuthorizedClientRepository 儲存 OAuth2AuthorizedClient。如果重新授權失敗，例如重新整理令牌不再有效，則先前儲存的 OAuth2AuthorizedClient 將透過 RemoveAuthorizedClientReactiveOAuth2AuthorizationFailureHandler 從 ServerOAuth2AuthorizedClientRepository 中移除。預設行為可以透過 setAuthorizationSuccessHandler(ReactiveOAuth2AuthorizationSuccessHandler) 和 setAuthorizationFailureHandler(ReactiveOAuth2AuthorizationFailureHandler) 進行自定義。

DefaultReactiveOAuth2AuthorizedClientManager 還關聯了一個型別為 Function<OAuth2AuthorizeRequest, Mono<Map<String, Object>>> 的 contextAttributesMapper，它負責將 OAuth2AuthorizeRequest 中的屬性對映到與 OAuth2AuthorizationContext 關聯的屬性 Map 中。當您需要向 ReactiveOAuth2AuthorizedClientProvider 提供必需（支援）的屬性時，這會很有用，例如 PasswordReactiveOAuth2AuthorizedClientProvider 要求資源所有者的 username 和 password 在 OAuth2AuthorizationContext.getAttributes() 中可用。

以下程式碼展示了 contextAttributesMapper 的示例

  • Java

  • Kotlin

@Bean
public ReactiveOAuth2AuthorizedClientManager authorizedClientManager(
		ReactiveClientRegistrationRepository clientRegistrationRepository,
		ServerOAuth2AuthorizedClientRepository authorizedClientRepository) {

	ReactiveOAuth2AuthorizedClientProvider authorizedClientProvider =
			ReactiveOAuth2AuthorizedClientProviderBuilder.builder()
					.password()
					.refreshToken()
					.build();

	DefaultReactiveOAuth2AuthorizedClientManager authorizedClientManager =
			new DefaultReactiveOAuth2AuthorizedClientManager(
					clientRegistrationRepository, authorizedClientRepository);
	authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider);

	// Assuming the `username` and `password` are supplied as `ServerHttpRequest` parameters,
	// map the `ServerHttpRequest` parameters to `OAuth2AuthorizationContext.getAttributes()`
	authorizedClientManager.setContextAttributesMapper(contextAttributesMapper());

	return authorizedClientManager;
}

private Function<OAuth2AuthorizeRequest, Mono<Map<String, Object>>> contextAttributesMapper() {
	return authorizeRequest -> {
		Map<String, Object> contextAttributes = Collections.emptyMap();
		ServerWebExchange exchange = authorizeRequest.getAttribute(ServerWebExchange.class.getName());
		ServerHttpRequest request = exchange.getRequest();
		String username = request.getQueryParams().getFirst(OAuth2ParameterNames.USERNAME);
		String password = request.getQueryParams().getFirst(OAuth2ParameterNames.PASSWORD);
		if (StringUtils.hasText(username) && StringUtils.hasText(password)) {
			contextAttributes = new HashMap<>();

			// `PasswordReactiveOAuth2AuthorizedClientProvider` requires both attributes
			contextAttributes.put(OAuth2AuthorizationContext.USERNAME_ATTRIBUTE_NAME, username);
			contextAttributes.put(OAuth2AuthorizationContext.PASSWORD_ATTRIBUTE_NAME, password);
		}
		return Mono.just(contextAttributes);
	};
}
@Bean
fun authorizedClientManager(
        clientRegistrationRepository: ReactiveClientRegistrationRepository,
        authorizedClientRepository: ServerOAuth2AuthorizedClientRepository): ReactiveOAuth2AuthorizedClientManager {
    val authorizedClientProvider: ReactiveOAuth2AuthorizedClientProvider = ReactiveOAuth2AuthorizedClientProviderBuilder.builder()
            .password()
            .refreshToken()
            .build()
    val authorizedClientManager = DefaultReactiveOAuth2AuthorizedClientManager(
            clientRegistrationRepository, authorizedClientRepository)
    authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider)

    // Assuming the `username` and `password` are supplied as `ServerHttpRequest` parameters,
    // map the `ServerHttpRequest` parameters to `OAuth2AuthorizationContext.getAttributes()`
    authorizedClientManager.setContextAttributesMapper(contextAttributesMapper())
    return authorizedClientManager
}

private fun contextAttributesMapper(): Function<OAuth2AuthorizeRequest, Mono<MutableMap<String, Any>>> {
    return Function { authorizeRequest ->
        var contextAttributes: MutableMap<String, Any> = mutableMapOf()
        val exchange: ServerWebExchange = authorizeRequest.getAttribute(ServerWebExchange::class.java.name)!!
        val request: ServerHttpRequest = exchange.request
        val username: String? = request.queryParams.getFirst(OAuth2ParameterNames.USERNAME)
        val password: String? = request.queryParams.getFirst(OAuth2ParameterNames.PASSWORD)
        if (StringUtils.hasText(username) && StringUtils.hasText(password)) {
            contextAttributes = hashMapOf()

            // `PasswordReactiveOAuth2AuthorizedClientProvider` requires both attributes
            contextAttributes[OAuth2AuthorizationContext.USERNAME_ATTRIBUTE_NAME] = username!!
            contextAttributes[OAuth2AuthorizationContext.PASSWORD_ATTRIBUTE_NAME] = password!!
        }
        Mono.just(contextAttributes)
    }
}

DefaultReactiveOAuth2AuthorizedClientManager 設計用於在 ServerWebExchange 的上下文中使用。當在 ServerWebExchange 上下文之外操作時，請使用 AuthorizedClientServiceReactiveOAuth2AuthorizedClientManager 代替。

服務應用 是使用 AuthorizedClientServiceReactiveOAuth2AuthorizedClientManager 的常見用例。服務應用通常在後臺執行，無需任何使用者互動，並且通常在系統級賬戶下執行而非使用者賬戶。配置了 client_credentials 授權許可型別的 OAuth 2.0 客戶端可以視為一種服務應用。

以下程式碼展示瞭如何配置一個支援 client_credentials 授權許可型別的 AuthorizedClientServiceReactiveOAuth2AuthorizedClientManager 的示例

  • Java

  • Kotlin

@Bean
public ReactiveOAuth2AuthorizedClientManager authorizedClientManager(
		ReactiveClientRegistrationRepository clientRegistrationRepository,
		ReactiveOAuth2AuthorizedClientService authorizedClientService) {

	ReactiveOAuth2AuthorizedClientProvider authorizedClientProvider =
			ReactiveOAuth2AuthorizedClientProviderBuilder.builder()
					.clientCredentials()
					.build();

	AuthorizedClientServiceReactiveOAuth2AuthorizedClientManager authorizedClientManager =
			new AuthorizedClientServiceReactiveOAuth2AuthorizedClientManager(
					clientRegistrationRepository, authorizedClientService);
	authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider);

	return authorizedClientManager;
}
@Bean
fun authorizedClientManager(
        clientRegistrationRepository: ReactiveClientRegistrationRepository,
        authorizedClientService: ReactiveOAuth2AuthorizedClientService): ReactiveOAuth2AuthorizedClientManager {
    val authorizedClientProvider: ReactiveOAuth2AuthorizedClientProvider = ReactiveOAuth2AuthorizedClientProviderBuilder.builder()
            .clientCredentials()
            .build()
    val authorizedClientManager = AuthorizedClientServiceReactiveOAuth2AuthorizedClientManager(
            clientRegistrationRepository, authorizedClientService)
    authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider)
    return authorizedClientManager
}