As described in xref:servlet/oauth2/resource-server/jwt.adoc#oauth2resourceserver-jwt-minimaldependencies[Minimal Dependencies for JWT] most of Resource Server support is collected in `spring-security-oauth2-resource-server`.
However unless a custom <<webflux-oauth2resourceserver-opaque-introspector-bean,`ReactiveOpaqueTokenIntrospector`>> is provided, the Resource Server will fallback to ReactiveOpaqueTokenIntrospector.
Meaning that both `spring-security-oauth2-resource-server` and `oauth2-oidc-sdk` are necessary in order to have a working minimal Resource Server that supports opaque Bearer Tokens.
Please refer to `spring-security-oauth2-resource-server` in order to determin the correct version for `oauth2-oidc-sdk`.
Typically, an opaque token can be verified via an https://tools.ietf.org/html/rfc7662[OAuth 2.0 Introspection Endpoint], hosted by the authorization server.
This can be handy when revocation is a requirement.
When using https://spring.io/projects/spring-boot[Spring Boot], configuring an application as a resource server that uses introspection consists of two basic steps.
First, include the needed dependencies and second, indicate the introspection endpoint details.
Where `https://idp.example.com/introspect` is the introspection endpoint hosted by your authorization server and `client-id` and `client-secret` are the credentials needed to hit that endpoint.
Resource Server will use these properties to further self-configure and subsequently validate incoming JWTs.
[NOTE]
When using introspection, the authorization server's word is the law.
If the authorization server responses that the token is valid, then it is.
And that's it!
=== Startup Expectations
When this property and these dependencies are used, Resource Server will automatically configure itself to validate Opaque Bearer Tokens.
This startup process is quite a bit simpler than for JWTs since no endpoints need to be discovered and no additional validation rules get added.
=== Runtime Expectations
Once the application is started up, Resource Server will attempt to process any request containing an `Authorization: Bearer` header:
[source,http]
----
GET / HTTP/1.1
Authorization: Bearer some-token-value # Resource Server will process this
----
So long as this scheme is indicated, Resource Server will attempt to process the request according to the Bearer Token specification.
Given an Opaque Token, Resource Server will
1. Query the provided introspection endpoint using the provided credentials and the token
2. Inspect the response for an `{ 'active' : true }` attribute
3. Map each scope to an authority with the prefix `SCOPE_`
The resulting `Authentication#getPrincipal`, by default, is a Spring Security `{security-api-url}org/springframework/security/oauth2/core/OAuth2AuthenticatedPrincipal.html[OAuth2AuthenticatedPrincipal]` object, and `Authentication#getName` maps to the token's `sub` property, if one is present.
From here, you may want to jump to:
* <<webflux-oauth2resourceserver-opaque-attributes,Looking Up Attributes Post-Authentication>>
The above requires the scope of `message:read` for any URL that starts with `/messages/`.
Methods on the `oauth2ResourceServer` DSL will also override or replace auto configuration.
For example, the second `@Bean` Spring Boot creates is a `ReactiveOpaqueTokenIntrospector`, which decodes `String` tokens into validated instances of `OAuth2AuthenticatedPrincipal`:
====
.Java
[source,java,role="primary"]
----
@Bean
public ReactiveOpaqueTokenIntrospector introspector() {
return new NimbusReactiveOpaqueTokenIntrospector(introspectionUri, clientId, clientSecret);
}
----
.Kotlin
[source,kotlin,role="secondary"]
----
@Bean
fun introspector(): ReactiveOpaqueTokenIntrospector {
An authorization server's Introspection Uri can be configured <<webflux-oauth2resourceserver-opaque-introspectionuri,as a configuration property>> or it can be supplied in the DSL:
More powerful than `introspectionUri()` is `introspector()`, which will completely replace any Boot auto configuration of `ReactiveOpaqueTokenIntrospector`:
fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
return http {
authorizeExchange {
authorize(anyExchange, authenticated)
}
oauth2ResourceServer {
opaqueToken {
introspector = myCustomIntrospector()
}
}
}
}
----
====
This is handy when deeper configuration, like <<webflux-oauth2resourceserver-opaque-authorization-extraction,authority mapping>>or <<webflux-oauth2resourceserver-opaque-jwt-introspector,JWT revocation>> is necessary.
An OAuth 2.0 Introspection endpoint will typically return a `scope` attribute, indicating the scopes (or authorities) it's been granted, for example:
`{ ..., "scope" : "messages contacts"}`
When this is the case, Resource Server will attempt to coerce these scopes into a list of granted authorities, prefixing each scope with the string "SCOPE_".
This means that to protect an endpoint or method with a scope derived from an Opaque Token, the corresponding expressions should include this prefix:
By default, Opaque Token support will extract the scope claim from an introspection response and parse it into individual `GrantedAuthority` instances.
For example, if the introspection response were:
[source,json]
----
{
"active" : true,
"scope" : "message:read message:write"
}
----
Then Resource Server would generate an `Authentication` with two authorities, one for `message:read` and the other for `message:write`.
This can, of course, be customized using a custom `ReactiveOpaqueTokenIntrospector` that takes a look at the attribute set and converts in its own way:
====
.Java
[source,java,role="primary"]
----
public class CustomAuthoritiesOpaqueTokenIntrospector implements ReactiveOpaqueTokenIntrospector {
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 will gladly pass any token to the introspection endpoint provided.
So, let's say that you've got a requirement that requires you to check with the authorization server on each request, in case the JWT has been revoked.
Even though you are using the JWT format for the token, your validation method is introspection, meaning you'd want to do:
In this case, the resulting `Authentication` would be `BearerTokenAuthentication`.
Any attributes in the corresponding `OAuth2AuthenticatedPrincipal` would be whatever was returned by the introspection endpoint.
But, let's say that, oddly enough, the introspection endpoint only returns whether or not the token is active.
Now what?
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:
====
.Java
[source,java,role="primary"]
----
public class JwtOpaqueTokenIntrospector implements ReactiveOpaqueTokenIntrospector {
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, this custom introspector can be configured simply by exposing it as a `@Bean`:
====
.Java
[source,java,role="primary"]
----
@Bean
public ReactiveOpaqueTokenIntrospector introspector() {
return new JwtOpaqueTokenIntropsector();
}
----
.Kotlin
[source,kotlin,role="secondary"]
----
@Bean
fun introspector(): ReactiveOpaqueTokenIntrospector {
return JwtOpaqueTokenIntrospector()
}
----
====
[[webflux-oauth2resourceserver-opaque-userinfo]]
== Calling a `/userinfo` Endpoint
Generally speaking, a Resource Server doesn't care about the underlying user, but instead about the authorities that have been granted.
That said, at times it can be valuable to tie the authorization statement back to a user.
If an application is also using `spring-security-oauth2-client`, having set up the appropriate `ClientRegistrationRepository`, then this is quite simple with a custom `OpaqueTokenIntrospector`.
This implementation below does three things:
* Delegates to the introspection endpoint, to affirm the token's validity
* Looks up the appropriate client registration associated with the `/userinfo` endpoint
* Invokes and returns the response from the `/userinfo` endpoint
====
.Java
[source,java,role="primary"]
----
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) {
