跳到主要内容
版本:7.0.2

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

DeepSeek V3 中英对照 Opaque Token OAuth 2.0 Resource Server Opaque Token

内省所需的最小依赖项

Minimal Dependencies for JWT所述,大多数资源服务器支持功能都集中在 spring-security-oauth2-resource-server 中。然而,除非你提供自定义的 ReactiveOpaqueTokenIntrospector,否则资源服务器将回退到 SpringReactiveOpaqueTokenIntrospector。这意味着,要构建一个支持不透明 Bearer Token 的最小化可运行资源服务器,仅需 spring-security-oauth2-resource-server 即可。

不透明令牌的最小配置

通常,你可以通过授权服务器托管的 OAuth 2.0 内省端点 来验证不透明令牌。这在需要撤销令牌时非常方便。

在使用 Spring Boot 时,将应用程序配置为使用自省(introspection)的资源服务器包含两个步骤:

  1. 包含所需的依赖项。

  2. 指明内省端点详情。

指定授权服务器

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

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

其中 [idp.example.com/introspect](https://idp.example.com/introspect) 是由您的授权服务器托管的令牌内省端点,而 client-idclient-secret 则是调用该端点所需的凭据。

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

备注

如果授权服务器响应令牌有效,那么它就是有效的。

启动预期

当使用此属性及这些依赖项时,资源服务器会自动配置自身以验证不透明承载令牌。

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

运行时预期

应用程序启动后,资源服务器会尝试处理任何包含 Authorization: Bearer 请求头的请求:

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

只要此方案被指定,资源服务器就会尝试根据 Bearer Token 规范处理请求。

给定一个不透明令牌,资源服务器:

  1. 使用提供的凭据和令牌查询指定的内省端点。

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

  3. 将每个权限范围映射为以 SCOPE_ 为前缀的权限。

默认情况下,生成的 Authentication#getPrincipal 是一个 Spring Security OAuth2AuthenticatedPrincipal 对象,而 Authentication#getName 则映射到令牌的 sub 属性(如果存在该属性)。

从这里开始,你可能想跳转到:

认证后查找属性

一旦令牌通过认证,BearerTokenAuthentication 的一个实例就会被设置在 SecurityContext 中。

这意味着,当你在配置中使用 @EnableWebFlux 时,它在 @Controller 方法中是可用的:

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

由于 BearerTokenAuthentication 持有 OAuth2AuthenticatedPrincipal,这也意味着控制器方法同样可以访问它:

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

使用SpEL查找属性

您可以使用Spring表达式语言(SpEL)访问属性。

例如,如果你使用 @EnableReactiveMethodSecurity 以便能够使用 @PreAuthorize 注解,你可以这样做:

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

覆盖或替换启动自动配置

Spring Boot 为 Resource Server 生成了两个 @Bean 实例。

第一个是 SecurityWebFilterChain,它将应用程序配置为资源服务器。当使用不透明令牌(Opaque Token)时,这个 SecurityWebFilterChain 的配置如下:

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

如果应用程序没有暴露 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((authorize) -> authorize
.pathMatchers("/messages/**").access(hasScope("message:read"))
.anyExchange().authenticated()
)
.oauth2ResourceServer((oauth2) -> oauth2
.opaqueToken((opaqueToken) -> opaqueToken
.introspector(myIntrospector())
)
);
return http.build();
}
}

前面的例子要求任何以 /messages/ 开头的 URL 都需要 message:read 权限范围。

oauth2ResourceServer DSL 上的方法同样会覆盖或替换自动配置。

例如,Spring Boot 创建的第二个 @Bean 是一个 ReactiveOpaqueTokenIntrospector,它负责将 String 类型的令牌解码为经过验证的 OAuth2AuthenticatedPrincipal 实例:

@Bean
public ReactiveOpaqueTokenIntrospector introspector() {
return SpringReactiveOpaqueTokenIntrospector.withIntrospectionUri(introspectionUri)
.clientId(clientId).clientSecret(clientSecret).build();
}

如果应用程序没有暴露一个 ReactiveOpaqueTokenIntrospector bean,Spring Boot 会暴露默认的(如前面列表所示)。

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

使用 introspectionUri()

你可以将授权服务器的内省URI配置为配置属性,也可以在DSL中提供:

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

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

使用 introspector()

introspector()introspectionUri() 功能更强大。它会完全替换掉 ReactiveOpaqueTokenIntrospector 的任何 Boot 自动配置:

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

这在需要更深层配置时非常方便,例如权限映射JWT 撤销

