跳到主要内容

QWen Max 中英对照 OAuth2 Authorization Grants #

授权许可支持

本节描述了 Spring Security 对授权许可的支持。

授权码​

备注

有关授权码授权的更多细节，请参阅 OAuth 2.0 授权框架。

获取授权​

备注

参见 授权请求/响应 协议流程以了解授权码授予。

发起授权请求​

OAuth2AuthorizationRequestRedirectFilter 使用 OAuth2AuthorizationRequestResolver 来解析 OAuth2AuthorizationRequest，并通过将终端用户的用户代理重定向到授权服务器的授权端点来启动授权码授予流程。

OAuth2AuthorizationRequestResolver 的主要作用是从提供的 Web 请求中解析出 OAuth2AuthorizationRequest。默认实现 DefaultOAuth2AuthorizationRequestResolver 会匹配（默认的）路径 /oauth2/authorization/{registrationId}，从中提取 registrationId，并使用它来构建与之关联的 ClientRegistration 的 OAuth2AuthorizationRequest。

考虑以下用于OAuth 2.0客户端注册的Spring Boot属性：

spring:
  security:
    oauth2:
      client:
        registration:
          okta:
            client-id: okta-client-id
            client-secret: okta-client-secret
            authorization-grant-type: authorization_code
            redirect-uri: "{baseUrl}/authorized/okta"
            scope: read, write
        provider:
          okta:
            authorization-uri: https://dev-1234.oktapreview.com/oauth2/v1/authorize
            token-uri: https://dev-1234.oktapreview.com/oauth2/v1/token
yaml

根据上述属性，具有基础路径 /oauth2/authorization/okta 的请求将由 OAuth2AuthorizationRequestRedirectFilter 发起授权请求重定向，并最终启动授权码授予流程。

备注

AuthorizationCodeOAuth2AuthorizedClientProvider 是 OAuth2AuthorizedClientProvider 的一个实现，用于授权码授权类型，它还会通过 OAuth2AuthorizationRequestRedirectFilter 发起授权请求重定向。

如果 OAuth 2.0 客户端是公共客户端，请按如下方式配置 OAuth 2.0 客户端注册：

spring:
  security:
    oauth2:
      client:
        registration:
          okta:
            client-id: okta-client-id
            client-authentication-method: none
            authorization-grant-type: authorization_code
            redirect-uri: "{baseUrl}/authorized/okta"
            # ...
yaml

公共客户端通过使用Proof Key for Code Exchange (PKCE) 来支持。如果客户端运行在不受信任的环境（例如本机应用程序或基于 Web 浏览器的应用程序）中，因此无法维护其凭据的机密性，则在满足以下条件时会自动使用 PKCE：

  1. client-secret 被省略（或为空）

  2. client-authentication-method 被设置为 none （ClientAuthenticationMethod.NONE）

提示

如果 OAuth 2.0 提供程序支持 Confidential Clients 的 PKCE，您可以（可选地）使用 DefaultOAuth2AuthorizationRequestResolver.setAuthorizationRequestCustomizer(OAuth2AuthorizationRequestCustomizers.withPkce()) 进行配置。

DefaultOAuth2AuthorizationRequestResolver 还通过使用 UriComponentsBuilder 支持 redirect-uri 的 URI 模板变量。

以下配置使用了所有支持的 URI 模板变量：

spring:
  security:
    oauth2:
      client:
        registration:
          okta:
            # ...
            redirect-uri: "{baseScheme}://{baseHost}{basePort}{basePath}/authorized/{registrationId}"
            # ...
yaml
备注

{baseUrl} 解析为 {baseScheme}://{baseHost}{basePort}{basePath}

使用 URI 模板变量配置 redirect-uri 在 OAuth 2.0 客户端运行在 代理服务器 后面时特别有用。这样做可以确保在扩展 redirect-uri 时使用 X-Forwarded-* 头。

自定义授权请求​

OAuth2AuthorizationRequestResolver 的主要用例之一是能够自定义授权请求，添加超出 OAuth 2.0 授权框架中定义的标准参数之外的其他参数。

例如，OpenID Connect 为 授权码流程 定义了额外的 OAuth 2.0 请求参数，这些参数扩展自 OAuth 2.0 授权框架 中定义的标准参数。其中一个扩展参数是 prompt 参数。

备注

prompt 参数是可选的。空格分隔、区分大小写的 ASCII 字符串值列表，指定授权服务器是否提示最终用户重新认证和同意。定义的值有：none、login、consent 和 select_account。

以下示例展示了如何使用 Consumer<OAuth2AuthorizationRequest.Builder> 配置 DefaultOAuth2AuthorizationRequestResolver，通过包含请求参数 prompt=consent 来自定义 oauth2Login() 的授权请求。

@Configuration
@EnableWebSecurity
public class OAuth2LoginSecurityConfig {

    @Autowired
    private ClientRegistrationRepository clientRegistrationRepository;

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authorize -> authorize
                .anyRequest().authenticated()
            )
            .oauth2Login(oauth2 -> oauth2
                .authorizationEndpoint(authorization -> authorization
                    .authorizationRequestResolver(
                        authorizationRequestResolver(this.clientRegistrationRepository)
                    )
                )
            );
        return http.build();
    }

    private OAuth2AuthorizationRequestResolver authorizationRequestResolver(
            ClientRegistrationRepository clientRegistrationRepository) {

        DefaultOAuth2AuthorizationRequestResolver authorizationRequestResolver =
                new DefaultOAuth2AuthorizationRequestResolver(
                        clientRegistrationRepository, "/oauth2/authorization");
        authorizationRequestResolver.setAuthorizationRequestCustomizer(
                authorizationRequestCustomizer());

        return  authorizationRequestResolver;
    }

    private Consumer<OAuth2AuthorizationRequest.Builder> authorizationRequestCustomizer() {
        return customizer -> customizer
                    .additionalParameters(params -> params.put("prompt", "consent"));
    }
}
java

对于简单的用例，如果特定提供者所需的额外请求参数始终相同，你可以直接在 authorization-uri 属性中添加它。

例如，如果提供商 okta 的请求参数 prompt 的值始终为 consent，你可以按如下方式配置：

spring:
  security:
    oauth2:
      client:
        provider:
          okta:
            authorization-uri: https://dev-1234.oktapreview.com/oauth2/v1/authorize?prompt=consent
yaml

前面的示例展示了在标准参数基础上添加自定义参数的常见用法。或者，如果你的需求更高级，可以通过重写 OAuth2AuthorizationRequest.authorizationRequestUri 属性来完全控制构建授权请求 URI。

提示

OAuth2AuthorizationRequest.Builder.build() 构建了 OAuth2AuthorizationRequest.authorizationRequestUri，它表示使用 application/x-www-form-urlencoded 格式的包含所有查询参数的授权请求 URI。

以下示例显示了前一个示例中 authorizationRequestCustomizer() 的一个变体，并改为覆盖 OAuth2AuthorizationRequest.authorizationRequestUri 属性：

private Consumer<OAuth2AuthorizationRequest.Builder> authorizationRequestCustomizer() {
    return customizer -> customizer
                .authorizationRequestUri(uriBuilder -> uriBuilder
                    .queryParam("prompt", "consent").build());
}
java

存储授权请求​

AuthorizationRequestRepository 负责在授权请求发起时到收到授权响应（回调）期间持久化 OAuth2AuthorizationRequest。

提示

OAuth2AuthorizationRequest 用于关联和验证授权响应。

AuthorizationRequestRepository 的默认实现是 HttpSessionOAuth2AuthorizationRequestRepository，它将 OAuth2AuthorizationRequest 存储在 HttpSession 中。

如果你有一个自定义的 AuthorizationRequestRepository 实现，你可以按如下方式进行配置：

@Configuration
@EnableWebSecurity
public class OAuth2ClientSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .oauth2Client(oauth2 -> oauth2
                .authorizationCodeGrant(codeGrant -> codeGrant
                    .authorizationRequestRepository(this.authorizationRequestRepository())
                    // ...
                )
            )
            .oauth2Login(oauth2 -> oauth2
                .authorizationEndpoint(endpoint -> endpoint
                    .authorizationRequestRepository(this.authorizationRequestRepository())
                    // ...
                )
            );
            return http.build();
    }

    @Bean
    public AuthorizationRequestRepository<OAuth2AuthorizationRequest> authorizationRequestRepository() {
        return new CustomOAuth2AuthorizationRequestRepository();
    }
}
java

请求访问令牌​

备注

参见 访问令牌请求/响应 协议流程，了解授权码许可。

有两种 OAuth2AccessTokenResponseClient 的实现，可以用来向令牌端点发送 HTTP 请求，以获取授权码许可的访问令牌：

  • DefaultAuthorizationCodeTokenResponseClient (默认)

  • RestClientAuthorizationCodeTokenResponseClient

默认实现使用 RestOperations 实例在授权服务器的令牌端点交换授权码以获取访问令牌。Spring Security 6.4 引入了一个基于 RestClient 的新实现，该实现提供了类似的功能，但与组件的响应式版本（基于 WebClient）更一致，以便为任一栈上的应用程序提供一致的配置。

