授权许可支持

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

授权码

有关授权码（Authorization Code）许可的更多详细信息，请参阅 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

给定上述属性，使用基础路径 /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"
            # ...

公共客户端通过使用授权码交换证明密钥 (PKCE) 来支持。如果客户端在不受信任的环境中运行（例如原生应用或基于 Web 浏览器的应用），因此无法维护其凭证的机密性，则在满足以下条件时会自动使用 PKCE

client-secret 被省略（或为空）
client-authentication-method 设置为 none (ClientAuthenticationMethod.NONE)

如果 OAuth 2.0 提供商支持对机密客户端使用 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}"
            # ...

{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() 的授权请求。

Java
Kotlin

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

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Autowired
    private lateinit var customClientRegistrationRepository: ClientRegistrationRepository

    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            authorizeRequests {
                authorize(anyRequest, authenticated)
            }
            oauth2Login {
                authorizationEndpoint {
                    authorizationRequestResolver = authorizationRequestResolver(customClientRegistrationRepository)
                }
            }
        }
        return http.build()
    }

    private fun authorizationRequestResolver(
            clientRegistrationRepository: ClientRegistrationRepository?): OAuth2AuthorizationRequestResolver {
        val authorizationRequestResolver = DefaultOAuth2AuthorizationRequestResolver(
                clientRegistrationRepository, "/oauth2/authorization")
        authorizationRequestResolver.setAuthorizationRequestCustomizer(
                authorizationRequestCustomizer())
        return authorizationRequestResolver
    }

    private fun authorizationRequestCustomizer(): Consumer<OAuth2AuthorizationRequest.Builder> {
        return Consumer { customizer ->
            customizer
                    .additionalParameters { params -> params["prompt"] = "consent" }
        }
    }
}

对于简单用例，如果额外请求参数对于特定提供商始终相同，可以直接将其添加到 authorization-uri 属性中。

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

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

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

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

以下示例展示了前面示例中 authorizationRequestCustomizer() 的变体，转而覆盖了 OAuth2AuthorizationRequest.authorizationRequestUri 属性

Java
Kotlin

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

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

存储授权请求

AuthorizationRequestRepository 负责 OAuth2AuthorizationRequest 的持久化，从授权请求发起时直到接收到授权响应时（即回调）。

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

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

如果您有 AuthorizationRequestRepository 的自定义实现，可以按如下方式配置

AuthorizationRequestRepository 配置

Java
Kotlin
Xml

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

@Configuration
@EnableWebSecurity
class OAuth2ClientSecurityConfig {

    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            oauth2Client {
                authorizationCodeGrant {
                    authorizationRequestRepository = authorizationRequestRepository()
                }
            }
        }
        return http.build()
    }
}

<http>
	<oauth2-client>
		<authorization-code-grant authorization-request-repository-ref="authorizationRequestRepository"/>
	</oauth2-client>
</http>

请求访问令牌

有关授权码许可的访问令牌请求/响应协议流程，请参阅。

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

DefaultAuthorizationCodeTokenResponseClient（默认）
RestClientAuthorizationCodeTokenResponseClient

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

本节重点介绍 RestClientAuthorizationCodeTokenResponseClient。您可以在 Spring Security 6.3 文档中阅读有关 DefaultAuthorizationCodeTokenResponseClient 的信息。

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

访问令牌响应配置

Java
Kotlin

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

@Bean
fun accessTokenResponseClient(): OAuth2AccessTokenResponseClient<Authorization Code> {
	return RestClientAuthorizationCodeTokenResponseClient()
}

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

RestClientAuthorizationCodeTokenResponseClient 非常灵活，为授权码许可的 OAuth 2.0 访问令牌请求和响应提供了多种定制选项。从以下用例中选择以了解更多信息

我想定制访问令牌请求的头信息
我想定制访问令牌请求的参数
我想定制使用的 RestClient 实例
我想定制访问令牌响应的参数
我想定制访问令牌响应的错误处理

定制访问令牌请求

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

定制请求头

定制 HTTP 头有两种选择

通过调用 addHeadersConverter() 添加额外的头
通过调用 setHeadersConverter() 完全定制头

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

包含额外的 HTTP 头

Java
Kotlin

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

val accessTokenResponseClient = RestClientAuthorizationCodeTokenResponseClient()
accessTokenResponseClient.addHeadersConverter { grantRequest ->
	val clientRegistration = grantRequest.getClientRegistration()
	val headers = HttpHeaders()
	if (clientRegistration.getRegistrationId() == "spring") {
        headers[HttpHeaders.USER_AGENT] = "my-user-agent"
	}
	headers
}

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

定制 HTTP 头

Java
Kotlin

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

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

val headersConverter = DefaultOAuth2TokenRequestHeadersConverter()
headersConverter.setEncodeClientCredentials(false)

val accessTokenResponseClient = RestClientAuthorizationCodeTokenResponseClient()
accessTokenResponseClient.setHeadersConverter(headersConverter)

定制请求参数

定制请求参数有三种选择

通过调用 addParametersConverter() 添加额外的参数
通过调用 setParametersConverter() 覆盖参数
通过调用 setParametersCustomizer() 完全定制参数

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

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

包含额外的请求参数

Java
Kotlin

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

