跳到主要内容

OAuth 2.0 资源服务器不透明令牌

QWen Max 中英对照 Opaque Token OAuth 2.0 Resource Server Opaque Token

用于自省的最小依赖项​

如JWT的最小依赖项中所述，资源服务器支持的大部分功能都集中在spring-security-oauth2-resource-server中。然而，除非提供了一个自定义的OpaqueTokenIntrospector，否则资源服务器将回退到NimbusOpaqueTokenIntrospector。这意味着为了使一个支持不透明Bearer Tokens的最小资源服务器正常工作，spring-security-oauth2-resource-server和oauth2-oidc-sdk都是必需的。请参阅spring-security-oauth2-resource-server以确定oauth2-oidc-sdk的正确版本。

用于内省的最小配置​

通常，可以通过由授权服务器托管的 OAuth 2.0 Introspection Endpoint 来验证一个不透明令牌。当需要撤销时，这会非常有用。

当使用 Spring Boot 时，将应用程序配置为使用 introspection 的资源服务器包括两个基本步骤。首先，包含所需的依赖项；其次，指明 introspection 端点的详细信息。

指定授权服务器​

要指定内省端点的位置，只需这样做：

spring:
  security:
    oauth2:
      resourceserver:
        opaque-token:
          introspection-uri: https://idp.example.com/introspect
          client-id: client
          client-secret: secret
yaml

其中 [idp.example.com/introspect](https://idp.example.com/introspect) 是由你的授权服务器托管的 introspection 端点，而 client-id 和 client-secret 是访问该端点所需的凭证。

资源服务器将使用这些属性进行进一步的自我配置，并随后验证传入的JWT。

备注

当使用内省时，授权服务器的话语就是法律。如果授权服务器响应令牌有效，那么它就是有效的。

就这样！

启动预期​

当使用此属性和这些依赖项时，资源服务器将自动配置自身以验证Opaque Bearer Tokens。

这个启动过程比JWT简单得多，因为不需要发现端点，也不需要添加额外的验证规则。

运行时预期​

一旦应用程序启动，资源服务器将尝试处理任何包含 Authorization: Bearer 头的请求：

GET / HTTP/1.1
Authorization: Bearer some-token-value # Resource Server will process this
http

只要指定了此方案，资源服务器将尝试根据Bearer Token规范处理请求。

给定一个不透明令牌，资源服务器将会

  1. 使用提供的凭证和令牌查询提供的introspection端点

  2. 检查响应中是否存在 { 'active' : true } 属性

  3. 将每个范围映射到带有前缀 SCOPE_ 的权限

生成的 Authentication#getPrincipal 默认是一个 Spring Security OAuth2AuthenticatedPrincipal 对象，而 Authentication#getName 映射到令牌的 sub 属性（如果存在的话）。

从这里，你可能想要跳转到：

不透明令牌认证的工作原理​

接下来，让我们看看 Spring Security 用来支持基于 Servlet 的应用程序（如我们刚刚看到的）中的 opaque token 身份验证的架构组件。

OpaqueTokenAuthenticationProvider 是一个 AuthenticationProvider 实现，它利用 OpaqueTokenIntrospector 来验证不透明令牌。

让我们来看看OpaqueTokenAuthenticationProvider在Spring Security中的工作原理。该图解释了Reading the Bearer Token中的图示中AuthenticationManager的工作细节。

opaquetokenauthenticationprovider

图 1. OpaqueTokenAuthenticationProvider 用法

1 从读取Bearer Token中的认证Filter会将一个BearerTokenAuthenticationToken传递给由ProviderManager实现的AuthenticationManager。

2 ProviderManager 被配置为使用类型为 OpaqueTokenAuthenticationProvider 的 AuthenticationProvider。

3 OpaqueTokenAuthenticationProvider 会检查不透明令牌，并使用 OpaqueTokenIntrospector 添加授权。当认证成功时，返回的 Authentication 类型为 BearerTokenAuthentication，其主体是配置的 OpaqueTokenIntrospector 返回的 OAuth2AuthenticatedPrincipal。最终，返回的 BearerTokenAuthentication 将由认证 Filter 设置到 SecurityContextHolder 中。

身份验证后的属性查询​

一旦令牌通过身份验证，就会在 SecurityContext 中设置一个 BearerTokenAuthentication 的实例。

这意味着在配置中使用 @EnableWebMvc 时，它在 @Controller 方法中可用：

@GetMapping("/foo")
public String foo(BearerTokenAuthentication authentication) {
    return authentication.getTokenAttributes().get("sub") + " is the subject";
}
java

由于 BearerTokenAuthentication 持有一个 OAuth2AuthenticatedPrincipal，这也意味着它也可以供控制器方法使用：

@GetMapping("/foo")
public String foo(@AuthenticationPrincipal OAuth2AuthenticatedPrincipal principal) {
    return principal.getAttribute("sub") + " is the subject";
}
java

通过 SpEL 查找属性​

当然，这也意味着可以通过 SpEL 访问属性。

例如，如果使用 @EnableGlobalMethodSecurity 以便您可以使用 @PreAuthorize 注解，您可以这样做：

@PreAuthorize("principal?.attributes['sub'] == 'foo'")
public String forFoosEyesOnly() {
    return "foo";
}
java

覆盖或替换启动自动配置​

Spring Boot 为资源服务器生成了两个 @Bean。

第一个是 SecurityFilterChain，它将应用程序配置为资源服务器。当使用 Opaque Token 时，这个 SecurityFilterChain 看起来像这样：

@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http
        .authorizeHttpRequests(authorize -> authorize
            .anyRequest().authenticated()
        )
        .oauth2ResourceServer(oauth2 -> oauth2
            .opaqueToken(Customizer.withDefaults())
        );
    return http.build();
}
java