备注

本节重点介绍 RestClientAuthorizationCodeTokenResponseClient。你可以在 Spring Security 6.3 文档中阅读有关 DefaultAuthorizationCodeTokenResponseClient 的内容。

要选择使用 RestClientAuthorizationCodeTokenResponseClient，只需提供一个 bean，如以下示例所示，它将被默认的 OAuth2AuthorizedClientManager 自动识别：

@Bean
public RestClientAuthorizationCodeTokenResponseClient restClientAuthorizationCodeTokenResponseClient() {
    return new RestClientAuthorizationCodeTokenResponseClient();
}
java
@Bean
public OAuth2AccessTokenResponseClient<OAuth2AuthorizationCodeGrantRequest> accessTokenResponseClient() {
    return new RestClientAuthorizationCodeTokenResponseClient();
}
java
备注

新的实现将在Spring Security 7中成为默认设置。

RestClientAuthorizationCodeTokenResponseClient 非常灵活，提供了多种选项来自定义授权码授权的 OAuth 2.0 访问令牌请求和响应。请选择以下用例以了解更多信息：

自定义访问令牌请求​

RestClientAuthorizationCodeTokenResponseClient 提供了用于自定义 OAuth 2.0 访问令牌请求的 HTTP 头和请求参数的钩子。

自定义请求头​

有两种方法可以自定义 HTTP 标头：

  • 通过调用 addHeadersConverter() 添加额外的头部

  • 通过调用 setHeadersConverter() 完全自定义头部

您可以使用 addHeadersConverter() 添加额外的标头，而不会影响添加到每个请求的默认标头。以下示例在 registrationId 为 spring 时向请求添加一个 User-Agent 标头：

RestClientAuthorizationCodeTokenResponseClient accessTokenResponseClient =
    new RestClientAuthorizationCodeTokenResponseClient();
accessTokenResponseClient.addHeadersConverter(grantRequest -> {
    ClientRegistration clientRegistration = grantRequest.getClientRegistration();
    HttpHeaders headers = new HttpHeaders();
    if (clientRegistration.getRegistrationId().equals("spring")) {
        headers.set(HttpHeaders.USER_AGENT, "my-user-agent");
    }
    return headers;
});
java

你可以通过重用 DefaultOAuth2TokenRequestHeadersConverter 或使用 setHeadersConverter() 提供自定义实现来完全自定义标头。以下示例重用了 DefaultOAuth2TokenRequestHeadersConverter 并禁用了 encodeClientCredentials，这样 HTTP Basic 凭据将不再使用 application/x-www-form-urlencoded 进行编码：

DefaultOAuth2TokenRequestHeadersConverter headersConverter =
    new DefaultOAuth2TokenRequestHeadersConverter();
headersConverter.setEncodeClientCredentials(false);

RestClientAuthorizationCodeTokenResponseClient accessTokenResponseClient =
    new RestClientAuthorizationCodeTokenResponseClient();
accessTokenResponseClient.setHeadersConverter(headersConverter);
java

自定义请求参数​

有三种自定义请求参数的选项：

  • 通过调用 addParametersConverter() 添加额外的参数

  • 通过调用 setParametersConverter() 覆写参数

  • 通过调用 setParametersCustomizer() 完全自定义参数

备注

使用 setParametersConverter() 不能完全自定义参数，因为它要求用户提供所有默认参数。默认参数总是会被提供，但可以通过调用 setParametersCustomizer() 来完全自定义或省略。

你可以使用 addParametersConverter() 添加额外的参数，而不会影响添加到每个请求中的默认参数。以下示例在 registrationId 为 keycloak 时向请求添加一个 audience 参数：

RestClientAuthorizationCodeTokenResponseClient accessTokenResponseClient =
    new RestClientAuthorizationCodeTokenResponseClient();
accessTokenResponseClient.addParametersConverter(grantRequest -> {
    ClientRegistration clientRegistration = grantRequest.getClientRegistration();
    MultiValueMap<String, String> parameters = new LinkedMultiValueMap<String, String>();
    if (clientRegistration.getRegistrationId().equals("keycloak")) {
        parameters.set(OAuth2ParameterNames.AUDIENCE, "my-audience");
    }
    return parameters;
});
java

您可以使用 setParametersConverter() 覆盖默认参数。以下示例在 registrationId 为 okta 时覆盖 client_id 参数：

RestClientAuthorizationCodeTokenResponseClient accessTokenResponseClient =
    new RestClientAuthorizationCodeTokenResponseClient();
accessTokenResponseClient.setParametersConverter(grantRequest -> {
    ClientRegistration clientRegistration = grantRequest.getClientRegistration();
    LinkedMultiValueMap<String, String> parameters = new LinkedMultiValueMap<>();
    if (clientRegistration.getRegistrationId().equals("okta")) {
        parameters.set(OAuth2ParameterNames.CLIENT_ID, "my-client");
    }
    return parameters;
});
java

您可以使用 setParametersCustomizer() 完全自定义参数（包括省略默认参数）。以下示例在请求中存在 client_assertion 参数时省略 client_id 参数：

RestClientAuthorizationCodeTokenResponseClient accessTokenResponseClient =
    new RestClientAuthorizationCodeTokenResponseClient();
accessTokenResponseClient.setParametersCustomizer(parameters -> {
    if (parameters.containsKey(OAuth2ParameterNames.CLIENT_ASSERTION)) {
        parameters.remove(OAuth2ParameterNames.CLIENT_ID);
    }
});
java

自定义访问令牌响应​

RestClientAuthorizationCodeTokenResponseClient 提供了用于自定义 OAuth 2.0 访问令牌响应的参数和错误处理的钩子。

自定义 WebClient​

你可以通过向 setRestClient() 提供一个预配置的 RestClient 来自定义令牌响应。默认的 RestClient 配置如下：

RestClient restClient = RestClient.builder()
    .messageConverters(messageConverters -> {
        messageConverters.clear();
        messageConverters.add(new FormHttpMessageConverter());
        messageConverters.add(new OAuth2AccessTokenResponseHttpMessageConverter());
    })
    .defaultStatusHandler(new OAuth2ErrorResponseErrorHandler())
    .build();

RestClientAuthorizationCodeTokenResponseClient accessTokenResponseClient =
    new RestClientAuthorizationCodeTokenResponseClient();
accessTokenResponseClient.setRestClient(restClient);
java

OAuth2AccessTokenResponseHttpMessageConverter 是一个用于 OAuth 2.0 访问令牌响应的 HttpMessageConverter。您可以通过调用 setAccessTokenResponseConverter() 来自定义将令牌响应参数转换为 OAuth2AccessTokenResponse 的过程。默认实现是 DefaultMapOAuth2AccessTokenResponseConverter。

OAuth2ErrorResponseErrorHandler 是一个 ResponseErrorHandler，可以处理 OAuth 2.0 错误，例如 400 Bad Request。它使用 OAuth2ErrorHttpMessageConverter 将 OAuth 2.0 错误参数转换为 OAuth2Error。您可以通过调用 setErrorConverter() 来自定义将 Token 响应参数转换为 OAuth2Error 的过程。

提示

Spring MVC FormHttpMessageConverter 是必需的，因为它在发送 OAuth 2.0 访问令牌请求时会被用到。

自定义响应参数​

以下示例提供了一个自定义 Token 响应参数转换为 OAuth2AccessTokenResponse 的起点：

OAuth2AccessTokenResponseHttpMessageConverter accessTokenResponseMessageConverter =
    new OAuth2AccessTokenResponseHttpMessageConverter();
accessTokenResponseMessageConverter.setAccessTokenResponseConverter(parameters -> {
    // ...
    return OAuth2AccessTokenResponse.withToken("custom-token")
        // ...
        .build();
});
java

自定义错误处理​

以下示例提供了一个自定义将 Error 参数转换为 OAuth2Error 的起点：

OAuth2ErrorHttpMessageConverter errorConverter =
    new OAuth2ErrorHttpMessageConverter();
errorConverter.setErrorConverter(parameters -> {
    // ...
    return new OAuth2Error("custom-error", "custom description", "custom-uri");
});

OAuth2ErrorResponseErrorHandler errorHandler =
    new OAuth2ErrorResponseErrorHandler();
errorHandler.setErrorConverter(errorConverter);
java

使用DSL进行自定义​

无论你是自定义 RestClientAuthorizationCodeTokenResponseClient 还是提供自己的 OAuth2AccessTokenResponseClient 实现，你都可以使用 DSL 进行配置（作为发布一个 bean 的替代方案），如下所示：

@Configuration
@EnableWebSecurity
public class OAuth2ClientSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .oauth2Client(oauth2 -> oauth2
                .authorizationCodeGrant(codeGrant -> codeGrant
                    .accessTokenResponseClient(this.accessTokenResponseClient())
                    // ...
                )
            );
        return http.build();
    }
}
java

刷新令牌​

备注

有关Refresh Token的更多详情，请参阅OAuth 2.0授权框架。

刷新访问令牌​

