QWen Max 中英对照 OAuth2 Authorized Clients #

授权的客户端功能

本节介绍 Spring Security 为 OAuth2 客户端提供的附加功能。

解决授权客户端

@RegisteredOAuth2AuthorizedClient 注解提供了将方法参数解析为 OAuth2AuthorizedClient 类型参数值的能力。与使用 OAuth2AuthorizedClientManager 或 OAuth2AuthorizedClientService 访问 OAuth2AuthorizedClient 相比，这是一种方便的替代方法。以下示例展示了如何使用 @RegisteredOAuth2AuthorizedClient：

Java

@Controller
public class OAuth2ClientController {

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

        ...

        return "index";
    }
}

java

Kotlin

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

        ...

        return "index"
    }
}

kotlin

@RegisteredOAuth2AuthorizedClient 注解由 OAuth2AuthorizedClientArgumentResolver 处理，该解析器直接使用 OAuth2AuthorizedClientManager，因此继承了其功能。

RestClient 集成

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

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

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

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

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

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

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

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

Java

@Configuration
public class RestClientConfig {

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

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

}

java

Kotlin

@Configuration
class RestClientConfig {

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

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

}

kotlin

提供 clientRegistrationId

OAuth2ClientHttpRequestInterceptor 使用 ClientRegistrationIdResolver 来确定使用哪个客户端来获取访问令牌。默认情况下，使用 RequestAttributeClientRegistrationIdResolver 从 HttpRequest#attributes() 中解析 clientRegistrationId。

以下示例演示了通过属性提供 clientRegistrationId：

Java

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

}

java

Kotlin

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

}

kotlin

• clientRegistrationId() 是 RequestAttributeClientRegistrationIdResolver 中的 static 方法。

或者，可以提供一个自定义的 ClientRegistrationIdResolver。以下示例配置了一个自定义实现，该实现从当前用户中解析 clientRegistrationId。

Java

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

}

java

Kotlin

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

}

kotlin

提供 principal

OAuth2ClientHttpRequestInterceptor 使用 PrincipalResolver 来确定与访问令牌关联的主体名称，这允许应用程序选择如何限定存储的 OAuth2AuthorizedClient 的范围。默认情况下，使用 SecurityContextHolderPrincipalResolver 从 SecurityContextHolder 中解析当前的 principal。

或者，可以通过配置 RequestAttributePrincipalResolver 从 HttpRequest#attributes() 中解析 principal，如下例所示：

Java

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

}

java

Kotlin

@Configuration
class RestClientConfig {

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

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

}

kotlin

以下示例演示了如何通过属性提供 principal 名称，从而将 OAuth2AuthorizedClient 的作用范围限定为应用程序而不是当前用户：

Java

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

}

java

Kotlin

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

}

kotlin

• principal() 是 RequestAttributePrincipalResolver 中的 static 方法。

处理失败

如果访问令牌由于任何原因（例如，令牌已过期）无效，处理失败时移除访问令牌是有益的，这样它就不能再被使用。你可以通过提供一个 OAuth2AuthorizationFailureHandler 来设置拦截器自动执行此操作，以移除访问令牌。

以下示例使用 OAuth2AuthorizedClientRepository 来设置一个 OAuth2AuthorizationFailureHandler，该处理器会在 HttpServletRequest 的上下文中移除无效的 OAuth2AuthorizedClient：

Java

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

}

java

Kotlin

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

}

kotlin

或者，可以使用 OAuth2AuthorizedClientService 在 HttpServletRequest 的外部上下文中移除无效的 OAuth2AuthorizedClient，如下例所示：

Java

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

}

java

Kotlin

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

}

kotlin

适用于 Servlet 环境的 WebClient 集成

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

ServletOAuth2AuthorizedClientExchangeFilterFunction 提供了一种机制，通过使用 OAuth2AuthorizedClient 并将关联的 OAuth2AccessToken 作为 Bearer Token 来请求受保护的资源。它直接使用 OAuth2AuthorizedClientManager，因此继承了以下功能：

• 如果客户端尚未获得授权，则请求 OAuth2AccessToken。

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

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

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

• 如果 OAuth2AccessToken 已过期，如果有可用的 OAuth2AuthorizedClientProvider 来执行授权，则会刷新（或更新）该令牌。

以下代码展示了如何配置带有 OAuth 2.0 客户端支持的 WebClient：

// 代码示例

java

Java

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

java

Kotlin

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

kotlin

提供授权客户端

ServletOAuth2AuthorizedClientExchangeFilterFunction 通过从 ClientRequest.attributes()（请求属性）中解析 OAuth2AuthorizedClient 来确定要使用的客户端（对于一个请求）。

以下代码展示了如何将 OAuth2AuthorizedClient 设置为请求属性：

Java

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

java

Kotlin

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

kotlin

• oauth2AuthorizedClient() 是 ServletOAuth2AuthorizedClientExchangeFilterFunction 中的一个 static 方法。

以下代码展示了如何将 ClientRegistration.getRegistrationId() 设置为请求属性：

Java

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

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

    ...

    return "index";
}

java

Kotlin

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

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

    ...

    return "index"
}

kotlin

• clientRegistrationId() 是 ServletOAuth2AuthorizedClientExchangeFilterFunction 中的 static 方法。

以下代码展示了如何将 Authentication 设置为请求属性：

// 代码示例

java

Java

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

java

Kotlin

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

kotlin

• authentication() 是 ServletOAuth2AuthorizedClientExchangeFilterFunction 中的 static 方法。

注意

建议谨慎使用此功能，因为所有 HTTP 请求都会收到与提供的主体绑定的访问令牌。

默认授权客户端

如果未将 OAuth2AuthorizedClient 或 ClientRegistration.getRegistrationId() 作为请求属性提供，则 ServletOAuth2AuthorizedClientExchangeFilterFunction 可以根据其配置确定要使用的默认客户端。

如果配置了 setDefaultOAuth2AuthorizedClient(true) 并且用户已通过 HttpSecurity.oauth2Login() 进行身份验证，则会使用与当前 OAuth2AuthenticationToken 关联的 OAuth2AccessToken。

以下代码显示了具体配置：

Java

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

java

Kotlin

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

kotlin

注意

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

或者，如果使用有效的 ClientRegistration 配置了 setDefaultClientRegistrationId("okta")，则使用与 OAuth2AuthorizedClient 关联的 OAuth2AccessToken。

以下代码显示了特定配置：

Java

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

java

Kotlin

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

kotlin

注意

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