授權客戶端功能

本節涵蓋 Spring Security 為 OAuth2 客戶端提供的附加功能。

解析授權客戶端

@RegisteredOAuth2AuthorizedClient 註解提供了將方法引數解析為 OAuth2AuthorizedClient 型別引數值的能力。與使用 OAuth2AuthorizedClientManager 或 OAuth2AuthorizedClientService 訪問 OAuth2AuthorizedClient 相比，這是一種方便的替代方法。以下示例展示瞭如何使用 @RegisteredOAuth2AuthorizedClient

Java
Kotlin

@Controller
public class OAuth2ClientController {

	@GetMapping("/")
	public String index(@RegisteredOAuth2AuthorizedClient("okta") OAuth2AuthorizedClient authorizedClient) {
		OAuth2AccessToken accessToken = authorizedClient.getAccessToken();

		...

		return "index";
	}
}

@Controller
class OAuth2ClientController {
    @GetMapping("/")
    fun index(@RegisteredOAuth2AuthorizedClient("okta") authorizedClient: OAuth2AuthorizedClient): String {
        val accessToken = authorizedClient.accessToken

        ...

        return "index"
    }
}

@RegisteredOAuth2AuthorizedClient 註解由 OAuth2AuthorizedClientArgumentResolver 處理，它直接使用 OAuth2AuthorizedClientManager，因此繼承了其能力。

RestClient 整合

OAuth2ClientHttpRequestInterceptor 提供了對 RestClient 的支援。此攔截器透過在出站請求的 Authorization 頭部放置 Bearer 令牌來請求受保護資源。此攔截器直接使用 OAuth2AuthorizedClientManager，因此繼承了以下能力

如果客戶端尚未獲得授權，則執行 OAuth 2.0 訪問令牌請求以獲取 OAuth2AccessToken
- authorization_code：觸發授權請求重定向以啟動流程
- client_credentials：訪問令牌直接從令牌端點獲取
- 透過啟用擴充套件授權型別支援其他授權型別
如果現有 OAuth2AccessToken 已過期，則重新整理（或續訂）它

以下示例使用預設的 OAuth2AuthorizedClientManager 配置 RestClient，它能夠透過在每個請求的 Authorization 頭部放置 Bearer 令牌來訪問受保護資源

使用 ClientHttpRequestInterceptor 配置 RestClient

Java
Kotlin

@Configuration
public class RestClientConfig {

	@Bean
	public RestClient restClient(OAuth2AuthorizedClientManager authorizedClientManager) {
		OAuth2ClientHttpRequestInterceptor requestInterceptor =
				new OAuth2ClientHttpRequestInterceptor(authorizedClientManager);

		return RestClient.builder()
				.requestInterceptor(requestInterceptor)
				.build();
	}

}

@Configuration
class RestClientConfig {

	@Bean
	fun restClient(authorizedClientManager: OAuth2AuthorizedClientManager): RestClient {
		val requestInterceptor = OAuth2ClientHttpRequestInterceptor(authorizedClientManager)

		return RestClient.builder()
			.requestInterceptor(requestInterceptor)
			.build()
	}

}

提供 `clientRegistrationId`

OAuth2ClientHttpRequestInterceptor 使用 ClientRegistrationIdResolver 來確定使用哪個客戶端獲取訪問令牌。預設情況下，RequestAttributeClientRegistrationIdResolver 用於從 HttpRequest#attributes() 解析 clientRegistrationId。

以下示例演示了透過屬性提供 clientRegistrationId

透過屬性提供 clientRegistrationId

Java
Kotlin

import static org.springframework.security.oauth2.client.web.client.RequestAttributeClientRegistrationIdResolver.clientRegistrationId;

@Controller
public class ResourceController {

	private final RestClient restClient;

	public ResourceController(RestClient restClient) {
		this.restClient = restClient;
	}

	@GetMapping("/")
	public String index() {
		String resourceUri = "...";

		String body = this.restClient.get()
				.uri(resourceUri)
				.attributes(clientRegistrationId("okta"))   (1)
				.retrieve()
				.body(String.class);

		// ...

		return "index";
	}

}