备注

参见 访问令牌请求/响应 协议流程以了解刷新令牌授权。

有两种 OAuth2AccessTokenResponseClient 的实现可以用于向令牌端点发送 HTTP 请求，以便为刷新令牌授权获取访问令牌：

  • DefaultRefreshTokenTokenResponseClient (默认)

  • RestClientRefreshTokenTokenResponseClient

默认实现使用 RestOperations 实例在授权服务器的令牌端点交换授权码以获取访问令牌。Spring Security 6.4 引入了一个基于 RestClient 的新实现，该实现提供了类似的功能，但与组件的响应式版本（基于 WebClient）更一致，以便为任一栈上的应用程序提供一致的配置。

备注

本节重点关注 RestClientRefreshTokenTokenResponseClient。您可以在 Spring Security 6.3 文档中阅读有关 DefaultRefreshTokenTokenResponseClient 的内容。

要选择使用 RestClientRefreshTokenTokenResponseClient，只需提供一个 bean，如以下示例所示，它将被默认的 OAuth2AuthorizedClientManager 自动识别：

@Bean
public RestClientRefreshTokenTokenResponseClient restClientRefreshTokenTokenResponseClient() {
    return new RestClientRefreshTokenTokenResponseClient();
}
java
@Bean
public OAuth2AccessTokenResponseClient<OAuth2RefreshTokenGrantRequest> accessTokenResponseClient() {
    return new RestClientRefreshTokenTokenResponseClient();
}
java
备注

新的实现将在 Spring Security 7 中成为默认设置。

RestClientRefreshTokenTokenResponseClient 非常灵活，提供了多种选项来自定义用于刷新令牌授权的 OAuth 2.0 访问令牌请求和响应。请选择以下用例以了解更多信息：

自定义访问令牌请求​

RestClientRefreshTokenTokenResponseClient 提供了用于自定义 OAuth 2.0 访问令牌请求的 HTTP 头和请求参数的钩子。

自定义请求头​

有两种方法可以自定义 HTTP 标头：

  • 通过调用 addHeadersConverter() 添加额外的头部

  • 通过调用 setHeadersConverter() 完全自定义头部

你可以使用 addHeadersConverter() 包含额外的标头，而不会影响添加到每个请求的默认标头。以下示例在 registrationId 为 spring 时向请求添加一个 User-Agent 标头：

RestClientRefreshTokenTokenResponseClient accessTokenResponseClient =
    new RestClientRefreshTokenTokenResponseClient();
accessTokenResponseClient.addHeadersConverter(grantRequest -> {
    ClientRegistration clientRegistration = grantRequest.getClientRegistration();
    HttpHeaders headers = new HttpHeaders();
    if (clientRegistration.getRegistrationId().equals("spring")) {
        headers.set(HttpHeaders.USER_AGENT, "my-user-agent");
    }
    return headers;
});
java

您可以完全自定义标头，方法是重用 DefaultOAuth2TokenRequestHeadersConverter 或使用 setHeadersConverter() 提供自定义实现。以下示例重用了 DefaultOAuth2TokenRequestHeadersConverter 并禁用了 encodeClientCredentials，以便 HTTP Basic 凭证不再使用 application/x-www-form-urlencoded 进行编码：

DefaultOAuth2TokenRequestHeadersConverter headersConverter =
    new DefaultOAuth2TokenRequestHeadersConverter();
headersConverter.setEncodeClientCredentials(false);

RestClientRefreshTokenTokenResponseClient accessTokenResponseClient =
    new RestClientRefreshTokenTokenResponseClient();
accessTokenResponseClient.setHeadersConverter(headersConverter);
java

自定义请求参数​

有三种自定义请求参数的选项：

  • 通过调用 addParametersConverter() 添加额外的参数

  • 通过调用 setParametersConverter() 覆盖参数

  • 通过调用 setParametersCustomizer() 完全自定义参数

备注

使用 setParametersConverter() 不能完全自定义参数，因为它要求用户提供所有默认参数。默认参数总是会被提供，但可以通过调用 setParametersCustomizer() 来完全自定义或省略。

您可以使用 addParametersConverter() 添加额外的参数，而不会影响添加到每个请求的默认参数。以下示例在 registrationId 为 keycloak 时向请求添加一个 audience 参数：

RestClientRefreshTokenTokenResponseClient accessTokenResponseClient =
    new RestClientRefreshTokenTokenResponseClient();
accessTokenResponseClient.addParametersConverter(grantRequest -> {
    ClientRegistration clientRegistration = grantRequest.getClientRegistration();
    MultiValueMap<String, String> parameters = new LinkedMultiValueMap<String, String>();
    if (clientRegistration.getRegistrationId().equals("keycloak")) {
        parameters.set(OAuth2ParameterNames.AUDIENCE, "my-audience");
    }
    return parameters;
});
java

你可以使用 setParametersConverter() 覆盖默认参数。以下示例在 registrationId 为 okta 时覆盖 client_id 参数：

RestClientRefreshTokenTokenResponseClient accessTokenResponseClient =
    new RestClientRefreshTokenTokenResponseClient();
accessTokenResponseClient.setParametersConverter(grantRequest -> {
    ClientRegistration clientRegistration = grantRequest.getClientRegistration();
    LinkedMultiValueMap<String, String> parameters = new LinkedMultiValueMap<>();
    if (clientRegistration.getRegistrationId().equals("okta")) {
        parameters.set(OAuth2ParameterNames.CLIENT_ID, "my-client");
    }
    return parameters;
});
java

您可以使用 setParametersCustomizer() 完全自定义参数（包括省略默认参数）。以下示例在请求中存在 client_assertion 参数时省略 client_id 参数：

RestClientRefreshTokenTokenResponseClient accessTokenResponseClient =
    new RestClientRefreshTokenTokenResponseClient();
accessTokenResponseClient.setParametersCustomizer(parameters -> {
    if (parameters.containsKey(OAuth2ParameterNames.CLIENT_ASSERTION)) {
        parameters.remove(OAuth2ParameterNames.CLIENT_ID);
    }
});
java

自定义访问令牌响应​

RestClientRefreshTokenTokenResponseClient 提供了用于自定义 OAuth 2.0 访问令牌响应的参数和错误处理的钩子。

自定义 WebClient​

你可以通过向 setRestClient() 提供一个预配置的 RestClient 来自定义令牌响应。默认的 RestClient 配置如下：

RestClient restClient = RestClient.builder()
    .messageConverters(messageConverters -> {
        messageConverters.clear();
        messageConverters.add(new FormHttpMessageConverter());
        messageConverters.add(new OAuth2AccessTokenResponseHttpMessageConverter());
    })
    .defaultStatusHandler(new OAuth2ErrorResponseErrorHandler())
    .build();

RestClientRefreshTokenTokenResponseClient accessTokenResponseClient =
    new RestClientRefreshTokenTokenResponseClient();
accessTokenResponseClient.setRestClient(restClient);
java

OAuth2AccessTokenResponseHttpMessageConverter 是一个用于 OAuth 2.0 访问令牌响应的 HttpMessageConverter。你可以通过调用 setAccessTokenResponseConverter() 来自定义将令牌响应参数转换为 OAuth2AccessTokenResponse 的过程。默认实现是 DefaultMapOAuth2AccessTokenResponseConverter。

OAuth2ErrorResponseErrorHandler 是一个 ResponseErrorHandler，可以处理 OAuth 2.0 错误，例如 400 Bad Request。它使用 OAuth2ErrorHttpMessageConverter 将 OAuth 2.0 错误参数转换为 OAuth2Error。您可以通过调用 setErrorConverter() 来自定义将 Token 响应参数转换为 OAuth2Error 的过程。

提示

Spring MVC FormHttpMessageConverter 是必需的，因为它在发送 OAuth 2.0 访问令牌请求时会被使用。

自定义响应参数​

以下示例提供了一个自定义 Token 响应参数转换为 OAuth2AccessTokenResponse 的起点：

OAuth2AccessTokenResponseHttpMessageConverter accessTokenResponseMessageConverter =
    new OAuth2AccessTokenResponseHttpMessageConverter();
accessTokenResponseMessageConverter.setAccessTokenResponseConverter(parameters -> {
    // ...
    return OAuth2AccessTokenResponse.withToken("custom-token")
        // ...
        .build();
});
java

自定义错误处理​

以下示例提供了一个自定义将 Error 参数转换为 OAuth2Error 的起点：

OAuth2ErrorHttpMessageConverter errorConverter =
    new OAuth2ErrorHttpMessageConverter();
errorConverter.setErrorConverter(parameters -> {
    // ...
    return new OAuth2Error("custom-error", "custom description", "custom-uri");
});

OAuth2ErrorResponseErrorHandler errorHandler =
    new OAuth2ErrorResponseErrorHandler();
errorHandler.setErrorConverter(errorConverter);
java

使用 Builder 进行自定义​

无论你是自定义 RestClientRefreshTokenTokenResponseClient 还是提供自己的 OAuth2AccessTokenResponseClient 实现，都可以使用 OAuth2AuthorizedClientProviderBuilder 来配置它（作为发布一个 bean 的替代方案），如下所示：