如果应用程序没有暴露 SecurityFilterChain bean，那么 Spring Boot 将会暴露上述默认的 SecurityFilterChain。

替换这个就像在应用程序中暴露 bean 一样简单：

import static org.springframework.security.oauth2.core.authorization.OAuth2AuthorizationManagers.hasScope;

@Configuration
@EnableWebSecurity
public class MyCustomSecurityConfiguration {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authorize -> authorize
                .requestMatchers("/messages/**").access(hasScope("message:read"))
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .opaqueToken(opaqueToken -> opaqueToken
                    .introspector(myIntrospector())
                )
            );
        return http.build();
    }
}
java

上述要求任何以 /messages/ 开头的 URL 都需要 message:read 的作用域。

oauth2ResourceServer DSL 中的方法也将覆盖或替换自动配置。

例如，Spring Boot 创建的第二个 @Bean 是一个 OpaqueTokenIntrospector，它将字符串令牌解码为经过验证的 OAuth2AuthenticatedPrincipal 实例：

@Bean
public OpaqueTokenIntrospector introspector() {
    return new NimbusOpaqueTokenIntrospector(introspectionUri, clientId, clientSecret);
}
java

如果应用程序没有暴露一个 OpaqueTokenIntrospector bean，那么 Spring Boot 将会暴露上述默认的 OpaqueTokenIntrospector。

并且可以使用 introspectionUri() 和 introspectionClientCredentials() 覆盖其配置，或者使用 introspector() 替换。

如果应用程序没有暴露 OpaqueTokenAuthenticationConverter bean，那么 spring-security 将构建 BearerTokenAuthentication。

或者，如果你根本没有使用 Spring Boot，那么所有这些组件 —— 过滤器链、一个 OpaqueTokenIntrospector 和一个 OpaqueTokenAuthenticationConverter 可以用 XML 来指定。

过滤链指定如下：

<http>
    <intercept-uri pattern="/**" access="authenticated"/>
    <oauth2-resource-server>
        <opaque-token introspector-ref="opaqueTokenIntrospector"
                authentication-converter-ref="opaqueTokenAuthenticationConverter"/>
    </oauth2-resource-server>
</http>
xml

并且 OpaqueTokenIntrospector 如下所示：

<bean id="opaqueTokenIntrospector"
        class="org.springframework.security.oauth2.server.resource.introspection.NimbusOpaqueTokenIntrospector">
    <constructor-arg value="${spring.security.oauth2.resourceserver.opaquetoken.introspection_uri}"/>
    <constructor-arg value="${spring.security.oauth2.resourceserver.opaquetoken.client_id}"/>
    <constructor-arg value="${spring.security.oauth2.resourceserver.opaquetoken.client_secret}"/>
</bean>
xml

并且 OpaqueTokenAuthenticationConverter 如下：

<bean id="opaqueTokenAuthenticationConverter"
        class="com.example.CustomOpaqueTokenAuthenticationConverter"/>
xml

使用 introspectionUri()​

授权服务器的 Introspection Uri 可以作为配置属性进行配置，也可以在DSL中提供：

@Configuration
@EnableWebSecurity
public class DirectlyConfiguredIntrospectionUri {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authorize -> authorize
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .opaqueToken(opaqueToken -> opaqueToken
                    .introspectionUri("https://idp.example.com/introspect")
                    .introspectionClientCredentials("client", "secret")
                )
            );
        return http.build();
    }
}
java

