OAuth 2.0 token introspection

OAuth 2.0 token introspection defines a method that allows an authorized protected resource to query the authorization server in order to determine the metadata associated with a given token (either an access token or a refresh token), provided by an OAuth client. Based on the metadata of the specific token, it allows the resource owner to access the protected resource.

This metadata includes:

• Whether the token is currently active (or if it has expired or been revoked)
• The permissions the access token grants (typically conveyed through OAuth 2.0 scopes)
• The authorization context in which the token was granted (including who authorized the token and to which client it was issued)

Token introspection enables the protected resource to query this information, regardless of whether it is contained within the token itself.

There are two types of access tokens, depending on how they are encoded:

• Identifier-based: The token represents a random, hard-to-guess identifier associated with the authorization in the authorization server’s database.
• Self-contained: The authorization is encoded within the token itself and is protected through cryptography to prevent tampering. JSON Web Token (JWT) is the common standard for this method.

For self-contained tokens, the authorization-related metadata can be directly parsed from the access token. However, for identifier-based tokens, the authorization server’s token introspection functionality must be used to validate/retrieve the metadata.

Token introspection request#

Using identifier-based access tokens requires verification with the authorization server via a network request. There is a standard protocol for this called OAuth 2.0 Token Introspection (RFC 7662).

The protected resource will POST the token to the authorization server’s introspection endpoint, and in return, it will receive a JSON object containing the token’s parameters.

Note that introspection requests cannot be initiated arbitrarily; they must meet one of the following conditions:

• Authentication using credentials (which must be pre-registered with the authorization server), or
• Authorization using an access token.

As a result, in this specific interaction, the protected resource becomes the OAuth client, and the authorization server becomes the protected resource.

Below is an example of an introspection request, where the protected resource authenticates using a client ID and client secret, which were obtained after registering as an OAuth client with the authorization server.

Below is an example of an introspection request that directly uses an access token. The access token can be obtained directly from the /token endpoint by using the credentials of a registered machine-to-machine app and the client_credentials grant type.

Token introspection response#

The most important parameter is active, which is a boolean value. If true, it indicates that the token is valid, and the JSON object will include other token details, such as the scope values. If false, the token is either invalid or expired, and the protected resource must return a 401 Unauthorized response with the invalid_token error code.

Here’s an example response for a valid token:

Other than active, which is required, all other parameters are optional.

The protected resource can use these additional fields to determine access permissions, similar to how it would parse and validate a JWT access token.