// Customize
OAuth2AccessTokenResponseClient<OAuth2RefreshTokenGrantRequest> refreshTokenTokenResponseClient = ...

OAuth2AuthorizedClientProvider authorizedClientProvider =
        OAuth2AuthorizedClientProviderBuilder.builder()
                .authorizationCode()
                .refreshToken(configurer -> configurer.accessTokenResponseClient(refreshTokenTokenResponseClient))
                .build();

// ...

authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider);
java
备注

OAuth2AuthorizedClientProviderBuilder.builder().refreshToken() 配置了一个 RefreshTokenOAuth2AuthorizedClientProvider，这是用于刷新令牌授权的 OAuth2AuthorizedClientProvider 的一个实现。

OAuth2RefreshToken 可以选择性地在 authorization_code 和 password 授权类型的访问令牌响应中返回。如果 OAuth2AuthorizedClient.getRefreshToken() 可用且 OAuth2AuthorizedClient.getAccessToken() 已过期，它将由 RefreshTokenOAuth2AuthorizedClientProvider 自动刷新。

Client Credentials​

备注

有关客户端凭证授权的更多详情，请参阅 OAuth 2.0 授权框架。

请求访问令牌​

备注

参见 访问令牌请求/响应 协议流程，了解客户端凭据授权。

有两种 OAuth2AccessTokenResponseClient 的实现可以用于向令牌端点发送 HTTP 请求，以便为客户端凭据授权获取访问令牌：

  • DefaultClientCredentialsTokenResponseClient (默认)

  • RestClientClientCredentialsTokenResponseClient

默认实现使用 RestOperations 实例在授权服务器的令牌端点交换授权代码以获取访问令牌。Spring Security 6.4 引入了一个基于 RestClient 的新实现，该实现提供了类似的功能，但与组件的响应式版本（基于 WebClient）更一致，以便为任一栈上的应用程序提供一致的配置。

备注

本节重点关注 RestClientClientCredentialsTokenResponseClient。你可以在 Spring Security 6.3 文档中阅读有关 DefaultClientCredentialsTokenResponseClient 的内容。

要选择使用 RestClientClientCredentialsTokenResponseClient，只需提供一个 bean，如以下示例所示，它将被默认的 OAuth2AuthorizedClientManager 自动识别：

@Bean
public ClientCredentialsTokenResponseClient clientCredentialsTokenResponseClient() {
    return new RestClientClientCredentialsTokenResponseClient();
}
java
@Bean
public OAuth2AccessTokenResponseClient<OAuth2ClientCredentialsGrantRequest> accessTokenResponseClient() {
    return new RestClientClientCredentialsTokenResponseClient();
}
java
备注

新的实现将在 Spring Security 7 中成为默认设置。

RestClientClientCredentialsTokenResponseClient 非常灵活，提供了多种选项来自定义客户端凭证授权的 OAuth 2.0 访问令牌请求和响应。请选择以下用例以了解更多信息：

自定义访问令牌请求​

RestClientClientCredentialsTokenResponseClient 提供了用于自定义 OAuth 2.0 访问令牌请求的 HTTP 头和请求参数的钩子。

自定义请求头​

有两种方法可以自定义 HTTP 标头：

  • 通过调用 addHeadersConverter() 添加额外的头部

  • 通过调用 setHeadersConverter() 完全自定义头部

您可以使用 addHeadersConverter() 添加额外的头部信息，而不会影响添加到每个请求的默认头部信息。以下示例在 registrationId 为 spring 时向请求添加一个 User-Agent 头部：

RestClientClientCredentialsTokenResponseClient accessTokenResponseClient =
    new RestClientClientCredentialsTokenResponseClient();
accessTokenResponseClient.addHeadersConverter(grantRequest -> {
    ClientRegistration clientRegistration = grantRequest.getClientRegistration();
    HttpHeaders headers = new HttpHeaders();
    if (clientRegistration.getRegistrationId().equals("spring")) {
        headers.set(HttpHeaders.USER_AGENT, "my-user-agent");
    }
    return headers;
});
java

您可以完全自定义标头，方法是重用 DefaultOAuth2TokenRequestHeadersConverter 或使用 setHeadersConverter() 提供自定义实现。以下示例重用了 DefaultOAuth2TokenRequestHeadersConverter 并禁用了 encodeClientCredentials，以便 HTTP Basic 凭据不再使用 application/x-www-form-urlencoded 进行编码：

DefaultOAuth2TokenRequestHeadersConverter headersConverter =
    new DefaultOAuth2TokenRequestHeadersConverter();
headersConverter.setEncodeClientCredentials(false);

RestClientClientCredentialsTokenResponseClient accessTokenResponseClient =
    new RestClientClientCredentialsTokenResponseClient();
accessTokenResponseClient.setHeadersConverter(headersConverter);
java

自定义请求参数​

有三种自定义请求参数的选项：

  • 通过调用 addParametersConverter() 添加额外的参数

  • 通过调用 setParametersConverter() 覆盖参数

  • 通过调用 setParametersCustomizer() 完全自定义参数

备注

使用 setParametersConverter() 不能完全自定义参数，因为它要求用户提供所有默认参数。默认参数总是会被提供，但可以通过调用 setParametersCustomizer() 来完全自定义或省略。

您可以使用 addParametersConverter() 添加额外的参数，而不会影响添加到每个请求的默认参数。以下示例在 registrationId 为 keycloak 时向请求添加一个 audience 参数：

RestClientClientCredentialsTokenResponseClient accessTokenResponseClient =
    new RestClientClientCredentialsTokenResponseClient();
accessTokenResponseClient.addParametersConverter(grantRequest -> {
    ClientRegistration clientRegistration = grantRequest.getClientRegistration();
    MultiValueMap<String, String> parameters = new LinkedMultiValueMap<String, String>();
    if (clientRegistration.getRegistrationId().equals("keycloak")) {
        parameters.set(OAuth2ParameterNames.AUDIENCE, "my-audience");
    }
    return parameters;
});
java

你可以使用 setParametersConverter() 覆盖默认参数。以下示例在 registrationId 为 okta 时覆盖 client_id 参数：

RestClientClientCredentialsTokenResponseClient accessTokenResponseClient =
    new RestClientClientCredentialsTokenResponseClient();
accessTokenResponseClient.setParametersConverter(grantRequest -> {
    ClientRegistration clientRegistration = grantRequest.getClientRegistration();
    LinkedMultiValueMap<String, String> parameters = new LinkedMultiValueMap<>();
    if (clientRegistration.getRegistrationId().equals("okta")) {
        parameters.set(OAuth2ParameterNames.CLIENT_ID, "my-client");
    }
    return parameters;
});
java

您可以使用 setParametersCustomizer() 完全自定义参数（包括省略默认参数）。以下示例在请求中存在 client_assertion 参数时省略 client_id 参数：

RestClientClientCredentialsTokenResponseClient accessTokenResponseClient =
    new RestClientClientCredentialsTokenResponseClient();
accessTokenResponseClient.setParametersCustomizer(parameters -> {
    if (parameters.containsKey(OAuth2ParameterNames.CLIENT_ASSERTION)) {
        parameters.remove(OAuth2ParameterNames.CLIENT_ID);
    }
});
java

自定义访问令牌响应​

RestClientClientCredentialsTokenResponseClient 提供了用于自定义 OAuth 2.0 访问令牌响应的参数和错误处理的钩子。

自定义 WebClient​

你可以通过向 setRestClient() 提供一个预配置的 RestClient 来自定义 Token 响应。默认的 RestClient 配置如下：

RestClient restClient = RestClient.builder()
    .messageConverters(messageConverters -> {
        messageConverters.clear();
        messageConverters.add(new FormHttpMessageConverter());
        messageConverters.add(new OAuth2AccessTokenResponseHttpMessageConverter());
    })
    .defaultStatusHandler(new OAuth2ErrorResponseErrorHandler())
    .build();

RestClientClientCredentialsTokenResponseClient accessTokenResponseClient =
    new RestClientClientCredentialsTokenResponseClient();
accessTokenResponseClient.setRestClient(restClient);
java

OAuth2AccessTokenResponseHttpMessageConverter 是一个用于 OAuth 2.0 访问令牌响应的 HttpMessageConverter。你可以通过调用 setAccessTokenResponseConverter() 来自定义令牌响应参数到 OAuth2AccessTokenResponse 的转换。默认实现是 DefaultMapOAuth2AccessTokenResponseConverter。

OAuth2ErrorResponseErrorHandler 是一个 ResponseErrorHandler，可以处理 OAuth 2.0 错误，例如 400 Bad Request。它使用 OAuth2ErrorHttpMessageConverter 将 OAuth 2.0 错误参数转换为 OAuth2Error。你可以通过调用 setErrorConverter() 来自定义将 Token 响应参数转换为 OAuth2Error 的过程。

提示

Spring MVC FormHttpMessageConverter 是必需的，因为它在发送 OAuth 2.0 访问令牌请求时会被使用。