import org.springframework.security.oauth2.client.web.client.RequestAttributeClientRegistrationIdResolver.clientRegistrationId
import org.springframework.web.client.body

@Controller
class ResourceController(private restClient: RestClient) {

	@GetMapping("/")
	fun index(): String {
		val resourceUri = "..."

		val body: String = restClient.get()
				.uri(resourceUri)
				.attributes(clientRegistrationId("okta"))   (1)
				.retrieve()
				.body<String>()

		// ...

		return "index"
	}

}

1	`clientRegistrationId()` 是 `RequestAttributeClientRegistrationIdResolver` 中的一個 `static` 方法。

或者，可以提供自定義的 ClientRegistrationIdResolver。以下示例配置了一個自定義實現，它從當前使用者解析 clientRegistrationId。

使用自定義 ClientRegistrationIdResolver 配置 ClientHttpRequestInterceptor

Java
Kotlin

@Configuration
public class RestClientConfig {

	@Bean
	public RestClient restClient(OAuth2AuthorizedClientManager authorizedClientManager) {
		OAuth2ClientHttpRequestInterceptor requestInterceptor =
				new OAuth2ClientHttpRequestInterceptor(authorizedClientManager);
		requestInterceptor.setClientRegistrationIdResolver(clientRegistrationIdResolver());

		return RestClient.builder()
				.requestInterceptor(requestInterceptor)
				.build();
	}

	private static ClientRegistrationIdResolver clientRegistrationIdResolver() {
		return (request) -> {
			Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
			return (authentication instanceof OAuth2AuthenticationToken principal)
					? principal.getAuthorizedClientRegistrationId() : null;
		};
	}

}

@Configuration
class RestClientConfig {

	@Bean
	fun restClient(authorizedClientManager: OAuth2AuthorizedClientManager): RestClient {
		val requestInterceptor = OAuth2ClientHttpRequestInterceptor(authorizedClientManager)
		requestInterceptor.setClientRegistrationIdResolver(clientRegistrationIdResolver())

		return RestClient.builder()
			.requestInterceptor(requestInterceptor)
			.build()
	}

	fun clientRegistrationIdResolver(): ClientRegistrationIdResolver {
		return ClientRegistrationIdResolver { request ->
			val authentication = SecurityContextHolder.getContext().getAuthentication()
			return if (authentication instanceof OAuth2AuthenticationToken) {
				authentication.getAuthorizedClientRegistrationId()
			} else {
                null
			}
		}
	}

}

提供 `principal`

OAuth2ClientHttpRequestInterceptor 使用 PrincipalResolver 來確定與訪問令牌關聯的主體名稱，這允許應用程式選擇如何作用域儲存的 OAuth2AuthorizedClient。預設情況下，SecurityContextHolderPrincipalResolver 用於從 SecurityContextHolder 解析當前 principal。

或者，可以透過配置 RequestAttributePrincipalResolver 從 HttpRequest#attributes() 解析 principal，如下例所示

使用 RequestAttributePrincipalResolver 配置 ClientHttpRequestInterceptor

Java
Kotlin

@Configuration
public class RestClientConfig {

	@Bean
	public RestClient restClient(OAuth2AuthorizedClientManager authorizedClientManager) {
		OAuth2ClientHttpRequestInterceptor requestInterceptor =
				new OAuth2ClientHttpRequestInterceptor(authorizedClientManager);
		requestInterceptor.setPrincipalResolver(new RequestAttributePrincipalResolver());

		return RestClient.builder()
				.requestInterceptor(requestInterceptor)
				.build();
	}

}

@Configuration
class RestClientConfig {

	@Bean
	fun restClient(authorizedClientManager: OAuth2AuthorizedClientManager): RestClient {
		val requestInterceptor = OAuth2ClientHttpRequestInterceptor(authorizedClientManager)
		requestInterceptor.setPrincipalResolver(RequestAttributePrincipalResolver())

		return RestClient.builder()
			.requestInterceptor(requestInterceptor)
			.build()
	}

}

以下示例演示了透過屬性提供 principal 名稱，該名稱將 OAuth2AuthorizedClient 的作用域設定為應用程式而不是當前使用者

