核心介面 / 類別

ClientRegistration

ClientRegistration 代表在 OAuth 2.0 或 OpenID Connect 1.0 提供者註冊的用戶端。

用戶端註冊資訊包含用戶端 ID、用戶端密碼、授權許可類型、重新導向 URI、Scope、授權 URI、令牌 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：用於向提供者驗證用戶端身份的方法。支援的值為 client_secret_basic、client_secret_post、private_key_jwt、client_secret_jwt 和 none (公開用戶端)。
5 authorizationGrantType：OAuth 2.0 授權框架定義了四種授權許可類型。支援的值為 authorization_code、client_credentials、password，以及擴充許可類型 urn:ietf:params:oauth:grant-type:jwt-bearer。
6 redirectUri：用戶端註冊的重新導向 URI，在終端使用者驗證身份並授權用戶端存取後，授權伺服器會將終端使用者的使用者代理程式重新導向至此 URI。
7 scopes：用戶端在授權請求流程期間請求的 Scope，例如 openid、email 或 profile。
8 clientName：用於用戶端的描述性名稱。此名稱可用於某些情境，例如在自動產生的登入頁面中顯示用戶端名稱時。
9 authorizationUri：授權伺服器的授權端點 URI。
10 tokenUri：授權伺服器的令牌端點 URI。
11 jwkSetUri：用於從授權伺服器檢索 JSON Web Key (JWK) 集的 URI，其中包含用於驗證 ID 令牌的 JSON Web Signature (JWS) 和可選的使用者資訊回應的加密金鑰。
12 issuerUri：傳回 OpenID Connect 1.0 提供者或 OAuth 2.0 授權伺服器的發行者識別符 URI。
13 configurationMetadata：OpenID 提供者組態資訊。僅當設定 Spring Boot 屬性 spring.security.oauth2.client.provider.[providerId].issuerUri 時，此資訊才可用。
14 (userInfoEndpoint)uri：使用者資訊端點 URI，用於存取已驗證終端使用者的宣告/屬性。
15 (userInfoEndpoint)authenticationMethod：將存取令牌傳送到使用者資訊端點時使用的身份驗證方法。支援的值為 header、form 和 query。
16 userNameAttributeName：使用者資訊回應中傳回的屬性名稱，該屬性引用終端使用者的名稱或識別符。

ClientRegistration 可以使用探索 OpenID Connect 提供者的 組態端點 或授權伺服器的 Metadata 端點 進行初始組態。

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 提供者的組態端點。

ReactiveClientRegistrationRepository

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

用戶端註冊資訊最終由相關聯的授權伺服器儲存和擁有。此儲存庫提供檢索主要用戶端註冊資訊子集的能力，這些資訊儲存在授權伺服器中。

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

ReactiveClientRegistrationRepository 的預設實作是 InMemoryReactiveClientRegistrationRepository。

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

以下清單顯示了一個範例

  • 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 用戶端結構描述中描述的表格定義。

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 關聯，後者可以使用基於委派的組合來支援多種授權許可類型。ReactiveOAuth2AuthorizedClientProviderBuilder 可用於組態和建置基於委派的組合。

以下程式碼範例顯示如何組態和建置 ReactiveOAuth2AuthorizedClientProvider 組合，該組合提供對 authorization_code、refresh_token、client_credentials 和 password 授權許可類型的支援

  • 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 還與 contextAttributesMapper (類型為 Function<OAuth2AuthorizeRequest, Mono<Map<String, Object>>>) 關聯，它負責將來自 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 用戶端可以被視為一種服務應用程式。

以下程式碼範例顯示如何組態 AuthorizedClientServiceReactiveOAuth2AuthorizedClientManager，該管理程式提供對 client_credentials 許可類型的支援

  • 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
}