此版本仍在开发中，尚未被视为稳定版本。对于最新的稳定版本，请使用 Spring Security 6.4.3！spring-doc.cadn.net.cn

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

Introspection 的最小依赖项

如 JWT 的最小依赖项中所述，大多数 Resource Server 支持都收集在spring-security-oauth2-resource-server. 但是，除非您提供自定义ReactiveOpaqueTokenIntrospector，则 Resource Server 会回退到ReactiveOpaqueTokenIntrospector. 这意味着spring-security-oauth2-resource-server和oauth2-oidc-sdk对于具有支持不透明 Bearer Token 的工作最小 Resource Server 是必需的。 看spring-security-oauth2-resource-server为了确定oauth2-oidc-sdk.spring-doc.cadn.net.cn

Introspection 的最小配置

通常，您可以使用授权服务器托管的 OAuth 2.0 Introspection Endpoint 验证不透明令牌。 当需要吊销时，这可能很方便。spring-doc.cadn.net.cn

使用 Spring Boot 时，将应用程序配置为使用内省的资源服务器包括两个步骤：spring-doc.cadn.net.cn

  1. 包括所需的依赖项。spring-doc.cadn.net.cn

  2. 指示自省终端节点详细信息。spring-doc.cadn.net.cn

指定 Authorization Server

您可以指定自省终端节点的位置：spring-doc.cadn.net.cn

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

哪里idp.example.com/introspect是由授权服务器托管的 Introspection 终端节点，client-id和client-secret是命中该终端节点所需的凭证。spring-doc.cadn.net.cn

Resource Server 使用这些属性进一步自我配置并随后验证传入的 JWT。spring-doc.cadn.net.cn

如果授权服务器响应令牌有效，则令牌有效。spring-doc.cadn.net.cn

创业期望

使用此属性和这些依赖项时，Resource Server 会自动将自身配置为验证不透明不记名令牌。spring-doc.cadn.net.cn

此启动过程比 JWT 简单得多，因为不需要发现端点，也不需要添加额外的验证规则。spring-doc.cadn.net.cn

运行时预期

应用程序启动后，Resource Server 会尝试处理任何包含Authorization: Bearer页眉：spring-doc.cadn.net.cn

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

只要指示此方案，Resource Server 就会尝试根据 Bearer Token 规范处理请求。spring-doc.cadn.net.cn

给定一个不透明的令牌，Resource Server：spring-doc.cadn.net.cn

  1. 使用提供的凭证和令牌查询提供的自省终端节点。spring-doc.cadn.net.cn

  2. 检查{ 'active' : true }属性。spring-doc.cadn.net.cn

  3. 将每个范围映射到前缀为SCOPE_.spring-doc.cadn.net.cn

默认情况下，生成的Authentication#getPrincipal是 Spring SecurityOAuth2AuthenticatedPrincipalobject 和Authentication#getName映射到令牌的sub属性（如果存在）。spring-doc.cadn.net.cn

从这里，您可能希望跳转到：spring-doc.cadn.net.cn

身份验证后查找属性

令牌通过身份验证后，BearerTokenAuthentication在SecurityContext.spring-doc.cadn.net.cn

这意味着它可用于@Controller方法时@EnableWebFlux在您的配置中：spring-doc.cadn.net.cn

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

因为BearerTokenAuthentication持有OAuth2AuthenticatedPrincipal，这也意味着它也可用于控制器方法：spring-doc.cadn.net.cn

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

使用 SPEL 查找属性

您可以使用 Spring 表达式语言 （SpEL） 访问属性。spring-doc.cadn.net.cn

例如，如果您使用@EnableReactiveMethodSecurity这样您就可以使用@PreAuthorizeannotations 中，您可以执行以下作：spring-doc.cadn.net.cn

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

覆盖或替换引导自动配置

Spring Boot 生成两个@Bean实例。spring-doc.cadn.net.cn

第一个是SecurityWebFilterChain，将应用程序配置为资源服务器。 当您使用 Opaque Token 时，此SecurityWebFilterChain看来：spring-doc.cadn.net.cn

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

如果应用程序未公开SecurityWebFilterChainbean，Spring Boot 公开了默认的 bean（如前面的清单所示）。spring-doc.cadn.net.cn

您可以通过在应用程序中公开 bean 来替换它：spring-doc.cadn.net.cn

替换 SecurityWebFilterChain
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();
    }
}
import org.springframework.security.oauth2.core.authorization.OAuth2ReactiveAuthorizationManagers.hasScope

@Bean
fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
    return http {
        authorizeExchange {
            authorize("/messages/**", hasScope("message:read"))
            authorize(anyExchange, authenticated)
        }
        oauth2ResourceServer {
            opaqueToken {
                introspector = myIntrospector()
            }
        }
    }
}

