OAuth Token IntrospectionThe MITRE Corporationjricher@mitre.org
Security
OAuth Working GroupThis 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. These pieces of
information are often vital to Protected Resources making authorization
decisions based on the tokens being presented. Since OAuth2 defines no
direct relationship between the Authorization Server and the Protected
Resource, only that they must have an agreement on the tokens
themselves, there have been many different approaches to bridging this
gap.This specification defines an Introspection Endpoint that allows the
holder of a token to query the Authorization Server to discover the set
of metadata for a token. A Protected Resource may use the mechanism
described in this draft to query the Introspection Endpoint in a
particular authorization decision context and ascertain the relevant
metadata about the token in order to make this authorization decision
appropriately.The Introspection Endpoint is an OAuth 2
Endpoint that responds to HTTP POST requests (and optionally HTTP GET
requests) from token holders, particularly including Resource Servers
and Clients. 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 endpoint MUST be protected by TLS or
equivalent.REQUIRED. The string value of the token.OPTIONAL. A service-specific string
identifying the resource that the client doing the introspection
is asking about.OPTIONAL. A hint about the type of
the token submitted for revocation. Clients MAY pass this
parameter in order 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 accross 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 OAuth Token Revocation.The endpoint MAY allow other parameters to
provide context to the query. For instance, an authorization service
may need to know the IP address of the Client in order to determine
the appropriateness of the token being presented.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 OAuth 2.0 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 currently active.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. A space-separated list of strings
representing the scopes associated with this token, in the format
described in Section 3.3 of OAuth
2.0.OPTIONAL. Client Identifier for the OAuth
Client that requested this token.OPTIONAL. Local identifier of the Resource Owner
who authorized this token.OPTIONAL. Service-specific string identifier or
list of string identifiers representing the intended audience for
this token.OPTIONAL. Type of the token as defined in
OAuth 2.0 section 5.1.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 Protected Resource is here authenticating
with its own Client ID and Client Secret as per OAuth2 Section 2.3.1.The Authorization Server validates the client credentials and looks
up the information in the token. If the token is currently active, it
returns the following JSON document.If the token presented is not currently active (but the
authentication presented is valid), it returns the following JSON
document.If the client credentials are invalid or there is another error,
the Authorization Server responds with an HTTP 400 (Bad Request) as
described in OAuth 2.0 section 5.2.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.Since the introspection endpoint takes in OAuth 2 tokens as
parameters, it MUST be protected by TLS or equivalent. A server MAY
require an HTTP POST method only to the endpoint.Thanks to the OAuth Working Group and the UMA Working Group for
feedback.OAuth Token RevocationDeutsche Telekom AG