OAuth 2.0 资源服务器 Opaque Token

本站(springdoc.cn)中的内容来源于 spring.io ，原始版权归属于 spring.io。由 springdoc.cn 进行翻译，整理。可供个人学习、研究，未经许可，不得进行任何转载、商用或与之相关的行为。 商标声明：Spring 是 Pivotal Software, Inc. 在美国以及其他国家的商标。

Introspection（内省）的最小依赖

如 JWT的最小依赖 中所述，大部分资源服务器支持都收集在 spring-security-oauth2-resource-server 中。然而，除非你提供一个自定义的 ReactiveOpaqueTokenIntrospector ，否则资源服务器会退回到 ReactiveOpaqueTokenIntrospector。这意味着 spring-security-oauth2-resource-server 和 oauth2-oidc-sdk 对于支持 opaque Bearer Token 的最小资源服务器来说都是必要的。请参阅 spring-security-oauth2-resource-server，以确定 oauth2-oidc-sdk 的正确版本。

Introspection（内省）的最小配置

通常，你可以通过授权服务器托管的 OAuth 2.0 Introspection Endpoint 来验证一个 opaque token。当需要撤销时，这可能很方便。

在使用 Spring Boot 时，将一个应用程序配置为使用内省（introspection）的资源服务器包括两个步骤。

  1. 添加所需的依赖。

  2. 指定内省端点细节。

指定授权服务器

你可以指定内省端点的位置。

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

其中 idp.example.com/introspect 是由你的授权服务器托管的内省端点，client-id 和 client-secret 是点击该端点所需的凭证。

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

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

初始期待（Startup Expectations）

当使用这个属性和这些依赖时，资源服务器会自动配置自己以验证 Opaque Bearer Token。

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

运行异常（Runtime Expectations）

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

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

只要指定了这个 scheme，资源服务器就会尝试根据 Bearer Token 规范来处理请求。

给定一个 Opaque Token，资源服务器：

  1. 通过使用提供的凭证和令牌查询所提供的内省端点。

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

  3. 将每个 scope 映射到一个前缀为 SCOPE_ 的授权。

默认情况下，产生的 Authentication#getPrincipal 是 Spring Security OAuth2AuthenticatedPrincipal对象， Authentication#getName 映射到 token 的 sub 属性，如果有的话。

从这里，你可能想跳到：

认证后查询属性

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

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

  • Java

  • Kotlin

@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，这也意味着它也可以用于 controller 方法。

  • Java

  • Kotlin

@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）访问属性。

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

  • Java

  • Kotlin

@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 实例。

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

  • Java

  • Kotlin

@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 { }
        }
    }
}

如果应用程序没有公开 SecurityWebFilterChain Bean，Spring Boot就会公开默认的bean（如前面的列表所示）。

你可以通过在应用程序中公开bean来取代它。

Replacing SecurityWebFilterChain

  • Java

  • Kotlin

@Configuration
@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();
    }
}
@Bean
fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
    return http {
        authorizeExchange {
            authorize("/messages/**", hasAuthority("SCOPE_message:read"))
            authorize(anyExchange, authenticated)
        }
        oauth2ResourceServer {
            opaqueToken {
                introspector = myIntrospector()
            }
        }
    }
}

前面的例子要求任何以 /messages/ 开头的URL的 scope 为 message:read。

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

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

  • Java

  • Kotlin

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

如果应用程序没有公开 ReactiveOpaqueTokenIntrospector Bean，Spring Boot就会公开默认的一个（如前面的列表所示）。

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

使用 introspectionUri()

你可以把授权服务器的内省URI配置为一个 配置属性，也可以在DSL中提供。

  • Java

  • Kotlin

@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")
            }
        }
    }
}

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

使用 introspector()

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

  • Java

  • Kotlin

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

当需要更深层次的配置时，如授权映射或JWT撤销，这很方便。

暴露 ReactiveOpaqueTokenIntrospector @Bean

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

  • Java

  • Kotlin

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

配置授权

一个OAuth 2.0自省端点通常会返回一个 scope 属性，表明它被授予的scope（或权限） - 例如。

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

在这种情况下，资源服务器试图将这些 scope “胁迫”成一个授予权限的列表，在每个scope前加上一个字符串。SCOPE_。

这意味着，为了保护具有源自 Opaque Token 的 scope 的端点或方法，相应的表达式应该包括这个前缀。

  • Java

  • Kotlin

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

  • Kotlin

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

手动提取授权

默认情况下，Opaque Token支持从内省响应中提取 scope claim，并将其解析为单个 GrantedAuthority 实例。

请考虑以下例子。

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

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

你可以通过使用一个自定义的 ReactiveOpaqueTokenIntrospector 来定制行为，它查看属性集并以自己的方式进行转换。

  • Java

  • Kotlin

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

此后，你可以通过将其作为一个 @Bean 公开来配置这个自定义 introspector（内省）。

  • Java

  • Kotlin

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

使用JWT的内省（Introspection）

一个常见的问题是内省是否与JWT兼容。Spring Security的 Opaque Token 支持被设计为不关心令牌的格式。它很高兴地将任何令牌传递给所提供的内省端点。

因此，假设你需要在每次请求时与授权服务器进行检查，以防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，它仍然点击端点，但随后更新返回的 principal，使其拥有 JWT 的 claim 作为属性。

  • Java

  • Kotlin

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

此后，你可以通过将其作为一个 @Bean 公开来配置这个自定义的 introspector。

  • Java

  • Kotlin

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

调用 /userinfo 端点

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

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

如果应用程序也使用 spring-security-oauth2-client，在设置了相应的 ClientRegistrationRepository 后，你可以用一个自定义的 OpaqueTokenIntrospector 来完成。下一个列表中的实现做了三件事。

  • 委托给内省端点，以确认Token的有效性。

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

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

  • Java

  • Kotlin

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

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

  • Java

  • Kotlin

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

无论如何，在创建了你的 ReactiveOpaqueTokenIntrospector之 后，你应该把它作为一个 @Bean 发布，以覆盖默认值。

  • Java

  • Kotlin

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