OAuth Token IntrospectionThe MITRE Corporationjricher@mitre.orgThis specification defines a method for a client or protected
resource to query an OAuth authorization server to determine
meta-information about an OAuth token. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119.In OAuth, 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 extra information about the
authentication context in which the token was issued.This specification defines an Introspection Endpoint that allows the
holder of a token to query the Authorization Server to discover the set
of meta-information for a token.The Introspection Endpoint is an OAuth 2
Endpoint that responds to HTTP GET and HTTP POST requests from token
holders. The endpoint takes a single parameter representing the token
(and optionally further authentication) and returns a JSON document
representing the meta information surrounding the token.the string value of the token.The endpoint SHOULD also require some form of authentication
to access this endpoint, such as the Client Authentication as
described in OAuth 2 Core Specification
or a separate OAuth2 Access Token. The methods of managing and
validating these authentication credentials are out of scope of this
specification. The server responds with a JSON object in application/json
format with the following top-level members. Specific implementations
MAY extend this structure with their own service-specific pieces of
information.REQUIRED. Boolean indicator of whether or not
the presented token is valid. OPTIONAL. Integer timestamp, measured in
the number of seconds since January 1 1970 UTC, indicating when
this token will expire.OPTIONAL. Integer timestamp, measured in
the number of seconds since January 1 1970 UTC, indicating when
this token was originally issued.OPTIONAL. Array of strings representing the
scopes associated with this token.OPTIONAL. Local identifier of the Resource
Owner who authorized this token.OPTIONAL. Client Identifier for the Client
that requested this token.OPTIONAL. Service-specific string
identifier of the intended audience for this token.For example, a Protected Resource accepts
a request from a Client carrying an OAuth2 Bearer Token. In order to
know how and whether to serve the request, the Protected Resource then
makes the following request to the Introspection Endpoint of the
Authorization Server.The Authorization Server validates the client credentials and looks
up the information in the token. If the token is valid, it returns the
following JSON document.If the token presented is not valid (but the authentication
presented is valid), it returns the following JSON document.If the credentials are invalid, the Authorization Server responds
with the appropriate error response from the OAuth2 Core.This document makes no request of IANA.If left unprotected and un-throttled, the Introspection Endpoint
could present a means for an attacker to poll a series of possible token
values, fishing for a valid token. Therefore, the Authorization Server
SHOULD issue special client credentials to any protected resources or
clients that need to access the introspection endpoint. These
credentials may be used directly at the endpoint, or they may be
exchanged for an OAuth2 Access token scoped specifically for the
Introspection Endpoint.Thanks to the OAuth Working Group for feedback.