This article explores OAuth 2.0 token introspection, a method that allows a protected resource to query the authorization server for token metadata, determining whether an access or refresh token is valid.
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:
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:
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.
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:
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.
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.