This version is still in development and is not considered stable yet. For the latest stable version, please use Spring Security 6.4.1!spring-doc.cn

OAuth 2.0 Resource Server Opaque Token

Minimal Dependencies for Introspection

As described in Minimal Dependencies for JWT most of Resource Server support is collected in spring-security-oauth2-resource-server. However unless a custom OpaqueTokenIntrospector is provided, the Resource Server will fallback to NimbusOpaqueTokenIntrospector. 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 determine the correct version for oauth2-oidc-sdk.spring-doc.cn

Minimal Configuration for Introspection

Typically, an opaque token can be verified via an OAuth 2.0 Introspection Endpoint, hosted by the authorization server. This can be handy when revocation is a requirement.spring-doc.cn

When using 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.spring-doc.cn

Specifying the Authorization Server

To specify where the introspection endpoint is, simply do:spring-doc.cn

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

Where 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.spring-doc.cn

Resource Server will use these properties to further self-configure and subsequently validate incoming JWTs.spring-doc.cn

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!spring-doc.cn

Startup Expectations

When this property and these dependencies are used, Resource Server will automatically configure itself to validate Opaque Bearer Tokens.spring-doc.cn

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.spring-doc.cn

Runtime Expectations

Once the application is started up, Resource Server will attempt to process any request containing an Authorization: Bearer header:spring-doc.cn

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.spring-doc.cn

Given an Opaque Token, Resource Server willspring-doc.cn

Query the provided introspection endpoint using the provided credentials and the tokenspring-doc.cn
Inspect the response for an { 'active' : true } attributespring-doc.cn
Map each scope to an authority with the prefix SCOPE_spring-doc.cn

The resulting Authentication#getPrincipal, by default, is a Spring Security OAuth2AuthenticatedPrincipal object, and Authentication#getName maps to the token’s sub property, if one is present.spring-doc.cn

From here, you may want to jump to:spring-doc.cn

How Opaque Token Authentication Works

Next, let’s see the architectural components that Spring Security uses to support opaque token Authentication in servlet-based applications, like the one we just saw.spring-doc.cn

OpaqueTokenAuthenticationProvider is an AuthenticationProvider implementation that leverages a OpaqueTokenIntrospector to authenticate an opaque token.spring-doc.cn

Let’s take a look at how OpaqueTokenAuthenticationProvider works within Spring Security. The figure explains details of how the AuthenticationManager in figures from Reading the Bearer Token works.spring-doc.cn

Figure 1. OpaqueTokenAuthenticationProvider Usage

number 1 The authentication Filter from Reading the Bearer Token passes a BearerTokenAuthenticationToken to the AuthenticationManager which is implemented by ProviderManager.spring-doc.cn

number 2 The ProviderManager is configured to use an AuthenticationProvider of type OpaqueTokenAuthenticationProvider.spring-doc.cn

number 3 OpaqueTokenAuthenticationProvider introspects the opaque token and adds granted authorities using an OpaqueTokenIntrospector. When authentication is successful, the Authentication that is returned is of type BearerTokenAuthentication and has a principal that is the OAuth2AuthenticatedPrincipal returned by the configured OpaqueTokenIntrospector. Ultimately, the returned BearerTokenAuthentication will be set on the SecurityContextHolder by the authentication Filter.spring-doc.cn

Looking Up Attributes Post-Authentication

Once a token is authenticated, an instance of BearerTokenAuthentication is set in the SecurityContext.spring-doc.cn

This means that it’s available in @Controller methods when using @EnableWebMvc in your configuration:spring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.cn

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

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

Since BearerTokenAuthentication holds an OAuth2AuthenticatedPrincipal, that also means that it’s available to controller methods, too:spring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.cn

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

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

Looking Up Attributes Via SpEL

Of course, this also means that attributes can be accessed via SpEL.spring-doc.cn

For example, if using @EnableGlobalMethodSecurity so that you can use @PreAuthorize annotations, you can do:spring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.cn

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

@PreAuthorize("principal?.attributes['sub'] == 'foo'")
fun forFoosEyesOnly(): String {
    return "foo"
}

Overriding or Replacing Boot Auto Configuration

There are two @Beans that Spring Boot generates on Resource Server’s behalf.spring-doc.cn

