授權許可支援

本節描述了 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

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

  2. 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 訪問令牌請求和響應提供了多種定製選項。從以下用例中選擇以瞭解更多資訊

定製訪問令牌請求

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

預設實現使用一個 RestOperations 例項在授權伺服器的令牌端點交換授權碼以獲取訪問令牌。Spring Security 6.4 引入了一個基於 RestClient 的新實現，它提供類似的功能，但與該元件的響應式版本（基於 WebClient）更一致，以便為任一棧上的應用程式提供一致的配置。

本節重點介紹 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 訪問令牌請求和響應提供了多種定製選項。從以下用例中選擇以瞭解更多資訊

定製訪問令牌請求

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
}

您可以透過重用 DefaultOAuth2TokenRequestHeadersConverter 或提供一個自定義實現並使用 setHeadersConverter() 來完全定製頭。以下示例重用 DefaultOAuth2TokenRequestHeadersConverter 並停用 encodeClientCredentials，以便 HTTP Basic 憑證不再使用 application/x-www-form-urlencoded 編碼

定製 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() 完全定製引數

使用 setParametersConverter() 不能完全定製引數，因為它需要使用者自己提供所有預設引數。預設引數總是提供的，但可以透過呼叫 setParametersCustomizer() 完全定製或省略。

您可以使用 addParametersConverter() 包含額外的引數，而不會影響新增到每個請求的預設引數。以下示例在 registrationId 為 keycloak 時向請求新增一個 audience 引數

包含額外的請求引數

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

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)

使用 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

預設實現使用一個 RestOperations 例項在授權伺服器的令牌端點交換授權碼以獲取訪問令牌。Spring Security 6.4 引入了一個基於 RestClient 的新實現，它提供類似的功能，但與該元件的響應式版本（基於 WebClient）更一致，以便為任一棧上的應用程式提供一致的配置。

本節重點介紹 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 訪問令牌請求和響應提供了多種定製選項。從以下用例中選擇以瞭解更多資訊

定製訪問令牌請求

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
}

您可以透過重用 DefaultOAuth2TokenRequestHeadersConverter 或提供一個自定義實現並使用 setHeadersConverter() 來完全定製頭。以下示例重用 DefaultOAuth2TokenRequestHeadersConverter 並停用 encodeClientCredentials，以便 HTTP Basic 憑證不再使用 application/x-www-form-urlencoded 編碼

定製 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() 完全定製引數

使用 setParametersConverter() 不能完全定製引數，因為它需要使用者自己提供所有預設引數。預設引數總是提供的，但可以透過呼叫 setParametersCustomizer() 完全定製或省略。

您可以使用 addParametersConverter() 包含額外的引數，而不會影響新增到每個請求的預設引數。以下示例在 registrationId 為 keycloak 時向請求新增一個 audience 引數

包含額外的請求引數

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

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)

使用 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。

OAuth2ErrorResponseErrorHandler 是一個可以處理 OAuth 2.0 錯誤（例如 400 Bad Request）的 ResponseErrorHandler。它使用一個 OAuth2ErrorHttpMessageConverter 將 OAuth 2.0 錯誤引數轉換為 OAuth2Error。

使用 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

預設實現使用一個 RestOperations 例項在授權伺服器的令牌端點交換授權碼以獲取訪問令牌。Spring Security 6.4 引入了一個基於 RestClient 的新實現，它提供類似的功能，但與該元件的響應式版本（基於 WebClient）更一致，以便為任一棧上的應用程式提供一致的配置。

本節重點介紹 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 授權）的選項。從以下用例中選擇以瞭解更多資訊

自定義訪問令牌請求

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
}

您可以透過重用 DefaultOAuth2TokenRequestHeadersConverter 或提供一個自定義實現並使用 setHeadersConverter() 來完全定製頭。以下示例重用 DefaultOAuth2TokenRequestHeadersConverter 並停用 encodeClientCredentials，以便 HTTP Basic 憑證不再使用 application/x-www-form-urlencoded 編碼

定製 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() 完全定製引數

使用 setParametersConverter() 不能完全定製引數，因為它需要使用者自己提供所有預設引數。預設引數總是提供的，但可以透過呼叫 setParametersCustomizer() 完全定製或省略。

您可以使用 addParametersConverter() 包含額外的引數，而不會影響新增到每個請求的預設引數。以下示例在 registrationId 為 keycloak 時向請求新增一個 audience 引數

包含額外的請求引數

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

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)

使用 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

預設實現使用一個 RestOperations 例項在授權伺服器的令牌端點交換授權碼以獲取訪問令牌。Spring Security 6.4 引入了一個基於 RestClient 的新實現，它提供類似的功能，但與該元件的響應式版本（基於 WebClient）更一致，以便為任一棧上的應用程式提供一致的配置。

本節重點介紹 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 訪問令牌請求和響應（針對令牌交換授權）的選項。從以下用例中選擇以瞭解更多資訊

自定義訪問令牌請求

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
}

您可以透過重用 DefaultOAuth2TokenRequestHeadersConverter 或提供一個自定義實現並使用 setHeadersConverter() 來完全定製頭。以下示例重用 DefaultOAuth2TokenRequestHeadersConverter 並停用 encodeClientCredentials，以便 HTTP Basic 憑證不再使用 application/x-www-form-urlencoded 編碼

定製 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() 完全定製引數

使用 setParametersConverter() 不能完全定製引數，因為它需要使用者自己提供所有預設引數。預設引數總是提供的，但可以透過呼叫 setParametersCustomizer() 完全定製或省略。

您可以使用 addParametersConverter() 包含額外的引數，而不會影響新增到每個請求的預設引數。以下示例在 registrationId 為 keycloak 時向請求新增一個 audience 引數

包含額外的請求引數

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

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)

使用 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>。