val accessTokenResponseClient = RestClientAuthorizationCodeTokenResponseClient()
accessTokenResponseClient.addParametersConverter { grantRequest ->
	val clientRegistration = grantRequest.getClientRegistration()
	val parameters = LinkedMultiValueMap<String, String>()
	if (clientRegistration.getRegistrationId() == "keycloak") {
        parameters[OAuth2ParameterNames.AUDIENCE] = "my-audience"
	}
	parameters
}

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

覆盖请求参数

Java
Kotlin

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

val parametersConverter = DefaultOAuth2TokenRequestParametersConverter<OAuth2AuthorizationCodeGrantRequest>()
parametersConverter.setParametersCustomizer { parameters ->
	if (parameters.containsKey(OAuth2ParameterNames.CLIENT_ASSERTION)) {
		parameters.remove(OAuth2ParameterNames.CLIENT_ID)
	}
}

val accessTokenResponseClient = RestClientAuthorizationCodeTokenResponseClient()
accessTokenResponseClient.setParametersConverter { grantRequest ->
    val clientRegistration = grantRequest.getClientRegistration()
	val parameters = LinkedMultiValueMap<String, String>()
	if (clientRegistration.getRegistrationId() == "okta") {
        parameters[OAuth2ParameterNames.CLIENT_ID] = "my-client"
	}
	parameters
}

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

省略请求参数

Java
Kotlin

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

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

定制访问令牌响应

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

定制 `WebClient`

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

默认 RestClient 配置

Java
Kotlin

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);

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

val accessTokenResponseClient = RestClientAuthorizationCodeTokenResponseClient()
accessTokenResponseClient.setRestClient(restClient)

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

OAuth2ErrorResponseErrorHandler 是一个可以处理 OAuth 2.0 错误（例如 400 Bad Request）的 ResponseErrorHandler。它使用一个 OAuth2ErrorHttpMessageConverter 将 OAuth 2.0 错误参数转换为 OAuth2Error。您可以通过调用 setErrorConverter() 来定制令牌响应参数到 OAuth2Error 的转换。

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

定制响应参数

以下示例提供了一个起点，用于定制令牌响应参数到 OAuth2AccessTokenResponse 的转换

定制访问令牌响应转换器

Java
Kotlin

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

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

定制错误处理

以下示例提供了一个起点，用于定制错误参数到 OAuth2Error 的转换

定制访问令牌错误处理器

Java
Kotlin

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

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

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

val errorHandler = OAuth2ErrorResponseErrorHandler()
errorHandler.setErrorConverter(errorConverter)

使用 DSL 定制

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

通过 DSL 配置访问令牌响应

Java
Kotlin
Xml

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

@Configuration
@EnableWebSecurity
class OAuth2ClientSecurityConfig {

    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            oauth2Client {
                authorizationCodeGrant {
                    accessTokenResponseClient = accessTokenResponseClient()
                }
            }
        }
        return http.build()
    }
}

<http>
	<oauth2-client>
		<authorization-code-grant access-token-response-client-ref="accessTokenResponseClient"/>
	</oauth2-client>
</http>

刷新令牌

有关刷新令牌的更多详细信息，请参阅 OAuth 2.0 授权框架。

刷新访问令牌

有关刷新令牌许可的访问令牌请求/响应协议流程，请参阅。

有两种 OAuth2AccessTokenResponseClient 实现可用于向令牌端点发起 HTTP 请求，以获取刷新令牌许可的访问令牌

DefaultRefreshTokenTokenResponseClient（默认）
RestClientRefreshTokenTokenResponseClient

本节重点介绍 RestClientRefreshTokenTokenResponseClient。您可以在 Spring Security 6.3 文档中阅读有关 DefaultRefreshTokenTokenResponseClient 的信息。

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

访问令牌响应配置

Java
Kotlin

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

@Bean
fun accessTokenResponseClient(): OAuth2AccessTokenResponseClient<Refresh Token> {
	return RestClientRefreshTokenTokenResponseClient()
}

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

RestClientRefreshTokenTokenResponseClient 非常灵活，为刷新令牌许可的 OAuth 2.0 访问令牌请求和响应提供了多种定制选项。从以下用例中选择以了解更多信息

我想定制访问令牌请求的头信息
我想定制访问令牌请求的参数
我想定制使用的 RestClient 实例
我想定制访问令牌响应的参数
我想定制访问令牌响应的错误处理

定制访问令牌请求

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

定制请求头

定制 HTTP 头有两种选择

通过调用 addHeadersConverter() 添加额外的头
通过调用 setHeadersConverter() 完全定制头

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

包含额外的 HTTP 头

Java
Kotlin

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

val accessTokenResponseClient = RestClientRefreshTokenTokenResponseClient()
accessTokenResponseClient.addHeadersConverter { grantRequest ->
	val clientRegistration = grantRequest.getClientRegistration()
	val headers = HttpHeaders()
	if (clientRegistration.getRegistrationId() == "spring") {
        headers[HttpHeaders.USER_AGENT] = "my-user-agent"
	}
	headers
}

定制 HTTP 头

Java
Kotlin

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

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

val headersConverter = DefaultOAuth2TokenRequestHeadersConverter()
headersConverter.setEncodeClientCredentials(false)