The first is a SecurityFilterChain that configures the app as a resource server. When use Opaque Token, this SecurityFilterChain looks like:spring-doc.cn

Default Opaque Token Configuration

Javaspring-doc.cn
Kotlinspring-doc.cn

@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http
        .authorizeHttpRequests(authorize -> authorize
            .anyRequest().authenticated()
        )
        .oauth2ResourceServer(OAuth2ResourceServerConfigurer::opaqueToken);
    return http.build();
}

@Bean
open fun filterChain(http: HttpSecurity): SecurityFilterChain {
    http {
        authorizeRequests {
            authorize(anyRequest, authenticated)
        }
        oauth2ResourceServer {
            opaqueToken { }
        }
    }
    return http.build()
}

If the application doesn’t expose a SecurityFilterChain bean, then Spring Boot will expose the above default one.spring-doc.cn

Replacing this is as simple as exposing the bean within the application:spring-doc.cn

Custom Opaque Token Configuration

Javaspring-doc.cn
Kotlinspring-doc.cn

import static org.springframework.security.oauth2.core.authorization.OAuth2AuthorizationManagers.hasScope;

@Configuration
@EnableWebSecurity
public class MyCustomSecurityConfiguration {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authorize -> authorize
                .requestMatchers("/messages/**").access(hasScope("message:read"))
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .opaqueToken(opaqueToken -> opaqueToken
                    .introspector(myIntrospector())
                )
            );
        return http.build();
    }
}

import org.springframework.security.oauth2.core.authorization.OAuth2AuthorizationManagers.hasScope;

@Configuration
@EnableWebSecurity
class MyCustomSecurityConfiguration {
    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            authorizeRequests {
                authorize("/messages/**", hasScope("SCOPE_message:read"))
                authorize(anyRequest, authenticated)
            }
            oauth2ResourceServer {
                opaqueToken {
                    introspector = myIntrospector()
                }
            }
        }
        return http.build()
    }
}

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

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

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

Javaspring-doc.cn
Kotlinspring-doc.cn

@Bean
public OpaqueTokenIntrospector introspector() {
    return new NimbusOpaqueTokenIntrospector(introspectionUri, clientId, clientSecret);
}

@Bean
fun introspector(): OpaqueTokenIntrospector {
    return NimbusOpaqueTokenIntrospector(introspectionUri, clientId, clientSecret)
}

If the application doesn’t expose an OpaqueTokenIntrospector bean, then Spring Boot will expose the above default one.spring-doc.cn

And its configuration can be overridden using introspectionUri() and introspectionClientCredentials() or replaced using introspector().spring-doc.cn

If the application doesn’t expose an OpaqueTokenAuthenticationConverter bean, then spring-security will build BearerTokenAuthentication.spring-doc.cn

Or, if you’re not using Spring Boot at all, then all of these components - the filter chain, an OpaqueTokenIntrospector and an OpaqueTokenAuthenticationConverter can be specified in XML.spring-doc.cn

The filter chain is specified like so:spring-doc.cn

Default Opaque Token Configuration

Xmlspring-doc.cn

<http>
    <intercept-uri pattern="/**" access="authenticated"/>
    <oauth2-resource-server>
        <opaque-token introspector-ref="opaqueTokenIntrospector"
                authentication-converter-ref="opaqueTokenAuthenticationConverter"/>
    </oauth2-resource-server>
</http>

And the OpaqueTokenIntrospector like so:spring-doc.cn

Opaque Token Introspector

Xmlspring-doc.cn

<bean id="opaqueTokenIntrospector"
        class="org.springframework.security.oauth2.server.resource.introspection.NimbusOpaqueTokenIntrospector">
    <constructor-arg value="${spring.security.oauth2.resourceserver.opaquetoken.introspection_uri}"/>
    <constructor-arg value="${spring.security.oauth2.resourceserver.opaquetoken.client_id}"/>
    <constructor-arg value="${spring.security.oauth2.resourceserver.opaquetoken.client_secret}"/>
</bean>

And the OpaqueTokenAuthenticationConverter like so:spring-doc.cn

Opaque Token Authentication Converter

Xmlspring-doc.cn

<bean id="opaqueTokenAuthenticationConverter"
        class="com.example.CustomOpaqueTokenAuthenticationConverter"/>