使用 introspectionUri() 优先于任何配置属性。

使用 introspector()​

比 introspectionUri() 更强大的是 introspector()，它将完全替换任何 Boot 对 OpaqueTokenIntrospector 的自动配置：

@Configuration
@EnableWebSecurity
public class DirectlyConfiguredIntrospector {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authorize -> authorize
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .opaqueToken(opaqueToken -> opaqueToken
                    .introspector(myCustomIntrospector())
                )
            );
        return http.build();
    }
}
java

这在需要更深层次的配置时非常方便，比如权限映射、JWT 撤销或请求超时。

暴露一个 OpaqueTokenIntrospector @Bean​

或者，暴露一个 OpaqueTokenIntrospector @Bean 与 introspector() 具有相同的效果：

@Bean
public OpaqueTokenIntrospector introspector() {
    return new NimbusOpaqueTokenIntrospector(introspectionUri, clientId, clientSecret);
}
java

配置授权​

OAuth 2.0 检省端点通常会返回一个 scope 属性，表示它被授予的范围（或权限），例如：

{ …​, "scope" : "messages contacts"}

在这种情况下，资源服务器会尝试将这些范围强制转换为授权列表，并在每个范围前加上字符串 "SCOPE_"。

这意味着要使用从不透明令牌派生的作用域来保护端点或方法，相应的表达式应包含此前缀：

import static org.springframework.security.oauth2.core.authorization.OAuth2AuthorizationManagers.hasScope;

@Configuration
@EnableWebSecurity
public class MappedAuthorities {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authorizeRequests -> authorizeRequests
                .requestMatchers("/contacts/**").access(hasScope("contacts"))
                .requestMatchers("/messages/**").access(hasScope("messages"))
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .opaqueToken(Customizer.withDefaults())
            );
        return http.build();
    }
}
java

或者类似的方法安全：

@PreAuthorize("hasAuthority('SCOPE_messages')")
public List<Message> getMessages(...) {}
java

手动提取授权​

默认情况下，Opaque Token 支持将从 introspection 响应中提取 scope 声明，并将其解析为单独的 GrantedAuthority 实例。

例如，如果内省响应是：

{
    "active" : true,
    "scope" : "message:read message:write"
}
json

然后资源服务器会生成一个包含两个权限的 Authentication，一个用于 message:read，另一个用于 message:write。

当然，可以使用自定义的 OpaqueTokenIntrospector 来查看属性集，并以自己的方式转换：

public class CustomAuthoritiesOpaqueTokenIntrospector implements OpaqueTokenIntrospector {
    private OpaqueTokenIntrospector delegate =
            new NimbusOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret");

    public OAuth2AuthenticatedPrincipal introspect(String token) {
        OAuth2AuthenticatedPrincipal principal = this.delegate.introspect(token);
        return new DefaultOAuth2AuthenticatedPrincipal(
                principal.getName(), principal.getAttributes(), extractAuthorities(principal));
    }

    private Collection<GrantedAuthority> extractAuthorities(OAuth2AuthenticatedPrincipal principal) {
        List<String> scopes = principal.getAttribute(OAuth2IntrospectionClaimNames.SCOPE);
        return scopes.stream()
                .map(SimpleGrantedAuthority::new)
                .collect(Collectors.toList());
    }
}
java

此后，只需将这个自定义内省器作为 @Bean 暴露出来即可进行配置：

@Bean
public OpaqueTokenIntrospector introspector() {
    return new CustomAuthoritiesOpaqueTokenIntrospector();
}
java

配置超时​

默认情况下，Resource Server 使用 30 秒的连接和套接字超时时间来与授权服务器协调。

这在某些场景下可能太短了。此外，它没有考虑到更复杂的模式，比如退避和发现。

要调整Resource Server连接到授权服务器的方式，NimbusOpaqueTokenIntrospector接受一个RestOperations的实例：

@Bean
public OpaqueTokenIntrospector introspector(RestTemplateBuilder builder, OAuth2ResourceServerProperties properties) {
    RestOperations rest = builder
            .basicAuthentication(properties.getOpaquetoken().getClientId(), properties.getOpaquetoken().getClientSecret())
            .setConnectTimeout(Duration.ofSeconds(60))
            .setReadTimeout(Duration.ofSeconds(60))
            .build();

    return new NimbusOpaqueTokenIntrospector(introspectionUri, rest);
}
java

使用内省与 JWT​

一个常见的问题是内省（introspection）是否与 JWT 兼容。Spring Security 的不透明令牌支持被设计为不关心令牌的格式 —— 它会很乐意将任何令牌传递给提供的内省端点。