自定义响应参数​

以下示例提供了一个自定义 Token 响应参数转换为 OAuth2AccessTokenResponse 的起点：

OAuth2AccessTokenResponseHttpMessageConverter accessTokenResponseMessageConverter =
    new OAuth2AccessTokenResponseHttpMessageConverter();
accessTokenResponseMessageConverter.setAccessTokenResponseConverter(parameters -> {
    // ...
    return OAuth2AccessTokenResponse.withToken("custom-token")
        // ...
        .build();
});
java

自定义错误处理​

以下示例为自定义将 Error 参数转换为 OAuth2Error 提供了一个起点：

OAuth2ErrorHttpMessageConverter errorConverter =
    new OAuth2ErrorHttpMessageConverter();
errorConverter.setErrorConverter(parameters -> {
    // ...
    return new OAuth2Error("custom-error", "custom description", "custom-uri");
});

OAuth2ErrorResponseErrorHandler errorHandler =
    new OAuth2ErrorResponseErrorHandler();
errorHandler.setErrorConverter(errorConverter);
java

使用 Builder 进行自定义​

无论你是自定义 RestClientClientCredentialsTokenResponseClient 还是提供自己的 OAuth2AccessTokenResponseClient 实现，你都可以使用 OAuth2AuthorizedClientProviderBuilder 来配置它（作为发布一个 bean 的替代方案），如下所示：

// Customize
OAuth2AccessTokenResponseClient<OAuth2ClientCredentialsGrantRequest> clientCredentialsTokenResponseClient = ...

OAuth2AuthorizedClientProvider authorizedClientProvider =
        OAuth2AuthorizedClientProviderBuilder.builder()
                .clientCredentials(configurer -> configurer.accessTokenResponseClient(clientCredentialsTokenResponseClient))
                .build();

// ...

authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider);
java
备注

OAuth2AuthorizedClientProviderBuilder.builder().clientCredentials() 配置了一个 ClientCredentialsOAuth2AuthorizedClientProvider，这是针对客户端凭证授权类型的 OAuth2AuthorizedClientProvider 的一个实现。

使用访问令牌​

请考虑以下用于OAuth 2.0客户端注册的Spring Boot属性：

spring:
  security:
    oauth2:
      client:
        registration:
          okta:
            client-id: okta-client-id
            client-secret: okta-client-secret
            authorization-grant-type: client_credentials
            scope: read, write
        provider:
          okta:
            token-uri: https://dev-1234.oktapreview.com/oauth2/v1/token
yaml

进一步考虑以下 OAuth2AuthorizedClientManager @Bean：

@Bean
public OAuth2AuthorizedClientManager authorizedClientManager(
        ClientRegistrationRepository clientRegistrationRepository,
        OAuth2AuthorizedClientRepository authorizedClientRepository) {

    OAuth2AuthorizedClientProvider authorizedClientProvider =
            OAuth2AuthorizedClientProviderBuilder.builder()
                    .clientCredentials()
                    .build();

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

    return authorizedClientManager;
}
java

根据前面的属性和 bean，你可以按如下方式获取 OAuth2AccessToken：

@Controller
public class OAuth2ClientController {

    @Autowired
    private OAuth2AuthorizedClientManager authorizedClientManager;

    @GetMapping("/")
    public String index(Authentication authentication,
                        HttpServletRequest servletRequest,
                        HttpServletResponse servletResponse) {

        OAuth2AuthorizeRequest authorizeRequest = OAuth2AuthorizeRequest.withClientRegistrationId("okta")
                .principal(authentication)
                .attributes(attrs -> {
                    attrs.put(HttpServletRequest.class.getName(), servletRequest);
                    attrs.put(HttpServletResponse.class.getName(), servletResponse);
                })
                .build();
        OAuth2AuthorizedClient authorizedClient = this.authorizedClientManager.authorize(authorizeRequest);

        OAuth2AccessToken accessToken = authorizedClient.getAccessToken();

        // ...

        return "index";
    }
}
java
备注

HttpServletRequest 和 HttpServletResponse 都是可选的属性。如果未提供，它们将默认使用 RequestContextHolder.getRequestAttributes() 的 ServletRequestAttributes。

资源所有者密码凭证​

备注

有关资源所有者密码凭证授权的更多详细信息，请参阅 OAuth 2.0 授权框架。

请求访问令牌​

备注

参见 访问令牌请求/响应 协议流程，了解 Resource Owner Password Credentials 授权。

OAuth2AccessTokenResponseClient 的默认实现是 DefaultPasswordTokenResponseClient，它在授权服务器的令牌端点请求访问令牌时使用 RestOperations。

警告

DefaultPasswordTokenResponseClient 类和对 Resource Owner Password Credentials 授权的支持已被弃用。此部分将在 Spring Security 7 中被移除。

DefaultPasswordTokenResponseClient 是灵活的，因为它允许你自定义 Token 请求的预处理或 Token 响应的后处理。

自定义访问令牌请求​

如果你需要自定义 Token 请求的预处理，可以为 DefaultPasswordTokenResponseClient.setRequestEntityConverter() 提供一个自定义的 Converter<OAuth2PasswordGrantRequest, RequestEntity<?>>。默认实现（OAuth2PasswordGrantRequestEntityConverter）构建了一个标准 OAuth 2.0 访问令牌请求 的 RequestEntity 表示。但是，提供一个自定义的 Converter 可以让你扩展标准的 Token 请求并添加自定义参数。

要仅自定义请求的参数，你可以提供 OAuth2PasswordGrantRequestEntityConverter.setParametersConverter() 一个自定义的 Converter<OAuth2PasswordGrantRequest, MultiValueMap<String, String>>，以完全覆盖请求中发送的参数。这通常比直接构造 RequestEntity 更简单。

提示

如果你只希望添加额外的参数，可以向 OAuth2PasswordGrantRequestEntityConverter.addParametersConverter() 提供一个自定义的 Converter<OAuth2PasswordGrantRequest, MultiValueMap<String, String>>，以构建一个聚合的 Converter。

important

自定义的 Converter 必须返回一个有效的 RequestEntity，该 RequestEntity 是 OAuth 2.0 提供者能够理解的 OAuth 2.0 访问令牌请求的表示形式。

自定义访问令牌响应​

在另一方面，如果你需要自定义 Token 响应的后处理，你需要为 DefaultPasswordTokenResponseClient.setRestOperations() 提供一个自定义配置的 RestOperations。默认的 RestOperations 配置如下：

RestTemplate restTemplate = new RestTemplate(Arrays.asList(
        new FormHttpMessageConverter(),
        new OAuth2AccessTokenResponseHttpMessageConverter()));

restTemplate.setErrorHandler(new OAuth2ErrorResponseErrorHandler());
java
提示

Spring MVC FormHttpMessageConverter 是必需的，因为它在发送 OAuth 2.0 访问令牌请求时会被用到。

OAuth2AccessTokenResponseHttpMessageConverter 是一个用于 OAuth 2.0 访问令牌响应的 HttpMessageConverter。你可以通过 OAuth2AccessTokenResponseHttpMessageConverter.setTokenResponseConverter() 提供一个自定义的 Converter<Map<String, String>, OAuth2AccessTokenResponse>，用于将 OAuth 2.0 访问令牌响应参数转换为 OAuth2AccessTokenResponse。

OAuth2ErrorResponseErrorHandler 是一个 ResponseErrorHandler，可以处理 OAuth 2.0 错误，例如 400 Bad Request。它使用 OAuth2ErrorHttpMessageConverter 将 OAuth 2.0 错误参数转换为 OAuth2Error。

使用构建器进行自定义​

无论你是自定义 DefaultPasswordTokenResponseClient 还是提供自己的 OAuth2AccessTokenResponseClient 实现，都需要按如下方式配置：

// Customize
OAuth2AccessTokenResponseClient<OAuth2PasswordGrantRequest> passwordTokenResponseClient = ...

OAuth2AuthorizedClientProvider authorizedClientProvider =
        OAuth2AuthorizedClientProviderBuilder.builder()
                .password(configurer -> configurer.accessTokenResponseClient(passwordTokenResponseClient))
                .refreshToken()
                .build();

// ...

authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider);
java
备注

OAuth2AuthorizedClientProviderBuilder.builder().password() 配置了一个 PasswordOAuth2AuthorizedClientProvider，它是用于资源所有者密码凭证授权类型的 OAuth2AuthorizedClientProvider 的一个实现。

使用访问令牌​

考虑以下用于OAuth 2.0客户端注册的Spring Boot属性：

spring:
  security:
    oauth2:
      client:
        registration:
          okta:
            client-id: okta-client-id
            client-secret: okta-client-secret
            authorization-grant-type: password
            scope: read, write
        provider:
          okta:
            token-uri: https://dev-1234.oktapreview.com/oauth2/v1/token
yaml

进一步考虑 OAuth2AuthorizedClientManager @Bean：

