Token introspection

RFC 7662 OAuth 2.0 Token Introspection

This resource provides a method for a OpenId Relying Parties / clients to query to determine the active state of an OAuth 2.0 token and to determine meta-information about the token. OAuth 2.0 deployments can use this method to convey information about the authorization context of the token from the authorization server to the protected resource.

In OAuth 2.0 RFC6749, the contents of tokens are opaque to 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.

Request

The following is a non-normative example request: where a 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 type token.

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

  token=2YotnFZFEjr1zCsicMWpAA&token_type_hint=access_token

If present, the token_type_hint value must be be set to one of:

• access_token for all (opaque) OAuth token codes; or
• pct all for JSON Web Tokens.

Introspection of refresh_token types is not supported.

Response

The following is a non-normative example response from the STS:

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,
  "token_type": "Bearer",
  "extension_field": "twenty-seven",
  "extended_claims": {}
}

Error response

If the OAuth 2.0 client credentials fail to authenticate at this introspection endpoint the authorization server responds with an HTTP 401 (Unauthorized) as described in Section 5.2 of OAuth 2.0 RFC6749.

Note that a properly formed and authorized query for an inactive or otherwise invalid token (or a token the protected resource is not allowed to know about) is not considered an error response by this specification. In these cases, the authorization server MUST instead respond with an introspection response with the "active" field set to "false" as described in RFC7662 Section 2.2.

The following is a non-normative example Token Error Response:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "error": "invalid_token",
  "error_description": "Access token not issued or recognized by this STS"
}

API resources