Using `introspectionUri()`

An authorization server’s Introspection Uri can be configured as a configuration property or it can be supplied in the DSL:spring-doc.cn

Introspection URI Configuration

@Configuration
@EnableWebSecurity
public class DirectlyConfiguredIntrospectionUri {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authorize -> authorize
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .opaqueToken(opaqueToken -> opaqueToken
                    .introspectionUri("https://idp.example.com/introspect")
                    .introspectionClientCredentials("client", "secret")
                )
            );
        return http.build();
    }
}

@Configuration
@EnableWebSecurity
class DirectlyConfiguredIntrospectionUri {
    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            authorizeRequests {
                authorize(anyRequest, authenticated)
            }
            oauth2ResourceServer {
                opaqueToken {
                    introspectionUri = "https://idp.example.com/introspect"
                    introspectionClientCredentials("client", "secret")
                }
            }
        }
        return http.build()
    }
}

<bean id="opaqueTokenIntrospector"
        class="org.springframework.security.oauth2.server.resource.introspection.NimbusOpaqueTokenIntrospector">
    <constructor-arg value="https://idp.example.com/introspect"/>
    <constructor-arg value="client"/>
    <constructor-arg value="secret"/>
</bean>

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

Using `introspector()`

More powerful than introspectionUri() is introspector(), which will completely replace any Boot auto configuration of OpaqueTokenIntrospector:spring-doc.cn

Introspector Configuration

@Configuration
@EnableWebSecurity
public class DirectlyConfiguredIntrospector {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authorize -> authorize
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .opaqueToken(opaqueToken -> opaqueToken
                    .introspector(myCustomIntrospector())
                )
            );
        return http.build();
    }
}

@Configuration
@EnableWebSecurity
class DirectlyConfiguredIntrospector {
    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            authorizeRequests {
                authorize(anyRequest, authenticated)
            }
            oauth2ResourceServer {
                opaqueToken {
                    introspector = myCustomIntrospector()
                }
            }
        }
        return http.build()
    }
}

<http>
    <intercept-uri pattern="/**" access="authenticated"/>
    <oauth2-resource-server>
        <opaque-token introspector-ref="myCustomIntrospector"/>
    </oauth2-resource-server>
</http>

This is handy when deeper configuration, like authority mapping, JWT revocation, or request timeouts, is necessary.spring-doc.cn

Exposing a `OpaqueTokenIntrospector` `@Bean`

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

@Bean
public OpaqueTokenIntrospector introspector() {
    return new NimbusOpaqueTokenIntrospector(introspectionUri, clientId, clientSecret);
}

Configuring Authorization

An OAuth 2.0 Introspection endpoint will typically return a scope attribute, indicating the scopes (or authorities) it’s been granted, for example:spring-doc.cn

{ …, "scope" : "messages contacts"}spring-doc.cn

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_".spring-doc.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.cn

Authorization Opaque Token Configuration

import static org.springframework.security.oauth2.core.authorization.OAuth2AuthorizationManagers.hasScope;

@Configuration
@EnableWebSecurity
public class MappedAuthorities {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authorizeRequests -> authorizeRequests
                .requestMatchers("/contacts/**").access(hasScope("contacts"))
                .requestMatchers("/messages/**").access(hasScope("messages"))
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(OAuth2ResourceServerConfigurer::opaqueToken);
        return http.build();
    }
}

import org.springframework.security.oauth2.core.authorization.OAuth2AuthorizationManagers.hasScope

@Configuration
@EnableWebSecurity
class MappedAuthorities {
    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
       http {
            authorizeRequests {
                authorize("/contacts/**", hasScope("contacts"))
                authorize("/messages/**", hasScope("messages"))
                authorize(anyRequest, authenticated)
            }
           oauth2ResourceServer {
               opaqueToken { }
           }
        }
        return http.build()
    }
}

<http>
    <intercept-uri pattern="/contacts/**" access="hasAuthority('SCOPE_contacts')"/>
    <intercept-uri pattern="/messages/**" access="hasAuthority('SCOPE_messages')"/>
    <oauth2-resource-server>
        <opaque-token introspector-ref="opaqueTokenIntrospector"/>
    </oauth2-resource-server>
</http>

Or similarly with method security:spring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.cn

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

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

