已授权客户端特性

本节介绍 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 集成

对 RestClient 的支持由 OAuth2ClientHttpRequestInterceptor 提供。此拦截器提供了通过将 Bearer 令牌放在出站请求的 Authorization 头中来发起对受保护资源的请求的能力。该拦截器直接使用 OAuth2AuthorizedClientManager，因此继承了以下能力

  • 如果客户端尚未被授权，则执行 OAuth 2.0 访问令牌请求以获取 OAuth2AccessToken

    • authorization_code：触发授权请求重定向以启动流程

    • client_credentials：直接从令牌端点获取访问令牌

    • password：直接从令牌端点获取访问令牌

    • 通过启用扩展授权类型支持其他授权类型

  • 如果现有的 OAuth2AccessToken 已过期，则会刷新（或续期）

以下示例使用默认的 OAuth2AuthorizedClientManager 配置一个能够通过在每个请求的 Authorization 头中放置 Bearer 令牌来访问受保护资源的 RestClient

使用 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()
	}

}

Servlet 环境下的 WebClient 集成

OAuth 2.0 客户端支持通过使用 ExchangeFilterFunction 集成到 WebClient 中。

ServletOAuth2AuthorizedClientExchangeFilterFunction 提供了一种机制，用于使用 OAuth2AuthorizedClient 并将关联的 OAuth2AccessToken 作为 Bearer 令牌包含在内，从而请求受保护的资源。它直接使用 OAuth2AuthorizedClientManager，因此继承了以下能力

  • 如果客户端尚未被授权，则请求一个 OAuth2AccessToken。

    • authorization_code：触发授权请求重定向以启动流程。

    • client_credentials：直接从令牌端点获取访问令牌。

    • password：直接从令牌端点获取访问令牌。

  • 如果 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。

以下代码展示了具体的配置

  • Java

  • Kotlin

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

谨慎使用此特性，因为所有 HTTP 请求都会接收到访问令牌。