The preceding example requires the scope of message:read for any URL that starts with /messages/.spring-doc.cadn.net.cn

Methods on the oauth2ResourceServer DSL also override or replace auto configuration.spring-doc.cadn.net.cn

For example, the second @Bean Spring Boot creates is a ReactiveOpaqueTokenIntrospector, which decodes String tokens into validated instances of OAuth2AuthenticatedPrincipal:spring-doc.cadn.net.cn

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

If the application does not expose a ReactiveOpaqueTokenIntrospector bean, Spring Boot exposes the default one (shown in the preceding listing).spring-doc.cadn.net.cn

You can override its configuration by using introspectionUri() and introspectionClientCredentials() or replace it by using introspector().spring-doc.cadn.net.cn

Using introspectionUri()

You can configure an authorization server’s Introspection URI as a configuration property, or you can supply in the DSL:spring-doc.cadn.net.cn

@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();
    }
}
@Bean
fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
    return http {
        authorizeExchange {
            authorize(anyExchange, authenticated)
        }
        oauth2ResourceServer {
            opaqueToken {
                introspectionUri = "https://idp.example.com/introspect"
                introspectionClientCredentials("client", "secret")
            }
        }
    }
}

Using introspectionUri() takes precedence over any configuration property.spring-doc.cadn.net.cn

Using introspector()

introspector() is more powerful than introspectionUri(). It completely replaces any Boot auto-configuration of ReactiveOpaqueTokenIntrospector:spring-doc.cadn.net.cn

@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();
    }
}
@Bean
fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
    return http {
        authorizeExchange {
            authorize(anyExchange, authenticated)
        }
        oauth2ResourceServer {
            opaqueToken {
                introspector = myCustomIntrospector()
            }
        }
    }
}

This is handy when deeper configuration, such as authority mappingor JWT revocation, is necessary.spring-doc.cadn.net.cn

Exposing a ReactiveOpaqueTokenIntrospector @Bean

Or, exposing a ReactiveOpaqueTokenIntrospector @Bean has the same effect as introspector():spring-doc.cadn.net.cn

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

Configuring Authorization

An OAuth 2.0 Introspection endpoint typically returns a scope attribute, indicating the scopes (or authorities) it has been granted — for example:spring-doc.cadn.net.cn

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

When this is the case, Resource Server tries to coerce these scopes into a list of granted authorities, prefixing each scope with a string: SCOPE_.spring-doc.cadn.net.cn

This means that, to protect an endpoint or method with a scope derived from an Opaque Token, the corresponding expressions should include this prefix:spring-doc.cadn.net.cn

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();
    }
}
import org.springframework.security.oauth2.core.authorization.OAuth2ReactiveAuthorizationManagers.hasScope

@Bean
fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
    return http {
        authorizeExchange {
            authorize("/contacts/**", hasScope("contacts"))
            authorize("/messages/**", hasScope("messages"))
            authorize(anyExchange, authenticated)
        }
        oauth2ResourceServer {
            opaqueToken { }
        }
    }
}

You can do something similar with method security:spring-doc.cadn.net.cn

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

Extracting Authorities Manually

By default, Opaque Token support extracts the scope claim from an introspection response and parses it into individual GrantedAuthority instances.spring-doc.cadn.net.cn

Consider the following example:spring-doc.cadn.net.cn

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

If the introspection response were as the preceding example shows, Resource Server would generate an Authentication with two authorities, one for message:read and the other for message:write.spring-doc.cadn.net.cn

You can customize behavior by using a custom ReactiveOpaqueTokenIntrospector that looks at the attribute set and converts in its own way:spring-doc.cadn.net.cn

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());
    }
}
class CustomAuthoritiesOpaqueTokenIntrospector : ReactiveOpaqueTokenIntrospector {
    private val delegate: ReactiveOpaqueTokenIntrospector = NimbusReactiveOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret")
    override fun introspect(token: String): Mono<OAuth2AuthenticatedPrincipal> {
        return delegate.introspect(token)
                .map { principal: OAuth2AuthenticatedPrincipal ->
                    DefaultOAuth2AuthenticatedPrincipal(
                            principal.name, principal.attributes, extractAuthorities(principal))
                }
    }

    private fun extractAuthorities(principal: OAuth2AuthenticatedPrincipal): Collection<GrantedAuthority> {
        val scopes = principal.getAttribute<List<String>>(OAuth2IntrospectionClaimNames.SCOPE)
        return scopes
                .map { SimpleGrantedAuthority(it) }
    }
}

Thereafter, you can configure this custom introspector by exposing it as a @Bean:spring-doc.cadn.net.cn

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

Using Introspection with JWTs