val accessTokenResponseClient = RestClientRefreshTokenTokenResponseClient()
accessTokenResponseClient.setHeadersConverter(headersConverter)

定制请求参数

定制请求参数有三种选择

通过调用 addParametersConverter() 添加额外的参数
通过调用 setParametersConverter() 覆盖参数
通过调用 setParametersCustomizer() 完全定制参数

包含额外的请求参数

Java
Kotlin

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

val accessTokenResponseClient = RestClientRefreshTokenTokenResponseClient()
accessTokenResponseClient.addParametersConverter { grantRequest ->
	val clientRegistration = grantRequest.getClientRegistration()
	val parameters = LinkedMultiValueMap<String, String>()
	if (clientRegistration.getRegistrationId() == "keycloak") {
        parameters[OAuth2ParameterNames.AUDIENCE] = "my-audience"
	}
	parameters
}

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

覆盖请求参数

Java
Kotlin

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

val parametersConverter = DefaultOAuth2TokenRequestParametersConverter<OAuth2RefreshTokenGrantRequest>()
parametersConverter.setParametersCustomizer { parameters ->
	if (parameters.containsKey(OAuth2ParameterNames.CLIENT_ASSERTION)) {
		parameters.remove(OAuth2ParameterNames.CLIENT_ID)
	}
}

val accessTokenResponseClient = RestClientRefreshTokenTokenResponseClient()
accessTokenResponseClient.setParametersConverter { grantRequest ->
    val clientRegistration = grantRequest.getClientRegistration()
	val parameters = LinkedMultiValueMap<String, String>()
	if (clientRegistration.getRegistrationId() == "okta") {
        parameters[OAuth2ParameterNames.CLIENT_ID] = "my-client"
	}
	parameters
}

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

省略请求参数

Java
Kotlin

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

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

定制访问令牌响应

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

定制 `WebClient`

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

默认 RestClient 配置

Java
Kotlin

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);

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

val accessTokenResponseClient = RestClientRefreshTokenTokenResponseClient()
accessTokenResponseClient.setRestClient(restClient)

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

定制响应参数

以下示例提供了一个起点，用于定制令牌响应参数到 OAuth2AccessTokenResponse 的转换

定制访问令牌响应转换器

Java
Kotlin

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

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

定制错误处理

以下示例提供了一个起点，用于定制错误参数到 OAuth2Error 的转换

定制访问令牌错误处理器

Java
Kotlin

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

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

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

val errorHandler = OAuth2ErrorResponseErrorHandler()
errorHandler.setErrorConverter(errorConverter)

使用 Builder 定制

无论您是定制 RestClientRefreshTokenTokenResponseClient 还是提供自己的 OAuth2AccessTokenResponseClient 实现，都可以使用 OAuth2AuthorizedClientProviderBuilder 进行配置（作为发布 bean 的替代方案），如下所示

通过 Builder 配置访问令牌响应

Java
Kotlin

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

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

// ...

authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider);

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

val authorizedClientProvider = OAuth2AuthorizedClientProviderBuilder.builder()
        .authorizationCode()
        .refreshToken { it.accessTokenResponseClient(refreshTokenTokenResponseClient) }
        .build()

// ...

authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider)

OAuth2AuthorizedClientProviderBuilder.builder().refreshToken() 配置了一个 RefreshTokenOAuth2AuthorizedClientProvider，它是 OAuth2AuthorizedClientProvider 在刷新令牌许可上的实现。

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

客户端凭证

有关客户端凭证（Client Credentials）许可的更多详细信息，请参阅 OAuth 2.0 授权框架。

请求访问令牌

有关客户端凭证许可的访问令牌请求/响应协议流程，请参阅。

有两种 OAuth2AccessTokenResponseClient 实现可用于向令牌端点发起 HTTP 请求，以获取客户端凭证许可的访问令牌

DefaultClientCredentialsTokenResponseClient（默认）
RestClientClientCredentialsTokenResponseClient

本节重点介绍 RestClientClientCredentialsTokenResponseClient。您可以在 Spring Security 6.3 文档中阅读有关 DefaultClientCredentialsTokenResponseClient 的信息。

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

访问令牌响应配置

Java
Kotlin

@Bean
public OAuth2AccessTokenResponseClient<OAuth2ClientCredentialsGrantRequest> accessTokenResponseClient() {
	return new RestClientClientCredentialsTokenResponseClient();
}

@Bean
fun accessTokenResponseClient(): OAuth2AccessTokenResponseClient<Client Credentials> {
	return RestClientClientCredentialsTokenResponseClient()
}

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

RestClientClientCredentialsTokenResponseClient 非常灵活，为客户端凭证许可的 OAuth 2.0 访问令牌请求和响应提供了多种定制选项。从以下用例中选择以了解更多信息

我想定制访问令牌请求的头信息
我想定制访问令牌请求的参数
我想定制使用的 RestClient 实例
我想定制访问令牌响应的参数
我想定制访问令牌响应的错误处理

定制访问令牌请求

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

定制请求头

定制 HTTP 头有两种选择

通过调用 addHeadersConverter() 添加额外的头
通过调用 setHeadersConverter() 完全定制头

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

包含额外的 HTTP 头

