跳到主要内容

核心接口 / 类

QWen Max 中英对照 Core Interfaces and Classes Core Interfaces / Classes

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

        }
    }
}
java

  • 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、password，以及扩展授权类型 urn:ietf:params:oauth:grant-type:jwt-bearer。

  • redirectUri: 授权服务器 在终端用户认证并授权访问客户端后重定向终端用户的用户代理到的客户端注册的重定向 URI。

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

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

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

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

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

  • 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 响应中返回的引用终端用户名或标识符的属性名称。

一个 ClientRegistration 可以通过发现 OpenID Connect 提供者的 Configuration 端点 或授权服务器的 Metadata 端点 来进行初始配置。

ClientRegistrations 提供了方便的方法来以这种方式配置 ClientRegistration，如下例所示：

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

上述代码将依次查询 [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");
    }
}
java

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

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 授权类型：

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

当授权尝试成功时，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 的一个示例：

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

DefaultReactiveOAuth2AuthorizedClientManager 被设计为在 ServerWebExchange 的上下文中使用。在 ServerWebExchange 上下文之外操作时，请使用 AuthorizedClientServiceReactiveOAuth2AuthorizedClientManager 代替。

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

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

// 代码示例
java
@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;
}
java