@Bean
public OAuth2AuthorizedClientManager authorizedClientManager(
        ClientRegistrationRepository clientRegistrationRepository,
        OAuth2AuthorizedClientRepository authorizedClientRepository) {

    OAuth2AuthorizedClientProvider authorizedClientProvider =
            OAuth2AuthorizedClientProviderBuilder.builder()
                    .password()
                    .refreshToken()
                    .build();

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

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

    return authorizedClientManager;
}

private Function<OAuth2AuthorizeRequest, Map<String, Object>> contextAttributesMapper() {
    return authorizeRequest -> {
        Map<String, Object> contextAttributes = Collections.emptyMap();
        HttpServletRequest servletRequest = authorizeRequest.getAttribute(HttpServletRequest.class.getName());
        String username = servletRequest.getParameter(OAuth2ParameterNames.USERNAME);
        String password = servletRequest.getParameter(OAuth2ParameterNames.PASSWORD);
        if (StringUtils.hasText(username) && StringUtils.hasText(password)) {
            contextAttributes = new HashMap<>();

            // `PasswordOAuth2AuthorizedClientProvider` requires both attributes
            contextAttributes.put(OAuth2AuthorizationContext.USERNAME_ATTRIBUTE_NAME, username);
            contextAttributes.put(OAuth2AuthorizationContext.PASSWORD_ATTRIBUTE_NAME, password);
        }
        return contextAttributes;
    };
}
java

给定上述属性和bean，你可以按如下方式获取 OAuth2AccessToken：

@Controller
public class OAuth2ClientController {

    @Autowired
    private OAuth2AuthorizedClientManager authorizedClientManager;

    @GetMapping("/")
    public String index(Authentication authentication,
                        HttpServletRequest servletRequest,
                        HttpServletResponse servletResponse) {

        OAuth2AuthorizeRequest authorizeRequest = OAuth2AuthorizeRequest.withClientRegistrationId("okta")
                .principal(authentication)
                .attributes(attrs -> {
                    attrs.put(HttpServletRequest.class.getName(), servletRequest);
                    attrs.put(HttpServletResponse.class.getName(), servletResponse);
                })
                .build();
        OAuth2AuthorizedClient authorizedClient = this.authorizedClientManager.authorize(authorizeRequest);

        OAuth2AccessToken accessToken = authorizedClient.getAccessToken();

        // ...

        return "index";
    }
}
java
备注

HttpServletRequest 和 HttpServletResponse 都是可选的属性。如果未提供，它们将默认使用 RequestContextHolder.getRequestAttributes() 的 ServletRequestAttributes。

JWT Bearer​

备注

请参阅适用于 OAuth 2.0 客户端身份验证和授权许可的 JSON Web Token (JWT) 规范，以获取有关 JWT Bearer 许可的更多详细信息。

请求访问令牌​

备注

请参考 访问令牌请求/响应 协议流程，了解 JWT 持有者授权。

有两种 OAuth2AccessTokenResponseClient 的实现可以用来向令牌端点发送 HTTP 请求，以便为 JWT Bearer 授权获取访问令牌：

  • DefaultJwtBearerTokenResponseClient (默认)

  • RestClientJwtBearerTokenResponseClient

默认实现使用 RestOperations 实例在授权服务器的令牌端点交换授权码以获取访问令牌。Spring Security 6.4 引入了一个基于 RestClient 的新实现，它提供了类似的功能，但与组件的响应式版本（基于 WebClient）更一致，以便为两种技术栈上的应用程序提供一致的配置。

备注

本节重点关注 RestClientJwtBearerTokenResponseClient。您可以在 Spring Security 6.3 文档中阅读有关 DefaultClientCredentialsTokenResponseClient 的内容。

要选择使用 RestClientJwtBearerTokenResponseClient，只需提供一个 bean，如以下示例所示，它将被默认的 OAuth2AuthorizedClientManager 自动识别：

@Bean
public RestClientJwtBearerTokenResponseClient jwtBearerTokenResponseClient() {
    return new RestClientJwtBearerTokenResponseClient();
}
java
@Bean
public OAuth2AccessTokenResponseClient<JwtBearerGrantRequest> accessTokenResponseClient() {
    return new RestClientJwtBearerTokenResponseClient();
}
java
备注

新的实现将在Spring Security 7中成为默认设置。

RestClientJwtBearerTokenResponseClient 非常灵活，并提供了多种选项来自定义 JWT Bearer 授权的 OAuth 2.0 访问令牌请求和响应。请选择以下用例以了解更多信息：

自定义访问令牌请求​

RestClientJwtBearerTokenResponseClient 提供了用于自定义 OAuth 2.0 访问令牌请求的 HTTP 头和请求参数的钩子。

自定义请求头​

有两种方法可以自定义 HTTP 标头：

  • 通过调用 addHeadersConverter() 添加额外的头部

  • 通过调用 setHeadersConverter() 完全自定义头部

你可以使用 addHeadersConverter() 包含额外的标头，而不会影响添加到每个请求的默认标头。以下示例在 registrationId 为 spring 时向请求添加一个 User-Agent 标头：

RestClientJwtBearerTokenResponseClient accessTokenResponseClient =
    new RestClientJwtBearerTokenResponseClient();
accessTokenResponseClient.addHeadersConverter(grantRequest -> {
    ClientRegistration clientRegistration = grantRequest.getClientRegistration();
    HttpHeaders headers = new HttpHeaders();
    if (clientRegistration.getRegistrationId().equals("spring")) {
        headers.set(HttpHeaders.USER_AGENT, "my-user-agent");
    }
    return headers;
});
java

你可以通过重用 DefaultOAuth2TokenRequestHeadersConverter 或使用 setHeadersConverter() 提供自定义实现来完全自定义标头。以下示例重用了 DefaultOAuth2TokenRequestHeadersConverter 并禁用了 encodeClientCredentials，以便 HTTP Basic 凭证不再使用 application/x-www-form-urlencoded 进行编码：

DefaultOAuth2TokenRequestHeadersConverter headersConverter =
    new DefaultOAuth2TokenRequestHeadersConverter();
headersConverter.setEncodeClientCredentials(false);

RestClientJwtBearerTokenResponseClient accessTokenResponseClient =
    new RestClientJwtBearerTokenResponseClient();
accessTokenResponseClient.setHeadersConverter(headersConverter);
java

自定义请求参数​

有三种自定义请求参数的选项：

  • 通过调用 addParametersConverter() 添加额外的参数

  • 通过调用 setParametersConverter() 覆盖参数

  • 通过调用 setParametersCustomizer() 完全自定义参数

备注

使用 setParametersConverter() 不能完全自定义参数，因为它要求用户提供所有默认参数。默认参数总是会被提供，但可以通过调用 setParametersCustomizer() 来完全自定义或省略。

你可以使用 addParametersConverter() 添加额外的参数，而不会影响每个请求中添加的默认参数。下面的示例在 registrationId 为 keycloak 时向请求添加一个 audience 参数：

RestClientJwtBearerTokenResponseClient accessTokenResponseClient =
    new RestClientJwtBearerTokenResponseClient();
accessTokenResponseClient.addParametersConverter(grantRequest -> {
    ClientRegistration clientRegistration = grantRequest.getClientRegistration();
    MultiValueMap<String, String> parameters = new LinkedMultiValueMap<String, String>();
    if (clientRegistration.getRegistrationId().equals("keycloak")) {
        parameters.set(OAuth2ParameterNames.AUDIENCE, "my-audience");
    }
    return parameters;
});
java

您可以使用 setParametersConverter() 覆盖默认参数。以下示例在 registrationId 为 okta 时覆盖 client_id 参数：

RestClientJwtBearerTokenResponseClient accessTokenResponseClient =
    new RestClientJwtBearerTokenResponseClient();
accessTokenResponseClient.setParametersConverter(grantRequest -> {
    ClientRegistration clientRegistration = grantRequest.getClientRegistration();
    LinkedMultiValueMap<String, String> parameters = new LinkedMultiValueMap<>();
    if (clientRegistration.getRegistrationId().equals("okta")) {
        parameters.set(OAuth2ParameterNames.CLIENT_ID, "my-client");
    }
    return parameters;
});
java

您可以使用 setParametersCustomizer() 完全自定义参数（包括省略默认参数）。以下示例在请求中存在 client_assertion 参数时省略 client_id 参数：

RestClientJwtBearerTokenResponseClient accessTokenResponseClient =
    new RestClientJwtBearerTokenResponseClient();
accessTokenResponseClient.setParametersCustomizer(parameters -> {
    if (parameters.containsKey(OAuth2ParameterNames.CLIENT_ASSERTION)) {
        parameters.remove(OAuth2ParameterNames.CLIENT_ID);
    }
});
java

自定义访问令牌响应​

RestClientJwtBearerTokenResponseClient 提供了用于自定义 OAuth 2.0 访问令牌响应的参数和错误处理的钩子。

自定义 WebClient​

您可以提供一个预配置的 RestClient 给 setRestClient() 来自定义令牌响应。默认的 RestClient 配置如下：