Java
Kotlin

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

val accessTokenResponseClient = RestClientClientCredentialsTokenResponseClient()
accessTokenResponseClient.addHeadersConverter { grantRequest ->
	val clientRegistration = grantRequest.getClientRegistration()
	val headers = HttpHeaders()
	if (clientRegistration.getRegistrationId() == "spring") {
        headers[HttpHeaders.USER_AGENT] = "my-user-agent"
	}
	headers
}

定制 HTTP 头

Java
Kotlin

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

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

val headersConverter = DefaultOAuth2TokenRequestHeadersConverter()
headersConverter.setEncodeClientCredentials(false)

val accessTokenResponseClient = RestClientClientCredentialsTokenResponseClient()
accessTokenResponseClient.setHeadersConverter(headersConverter)

定制请求参数

定制请求参数有三种选择

通过调用 addParametersConverter() 添加额外的参数
通过调用 setParametersConverter() 覆盖参数
通过调用 setParametersCustomizer() 完全定制参数

包含额外的请求参数

Java
Kotlin

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

val accessTokenResponseClient = RestClientClientCredentialsTokenResponseClient()
accessTokenResponseClient.addParametersConverter { grantRequest ->
	val clientRegistration = grantRequest.getClientRegistration()
	val parameters = LinkedMultiValueMap<String, String>()
	if (clientRegistration.getRegistrationId() == "keycloak") {
        parameters[OAuth2ParameterNames.AUDIENCE] = "my-audience"
	}
	parameters
}

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

覆盖请求参数

Java
Kotlin

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

val parametersConverter = DefaultOAuth2TokenRequestParametersConverter<OAuth2ClientCredentialsGrantRequest>()
parametersConverter.setParametersCustomizer { parameters ->
	if (parameters.containsKey(OAuth2ParameterNames.CLIENT_ASSERTION)) {
		parameters.remove(OAuth2ParameterNames.CLIENT_ID)
	}
}

val accessTokenResponseClient = RestClientClientCredentialsTokenResponseClient()
accessTokenResponseClient.setParametersConverter { grantRequest ->
    val clientRegistration = grantRequest.getClientRegistration()
	val parameters = LinkedMultiValueMap<String, String>()
	if (clientRegistration.getRegistrationId() == "okta") {
        parameters[OAuth2ParameterNames.CLIENT_ID] = "my-client"
	}
	parameters
}

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

省略请求参数

Java
Kotlin

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

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

定制访问令牌响应

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

定制 `WebClient`

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

默认 RestClient 配置

Java
Kotlin

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);

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

val accessTokenResponseClient = RestClientClientCredentialsTokenResponseClient()
accessTokenResponseClient.setRestClient(restClient)

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

定制响应参数

以下示例提供了一个起点，用于定制令牌响应参数到 OAuth2AccessTokenResponse 的转换

定制访问令牌响应转换器

Java
Kotlin

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

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

定制错误处理

以下示例提供了一个起点，用于定制错误参数到 OAuth2Error 的转换

定制访问令牌错误处理器

Java
Kotlin

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

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

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

val errorHandler = OAuth2ErrorResponseErrorHandler()
errorHandler.setErrorConverter(errorConverter)

使用 Builder 定制

无论您是定制 RestClientClientCredentialsTokenResponseClient 还是提供自己的 OAuth2AccessTokenResponseClient 实现，都可以使用 OAuth2AuthorizedClientProviderBuilder 进行配置（作为发布 bean 的替代方案），如下所示

通过 Builder 配置访问令牌响应

Java
Kotlin

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

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

// ...

authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider);

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

val authorizedClientProvider = OAuth2AuthorizedClientProviderBuilder.builder()
        .clientCredentials { it.accessTokenResponseClient(clientCredentialsTokenResponseClient) }
        .build()

// ...

authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider)

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

进一步考虑以下 OAuth2AuthorizedClientManager 的 @Bean

Java
Kotlin

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

@Bean
fun authorizedClientManager(
        clientRegistrationRepository: ClientRegistrationRepository,
        authorizedClientRepository: OAuth2AuthorizedClientRepository): OAuth2AuthorizedClientManager {
    val authorizedClientProvider = OAuth2AuthorizedClientProviderBuilder.builder()
            .clientCredentials()
            .build()
    val authorizedClientManager = DefaultOAuth2AuthorizedClientManager(
            clientRegistrationRepository, authorizedClientRepository)
    authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider)
    return authorizedClientManager
}

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

Java
Kotlin

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

class OAuth2ClientController {

    @Autowired
    private lateinit var authorizedClientManager: OAuth2AuthorizedClientManager

    @GetMapping("/")
    fun index(authentication: Authentication?,
              servletRequest: HttpServletRequest,
              servletResponse: HttpServletResponse): String {
        val authorizeRequest: OAuth2AuthorizeRequest = OAuth2AuthorizeRequest.withClientRegistrationId("okta")
                .principal(authentication)
                .attributes(Consumer { attrs: MutableMap<String, Any> ->
                    attrs[HttpServletRequest::class.java.name] = servletRequest
                    attrs[HttpServletResponse::class.java.name] = servletResponse
                })
                .build()
        val authorizedClient = authorizedClientManager.authorize(authorizeRequest)
        val accessToken: OAuth2AccessToken = authorizedClient.accessToken

        // ...

        return "index"
    }
}

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