Extracting Authorities Manually

By default, Opaque Token support will extract the scope claim from an introspection response and parse it into individual GrantedAuthority instances.spring-doc.cn

For example, if the introspection response were:spring-doc.cn

{
    "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.spring-doc.cn

This can, of course, be customized using a custom OpaqueTokenIntrospector that takes a look at the attribute set and converts in its own way:spring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.cn

public class CustomAuthoritiesOpaqueTokenIntrospector implements OpaqueTokenIntrospector {
    private OpaqueTokenIntrospector delegate =
            new NimbusOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret");

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

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

Thereafter, this custom introspector can be configured simply by exposing it as a @Bean:spring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.cn

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

@Bean
fun introspector(): OpaqueTokenIntrospector {
    return CustomAuthoritiesOpaqueTokenIntrospector()
}

Configuring Timeouts

By default, Resource Server uses connection and socket timeouts of 30 seconds each for coordinating with the authorization server.spring-doc.cn

This may be too short in some scenarios. Further, it doesn’t take into account more sophisticated patterns like back-off and discovery.spring-doc.cn

To adjust the way in which Resource Server connects to the authorization server, NimbusOpaqueTokenIntrospector accepts an instance of RestOperations:spring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.cn

@Bean
public OpaqueTokenIntrospector introspector(RestTemplateBuilder builder, OAuth2ResourceServerProperties properties) {
    RestOperations rest = builder
            .basicAuthentication(properties.getOpaquetoken().getClientId(), properties.getOpaquetoken().getClientSecret())
            .setConnectTimeout(Duration.ofSeconds(60))
            .setReadTimeout(Duration.ofSeconds(60))
            .build();

    return new NimbusOpaqueTokenIntrospector(introspectionUri, rest);
}

@Bean
fun introspector(builder: RestTemplateBuilder, properties: OAuth2ResourceServerProperties): OpaqueTokenIntrospector? {
    val rest: RestOperations = builder
            .basicAuthentication(properties.opaquetoken.clientId, properties.opaquetoken.clientSecret)
            .setConnectTimeout(Duration.ofSeconds(60))
            .setReadTimeout(Duration.ofSeconds(60))
            .build()
    return NimbusOpaqueTokenIntrospector(introspectionUri, rest)
}

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 will gladly pass any token to the introspection endpoint provided.spring-doc.cn

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.spring-doc.cn

Even though you are using the JWT format for the token, your validation method is introspection, meaning you’d want to do:spring-doc.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.cn

But, let’s say that, oddly enough, the introspection endpoint only returns whether or not the token is active. Now what?spring-doc.cn

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

Javaspring-doc.cn
Kotlinspring-doc.cn

public class JwtOpaqueTokenIntrospector implements OpaqueTokenIntrospector {
    private OpaqueTokenIntrospector delegate =
            new NimbusOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret");
    private JwtDecoder jwtDecoder = new NimbusJwtDecoder(new ParseOnlyJWTProcessor());

    public OAuth2AuthenticatedPrincipal introspect(String token) {
        OAuth2AuthenticatedPrincipal principal = this.delegate.introspect(token);
        try {
            Jwt jwt = this.jwtDecoder.decode(token);
            return new DefaultOAuth2AuthenticatedPrincipal(jwt.getClaims(), NO_AUTHORITIES);
        } catch (JwtException ex) {
            throw new OAuth2IntrospectionException(ex);
        }
    }

    private static class ParseOnlyJWTProcessor extends DefaultJWTProcessor<SecurityContext> {
    	JWTClaimsSet process(SignedJWT jwt, SecurityContext context)
                throws JOSEException {
            return jwt.getJWTClaimsSet();
        }
    }
}

class JwtOpaqueTokenIntrospector : OpaqueTokenIntrospector {
    private val delegate: OpaqueTokenIntrospector = NimbusOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret")
    private val jwtDecoder: JwtDecoder = NimbusJwtDecoder(ParseOnlyJWTProcessor())
    override fun introspect(token: String): OAuth2AuthenticatedPrincipal {
        val principal = delegate.introspect(token)
        return try {
            val jwt: Jwt = jwtDecoder.decode(token)
            DefaultOAuth2AuthenticatedPrincipal(jwt.claims, NO_AUTHORITIES)
        } catch (ex: JwtException) {
            throw OAuth2IntrospectionException(ex.message)
        }
    }

    private class ParseOnlyJWTProcessor : DefaultJWTProcessor<SecurityContext>() {
        override fun process(jwt: SignedJWT, context: SecurityContext): JWTClaimsSet {
            return jwt.jwtClaimsSet
        }
    }
}

Thereafter, this custom introspector can be configured simply by exposing it as a @Bean:spring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.cn

@Bean
public OpaqueTokenIntrospector introspector() {
    return new JwtOpaqueTokenIntrospector();
}

@Bean
fun introspector(): OpaqueTokenIntrospector {
    return JwtOpaqueTokenIntrospector()
}

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.spring-doc.cn

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

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:spring-doc.cn

Delegates to the introspection endpoint, to affirm the token’s validityspring-doc.cn
Looks up the appropriate client registration associated with the /userinfo endpointspring-doc.cn
Invokes and returns the response from the /userinfo endpointspring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.cn

public class UserInfoOpaqueTokenIntrospector implements OpaqueTokenIntrospector {
    private final OpaqueTokenIntrospector delegate =
            new NimbusOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret");
    private final OAuth2UserService oauth2UserService = new DefaultOAuth2UserService();

    private final ClientRegistrationRepository repository;

    // ... constructor

    @Override
    public OAuth2AuthenticatedPrincipal introspect(String token) {
        OAuth2AuthenticatedPrincipal authorized = this.delegate.introspect(token);
        Instant issuedAt = authorized.getAttribute(ISSUED_AT);
        Instant expiresAt = authorized.getAttribute(EXPIRES_AT);
        ClientRegistration clientRegistration = this.repository.findByRegistrationId("registration-id");
        OAuth2AccessToken token = new OAuth2AccessToken(BEARER, token, issuedAt, expiresAt);
        OAuth2UserRequest oauth2UserRequest = new OAuth2UserRequest(clientRegistration, token);
        return this.oauth2UserService.loadUser(oauth2UserRequest);
    }
}

class UserInfoOpaqueTokenIntrospector : OpaqueTokenIntrospector {
    private val delegate: OpaqueTokenIntrospector = NimbusOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret")
    private val oauth2UserService = DefaultOAuth2UserService()
    private val repository: ClientRegistrationRepository? = null

    // ... constructor

    override fun introspect(token: String): OAuth2AuthenticatedPrincipal {
        val authorized = delegate.introspect(token)
        val issuedAt: Instant? = authorized.getAttribute(ISSUED_AT)
        val expiresAt: Instant? = authorized.getAttribute(EXPIRES_AT)
        val clientRegistration: ClientRegistration = repository!!.findByRegistrationId("registration-id")
        val accessToken = OAuth2AccessToken(BEARER, token, issuedAt, expiresAt)
        val oauth2UserRequest = OAuth2UserRequest(clientRegistration, accessToken)
        return oauth2UserService.loadUser(oauth2UserRequest)
    }
}

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.cn

Javaspring-doc.cn
Kotlinspring-doc.cn

public class UserInfoOpaqueTokenIntrospector implements OpaqueTokenIntrospector {
    private final OpaqueTokenIntrospector delegate =
            new NimbusOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret");
    private final WebClient rest = WebClient.create();

    @Override
    public OAuth2AuthenticatedPrincipal introspect(String token) {
        OAuth2AuthenticatedPrincipal authorized = this.delegate.introspect(token);
        return makeUserInfoRequest(authorized);
    }
}

class UserInfoOpaqueTokenIntrospector : OpaqueTokenIntrospector {
    private val delegate: OpaqueTokenIntrospector = NimbusOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret")
    private val rest: WebClient = WebClient.create()

    override fun introspect(token: String): OAuth2AuthenticatedPrincipal {
        val authorized = delegate.introspect(token)
        return makeUserInfoRequest(authorized)
    }
}

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

Javaspring-doc.cn
Kotlinspring-doc.cn

@Bean
OpaqueTokenIntrospector introspector() {
    return new UserInfoOpaqueTokenIntrospector(...);
}

@Bean
fun introspector(): OpaqueTokenIntrospector {
    return UserInfoOpaqueTokenIntrospector(...)
}