跳到主要内容
版本：7.0.2

核心接口 / 类

DeepSeek V3 中英对照 Core Interfaces and Classes Core Interfaces / Classes

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

		}
	}

	public static final class ClientSettings {
		private boolean requireProofKey; 17
	}
}

  • registrationId: 唯一标识 ClientRegistration 的 ID。

  • clientId: 客户端标识符。

  • clientSecret: 客户端密钥。

  • clientAuthenticationMethod: 客户端用于向提供者进行身份验证的方法。支持的值为 client_secret_basic、client_secret_post、private_key_jwt、client_secret_jwt 和 none (公共客户端)。

  • authorizationGrantType: OAuth 2.0 授权框架定义了四种授权许可类型。支持的值为 authorization_code、client_credentials，以及扩展授权类型 urn:ietf:params:oauth:grant-type:jwt-bearer。

  • redirectUri: 客户端注册的重定向 URI，在最终用户完成身份验证并授权客户端访问后，授权服务器会将最终用户的用户代理重定向到此 URI。

  • scopes: 客户端在授权请求流程中请求的范围，例如 openid、email 或 profile。

  • clientName: 客户端的描述性名称。该名称可能在特定场景中使用，例如在自动生成的登录页面中显示客户端名称。

  • authorizationUri: 授权服务器的授权端点 URI。

  • tokenUri: 授权服务器的令牌端点 URI。

  • jwkSetUri: 用于从授权服务器检索 JSON Web Key (JWK) 集的 URI，该集合包含用于验证 ID Token 和（可选的）UserInfo 响应的 JSON Web Signature (JWS) 的加密密钥。

  • issuerUri: 返回 OpenID Connect 1.0 提供者或 OAuth 2.0 授权服务器的颁发者标识符 URI。

  • configurationMetadata: OpenID 提供者配置信息。仅当配置了 Spring Boot 属性 spring.security.oauth2.client.provider.[providerId].issuerUri 时，此信息才可用。

  • (userInfoEndpoint)uri: 用于访问已认证最终用户的声明/属性的 UserInfo 端点 URI。

  • (userInfoEndpoint)authenticationMethod: 向 UserInfo 端点发送访问令牌时使用的身份验证方法。支持的值为 header、form 和 query。

  • userNameAttributeName: UserInfo 响应中返回的属性名称，该属性引用最终用户的名称或标识符。


  • requireProofKey: 如果为 true 或者 authorizationGrantType 为 none，则默认启用 PKCE。

ClientRegistration 最初可以通过发现 OpenID Connect 提供者的配置端点或授权服务器的元数据端点来进行配置。

ClientRegistrations 提供了便捷方法来配置 ClientRegistration，如下例所示：

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

上述代码将依次查询 [idp.example.com/issuer/.well-known/openid-configuration](https://idp.example.com/issuer/.well-known/openid-configuration)，接着查询 [idp.example.com/.well-known/openid-configuration/issuer](https://idp.example.com/.well-known/openid-configuration/issuer)，最后查询 [idp.example.com/.well-known/oauth-authorization-server/issuer](https://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，以便在应用程序需要时可用于依赖注入。

以下清单展示了一个示例：

@Controller
public class OAuth2ClientController {

	@Autowired
	private ReactiveClientRegistrationRepository clientRegistrationRepository;

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

OAuth2AuthorizedClient​

OAuth2AuthorizedClient 是已授权客户端的表示形式。当最终用户（资源所有者）已授权客户端访问其受保护资源时，该客户端即被视为已授权。

OAuth2AuthorizedClient 的作用是将 OAuth2AccessToken（以及可选的 OAuth2RefreshToken）与一个 ClientRegistration（客户端）以及资源所有者（即授予授权的最终用户 Principal）关联起来。

ServerOAuth2AuthorizedClientRepository / ReactiveOAuth2AuthorizedClientService​

ServerOAuth2AuthorizedClientRepository 负责在 Web 请求之间持久化 OAuth2AuthorizedClient。而 ReactiveOAuth2AuthorizedClientService 的主要作用是在应用级别管理 OAuth2AuthorizedClient。

从开发者视角来看，ServerOAuth2AuthorizedClientRepository 或 ReactiveOAuth2AuthorizedClientService 提供了查找与客户端关联的 OAuth2AccessToken 的能力，以便该令牌可用于发起受保护资源的请求。

以下清单展示了一个示例：

@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");
	}
}
备注

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 相关联，该提供者可以通过基于委托的复合结构支持多种授权许可类型。ReactiveOAuth2AuthorizedClientProviderBuilder 可用于配置和构建这种基于委托的复合结构。

以下代码展示了如何配置并构建一个 ReactiveOAuth2AuthorizedClientProvider 复合对象，该对象支持 authorization_code、refresh_token 和 client_credentials 授权类型：

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

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

	DefaultReactiveOAuth2AuthorizedClientManager authorizedClientManager =
			new 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 中的属性映射到一个 Map 中，这些属性将与 OAuth2AuthorizationContext 相关联。当你需要为 ReactiveOAuth2AuthorizedClientProvider 提供必需（或受支持）的属性时，这会非常有用。

以下代码展示了 contextAttributesMapper 的示例：

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

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

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

	// Assuming the attributes 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 param1 = request.getQueryParams().getFirst("param1");
		String param2 = request.getQueryParams().getFirst("param2");
		if (StringUtils.hasText(param1) && StringUtils.hasText(param2)) {
			contextAttributes = new HashMap<>();
			contextAttributes.put("param1", param1);
			contextAttributes.put("param2", param2);
		}
		return Mono.just(contextAttributes);
	};
}

DefaultReactiveOAuth2AuthorizedClientManager 设计用于在 ServerWebExchange 上下文内部使用。当在 ServerWebExchange 上下文外部操作时，请改用 AuthorizedClientServiceReactiveOAuth2AuthorizedClientManager。

服务应用程序是使用 AuthorizedClientServiceReactiveOAuth2AuthorizedClientManager 的常见场景。服务应用程序通常在后台运行，无需任何用户交互，并且通常在系统级账户而非用户账户下运行。配置了 client_credentials 授权类型的 OAuth 2.0 客户端可被视为一种服务应用程序。

以下代码展示了如何配置一个支持 client_credentials 授权类型的 AuthorizedClientServiceReactiveOAuth2AuthorizedClientManager 示例：

@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;
}