资源所有者密码凭证

有关资源所有者密码凭证（Resource Owner Password Credentials）许可的更多详细信息，请参阅 OAuth 2.0 授权框架。

请求访问令牌

有关资源所有者密码凭证许可的访问令牌请求/响应协议流程，请参阅。

资源所有者密码凭证许可的 OAuth2AccessTokenResponseClient 默认实现是 DefaultPasswordTokenResponseClient，它在授权服务器的令牌端点请求访问令牌时使用 RestOperations。

DefaultPasswordTokenResponseClient 类和对资源所有者密码凭证许可的支持已被弃用。本节将在 Spring Security 7 中移除。

DefaultPasswordTokenResponseClient 是灵活的，它允许您定制令牌请求的预处理或令牌响应的后处理。

定制访问令牌请求

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

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

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

自定义的 Converter 必须返回一个有效的 OAuth 2.0 访问令牌请求的 RequestEntity 表示，该表示需要被预期的 OAuth 2.0 提供商理解。

定制访问令牌响应

另一方面，如果您需要定制令牌响应的后处理，则需要向 DefaultPasswordTokenResponseClient.setRestOperations() 提供一个自定义配置的 RestOperations。默认的 RestOperations 配置如下

Java
Kotlin

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

restTemplate.setErrorHandler(new OAuth2ErrorResponseErrorHandler());

val restTemplate = RestTemplate(listOf(
        FormHttpMessageConverter(),
        OAuth2AccessTokenResponseHttpMessageConverter()))

restTemplate.errorHandler = OAuth2ErrorResponseErrorHandler()

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

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

使用 Builder 进行自定义

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

通过 Builder 配置访问令牌响应

Java
Kotlin

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

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

// ...

authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider);

val passwordTokenResponseClient: OAuth2AccessTokenResponseClient<OAuth2PasswordGrantRequest> = ...

val authorizedClientProvider = OAuth2AuthorizedClientProviderBuilder.builder()
        .password { it.accessTokenResponseClient(passwordTokenResponseClient) }
        .refreshToken()
        .build()

// ...

authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider)

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

进一步考虑 OAuth2AuthorizedClientManager @Bean

Java
Kotlin

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

