跳到主要内容

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

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

最小依赖项用于自省​

正如Minimal Dependencies for JWT中所述，大多数资源服务器支持都集中在 spring-security-oauth2-resource-server 中。然而，除非你提供一个自定义的 ReactiveOpaqueTokenIntrospector，否则资源服务器将回退到 ReactiveOpaqueTokenIntrospector。这意味着 spring-security-oauth2-resource-server 和 oauth2-oidc-sdk 都是必需的，以便拥有一个支持不透明承载令牌的工作的最小资源服务器。请参阅 spring-security-oauth2-resource-server 以确定 oauth2-oidc-sdk 的正确版本。

用于内省的最小配置​

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

当使用 Spring Boot 时，将应用程序配置为使用内省的资源服务器包括两个步骤：

  1. 包含所需的依赖项。

  2. 指示内省端点的详细信息。

指定授权服务器​

您可以指定内省端点的位置：

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 属性（如果存在的话）。

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

在认证后查找属性​

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

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

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

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

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

查找属性使用 SpEL​

你可以使用 Spring 表达式语言（SpEL）访问属性。

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

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

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

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

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

@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
    http
        .authorizeExchange(exchanges -> exchanges
            .anyExchange().authenticated()
        )
        .oauth2ResourceServer(ServerHttpSecurity.OAuth2ResourceServerSpec::opaqueToken)
    return http.build();
}
java

如果应用程序没有暴露 SecurityWebFilterChain bean，Spring Boot 会暴露默认的 bean（如前面的代码清单所示）。

您可以将其替换为在应用程序中暴露该 bean：

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

@Configuration
@EnableWebFluxSecurity
public class MyCustomSecurityConfiguration {
    @Bean
    SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
        http
            .authorizeExchange(exchanges -> exchanges
                .pathMatchers("/messages/**").access(hasScope("message:read"))
                .anyExchange().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .opaqueToken(opaqueToken -> opaqueToken
                    .introspector(myIntrospector())
                )
            );
        return http.build();
    }
}
java

上述示例要求任何以 /messages/ 开头的 URL 都需要 message:read 范围。

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

例如，Spring Boot 创建的第二个 @Bean 是 ReactiveOpaqueTokenIntrospector，它将 String 令牌解码为已验证的 OAuth2AuthenticatedPrincipal 实例：

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

如果应用程序没有暴露 ReactiveOpaqueTokenIntrospector bean，Spring Boot 会暴露默认的（如前面的代码清单所示）。

你可以通过使用 introspectionUri() 和 introspectionClientCredentials() 来覆盖其配置，或者通过使用 introspector() 来替换它。

使用 introspectionUri()​

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

@Configuration
@EnableWebFluxSecurity
public class DirectlyConfiguredIntrospectionUri {
    @Bean
    SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
        http
            .authorizeExchange(exchanges -> exchanges
                .anyExchange().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .opaqueToken(opaqueToken -> opaqueToken
                    .introspectionUri("https://idp.example.com/introspect")
                    .introspectionClientCredentials("client", "secret")
                )
            );
        return http.build();
    }
}
java

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

使用 introspector()​

introspector() 比 introspectionUri() 更强大。它完全替换了 ReactiveOpaqueTokenIntrospector 的任何 Boot 自动配置：

@Configuration
@EnableWebFluxSecurity
public class DirectlyConfiguredIntrospector {
    @Bean
    SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
        http
            .authorizeExchange(exchanges -> exchanges
                .anyExchange().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .opaqueToken(opaqueToken -> opaqueToken
                    .introspector(myCustomIntrospector())
                )
            );
        return http.build();
    }
}
java

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

暴露 ReactiveOpaqueTokenIntrospector @Bean​

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

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

配置授权​

OAuth 2.0 检验端点通常返回一个 scope 属性，表示它被授予的作用域（或权限） — 例如：

{ ..., "scope" : "messages contacts"}
json

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

这意味着，要使用从Opaque Token派生的范围来保护端点或方法，相应的表达式应包含此前缀：

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