暴露 ReactiveOpaqueTokenIntrospector @Bean

或者,暴露一个 ReactiveOpaqueTokenIntrospector 类型的 @Bean 与使用 introspector() 方法具有相同的效果:

@Bean
public ReactiveOpaqueTokenIntrospector introspector() {
return SpringReactiveOpaqueTokenIntrospector.withIntrospectionUri(introspectionUri)
.clientId(clientId).clientSecret(clientSecret).build()
}

配置授权

OAuth 2.0 的 Introspection 端点通常会返回一个 scope 属性,用以表明其被授予的权限范围(或权限)——例如:

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

在这种情况下,资源服务器会尝试将这些作用域强制转换为已授予权限的列表,并在每个作用域前加上字符串前缀: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((authorize) -> authorize
.pathMatchers("/contacts/**").access(hasScope("contacts"))
.pathMatchers("/messages/**").access(hasScope("messages"))
.anyExchange().authenticated()
)
.oauth2ResourceServer(ServerHttpSecurity.OAuth2ResourceServerSpec::opaqueToken);
return http.build();
}
}

在方法安全方面,你也可以采取类似的做法:

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

手动提取权限

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

考虑以下示例:

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

如果内省响应如上例所示,资源服务器将生成一个包含两个权限的Authentication对象,一个对应message:read,另一个对应message:write

您可以通过使用自定义的 ReactiveOpaqueTokenIntrospector 来定制行为,该检查器会查看属性集并以自己的方式进行转换:

public class CustomAuthoritiesOpaqueTokenIntrospector implements ReactiveOpaqueTokenIntrospector {
private ReactiveOpaqueTokenIntrospector delegate = SpringReactiveOpaqueTokenIntrospector
.withIntrospectionUri("https://idp.example.org/introspect")
.clientId("client").clientSecret("secret").build();

public Mono<OAuth2AuthenticatedPrincipal> introspect(String token) {
return this.delegate.introspect(token)
.map((principal) -> principal 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());
}
}

随后,你可以通过将其暴露为 @Bean 来配置这个自定义内省器:

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

使用内省机制处理JWT令牌

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

那么,假设你需要在每次请求时都向授权服务器进行验证,以防JWT已被撤销。

尽管你使用了 JWT 格式的令牌,但你的验证方法是内省(introspection),这意味着你需要执行:

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

在这种情况下,生成的 Authentication 对象将是 BearerTokenAuthentication。而对应的 OAuth2AuthenticatedPrincipal 中的属性,则会是自省端点(introspection endpoint)返回的任何内容。

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

在这种情况下,您可以创建一个自定义的 ReactiveOpaqueTokenIntrospector,它仍然会调用端点,但随后会更新返回的主体,使其将 JWT 的声明作为属性:

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

public Mono<OAuth2AuthenticatedPrincipal> introspect(String token) {
return this.delegate.introspect(token)
.flatMap((principal) -> principal.jwtDecoder.decode(token))
.map((jwt) -> jwt 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);
}
}
}
}

随后,你可以通过将其暴露为 @Bean 来配置这个自定义内省器:

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

调用 /userinfo 端点

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

话虽如此,有时将授权声明与用户关联起来会很有价值。

如果应用程序同时使用了 spring-security-oauth2-client,并已配置好相应的 ClientRegistrationRepository,你可以通过自定义 OpaqueTokenIntrospector 来实现。以下清单中的实现主要完成三件事:

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

  • 查找与 /userinfo 端点关联的相应客户端注册信息。

  • 调用 /userinfo 端点并返回其响应。

public class UserInfoOpaqueTokenIntrospector implements ReactiveOpaqueTokenIntrospector {
private final ReactiveOpaqueTokenIntrospector delegate = SpringReactiveOpaqueTokenIntrospector
.withIntrospectionUri("https://idp.example.org/introspect")
.clientId("client").clientSecret("secret").build();
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);
}
}

如果你没有使用 spring-security-oauth2-client,操作仍然相当简单。你只需要使用自己的 WebClient 实例来调用 /userinfo 接口:

public class UserInfoOpaqueTokenIntrospector implements ReactiveOpaqueTokenIntrospector {
private final ReactiveOpaqueTokenIntrospector delegate = SpringReactiveOpaqueTokenIntrospector
.withIntrospectionUri("https://idp.example.org/introspect")
.clientId("client").clientSecret("secret").build();
private final WebClient rest = WebClient.create();

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

无论哪种方式,创建好你的 ReactiveOpaqueTokenIntrospector 后,都应将其发布为 @Bean 以覆盖默认配置:

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