@Bean
fun authorizedClientManager(
        clientRegistrationRepository: ClientRegistrationRepository,
        authorizedClientRepository: OAuth2AuthorizedClientRepository): OAuth2AuthorizedClientManager {
    val authorizedClientProvider = OAuth2AuthorizedClientProviderBuilder.builder()
            .password()
            .refreshToken()
            .build()
    val authorizedClientManager = 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 fun contextAttributesMapper(): Function<OAuth2AuthorizeRequest, MutableMap<String, Any>> {
    return Function { authorizeRequest ->
        var contextAttributes: MutableMap<String, Any> = mutableMapOf()
        val servletRequest: HttpServletRequest = authorizeRequest.getAttribute(HttpServletRequest::class.java.name)
        val username = servletRequest.getParameter(OAuth2ParameterNames.USERNAME)
        val password = servletRequest.getParameter(OAuth2ParameterNames.PASSWORD)
        if (StringUtils.hasText(username) && StringUtils.hasText(password)) {
            contextAttributes = hashMapOf()

            // `PasswordOAuth2AuthorizedClientProvider` requires both attributes
            contextAttributes[OAuth2AuthorizationContext.USERNAME_ATTRIBUTE_NAME] = username
            contextAttributes[OAuth2AuthorizationContext.PASSWORD_ATTRIBUTE_NAME] = password
        }
        contextAttributes
    }
}

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

Java
Kotlin

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

@Controller
class OAuth2ClientController {
    @Autowired
    private lateinit var authorizedClientManager: OAuth2AuthorizedClientManager

    @GetMapping("/")
    fun index(authentication: Authentication?,
              servletRequest: HttpServletRequest,
              servletResponse: HttpServletResponse): String {
        val authorizeRequest: OAuth2AuthorizeRequest = OAuth2AuthorizeRequest.withClientRegistrationId("okta")
                .principal(authentication)
                .attributes(Consumer {
                    it[HttpServletRequest::class.java.name] = servletRequest
                    it[HttpServletResponse::class.java.name] = servletResponse
                })
                .build()
        val authorizedClient = authorizedClientManager.authorize(authorizeRequest)
        val accessToken: OAuth2AccessToken = authorizedClient.accessToken

        // ...

        return "index"
    }
}

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

JWT Bearer

请参阅 JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants，以了解关于 JWT Bearer 授权的更多详情。

请求访问令牌

请参阅 JWT Bearer 授权的 Access Token Request/Response 协议流程。

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

DefaultJwtBearerTokenResponseClient (默认)
RestClientJwtBearerTokenResponseClient

本节重点介绍 RestClientJwtBearerTokenResponseClient。您可以在 Spring Security 6.3 文档中阅读有关 DefaultClientCredentialsTokenResponseClient 的信息。

要选择使用 RestClientJwtBearerTokenResponseClient，只需提供如下示例中的 bean，它将由默认的 OAuth2AuthorizedClientManager 自动选取

访问令牌响应配置

Java
Kotlin

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

@Bean
fun accessTokenResponseClient(): OAuth2AccessTokenResponseClient<JWT Bearer> {
	return RestClientJwtBearerTokenResponseClient()
}

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

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

我想自定义访问令牌请求的头部
我想自定义访问令牌请求的参数
我想自定义使用的 RestClient 实例
我想自定义访问令牌响应的参数
我想自定义访问令牌响应的错误处理

自定义访问令牌请求

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

自定义请求头部

定制 HTTP 头有两种选择

通过调用 addHeadersConverter() 添加额外的头
通过调用 setHeadersConverter() 完全定制头

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

包含额外的 HTTP 头

Java
Kotlin

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

val accessTokenResponseClient = RestClientJwtBearerTokenResponseClient()
accessTokenResponseClient.addHeadersConverter { grantRequest ->
	val clientRegistration = grantRequest.getClientRegistration()
	val headers = HttpHeaders()
	if (clientRegistration.getRegistrationId() == "spring") {
        headers[HttpHeaders.USER_AGENT] = "my-user-agent"
	}
	headers
}

定制 HTTP 头

Java
Kotlin

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

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

val headersConverter = DefaultOAuth2TokenRequestHeadersConverter()
headersConverter.setEncodeClientCredentials(false)

val accessTokenResponseClient = RestClientJwtBearerTokenResponseClient()
accessTokenResponseClient.setHeadersConverter(headersConverter)

自定义请求参数

定制请求参数有三种选择

通过调用 addParametersConverter() 添加额外的参数
通过调用 setParametersConverter() 覆盖参数
通过调用 setParametersCustomizer() 完全定制参数

包含额外的请求参数

Java
Kotlin

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

val accessTokenResponseClient = RestClientJwtBearerTokenResponseClient()
accessTokenResponseClient.addParametersConverter { grantRequest ->
	val clientRegistration = grantRequest.getClientRegistration()
	val parameters = LinkedMultiValueMap<String, String>()
	if (clientRegistration.getRegistrationId() == "keycloak") {
        parameters[OAuth2ParameterNames.AUDIENCE] = "my-audience"
	}
	parameters
}

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

覆盖请求参数

Java
Kotlin

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

val parametersConverter = DefaultOAuth2TokenRequestParametersConverter<JwtBearerGrantRequest>()
parametersConverter.setParametersCustomizer { parameters ->
	if (parameters.containsKey(OAuth2ParameterNames.CLIENT_ASSERTION)) {
		parameters.remove(OAuth2ParameterNames.CLIENT_ID)
	}
}

val accessTokenResponseClient = RestClientJwtBearerTokenResponseClient()
accessTokenResponseClient.setParametersConverter { grantRequest ->
    val clientRegistration = grantRequest.getClientRegistration()
	val parameters = LinkedMultiValueMap<String, String>()
	if (clientRegistration.getRegistrationId() == "okta") {
        parameters[OAuth2ParameterNames.CLIENT_ID] = "my-client"
	}
	parameters
}

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

省略请求参数

Java
Kotlin

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

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

自定义访问令牌响应

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

自定义 `RestClient`

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

默认 RestClient 配置

Java
Kotlin

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);

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

val accessTokenResponseClient = RestClientJwtBearerTokenResponseClient()
accessTokenResponseClient.setRestClient(restClient)

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

自定义响应参数

以下示例提供了一个起点，用于定制令牌响应参数到 OAuth2AccessTokenResponse 的转换

定制访问令牌响应转换器

Java
Kotlin

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

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

自定义错误处理

以下示例提供了一个起点，用于定制错误参数到 OAuth2Error 的转换

定制访问令牌错误处理器

Java
Kotlin

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

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

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

val errorHandler = OAuth2ErrorResponseErrorHandler()
errorHandler.setErrorConverter(errorConverter)

使用 Builder 进行自定义

无论您是自定义 RestClientJwtBearerTokenResponseClient 还是提供自己的 OAuth2AccessTokenResponseClient 实现，您都可以使用 OAuth2AuthorizedClientProviderBuilder (作为发布 bean 的替代方案) 进行配置，如下所示

通过 Builder 配置访问令牌响应

Java
Kotlin

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

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

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

// ...

authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider);

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

val jwtBearerAuthorizedClientProvider = JwtBearerOAuth2AuthorizedClientProvider()
jwtBearerAuthorizedClientProvider.setAccessTokenResponseClient(jwtBearerTokenResponseClient)

val authorizedClientProvider = OAuth2AuthorizedClientProviderBuilder.builder()
        .provider(jwtBearerAuthorizedClientProvider)
        .build()

// ...

authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider)

使用访问令牌

给定以下用于 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

…以及 OAuth2AuthorizedClientManager @Bean

Java
Kotlin

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

@Bean
fun authorizedClientManager(
        clientRegistrationRepository: ClientRegistrationRepository,
        authorizedClientRepository: OAuth2AuthorizedClientRepository): OAuth2AuthorizedClientManager {
    val jwtBearerAuthorizedClientProvider = JwtBearerOAuth2AuthorizedClientProvider()
    val authorizedClientProvider = OAuth2AuthorizedClientProviderBuilder.builder()
            .provider(jwtBearerAuthorizedClientProvider)
            .build()
    val authorizedClientManager = DefaultOAuth2AuthorizedClientManager(
            clientRegistrationRepository, authorizedClientRepository)
    authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider)
    return authorizedClientManager
}