RestClient restClient = RestClient.builder()
    .messageConverters(messageConverters -> {
        messageConverters.clear();
        messageConverters.add(new FormHttpMessageConverter());
        messageConverters.add(new OAuth2AccessTokenResponseHttpMessageConverter());
    })
    .defaultStatusHandler(new OAuth2ErrorResponseErrorHandler())
    .build();

RestClientJwtBearerTokenResponseClient accessTokenResponseClient =
    new RestClientJwtBearerTokenResponseClient();
accessTokenResponseClient.setRestClient(restClient);
java

OAuth2AccessTokenResponseHttpMessageConverter 是一个用于 OAuth 2.0 访问令牌响应的 HttpMessageConverter。您可以通过调用 setAccessTokenResponseConverter() 来自定义令牌响应参数到 OAuth2AccessTokenResponse 的转换。默认实现是 DefaultMapOAuth2AccessTokenResponseConverter。

OAuth2ErrorResponseErrorHandler 是一个 ResponseErrorHandler，可以处理 OAuth 2.0 错误，例如 400 Bad Request。它使用 OAuth2ErrorHttpMessageConverter 将 OAuth 2.0 错误参数转换为 OAuth2Error。你可以通过调用 setErrorConverter() 来自定义将 Token 响应参数转换为 OAuth2Error 的过程。

提示

Spring MVC FormHttpMessageConverter 是必需的，因为它在发送 OAuth 2.0 访问令牌请求时会被使用。

自定义响应参数​

以下示例提供了一个自定义 Token 响应参数转换为 OAuth2AccessTokenResponse 的起点：

OAuth2AccessTokenResponseHttpMessageConverter accessTokenResponseMessageConverter =
    new OAuth2AccessTokenResponseHttpMessageConverter();
accessTokenResponseMessageConverter.setAccessTokenResponseConverter(parameters -> {
    // ...
    return OAuth2AccessTokenResponse.withToken("custom-token")
        // ...
        .build();
});
java

自定义错误处理​

以下示例提供了一个自定义将 Error 参数转换为 OAuth2Error 的起点：

OAuth2ErrorHttpMessageConverter errorConverter =
    new OAuth2ErrorHttpMessageConverter();
errorConverter.setErrorConverter(parameters -> {
    // ...
    return new OAuth2Error("custom-error", "custom description", "custom-uri");
});

OAuth2ErrorResponseErrorHandler errorHandler =
    new OAuth2ErrorResponseErrorHandler();
errorHandler.setErrorConverter(errorConverter);
java

使用构建器进行自定义​

无论你是自定义 RestClientJwtBearerTokenResponseClient 还是提供自己的 OAuth2AccessTokenResponseClient 实现，都可以使用 OAuth2AuthorizedClientProviderBuilder 来配置它（作为发布一个 bean 的替代方案），如下所示：

// Customize
OAuth2AccessTokenResponseClient<JwtBearerGrantRequest> jwtBearerTokenResponseClient = ...

JwtBearerOAuth2AuthorizedClientProvider jwtBearerAuthorizedClientProvider = new JwtBearerOAuth2AuthorizedClientProvider();
jwtBearerAuthorizedClientProvider.setAccessTokenResponseClient(jwtBearerTokenResponseClient);

OAuth2AuthorizedClientProvider authorizedClientProvider =
        OAuth2AuthorizedClientProviderBuilder.builder()
                .provider(jwtBearerAuthorizedClientProvider)
                .build();

// ...

authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider);
java

使用访问令牌​

给定以下用于OAuth 2.0客户端注册的Spring Boot属性：

spring:
  security:
    oauth2:
      client:
        registration:
          okta:
            client-id: okta-client-id
            client-secret: okta-client-secret
            authorization-grant-type: urn:ietf:params:oauth:grant-type:jwt-bearer
            scope: read
        provider:
          okta:
            token-uri: https://dev-1234.oktapreview.com/oauth2/v1/token
yaml

…​和 OAuth2AuthorizedClientManager @Bean：

@Bean
public OAuth2AuthorizedClientManager authorizedClientManager(
        ClientRegistrationRepository clientRegistrationRepository,
        OAuth2AuthorizedClientRepository authorizedClientRepository) {

    JwtBearerOAuth2AuthorizedClientProvider jwtBearerAuthorizedClientProvider =
            new JwtBearerOAuth2AuthorizedClientProvider();

    OAuth2AuthorizedClientProvider authorizedClientProvider =
            OAuth2AuthorizedClientProviderBuilder.builder()
                    .provider(jwtBearerAuthorizedClientProvider)
                    .build();

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

    return authorizedClientManager;
}
java

您可以按如下方式获取 OAuth2AccessToken：

@RestController
public class OAuth2ResourceServerController {

    @Autowired
    private OAuth2AuthorizedClientManager authorizedClientManager;

    @GetMapping("/resource")
    public String resource(JwtAuthenticationToken jwtAuthentication) {
        OAuth2AuthorizeRequest authorizeRequest = OAuth2AuthorizeRequest.withClientRegistrationId("okta")
                .principal(jwtAuthentication)
                .build();
        OAuth2AuthorizedClient authorizedClient = this.authorizedClientManager.authorize(authorizeRequest);
        OAuth2AccessToken accessToken = authorizedClient.getAccessToken();

        // ...

    }
}
java
备注

JwtBearerOAuth2AuthorizedClientProvider 默认通过 OAuth2AuthorizationContext.getPrincipal().getPrincipal() 解析 Jwt 断言，因此在前面的示例中使用了 JwtAuthenticationToken。

提示

如果你需要从不同的来源解析 Jwt 断言，你可以通过提供 JwtBearerOAuth2AuthorizedClientProvider.setJwtAssertionResolver() 一个自定义的 Function<OAuth2AuthorizationContext, Jwt> 来实现。

令牌交换​

备注

有关Token Exchange授权的更多详情，请参阅 OAuth 2.0 Token Exchange。

请求访问令牌​

备注

请参阅 Token Exchange 请求和响应 协议流程以了解 Token Exchange 授权。

有两种 OAuth2AccessTokenResponseClient 实现可用于向令牌端点发出 HTTP 请求，以便为令牌交换授权获取访问令牌：

  • DefaultTokenExchangeTokenResponseClient (默认)

  • RestClientTokenExchangeTokenResponseClient

默认实现使用 RestOperations 实例在授权服务器的令牌端点交换授权码以获取访问令牌。Spring Security 6.4 引入了一个基于 RestClient 的新实现，它提供了类似的功能，但更好地与该组件的响应式版本（基于 WebClient）保持一致，以便为任一栈上的应用程序提供一致的配置。

备注

本节重点介绍 RestClientTokenExchangeTokenResponseClient。您可以在 Spring Security 6.3 文档中阅读有关 DefaultTokenExchangeTokenResponseClient 的内容。

要选择使用 RestClientTokenExchangeTokenResponseClient，只需提供一个 bean，如以下示例所示，它将被默认的 OAuth2AuthorizedClientManager 自动识别：

@Bean
public TokenResponseClient tokenResponseClient() {
    return new RestClientTokenExchangeTokenResponseClient();
}
java
@Bean
public OAuth2AccessTokenResponseClient<TokenExchangeGrantRequest> accessTokenResponseClient() {
    return new RestClientTokenExchangeTokenResponseClient();
}
java
备注

新的实现将在 Spring Security 7 中成为默认设置。

RestClientTokenExchangeTokenResponseClient 非常灵活，提供了多种选项来自定义 Token Exchange 授权的 OAuth 2.0 访问令牌请求和响应。请选择以下用例以了解更多信息：

自定义访问令牌请求​

RestClientTokenExchangeTokenResponseClient 提供了用于自定义 OAuth 2.0 访问令牌请求的 HTTP 头和请求参数的钩子。

自定义请求头​

有两种方法可以自定义 HTTP 标头：

  • 通过调用 addHeadersConverter() 添加额外的头部

  • 通过调用 setHeadersConverter() 完全自定义头部

你可以使用 addHeadersConverter() 添加额外的头部信息，而不会影响添加到每个请求的默认头部。以下示例在 registrationId 为 spring 时，向请求中添加一个 User-Agent 头部：

RestClientTokenExchangeTokenResponseClient accessTokenResponseClient =
    new RestClientTokenExchangeTokenResponseClient();
accessTokenResponseClient.addHeadersConverter(grantRequest -> {
    ClientRegistration clientRegistration = grantRequest.getClientRegistration();
    HttpHeaders headers = new HttpHeaders();
    if (clientRegistration.getRegistrationId().equals("spring")) {
        headers.set(HttpHeaders.USER_AGENT, "my-user-agent");
    }
    return headers;
});
java

你可以通过重用 DefaultOAuth2TokenRequestHeadersConverter 或使用 setHeadersConverter() 提供自定义实现来完全自定义头部。以下示例重用了 DefaultOAuth2TokenRequestHeadersConverter，并禁用了 encodeClientCredentials，这样 HTTP Basic 凭据就不会再用 application/x-www-form-urlencoded 进行编码：

DefaultOAuth2TokenRequestHeadersConverter headersConverter =
    new DefaultOAuth2TokenRequestHeadersConverter();
headersConverter.setEncodeClientCredentials(false);