@Configuration
@EnableWebFluxSecurity
public class MappedAuthorities {
    @Bean
    SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
        http
            .authorizeExchange(exchange -> exchange
                .pathMatchers("/contacts/**").access(hasScope("contacts"))
                .pathMatchers("/messages/**").access(hasScope("messages"))
                .anyExchange().authenticated()
            )
            .oauth2ResourceServer(ServerHttpSecurity.OAuth2ResourceServerSpec::opaqueToken);
        return http.build();
    }
}
java

你可以用方法安全性做类似的事情：

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

手动提取授权​

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

考虑以下示例：

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

如果内省响应如前面的示例所示，资源服务器将生成一个具有两个权限的 Authentication，一个用于 message:read，另一个用于 message:write。

你可以通过使用自定义的 ReactiveOpaqueTokenIntrospector 来自定义行为，该自定义方法会查看属性集并以自己的方式转换：

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

    public Mono<OAuth2AuthenticatedPrincipal> introspect(String token) {
        return this.delegate.introspect(token)
                .map(principal -> 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 ReactiveOpaqueTokenIntrospector introspector() {
    return new CustomAuthoritiesOpaqueTokenIntrospector();
}
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 端点返回的内容。

然而，假设由于某种原因，内省端点仅返回该令牌是否处于活动状态。那么现在该怎么办？

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

public class JwtOpaqueTokenIntrospector implements ReactiveOpaqueTokenIntrospector {
    private ReactiveOpaqueTokenIntrospector delegate =
            new NimbusReactiveOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret");
    private ReactiveJwtDecoder jwtDecoder = new NimbusReactiveJwtDecoder(new ParseOnlyJWTProcessor());

    public Mono<OAuth2AuthenticatedPrincipal> introspect(String token) {
        return this.delegate.introspect(token)
                .flatMap(principal -> this.jwtDecoder.decode(token))
                .map(jwt -> new DefaultOAuth2AuthenticatedPrincipal(jwt.getClaims(), NO_AUTHORITIES));
    }

    private static class ParseOnlyJWTProcessor implements Converter<JWT, Mono<JWTClaimsSet>> {
        public Mono<JWTClaimsSet> convert(JWT jwt) {
            try {
                return Mono.just(jwt.getJWTClaimsSet());
            } catch (Exception ex) {
                return Mono.error(ex);
            }
        }
    }
}
java

此后，你可以通过将其暴露为 @Bean 来配置这个自定义 introspector：

@Bean
public ReactiveOpaqueTokenIntrospector introspector() {
    return new JwtOpaqueTokenIntropsector();
}
java

调用 /userinfo 端点​

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

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

如果应用程序还使用了 spring-security-oauth2-client，并且已经设置了相应的 ClientRegistrationRepository，则可以使用自定义的 OpaqueTokenIntrospector 来实现。下面列出的实现做了三件事：

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

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

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

public class UserInfoOpaqueTokenIntrospector implements ReactiveOpaqueTokenIntrospector {
    private final ReactiveOpaqueTokenIntrospector delegate =
            new NimbusReactiveOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret");
    private final ReactiveOAuth2UserService<OAuth2UserRequest, OAuth2User> oauth2UserService =
            new DefaultReactiveOAuth2UserService();

    private final ReactiveClientRegistrationRepository repository;

    // ... constructor

    @Override
    public Mono<OAuth2AuthenticatedPrincipal> introspect(String token) {
        return Mono.zip(this.delegate.introspect(token), this.repository.findByRegistrationId("registration-id"))
                .map(t -> {
                    OAuth2AuthenticatedPrincipal authorized = t.getT1();
                    ClientRegistration clientRegistration = t.getT2();
                    Instant issuedAt = authorized.getAttribute(ISSUED_AT);
                    Instant expiresAt = authorized.getAttribute(OAuth2IntrospectionClaimNames.EXPIRES_AT);
                    OAuth2AccessToken accessToken = new OAuth2AccessToken(BEARER, token, issuedAt, expiresAt);
                    return new OAuth2UserRequest(clientRegistration, accessToken);
                })
                .flatMap(this.oauth2UserService::loadUser);
    }
}
java

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

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

    @Override
    public Mono<OAuth2AuthenticatedPrincipal> introspect(String token) {
        return this.delegate.introspect(token)
                .map(this::makeUserInfoRequest);
    }
}
java

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

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