您可以通过如下方式获取 OAuth2AccessToken

Java
Kotlin

@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();

		// ...

	}
}

class OAuth2ResourceServerController {

    @Autowired
    private lateinit var authorizedClientManager: OAuth2AuthorizedClientManager

    @GetMapping("/resource")
    fun resource(jwtAuthentication: JwtAuthenticationToken?): String {
        val authorizeRequest: OAuth2AuthorizeRequest = OAuth2AuthorizeRequest.withClientRegistrationId("okta")
                .principal(jwtAuthentication)
                .build()
        val authorizedClient = authorizedClientManager.authorize(authorizeRequest)
        val accessToken: OAuth2AccessToken = authorizedClient.accessToken

        // ...

    }
}

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

如果您需要从不同来源解析 Jwt 断言，您可以为 JwtBearerOAuth2AuthorizedClientProvider.setJwtAssertionResolver() 提供自定义的 Function<OAuth2AuthorizationContext, Jwt>。

令牌交换

请参阅 OAuth 2.0 Token Exchange，以了解关于令牌交换授权的更多详情。

请求访问令牌

请参阅令牌交换授权的 Token Exchange Request and Response 协议流程。

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

DefaultTokenExchangeTokenResponseClient (默认)
RestClientTokenExchangeTokenResponseClient

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

要选择使用 RestClientTokenExchangeTokenResponseClient，只需提供如下示例中的 bean，它将由默认的 OAuth2AuthorizedClientManager 自动选取

访问令牌响应配置

Java
Kotlin

@Bean
public OAuth2AccessTokenResponseClient<TokenExchangeGrantRequest> accessTokenResponseClient() {
	return new RestClientTokenExchangeTokenResponseClient();
}

@Bean
fun accessTokenResponseClient(): OAuth2AccessTokenResponseClient<Token Exchange> {
	return RestClientTokenExchangeTokenResponseClient()
}

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

RestClientTokenExchangeTokenResponseClient 非常灵活，并提供了多种自定义 OAuth 2.0 访问令牌请求和响应（针对令牌交换授权）的选项。从以下用例中选择以了解更多信息

我想自定义访问令牌请求的头部
我想自定义访问令牌请求的参数
我想自定义使用的 RestClient 实例
我想自定义访问令牌响应的参数
我想自定义访问令牌响应的错误处理

自定义访问令牌请求

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

自定义请求头部

定制 HTTP 头有两种选择

通过调用 addHeadersConverter() 添加额外的头
通过调用 setHeadersConverter() 完全定制头

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

包含额外的 HTTP 头

Java
Kotlin

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

val accessTokenResponseClient = RestClientTokenExchangeTokenResponseClient()
accessTokenResponseClient.addHeadersConverter { grantRequest ->
	val clientRegistration = grantRequest.getClientRegistration()
	val headers = HttpHeaders()
	if (clientRegistration.getRegistrationId() == "spring") {
        headers[HttpHeaders.USER_AGENT] = "my-user-agent"
	}
	headers
}

定制 HTTP 头

Java
Kotlin

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

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

val headersConverter = DefaultOAuth2TokenRequestHeadersConverter()
headersConverter.setEncodeClientCredentials(false)

val accessTokenResponseClient = RestClientTokenExchangeTokenResponseClient()
accessTokenResponseClient.setHeadersConverter(headersConverter)

自定义请求参数

定制请求参数有三种选择

通过调用 addParametersConverter() 添加额外的参数
通过调用 setParametersConverter() 覆盖参数
通过调用 setParametersCustomizer() 完全定制参数

包含额外的请求参数

Java
Kotlin

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

val accessTokenResponseClient = RestClientTokenExchangeTokenResponseClient()
accessTokenResponseClient.addParametersConverter { grantRequest ->
	val clientRegistration = grantRequest.getClientRegistration()
	val parameters = LinkedMultiValueMap<String, String>()
	if (clientRegistration.getRegistrationId() == "keycloak") {
        parameters[OAuth2ParameterNames.AUDIENCE] = "my-audience"
	}
	parameters
}

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

覆盖请求参数

Java
Kotlin

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

val parametersConverter = DefaultOAuth2TokenRequestParametersConverter<TokenExchangeGrantRequest>()
parametersConverter.setParametersCustomizer { parameters ->
	if (parameters.containsKey(OAuth2ParameterNames.CLIENT_ASSERTION)) {
		parameters.remove(OAuth2ParameterNames.CLIENT_ID)
	}
}

val accessTokenResponseClient = RestClientTokenExchangeTokenResponseClient()
accessTokenResponseClient.setParametersConverter { grantRequest ->
    val clientRegistration = grantRequest.getClientRegistration()
	val parameters = LinkedMultiValueMap<String, String>()
	if (clientRegistration.getRegistrationId() == "okta") {
        parameters[OAuth2ParameterNames.CLIENT_ID] = "my-client"
	}
	parameters
}

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

省略请求参数