透過屬性提供 principal 名稱

Java
Kotlin

import static org.springframework.security.oauth2.client.web.client.RequestAttributeClientRegistrationIdResolver.clientRegistrationId;
import static org.springframework.security.oauth2.client.web.client.RequestAttributePrincipalResolver.principal;

@Controller
public class ResourceController {

	private final RestClient restClient;

	public ResourceController(RestClient restClient) {
		this.restClient = restClient;
	}

	@GetMapping("/")
	public String index() {
		String resourceUri = "...";

		String body = this.restClient.get()
				.uri(resourceUri)
				.attributes(clientRegistrationId("okta"))
				.attributes(principal("my-application"))   (1)
				.retrieve()
				.body(String.class);

		// ...

		return "index";
	}

}

import org.springframework.security.oauth2.client.web.client.RequestAttributeClientRegistrationIdResolver.clientRegistrationId
import org.springframework.security.oauth2.client.web.client.RequestAttributePrincipalResolver.principal
import org.springframework.web.client.body

@Controller
class ResourceController(private restClient: RestClient) {

    @GetMapping("/")
	fun index(): String {
		val resourceUri = "..."

		val body: String = restClient.get()
				.uri(resourceUri)
				.attributes(clientRegistrationId("okta"))
				.attributes(principal("my-application"))   (1)
				.retrieve()
				.body<String>()

		// ...

		return "index"
	}

}

1	`principal()` 是 `RequestAttributePrincipalResolver` 中的一個 `static` 方法。

處理失敗

如果訪問令牌因任何原因（例如過期令牌）無效，則透過刪除訪問令牌以使其無法再次使用來處理失敗可能會很有益。您可以設定攔截器，透過提供 OAuth2AuthorizationFailureHandler 自動執行此操作以刪除訪問令牌。

以下示例使用 OAuth2AuthorizedClientRepository 設定 OAuth2AuthorizationFailureHandler，該處理程式在 HttpServletRequest 的上下文中刪除無效的 OAuth2AuthorizedClient

使用 OAuth2AuthorizedClientRepository 配置 OAuth2AuthorizationFailureHandler

Java
Kotlin

@Configuration
public class RestClientConfig {

	@Bean
	public RestClient restClient(OAuth2AuthorizedClientManager authorizedClientManager,
			OAuth2AuthorizedClientRepository authorizedClientRepository) {

		OAuth2ClientHttpRequestInterceptor requestInterceptor =
				new OAuth2ClientHttpRequestInterceptor(authorizedClientManager);

		OAuth2AuthorizationFailureHandler authorizationFailureHandler =
			OAuth2ClientHttpRequestInterceptor.authorizationFailureHandler(authorizedClientRepository);
		requestInterceptor.setAuthorizationFailureHandler(authorizationFailureHandler);

		return RestClient.builder()
				.requestInterceptor(requestInterceptor)
				.build();
	}

}

@Configuration
class RestClientConfig {

	@Bean
	fun restClient(authorizedClientManager: OAuth2AuthorizedClientManager,
			authorizedClientRepository: OAuth2AuthorizedClientRepository): RestClient {

		val requestInterceptor = OAuth2ClientHttpRequestInterceptor(authorizedClientManager)

		val authorizationFailureHandler = OAuth2ClientHttpRequestInterceptor
			.authorizationFailureHandler(authorizedClientRepository)
		requestInterceptor.setAuthorizationFailureHandler(authorizationFailureHandler)

		return RestClient.builder()
			.requestInterceptor(requestInterceptor)
			.build()
	}

}

或者，可以使用 OAuth2AuthorizedClientService 在 HttpServletRequest 的上下文之外刪除無效的 OAuth2AuthorizedClient，如下例所示

使用 OAuth2AuthorizedClientService 配置 OAuth2AuthorizationFailureHandler

Java
Kotlin

@Configuration
public class RestClientConfig {