所以，假设你有一个需求，需要在每次请求时都与授权服务器进行检查，以防 JWT 被撤销。

尽管你使用的是 JWT 格式的令牌，但你的验证方法是内省（introspection），这意味着你需要执行：

spring:
  security:
    oauth2:
      resourceserver:
        opaque-token:
          introspection-uri: https://idp.example.org/introspection
          client-id: client
          client-secret: secret
yaml

在这种情况下，生成的 Authentication 将是 BearerTokenAuthentication。对应 OAuth2AuthenticatedPrincipal 中的任何属性将是 introspection 端点返回的内容。

但是，假设出于某种奇怪的原因，内省端点只返回该令牌是否处于活动状态。现在该怎么办？

在这种情况下，您可以创建一个自定义的 OpaqueTokenIntrospector，它仍然会访问端点，但随后将返回的主体更新为具有 JWT 声明的属性：

public class JwtOpaqueTokenIntrospector implements OpaqueTokenIntrospector {
    private OpaqueTokenIntrospector delegate =
            new NimbusOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret");
    private JwtDecoder jwtDecoder = new NimbusJwtDecoder(new ParseOnlyJWTProcessor());

    public OAuth2AuthenticatedPrincipal introspect(String token) {
        OAuth2AuthenticatedPrincipal principal = this.delegate.introspect(token);
        try {
            Jwt jwt = this.jwtDecoder.decode(token);
            return new DefaultOAuth2AuthenticatedPrincipal(jwt.getClaims(), NO_AUTHORITIES);
        } catch (JwtException ex) {
            throw new OAuth2IntrospectionException(ex);
        }
    }

    private static class ParseOnlyJWTProcessor extends DefaultJWTProcessor<SecurityContext> {
        JWTClaimsSet process(SignedJWT jwt, SecurityContext context)
                throws JOSEException {
            return jwt.getJWTClaimsSet();
        }
    }
}
java

此后，可以通过将其暴露为 @Bean 来简单地配置此自定义 introspector：

@Bean
public OpaqueTokenIntrospector introspector() {
    return new JwtOpaqueTokenIntrospector();
}
java

调用 /userinfo 端点​

一般来说，资源服务器并不关心底层用户，而是关心已授予的权限。

也就是说，有时将授权声明与用户关联起来是有价值的。

如果应用程序还使用了 spring-security-oauth2-client，并且已经设置了适当的 ClientRegistrationRepository，那么通过自定义 OpaqueTokenIntrospector 就可以很容易地实现。下面的实现做了三件事：

  • 委托给自省端点，以确认令牌的有效性

  • 查找与 /userinfo 端点关联的适当客户端注册

  • 调用并返回来自 /userinfo 端点的响应

public class UserInfoOpaqueTokenIntrospector implements OpaqueTokenIntrospector {
    private final OpaqueTokenIntrospector delegate =
            new NimbusOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret");
    private final OAuth2UserService oauth2UserService = new DefaultOAuth2UserService();

    private final ClientRegistrationRepository repository;

    // ... constructor

    @Override
    public OAuth2AuthenticatedPrincipal introspect(String token) {
        OAuth2AuthenticatedPrincipal authorized = this.delegate.introspect(token);
        Instant issuedAt = authorized.getAttribute(ISSUED_AT);
        Instant expiresAt = authorized.getAttribute(EXPIRES_AT);
        ClientRegistration clientRegistration = this.repository.findByRegistrationId("registration-id");
        OAuth2AccessToken token = new OAuth2AccessToken(BEARER, token, issuedAt, expiresAt);
        OAuth2UserRequest oauth2UserRequest = new OAuth2UserRequest(clientRegistration, token);
        return this.oauth2UserService.loadUser(oauth2UserRequest);
    }
}
java

如果你没有使用 spring-security-oauth2-client，操作仍然很简单。你只需要用你自己的 WebClient 实例调用 /userinfo 即可：

public class UserInfoOpaqueTokenIntrospector implements OpaqueTokenIntrospector {
    private final OpaqueTokenIntrospector delegate =
            new NimbusOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret");
    private final WebClient rest = WebClient.create();

    @Override
    public OAuth2AuthenticatedPrincipal introspect(String token) {
        OAuth2AuthenticatedPrincipal authorized = this.delegate.introspect(token);
        return makeUserInfoRequest(authorized);
    }
}
java

无论哪种方式，在创建了 OpaqueTokenIntrospector 之后，你应该将其发布为一个 @Bean 以覆盖默认设置：

@Bean
OpaqueTokenIntrospector introspector() {
    return new UserInfoOpaqueTokenIntrospector(...);
}
java