Overview#

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.

Introspection_endpoint#

Token Introspection Request#

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

token=2YotnFZFEjr1zCsicMWpAA

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=mF_9.B5f-4.1JqM&token_type_hint=access_token

Token Introspection Response#

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#

• Access Token Validation
• Act (Actor) Claim
• Introspection_endpoint
• May_act (May Act For) Claim
• OAuth Token Introspection Response registry
• Openid-configuration
• Protection API
• RFC 7662
• Scp (Scopes) Claim
• Token Introspection Endpoint
• Uma-configuration