reactive-oauth2-resource-server-opaque-token.md

# OAuth2.0 资源服务器不透明令牌

## 用于自省的最小依赖项

如[JWT 的最小依赖项](../../../servlet/oauth2/resource-server/jwt.html#oauth2resourceserver-jwt-minimaldependencies)中所描述的，大多数资源服务器支持都是在`spring-security-oauth2-resource-server`中收集的。但是，除非提供自定义[`ReactiveOpaqueTokenIntrospector`]（#WebFlux-OAuth2Resourceserver-Opaque-Introspector- Bean），否则资源服务器将退回到 ReactiveOpaQuetokenIntrospector。这意味着`spring-security-oauth2-resource-server`和`oauth2-oidc-sdk`都是必需的，以便拥有支持不透明承载令牌的工作最小资源服务器。请参阅`spring-security-oauth2-resource-server`以确定`oauth2-oidc-sdk`的正确版本。

## 用于内省的最小配置

通常，可以通过由授权服务器托管的[OAuth2.0 内省终点](https://tools.ietf.org/html/rfc7662)来验证不透明令牌。当要求撤销时，这可能很方便。

当使用[Spring Boot](https://spring.io/projects/spring-boot)时，将应用程序配置为使用内省的资源服务器包括两个基本步骤。首先，包括所需的依赖关系，其次，指示内省端点细节。

### 指定授权服务器

要指定内省端点的位置，只需执行以下操作：

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

其中`[https://idp.example.com/introspect](https://idp.example.com/introspect)`是由授权服务器托管的内省端点，`client-id`和`client-secret`是达到该端点所需的凭据。

Resource Server 将使用这些属性进一步自我配置，并随后验证传入的 JWTS。

|   |在使用内省时，授权服务器的单词是 law。<br/>如果授权服务器响应令牌是有效的，那么它是有效的。|
|---|----------------------------------------------------------------------------------------------------------------------------------------------------|

就这样！

### 创业期望

当使用此属性和这些依赖项时，Resource Server 将自动配置自身以验证不透明承载令牌。

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

### 运行时期望

一旦启动应用程序，Resource Server 将尝试处理任何包含`Authorization: Bearer`报头的请求：

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

只要表明了该方案，资源服务器就会尝试根据承载令牌规范来处理请求。

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

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

2. 检查`{ 'active' : true }`属性的响应

3. 将每个作用域映射到一个前缀`SCOPE_`的权限

默认情况下，生成的`Authentication#getPrincipal`是 Spring security`[OAuth2AuthenticatedPrincipal](https://docs.spring.io/spring-security/site/docs/5.6.2/api/org/springframework/security/oauth2/core/OAuth2AuthenticatedPrincipal.html)`对象，并且`Authentication#getName`映射到令牌的`sub`属性（如果存在）。

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

* [身份验证后查找属性](#webflux-oauth2resourceserver-opaque-attributes)

* [手动提取权限](#webflux-oauth2resourceserver-opaque-authorization-extraction)

* [使用 JWTS 进行内省](#webflux-oauth2resourceserver-opaque-jwt-introspector)

## 身份验证后查找属性

一旦对令牌进行了身份验证，就会在`SecurityContext`中设置`BearerTokenAuthentication`的实例。

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

Java

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

Kotlin

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

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

Java

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

Kotlin

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

### 通过 SPEL 查找属性

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

例如，如果使用`@EnableReactiveMethodSecurity`使你可以使用`@PreAuthorize`注释，则可以这样做：

Java

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

Kotlin

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

## 覆盖或替换 Boot Auto 配置

有两个`@Bean`s， Spring boot 代表资源服务器生成。

第一个是将应用程序配置为资源服务器的`SecurityWebFilterChain`。当使用不透明令牌时，这个`SecurityWebFilterChain`看起来像：

Java

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

Kotlin

```
@Bean
fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
    return http {
        authorizeExchange {
            authorize(anyExchange, authenticated)
        }
        oauth2ResourceServer {
            opaqueToken { }
        }
    }
}
```

如果应用程序不公开`SecurityWebFilterChain` Bean，那么 Spring 引导将公开上面的默认引导。

替换它就像在应用程序中公开 Bean 一样简单：

例 1。替换 SecurityWebFilterchain

Java

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

Kotlin

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

对于任何以`/messages/`开头的 URL，上述条件要求`message:read`的范围。

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

例如，第二个`@Bean` Spring 启动创建了一个`ReactiveOpaqueTokenIntrospector`，它将`String`令牌解码为`OAuth2AuthenticatedPrincipal`的验证实例：

Java

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

Kotlin

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

如果应用程序不公开`ReactiveOpaqueTokenIntrospector` Bean，那么 Spring 引导将公开上面的默认引导。

并且它的配置可以使用`introspectionUri()`和`introspectionClientCredentials()`进行重写，或者使用`introspector()`进行替换。

### 使用`inrospectionUri()`
可以配置授权服务器的内省 URI[作为配置属性](#webflux-oauth2resourceserver-opaque-introspectionuri)，也可以在 DSL 中提供它：

Java

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

Kotlin

```
@Bean
fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
    return http {
        authorizeExchange {
            authorize(anyExchange, authenticated)
        }
        oauth2ResourceServer {
            opaqueToken {
                introspectionUri = "https://idp.example.com/introspect"
                introspectionClientCredentials("client", "secret")
            }
        }
    }
}
```

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

比`introspectionUri()`更强大的是`introspector()`，它将完全取代`ReactiveOpaqueTokenIntrospector`的任何引导自动配置：

Java

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

Kotlin

```
@Bean
fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
    return http {
        authorizeExchange {
            authorize(anyExchange, authenticated)
        }
        oauth2ResourceServer {
            opaqueToken {
                introspector = myCustomIntrospector()
            }
        }
    }
}
```

当需要更深的配置时，比如[权限映射](#webflux-oauth2resourceserver-opaque-authorization-extraction)或[JWT 撤销](#webflux-oauth2resourceserver-opaque-jwt-introspector)，这是很方便的。

### 曝光`ReactiveOpaqueTokenIntrospector``@Bean`

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

Java

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

Kotlin

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

## 配置授权

OAuth2.0 内省端点通常会返回一个`scope`属性，指示它被授予的作用域（或权限），例如：

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

在这种情况下，Resource Server 将尝试强制将这些作用域放入一个已授予权限的列表中，并在每个作用域前加上字符串“scope\_”。

这意味着，要保护具有由不透明令牌派生的作用域的端点或方法，相应的表达式应该包括以下前缀：

Java

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

Kotlin

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

或类似于方法安全性：

Java

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

Kotlin

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

### 手动提取权限

默认情况下，不透明令牌支持将从内省响应中提取范围声明，并将其解析为单个`GrantedAuthority`实例。

例如，如果内省反应是：

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

然后，资源服务器将生成一个带有两个权限的`Authentication`，一个用于`message:read`，另一个用于`message:write`。

当然，这可以使用自定义`ReactiveOpaqueTokenIntrospector`进行定制，该自定义`ReactiveOpaqueTokenIntrospector`查看属性集并以其自己的方式进行转换：

Java

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

Kotlin

```
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) }
    }
}
```

在此之后，可以简单地将此自定义内省检测器配置为`@Bean`:

Java

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

Kotlin

```
@Bean
fun introspector(): ReactiveOpaqueTokenIntrospector {
    return CustomAuthoritiesOpaqueTokenIntrospector()
}
```

## 使用 JWTS 进行内省

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

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

尽管你使用的是 JWT 格式的令牌，但你的验证方法是内省，这意味着你希望这样做：

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

在这种情况下，得到的`Authentication`将是`BearerTokenAuthentication`。对应的`OAuth2AuthenticatedPrincipal`中的任何属性都将是内省端点返回的任何属性。

但是，让我们说，奇怪的是，内省端点只返回令牌是否处于活动状态。现在怎么办？

在这种情况下，你可以创建一个自定义的`ReactiveOpaqueTokenIntrospector`，它仍然会到达端点，但随后会更新返回的主体，使其具有 JWTS 声明的属性：

Java

```
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);
			}
		}
	}
}
```

Kotlin

```
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)
            }
        }
    }
}
```

在此之后，可以简单地将此自定义内省检测器配置为`@Bean`:

Java

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

Kotlin

```
@Bean
fun introspector(): ReactiveOpaqueTokenIntrospector {
    return JwtOpaqueTokenIntrospector()
}
```

## 调用`/userinfo`端点

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

话虽如此，有时将授权声明与用户绑定在一起可能是有价值的。

如果一个应用程序也在使用`spring-security-oauth2-client`，已经设置了适当的`ClientRegistrationRepository`，那么使用自定义的`OpaqueTokenIntrospector`就很简单了。下面的实现做了三件事：

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

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

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

Java

```
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);
	}
}
```

Kotlin

```
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) }
    }
}
```

如果你 AREN 不使用`spring-security-oauth2-client`，它仍然很简单。你只需要用你自己的`WebClient`实例调用`/userinfo`:

Java

```
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);
    }
}
```

Kotlin

```
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)
    }
}
```

无论哪种方式，在创建了`ReactiveOpaqueTokenIntrospector`之后，你应该将其发布为`@Bean`，以覆盖默认值：

Java

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

Kotlin

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

[JWT](jwt.html)[多租约](multitenancy.html)