RestClientTokenExchangeTokenResponseClient accessTokenResponseClient =
    new RestClientTokenExchangeTokenResponseClient();
accessTokenResponseClient.setHeadersConverter(headersConverter);
java

自定义请求参数​

有三种自定义请求参数的选项：

  • 通过调用 addParametersConverter() 添加额外的参数

  • 通过调用 setParametersConverter() 覆盖参数

  • 通过调用 setParametersCustomizer() 完全自定义参数

备注

使用 setParametersConverter() 不能完全自定义参数，因为它要求用户提供所有默认参数。默认参数总是会被提供，但可以通过调用 setParametersCustomizer() 来完全自定义或省略。

您可以使用 addParametersConverter() 添加额外的参数，而不会影响添加到每个请求的默认参数。以下示例在 registrationId 为 keycloak 时向请求添加一个 audience 参数：

RestClientTokenExchangeTokenResponseClient accessTokenResponseClient =
    new RestClientTokenExchangeTokenResponseClient();
accessTokenResponseClient.addParametersConverter(grantRequest -> {
    ClientRegistration clientRegistration = grantRequest.getClientRegistration();
    MultiValueMap<String, String> parameters = new LinkedMultiValueMap<String, String>();
    if (clientRegistration.getRegistrationId().equals("keycloak")) {
        parameters.set(OAuth2ParameterNames.AUDIENCE, "my-audience");
    }
    return parameters;
});
java

你可以使用 setParametersConverter() 覆盖默认参数。以下示例在 registrationId 为 okta 时覆盖 client_id 参数：

RestClientTokenExchangeTokenResponseClient accessTokenResponseClient =
    new RestClientTokenExchangeTokenResponseClient();
accessTokenResponseClient.setParametersConverter(grantRequest -> {
    ClientRegistration clientRegistration = grantRequest.getClientRegistration();
    LinkedMultiValueMap<String, String> parameters = new LinkedMultiValueMap<>();
    if (clientRegistration.getRegistrationId().equals("okta")) {
        parameters.set(OAuth2ParameterNames.CLIENT_ID, "my-client");
    }
    return parameters;
});
java

您可以使用 setParametersCustomizer() 完全自定义参数（包括省略默认参数）。以下示例在请求中存在 client_assertion 参数时省略 client_id 参数：

RestClientTokenExchangeTokenResponseClient accessTokenResponseClient =
    new RestClientTokenExchangeTokenResponseClient();
accessTokenResponseClient.setParametersCustomizer(parameters -> {
    if (parameters.containsKey(OAuth2ParameterNames.CLIENT_ASSERTION)) {
        parameters.remove(OAuth2ParameterNames.CLIENT_ID);
    }
});
java

自定义访问令牌响应​

RestClientTokenExchangeTokenResponseClient 提供了用于自定义 OAuth 2.0 访问令牌响应参数和错误处理的钩子。

自定义 WebClient​

你可以通过向 setRestClient() 提供一个预配置的 RestClient 来自定义 Token 响应。默认的 RestClient 配置如下：

RestClient restClient = RestClient.builder()
    .messageConverters(messageConverters -> {
        messageConverters.clear();
        messageConverters.add(new FormHttpMessageConverter());
        messageConverters.add(new OAuth2AccessTokenResponseHttpMessageConverter());
    })
    .defaultStatusHandler(new OAuth2ErrorResponseErrorHandler())
    .build();

RestClientTokenExchangeTokenResponseClient accessTokenResponseClient =
    new RestClientTokenExchangeTokenResponseClient();
accessTokenResponseClient.setRestClient(restClient);
java

OAuth2AccessTokenResponseHttpMessageConverter 是一个用于 OAuth 2.0 访问令牌响应的 HttpMessageConverter。你可以通过调用 setAccessTokenResponseConverter() 来自定义令牌响应参数到 OAuth2AccessTokenResponse 的转换。默认实现是 DefaultMapOAuth2AccessTokenResponseConverter。

OAuth2ErrorResponseErrorHandler 是一个 ResponseErrorHandler，可以处理 OAuth 2.0 错误，例如 400 Bad Request。它使用 OAuth2ErrorHttpMessageConverter 将 OAuth 2.0 错误参数转换为 OAuth2Error。你可以通过调用 setErrorConverter() 来自定义将 Token 响应参数转换为 OAuth2Error 的过程。

提示

Spring MVC FormHttpMessageConverter 是必需的，因为它在发送 OAuth 2.0 访问令牌请求时会被用到。

自定义响应参数​

以下示例提供了一个自定义 Token 响应参数转换为 OAuth2AccessTokenResponse 的起点：

OAuth2AccessTokenResponseHttpMessageConverter accessTokenResponseMessageConverter =
    new OAuth2AccessTokenResponseHttpMessageConverter();
accessTokenResponseMessageConverter.setAccessTokenResponseConverter(parameters -> {
    // ...
    return OAuth2AccessTokenResponse.withToken("custom-token")
        // ...
        .build();
});
java

自定义错误处理​

以下示例提供了一个将 Error 参数自定义转换为 OAuth2Error 的起点：

OAuth2ErrorHttpMessageConverter errorConverter =
    new OAuth2ErrorHttpMessageConverter();
errorConverter.setErrorConverter(parameters -> {
    // ...
    return new OAuth2Error("custom-error", "custom description", "custom-uri");
});

OAuth2ErrorResponseErrorHandler errorHandler =
    new OAuth2ErrorResponseErrorHandler();
errorHandler.setErrorConverter(errorConverter);
java

使用 Builder 进行自定义​

无论你是自定义 RestClientTokenExchangeTokenResponseClient 还是提供自己的 OAuth2AccessTokenResponseClient 实现，你都可以使用 OAuth2AuthorizedClientProviderBuilder 来配置它（作为发布一个 bean 的替代方案），如下所示：

// Customize
OAuth2AccessTokenResponseClient<TokenExchangeGrantRequest> tokenExchangeTokenResponseClient = ...

TokenExchangeOAuth2AuthorizedClientProvider tokenExchangeAuthorizedClientProvider = new TokenExchangeOAuth2AuthorizedClientProvider();
tokenExchangeAuthorizedClientProvider.setAccessTokenResponseClient(tokenExchangeTokenResponseClient);

OAuth2AuthorizedClientProvider authorizedClientProvider =
        OAuth2AuthorizedClientProviderBuilder.builder()
                .provider(tokenExchangeAuthorizedClientProvider)
                .build();

// ...

authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider);
java

使用访问令牌​

给定以下用于OAuth 2.0客户端注册的Spring Boot属性：

spring:
  security:
    oauth2:
      client:
        registration:
          okta:
            client-id: okta-client-id
            client-secret: okta-client-secret
            authorization-grant-type: urn:ietf:params:oauth:grant-type:token-exchange
            scope: read
        provider:
          okta:
            token-uri: https://dev-1234.oktapreview.com/oauth2/v1/token
yaml

…​和 OAuth2AuthorizedClientManager @Bean：

@Bean
public OAuth2AuthorizedClientManager authorizedClientManager(
        ClientRegistrationRepository clientRegistrationRepository,
        OAuth2AuthorizedClientRepository authorizedClientRepository) {

    TokenExchangeOAuth2AuthorizedClientProvider tokenExchangeAuthorizedClientProvider =
            new TokenExchangeOAuth2AuthorizedClientProvider();

    OAuth2AuthorizedClientProvider authorizedClientProvider =
            OAuth2AuthorizedClientProviderBuilder.builder()
                    .provider(tokenExchangeAuthorizedClientProvider)
                    .build();

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

    return authorizedClientManager;
}
java

您可以按如下方式获取 OAuth2AccessToken：

@RestController
public class OAuth2ResourceServerController {

    @Autowired
    private OAuth2AuthorizedClientManager authorizedClientManager;

    @GetMapping("/resource")
    public String resource(JwtAuthenticationToken jwtAuthentication) {
        OAuth2AuthorizeRequest authorizeRequest = OAuth2AuthorizeRequest.withClientRegistrationId("okta")
                .principal(jwtAuthentication)
                .build();
        OAuth2AuthorizedClient authorizedClient = this.authorizedClientManager.authorize(authorizeRequest);
        OAuth2AccessToken accessToken = authorizedClient.getAccessToken();

        // ...

    }
}
java
备注

TokenExchangeOAuth2AuthorizedClientProvider 默认通过 OAuth2AuthorizationContext.getPrincipal().getPrincipal() 解析主体令牌（作为 OAuth2Token），因此在前面的示例中使用了 JwtAuthenticationToken。默认情况下，不会解析扮演者令牌。

提示

如果你需要从不同的来源解析主体令牌，可以使用 TokenExchangeOAuth2AuthorizedClientProvider.setSubjectTokenResolver() 提供一个自定义的 Function<OAuth2AuthorizationContext, OAuth2Token>。

提示

如果你需要解析一个actor token，你可以通过 TokenExchangeOAuth2AuthorizedClientProvider.setActorTokenResolver() 提供一个自定义的 Function<OAuth2AuthorizationContext, OAuth2Token>。