Tuesday, October 7, 2014

OAuth 2.0 Token Introspection Profile

OAuth 2.0 doesn’t define a standard API for communication between the resource server and the authorization server. As a result, vendor-specific, proprietary APIs have crept in to couple the resource server to the authorization server. The Token Introspection profile for OAuth 2.0 fills this gap by proposing a standard API to be exposed by the authorization server, allowing the resource server to talk to it and retrieve token metadata.

OAuth 2.0 Token Introspection Internet draft is available at https://datatracker.ietf.org/doc/draft-richer-oauth-introspection/

A token-introspection request can be generated by any party in possession of the access token. The introspection endpoint can be secured with HTTP Basic Authentication:

POST /introspection HTTP/1.1 
Accept: application/x-www-form-urlencoded 
Host: authz.server.com 
Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 


Let’s have a look at the definition of each parameter.
  • token: The value of the access-token 
  • token_type_hint: The type of the token (either the access_token or the refresh_token) 
  • resource_id: An identifier that represents the corresponding resource for introspection
This request returns the following JSON response:

HTTP/1.1 200 OK 
Content-Type: application/json Cache-Control: no-store 

  "active": true, 
  "scope": "read write dolphin", 
  "sub": "2309fj32kl", 
  "aud": " http://my-resource/* 

Let’s have a look at the definition of each parameter.
  • active: Indicates whether the token is active. To be active, the token should not be expired or revoked. The authorization server can define its own criteria for how to define active. 
  • client_id: The identifier of the client to which the token was issued. 
  • scope: Approved scopes associated with the token. 
  • sub: The subject identifier of the user who approved the authorization grant. 
  • aud: The allowed audience for the token. 
The audience (aud) parameter is defined in the OAuth 2.0: Audience Information Internet draft available at http://tools.ietf.org/html/draft-tschofenig-oauth-audience-00. This is a new parameter introduced into the OAuth token-request flow and is independent of the token type. 

While validating the response from the introspection endpoint, the resource server should first check whether the value of active is set to true. Then it should check whether the value of aud in the response matches the aud URI associated with the resource server or the resource. Finally, it can validate the scope. The required scope to access the resource should be a subset of the scope values returned in the introspection response. If the resource server wants to do further access control based on the client or the resource owner, it can do so with respect to the values of sub and client_id.

More details and the applications of the OAuth 2.0 Token Introspection Profile are covered in my book Advanced API Security.


  1. Can we not remove the need for an introspection point if the Access Token is a JWT token containing the introspection data? Having to introspect on each API call is not very scalable.

    1. That is true. But a self contained JWT has its own pitfalls. For example if the token is revoked by the authorization server there is no way to know it. In the introspection scenario this will be handled.

      But then again having a shorter expiry time for the self contained access token should reduce the impact to a certain level.