OAuth 2.0 Token Introspection


OAuth 2.0 Token Introspection is defined in RFC 7662 which describes in OAuth 2.0 RFC 6749, the contents of tokens are opaque to OAuth Clients.

This means that the client does not need to know anything about the content or structure of the token itself, if there is any. However, there is still a large amount of metadata that may be attached to a token, such as its current validity, approved scopes, and information about the context in which the token was issued. These pieces of information are often vital to protected resources making authorization decisions based on the tokens being presented. Since OAuth 2.0 does not define a protocol for the Resource Server to learn meta-information about a token that it has received from an authorization server, several different approaches have been developed to bridge this gap. These include using structured token formats such as JWT RFC 7519 or proprietary inter-service communication mechanisms (such as shared databases and protected enterprise service buses) that convey token information.

OAuth 2.0 Token Introspection defines a protocol that allows authorized Protected Resources to query the Authorization Server to determine the set of metadata for a given token that was presented to them by an OAuth Client. This metadata includes whether or not the token is currently active (or if it has expired or otherwise been revoked), what rights of access the token carries (usually conveyed through OAuth 2.0 scopes), and the authorization context in which the token was granted (including who authorized the token and which client it was issued to). Token introspection allows a protected resource to query this information regardless of whether or not it is carried in the token itself, allowing this method to be used along with or independently of structured token values. Additionally, a protected resource can use the mechanism described in this specification to introspect the token in a particular authorization decision context and ascertain the relevant metadata about the token to make this authorization decision appropriately.


Token Introspection Request#

The Protected Resource calls the introspection endpoint using an HTTP POST RFC 7231 request with parameters sent as "application/x-www-form-urlencoded" data as defined in W3C.REC-html5-20141028. The protected resource sends a parameter representing the token along with optional parameters representing additional context that is known by the protected resource to aid the authorization server in its response.
tokenREQUIREDThe string value of the token. For access tokens, this is the "access_token" value returned from the token endpoint defined in OAuth 2.0 RFC 6749 section 5.1. For refresh tokens, this is the "refresh_token" value returned from the token endpoint as defined in OAuth 2.0 RFC 6749 section 5.1. Other token types are outside the scope of this specification.
token_type_hintOPTIONALA hint about the type of the token submitted for introspection. The protected resource MAY pass this parameter to help the authorization server to optimize the token lookup. If the server is unable to locate the token using the given hint, it MUST extend its search across all of its supported token types. An authorization server MAY ignore this parameter, particularly if it is able to detect the token type automatically. Values for this field are defined in the OAuth Token Type Hints registry defined in OAuth 2.0 Token Revocation RFC 7009.
The Introspection_endpoint MAY accept other OPTIONAL parameters to provide further context to the query. For instance, an authorization server may desire to know the IP address of the client accessing the protected resource to determine if the correct client is likely to be presenting the token. The definition of this or any other parameters are outside the scope of this specification, to be defined by service documentation or extensions to this specification. If the authorization server is unable to determine the state of the token without additional information, it SHOULD return an introspection response indicating the token is not active as described in Section 2.2.

To prevent token scanning attacks, the Introspection_endpoint MUST also require some form of authorization to access this endpoint, such as client authentication as described in OAuth 2.0 RFC 6749 or a separate OAuth 2.0 Access Token such as the bearer token described in OAuth 2.0 Bearer Token Usage RFC 6750. The methods of managing and validating these authentication credentials are out of scope of this specification.

For example, the following example shows a protected resource calling the token Introspection_endpoint to query about an OAuth 2.0 bearer token. The protected resource is using a separate OAuth 2.0 bearer Token to authorize this call.

Following is a non-normative example request:

POST /introspect HTTP/1.1
Host: server.example.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer 23410913-abewfq.123483


In the following example, the protected resource uses a client identifier and client secret to authenticate itself to the introspection endpoint. The protected resource also sends a token type hint indicating that it is inquiring about an access token.

Following is a non-normative example request:

POST /introspect HTTP/1.1
     Host: server.example.com
     Accept: application/json
     Content-Type: application/x-www-form-urlencoded
     Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW


Token Introspection Response#

The Authorization Server responds with a JSON object in "application/json" format with the following top-level members.
activeREQUIREDBoolean indicator of whether or not the presented token is currently active. The specifics of a token's "active" state will vary depending on the implementation of the authorization server, and the information it keeps about its tokens, but a "true" value return for the "active" property will generally indicate that a given token has been issued by this authorization server, has not been revoked by the resource owner, and is within its given time window of validity (e.g. after its issuance time and before its expiration time).
scopesOPTIONALA JSON string containing a space-separated list of OAuth Scopes associated with this token, in the format described in section 3.3 of OAuth 2.0 RFC 6749.
client_idOPTIONALClient identifier for the OAuth Client that requested this token.
usernameOPTIONALHuman-readable identifier for the resource owner who authorized this token.
token_typeOPTIONALType of the token as defined in section 5.1 of OAuth 2.0 RFC 6749.
expOPTIONALInteger timestamp, measured in the number of seconds since January 1 1970 UTC, indicating when this token will expire, as defined in JWT RFC 7519.
iatOPTIONALInteger timestamp, measured in the number of seconds since January 1 1970 UTC, indicating when this token was originally issued, as defined in JWT RFC 7519.
nbfOPTIONALInteger timestamp, measured in the number of seconds since January 1 1970 UTC, indicating when this token is not to be used before, as defined in JWT RFC 7519.
subOPTIONALSubject of the token, as defined in JWT RFC 7519. Usually a machine-readable identifier of the Resource Owner who authorized this token.
audOPTIONALService-specific string identifier or list of string identifiers representing the intended audience for this token, as defined in JWT RFC 7519.
issOPTIONALString representing the issuer of this token, as defined in JWT RFC 7519.
jtiOPTIONALString identifier for the token, as defined in JWT RFC 7519.
Specific implementations MAY extend this structure with their own service-specific response names as top-level members of this JSON object. Response names intended to be used across domains MUST be registered in the OAuth Token Introspection Response registry defined in RFC 7662 Section 3.1.

The Authorization Server MAY respond differently to different Protected Resources making the same request. For instance, an Authorization Server MAY limit which scopes from a given token are returned for each protected resource to prevent Protected Resources from learning more about the larger network than is necessary for its operation.

The response MAY be cached by the Protected Resource to improve performance and reduce load on the Introspection_endpoint, but at the cost of liveness of the information used by the protected resource. See Section 4 for more information regarding the trade off when the response is cached.

For example, the following response contains a set of information about an active token:

Following is a non-normative Example response:

     HTTP/1.1 200 OK
     Content-Type: application/json

      "active": true,
      "client_id": "l238j323ds-23ij4",
      "username": "jdoe",
      "scope": "read write dolphin",
      "sub": "Z5O3upPC88QrAjx00dis",
      "aud": "https://protected.example.net/resource",
      "iss": "https://server.example.com/",
      "exp": 1419356238,
      "iat": 1419350238,
      "extension_field": "twenty-seven"

If the introspection call is properly authorized but the token is not active, does not exist on this server, or the Protected Resource is not allowed to introspect this particular token, the Authorization Server MUST return an introspection response with the active field set to false. Note that to avoid disclosing too much of the Authorization Server's state to a third party, the authorization server SHOULD NOT include any additional information about an inactive Token, including why the token is inactive. For example, the response for a token that has been revoked or is otherwise invalid would look like the following:

Following is a non-normative example response:

     HTTP/1.1 200 OK
     Content-Type: application/json

      "active": false

More Information#

There might be more information for this subject on one of the following: