核心接口/类

ClientRegistration

ClientRegistration 代表与 OAuth 2.0 或 OpenID Connect 1.0 提供商注册的客户端。

客户端注册保存信息，例如客户端 ID、客户端密钥、授权授权类型、重定向 URI、范围、授权 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：客户端在授权请求流程中请求的范围，例如 openid、email 或 profile。
8 clientName：客户端的描述性名称。该名称可能用于某些场景，例如在自动生成的登录页面中显示客户端的名称。
9 authorizationUri：授权服务器的授权端点 URI。
10 tokenUri：授权服务器的令牌端点 URI。
11 jwkSetUri：用于从授权服务器检索 JSON Web 密钥 (JWK) 集的 URI，其中包含用于验证 JSON Web 签名 (JWS) 的 ID 令牌以及可选的用户详细信息响应的加密密钥。
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 提供商的 配置端点 或授权服务器的 元数据端点 的发现来初始配置。

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 的实例，然后将每个 ClientRegistration 实例组合到 ReactiveClientRegistrationRepository 中。

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负责在网络请求之间持久化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
}