	@Bean
	public RestClient restClient(OAuth2AuthorizedClientManager authorizedClientManager,
			OAuth2AuthorizedClientService authorizedClientService) {

		OAuth2ClientHttpRequestInterceptor requestInterceptor =
				new OAuth2ClientHttpRequestInterceptor(authorizedClientManager);

		OAuth2AuthorizationFailureHandler authorizationFailureHandler =
			OAuth2ClientHttpRequestInterceptor.authorizationFailureHandler(authorizedClientService);
		requestInterceptor.setAuthorizationFailureHandler(authorizationFailureHandler);

		return RestClient.builder()
				.requestInterceptor(requestInterceptor)
				.build();
	}

}

@Configuration
class RestClientConfig {

	@Bean
	fun restClient(authorizedClientManager: OAuth2AuthorizedClientManager,
			authorizedClientService: OAuth2AuthorizedClientService): RestClient {

		val requestInterceptor = OAuth2ClientHttpRequestInterceptor(authorizedClientManager)

		val authorizationFailureHandler = OAuth2ClientHttpRequestInterceptor
			.authorizationFailureHandler(authorizedClientService)
		requestInterceptor.setAuthorizationFailureHandler(authorizationFailureHandler)

		return RestClient.builder()
			.requestInterceptor(requestInterceptor)
			.build()
	}

}

HTTP 服務客戶端

Spring Security 的 OAuth 支援與 HTTP 服務客戶端整合整合。

WebClient 對 Servlet 環境的整合

OAuth 2.0 客戶端支援透過使用 ExchangeFilterFunction 與 WebClient 整合。

ServletOAuth2AuthorizedClientExchangeFilterFunction 提供了一種使用 OAuth2AuthorizedClient 請求受保護資源並將關聯的 OAuth2AccessToken 作為 Bearer 令牌包含在內的機制。它直接使用 OAuth2AuthorizedClientManager，因此繼承了以下功能

如果客戶端尚未獲得授權，則請求 OAuth2AccessToken。
- authorization_code：觸發授權請求重定向以啟動流程。
- client_credentials：訪問令牌直接從令牌端點獲取。
如果 OAuth2AccessToken 已過期，並且 OAuth2AuthorizedClientProvider 可用於執行授權，則重新整理（或續訂）它

以下程式碼顯示瞭如何使用 OAuth 2.0 客戶端支援配置 WebClient 的示例

Java
Kotlin

@Bean
WebClient webClient(OAuth2AuthorizedClientManager authorizedClientManager) {
	ServletOAuth2AuthorizedClientExchangeFilterFunction oauth2Client =
			new ServletOAuth2AuthorizedClientExchangeFilterFunction(authorizedClientManager);
	return WebClient.builder()
			.apply(oauth2Client.oauth2Configuration())
			.build();
}

@Bean
fun webClient(authorizedClientManager: OAuth2AuthorizedClientManager?): WebClient {
    val oauth2Client = ServletOAuth2AuthorizedClientExchangeFilterFunction(authorizedClientManager)
    return WebClient.builder()
            .apply(oauth2Client.oauth2Configuration())
            .build()
}

提供授權客戶端

ServletOAuth2AuthorizedClientExchangeFilterFunction 透過從 ClientRequest.attributes()（請求屬性）解析 OAuth2AuthorizedClient 來確定要使用的客戶端（用於請求）。

以下程式碼顯示瞭如何將 OAuth2AuthorizedClient 設定為請求屬性

Java
Kotlin

@GetMapping("/")
public String index(@RegisteredOAuth2AuthorizedClient("okta") OAuth2AuthorizedClient authorizedClient) {
	String resourceUri = ...

	String body = webClient
			.get()
			.uri(resourceUri)
			.attributes(oauth2AuthorizedClient(authorizedClient))   (1)
			.retrieve()
			.bodyToMono(String.class)
			.block();

	...

	return "index";
}

@GetMapping("/")
fun index(@RegisteredOAuth2AuthorizedClient("okta") authorizedClient: OAuth2AuthorizedClient): String {
    val resourceUri: String = ...
    val body: String = webClient
            .get()
            .uri(resourceUri)
            .attributes(oauth2AuthorizedClient(authorizedClient)) (1)
            .retrieve()
            .bodyToMono()
            .block()

    ...

    return "index"
}