A common question is whether or not introspection is compatible with JWTs. Spring Security’s Opaque Token support has been designed to not care about the format of the token. It gladly passes any token to the provided introspection endpoint.spring-doc.cadn.net.cn

So, suppose you need to check with the authorization server on each request, in case the JWT has been revoked.spring-doc.cadn.net.cn

Even though you are using the JWT format for the token, your validation method is introspection, meaning you would want to do:spring-doc.cadn.net.cn

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

In this case, the resulting Authentication would be BearerTokenAuthentication. Any attributes in the corresponding OAuth2AuthenticatedPrincipal would be whatever was returned by the introspection endpoint.spring-doc.cadn.net.cn

However, suppose that, for whatever reason, the introspection endpoint returns only whether or not the token is active. Now what?spring-doc.cadn.net.cn

In this case, you can create a custom ReactiveOpaqueTokenIntrospector that still hits the endpoint but then updates the returned principal to have the JWTs claims as the attributes:spring-doc.cadn.net.cn

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);
			}
		}
	}
}
class JwtOpaqueTokenIntrospector : ReactiveOpaqueTokenIntrospector {
    private val delegate: ReactiveOpaqueTokenIntrospector = NimbusReactiveOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret")
    private val jwtDecoder: ReactiveJwtDecoder = NimbusReactiveJwtDecoder(ParseOnlyJWTProcessor())
    override fun introspect(token: String): Mono<OAuth2AuthenticatedPrincipal> {
        return delegate.introspect(token)
                .flatMap { jwtDecoder.decode(token) }
                .map { jwt: Jwt -> DefaultOAuth2AuthenticatedPrincipal(jwt.claims, NO_AUTHORITIES) }
    }

    private class ParseOnlyJWTProcessor : Converter<JWT, Mono<JWTClaimsSet>> {
        override fun convert(jwt: JWT): Mono<JWTClaimsSet> {
            return try {
                Mono.just(jwt.jwtClaimsSet)
            } catch (e: Exception) {
                Mono.error(e)
            }
        }
    }
}

Thereafter, you can configure this custom introspector by exposing it as a @Bean:spring-doc.cadn.net.cn

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

Calling a /userinfo Endpoint

Generally speaking, a Resource Server does not care about the underlying user but, instead, cares about the authorities that have been granted.spring-doc.cadn.net.cn

That said, at times it can be valuable to tie the authorization statement back to a user.spring-doc.cadn.net.cn

If an application also uses spring-security-oauth2-client, having set up the appropriate ClientRegistrationRepository, you can do so with a custom OpaqueTokenIntrospector. The implementation in the next listing does three things:spring-doc.cadn.net.cn

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);
	}
}
class UserInfoOpaqueTokenIntrospector : ReactiveOpaqueTokenIntrospector {
    private val delegate: ReactiveOpaqueTokenIntrospector = NimbusReactiveOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret")
    private val oauth2UserService: ReactiveOAuth2UserService<OAuth2UserRequest, OAuth2User> = DefaultReactiveOAuth2UserService()
    private val repository: ReactiveClientRegistrationRepository? = null

    // ... constructor
    override fun introspect(token: String?): Mono<OAuth2AuthenticatedPrincipal> {
        return Mono.zip<OAuth2AuthenticatedPrincipal, ClientRegistration>(delegate.introspect(token), repository!!.findByRegistrationId("registration-id"))
                .map<OAuth2UserRequest> { t: Tuple2<OAuth2AuthenticatedPrincipal, ClientRegistration> ->
                    val authorized = t.t1
                    val clientRegistration = t.t2
                    val issuedAt: Instant? = authorized.getAttribute(ISSUED_AT)
                    val expiresAt: Instant? = authorized.getAttribute(OAuth2IntrospectionClaimNames.EXPIRES_AT)
                    val accessToken = OAuth2AccessToken(BEARER, token, issuedAt, expiresAt)
                    OAuth2UserRequest(clientRegistration, accessToken)
                }
                .flatMap { userRequest: OAuth2UserRequest -> oauth2UserService.loadUser(userRequest) }
    }
}

If you aren’t using spring-security-oauth2-client, it’s still quite simple. You will simply need to invoke the /userinfo with your own instance of WebClient:spring-doc.cadn.net.cn

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);
    }
}
class UserInfoOpaqueTokenIntrospector : ReactiveOpaqueTokenIntrospector {
    private val delegate: ReactiveOpaqueTokenIntrospector = NimbusReactiveOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret")
    private val rest: WebClient = WebClient.create()

    override fun introspect(token: String): Mono<OAuth2AuthenticatedPrincipal> {
        return delegate.introspect(token)
                .map(this::makeUserInfoRequest)
    }
}

Either way, having created your ReactiveOpaqueTokenIntrospector, you should publish it as a @Bean to override the defaults:spring-doc.cadn.net.cn

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