Java
Kotlin

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

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

自定义访问令牌响应

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

自定义 `RestClient`

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

默认 RestClient 配置

Java
Kotlin

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);

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

val accessTokenResponseClient = RestClientTokenExchangeTokenResponseClient()
accessTokenResponseClient.setRestClient(restClient)

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

自定义响应参数

以下示例提供了一个起点，用于定制令牌响应参数到 OAuth2AccessTokenResponse 的转换

定制访问令牌响应转换器

Java
Kotlin

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

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

自定义错误处理

以下示例提供了一个起点，用于定制错误参数到 OAuth2Error 的转换

定制访问令牌错误处理器

Java
Kotlin

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

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

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

val errorHandler = OAuth2ErrorResponseErrorHandler()
errorHandler.setErrorConverter(errorConverter)

使用 Builder 进行自定义

无论您是自定义 RestClientTokenExchangeTokenResponseClient 还是提供自己的 OAuth2AccessTokenResponseClient 实现，您都可以使用 OAuth2AuthorizedClientProviderBuilder (作为发布 bean 的替代方案) 进行配置，如下所示

通过 Builder 配置访问令牌响应

Java
Kotlin

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

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

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

// ...

authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider);

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

val tokenExchangeAuthorizedClientProvider = TokenExchangeOAuth2AuthorizedClientProvider()
tokenExchangeAuthorizedClientProvider.setAccessTokenResponseClient(tokenExchangeTokenResponseClient)

val authorizedClientProvider = OAuth2AuthorizedClientProviderBuilder.builder()
        .provider(tokenExchangeAuthorizedClientProvider)
        .build()

// ...

authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider)

使用访问令牌

给定以下用于 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

…以及 OAuth2AuthorizedClientManager @Bean

Java
Kotlin

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

@Bean
fun authorizedClientManager(
        clientRegistrationRepository: ClientRegistrationRepository,
        authorizedClientRepository: OAuth2AuthorizedClientRepository): OAuth2AuthorizedClientManager {
    val tokenExchangeAuthorizedClientProvider = TokenExchangeOAuth2AuthorizedClientProvider()
    val authorizedClientProvider = OAuth2AuthorizedClientProviderBuilder.builder()
            .provider(tokenExchangeAuthorizedClientProvider)
            .build()
    val authorizedClientManager = DefaultOAuth2AuthorizedClientManager(
            clientRegistrationRepository, authorizedClientRepository)
    authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider)
    return authorizedClientManager
}

您可以通过如下方式获取 OAuth2AccessToken

Java
Kotlin

@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();

		// ...

	}
}

class OAuth2ResourceServerController {

    @Autowired
    private lateinit var authorizedClientManager: OAuth2AuthorizedClientManager

    @GetMapping("/resource")
    fun resource(jwtAuthentication: JwtAuthenticationToken?): String {
        val authorizeRequest: OAuth2AuthorizeRequest = OAuth2AuthorizeRequest.withClientRegistrationId("okta")
                .principal(jwtAuthentication)
                .build()
        val authorizedClient = authorizedClientManager.authorize(authorizeRequest)
        val accessToken: OAuth2AccessToken = authorizedClient.accessToken

        // ...

    }
}

默认情况下，TokenExchangeOAuth2AuthorizedClientProvider 通过 OAuth2AuthorizationContext.getPrincipal().getPrincipal() 解析 subject token (作为 OAuth2Token)，因此在前述示例中使用了 JwtAuthenticationToken。actor token 默认情况下不会被解析。

如果您需要从不同来源解析 subject token，您可以为 TokenExchangeOAuth2AuthorizedClientProvider.setSubjectTokenResolver() 提供自定义的 Function<OAuth2AuthorizationContext, OAuth2Token>。

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

授权许可支持

授权码

获取授权

发起授权请求

定制授权请求

存储授权请求

请求访问令牌

定制访问令牌请求

定制请求头

定制请求参数

定制访问令牌响应

定制 WebClient

定制响应参数

定制错误处理

使用 DSL 定制

刷新令牌

刷新访问令牌

定制访问令牌请求

定制请求头

定制请求参数

定制访问令牌响应

定制 WebClient

定制响应参数

定制错误处理

使用 Builder 定制

客户端凭证

请求访问令牌

定制访问令牌请求

定制请求头

定制请求参数

定制访问令牌响应

定制 WebClient

定制响应参数

定制错误处理

使用 Builder 定制

使用访问令牌

资源所有者密码凭证

请求访问令牌

定制访问令牌请求

定制访问令牌响应

使用 Builder 进行自定义

使用访问令牌

JWT Bearer

请求访问令牌

自定义访问令牌请求

自定义请求头部

自定义请求参数

自定义访问令牌响应

自定义 RestClient

自定义响应参数

自定义错误处理

使用 Builder 进行自定义

使用访问令牌

令牌交换

请求访问令牌

自定义访问令牌请求

自定义请求头部

自定义请求参数

自定义访问令牌响应

自定义 RestClient

自定义响应参数

自定义错误处理

使用 Builder 进行自定义

使用访问令牌

定制 `WebClient`

定制 `WebClient`

定制 `WebClient`

自定义 `RestClient`

自定义 `RestClient`