An opaque token is an access token that carries no usable user or client details. A resource server must ask the authorization server whether the token is valid and retrieve the details needed for authorization. section 13.2 section 13.2.1
A request using an opaque token follows this sequence:
- The client receives the token from the authorization server and sends it to the resource server as an access credential. section 13.6
- The resource server sends the token to the authorization server’s introspection endpoint. section 13.2.1
- The authorization server returns validity and associated details, allowing the resource server to apply authorization constraints. section 13.2.1
Opaque tokens are shorter and lack the three-part, dot-separated structure of JWTs. They can avoid sending larger or more sensitive details through the token, but validation requires communication with the authorization server. section 14.4 section 13.2.2
Spring Security configures opaque-token authentication with opaqueToken(). The resource server supplies the introspection URI and its own client credentials, because it authenticates as a client when making introspection requests. section 15.3 section 15.5
Configure an opaque-token resource server
Set the authorization server’s introspection endpoint and resource-server credentials outside the implementation, then configure the security filter chain with oauth2ResourceServer(c -> c.opaqueToken(o -> o.introspectionUri(introspectionUri).introspectionClientCredentials(resourceServerClientID, resourceServerSecret))). Require authentication with authorizeHttpRequests(c -> c.anyRequest().authenticated()).
Issue and inspect an opaque token
Register a client with accessTokenFormat(OAuth2TokenFormat.REFERENCE), request a client-credentials token, and submit that token to the introspection endpoint. An active response includes details such as scope, subject, issuer, and expiration; an inactive response reports active as false.
Test without a live token
Use MockMvc with .with(opaqueToken()) to authenticate a resource-server request in a Spring Security test. Add authorities with opaqueToken().authorities(...) when the test needs a specific authorization context. section 18.5
Figure 13.6 The token introspection call. The resource server sends a request to the authorization server to find out whether the opaque token is valid and details about to whom it was issued.
Follow the introspection request from the resource server to the authorization server, including validity checking and retrieval of token details. section 13.2.1
