Token introspection

As explained in Spring Security in Action, Second Edition

Token introspection is an OAuth protocol operation in which a resource server asks an authorization server whether a token is valid and requests its associated metadata.

Token introspection lets a resource server ask an authorization server whether an access token is valid and retrieve the client and user details needed for authorization. It is primarily used with opaque tokens, which contain no authorization data themselves. section 13.2 section 13.2.1

An introspection-based request follows this sequence:

• Register the resource server as a client at the authorization server and provide client credentials. section 15.3
• Configure the resource server with the introspection endpoint, client ID, and client secret. section 15.3
• Send the token to the authorization server using an authenticated introspection request. section 14.4
• Use the response to accept or reject the request and apply authorization constraints; valid responses report active true, while expired or unknown tokens report active false. section 13.2.1 section 14.4

Configure a Spring Security resource server

Set the introspection URI and resource-server credentials as external properties, then configure Spring Security with `oauth2ResourceServer().opaqueToken()`. Supply `introspectionUri` and `introspectionClientCredentials(...)`, and require authentication with `anyRequest().authenticated()`. Obtain an opaque access token from the authorization server, call the protected `/demo` endpoint with a Bearer token, and use the response to verify the setup.

Figure 15.6 Token introspection. In situations where the resource server cannot depend on signature-based validation of access tokens (such as when token revocation is necessary), or when the token does not contain detailed information (as with opaque tokens), the resource server is required to make inquiries to the authorization server. This is done to ascertain the validity of a token and to gather additional information about it.

Trace how the resource server queries the authorization server when opaque tokens lack local details or early revocation must be supported. section 15.3

How Spring Security in Action, Second Edition covers it

How deep it goes

Implements registration, property configuration, Spring Security wiring, token acquisition, and protected-endpoint testing.

Examples

Uses Spring Security configuration, authorization-server cURL requests, introspection responses, and a protected `/demo` endpoint.

What it assumes

Assumes an authorization server, registered client credentials, an introspection endpoint, and an opaque access token.

What you can do after

Configure Spring Security to validate opaque Bearer tokens through an authorization server and test a protected endpoint.

How it connects

Connects OAuth 2, authorization servers, resource servers, opaque tokens, JWTs, and token revocation.

liveBookmanning.com

Read Spring Security in Action, Second Edition on liveBook Get the book at manning.com

Also explained in

• 

  liveBookmanning.com
  Software Security for DevelopersToken introspection is a validation process in which a service queries an issuer or authorization server to obtain the status and metadata of a token.
• 

  liveBookmanning.com
  Secure APIsA token introspection endpoint is an authorization-server endpoint that returns metadata about an access token to an authorized client or resource server.

Compare how 3 books explain token introspection →

Related concepts

• opaque tokenused by · An opaque token is an access token whose contents are not directly interpretable by its recipient, typically requiring server-side validation or lookup.
• revocationused by · Revocation is the invalidation or withdrawal of a previously issued credential, key, certificate, token, or permission before or when its authorization ends.
• resource serverused by · A resource server is a service that hosts protected resources, validates access credentials such as tokens, and enforces authorization for client requests.
• identity provideruses · An identity provider is a system that authenticates users or other entities and supplies identity information or authentication assertions to relying applications and services.
• JSON Web Tokenalternative to · A JSON Web Token is a compact, URL-safe representation of claims encoded as a JSON object and protected by a digital signature, message authentication code, or encryption.
• authorization serveruses · An authorization server is an OAuth component that authenticates clients or resource owners, obtains authorization, and issues credentials such as authorization codes and access tokens.

This explainer was generated by Manning's knowledge graph from the text of Spring Security in Action, Second Edition. The section links point to the parts of the book it draws on.