1	`oauth2AuthorizedClient()` 是 `ServletOAuth2AuthorizedClientExchangeFilterFunction` 中的一個 `static` 方法。

以下程式碼顯示瞭如何將 ClientRegistration.getRegistrationId() 設定為請求屬性

Java
Kotlin

@GetMapping("/")
public String index() {
	String resourceUri = ...

	String body = webClient
			.get()
			.uri(resourceUri)
			.attributes(clientRegistrationId("okta"))   (1)
			.retrieve()
			.bodyToMono(String.class)
			.block();

	...

	return "index";
}

@GetMapping("/")
fun index(): String {
    val resourceUri: String = ...

    val body: String = webClient
            .get()
            .uri(resourceUri)
            .attributes(clientRegistrationId("okta"))  (1)
            .retrieve()
            .bodyToMono()
            .block()

    ...

    return "index"
}

1	`clientRegistrationId()` 是 `ServletOAuth2AuthorizedClientExchangeFilterFunction` 中的一個 `static` 方法。

以下程式碼顯示瞭如何將 Authentication 設定為請求屬性

Java
Kotlin

@GetMapping("/")
public String index() {
	String resourceUri = ...

	Authentication anonymousAuthentication = new AnonymousAuthenticationToken(
			"anonymous", "anonymousUser", AuthorityUtils.createAuthorityList("ROLE_ANONYMOUS"));
	String body = webClient
			.get()
			.uri(resourceUri)
			.attributes(authentication(anonymousAuthentication))   (1)
			.retrieve()
			.bodyToMono(String.class)
			.block();

	...

	return "index";
}

@GetMapping("/")
fun index(): String {
    val resourceUri: String = ...

    val anonymousAuthentication: Authentication = AnonymousAuthenticationToken(
            "anonymous", "anonymousUser", AuthorityUtils.createAuthorityList("ROLE_ANONYMOUS"))
    val body: String = webClient
            .get()
            .uri(resourceUri)
            .attributes(authentication(anonymousAuthentication))  (1)
            .retrieve()
            .bodyToMono()
            .block()

    ...

    return "index"
}

1	`authentication()` 是 `ServletOAuth2AuthorizedClientExchangeFilterFunction` 中的一個 `static` 方法。

建議對此功能謹慎，因為所有 HTTP 請求都將收到繫結到所提供主體的訪問令牌。

預設授權客戶端

如果未將 OAuth2AuthorizedClient 或 ClientRegistration.getRegistrationId() 作為請求屬性提供，則 ServletOAuth2AuthorizedClientExchangeFilterFunction 可以根據其配置確定要使用的預設客戶端。

如果配置了 setDefaultOAuth2AuthorizedClient(true) 並且使用者已使用 HttpSecurity.oauth2Login() 進行身份驗證，則使用與當前 OAuth2AuthenticationToken 關聯的 OAuth2AccessToken。

以下程式碼顯示了具體配置

Java
Kotlin

@Bean
WebClient webClient(OAuth2AuthorizedClientManager authorizedClientManager) {
	ServletOAuth2AuthorizedClientExchangeFilterFunction oauth2Client =
			new ServletOAuth2AuthorizedClientExchangeFilterFunction(authorizedClientManager);
	oauth2Client.setDefaultOAuth2AuthorizedClient(true);
	return WebClient.builder()
			.apply(oauth2Client.oauth2Configuration())
			.build();
}

@Bean
fun webClient(authorizedClientManager: OAuth2AuthorizedClientManager?): WebClient {
    val oauth2Client = ServletOAuth2AuthorizedClientExchangeFilterFunction(authorizedClientManager)
    oauth2Client.setDefaultOAuth2AuthorizedClient(true)
    return WebClient.builder()
            .apply(oauth2Client.oauth2Configuration())
            .build()
}

對此功能要謹慎，因為所有 HTTP 請求都會收到訪問令牌。

或者，如果使用有效的 ClientRegistration 配置了 setDefaultClientRegistrationId("okta")，則使用與 OAuth2AuthorizedClient 關聯的 OAuth2AccessToken。