OAuth 2.0 Token Introspectionietf@justin.richer.org
Security
OAuth Working GroupexampleThis specification defines a method for a protected resource to query
an OAuth 2.0 authorization server to determine the active state of an
OAuth 2.0 token and to determine meta-information about this 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, 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. 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 or proprietary inter-service
communication mechanisms (such as shared databases and protected
enterprise service buses) that convey token information.This specification 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
2.0 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.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 .Unless otherwise noted, all the protocol parameter names and values
are case sensitive.This section defines the terminology used by this specification.
This section is a normative portion of this specification, imposing
requirements upon implementations.This specification uses the terms "access token", "authorization
endpoint", "authorization grant", "authorization server", "client",
"client identifier", "protected resource", "refresh token", "resource
owner", "resource server", and "token endpoint" defined by OAuth 2.0, and the terms "claim names" and
"claim values" defined by JSON Web Token
(JWT).This specification defines the following terms:The act of inquiring
about the current state of an OAuth 2.0 token through use of the
network protocol defined in this document.The OAuth 2.0
endpoint through which the token introspection operation is
accomplished.The introspection endpoint is an OAuth 2.0
endpoint that takes a parameter representing an OAuth 2.0 token and
returns a JSON document representing the
meta information surrounding the token, including whether this token is
currently active. The definition of an active token is dependent upon
the authorization server, but this is commonly a token that has been
issued by this authorization server, is not expired, has not been
revoked, and is valid for use at the protected resource making the
introspection call.The introspection endpoint MUST be protected
by a transport-layer security mechanism as described in . The means by which the protected resource discovers
the location of the introspection endpoint are outside the scope of this
specification.The protected resource calls the
introspection endpoint using an HTTP
POST request with parameters sent as application/x-www-form-urlencoded
data as defined in . The
protected resource sends a parameter representing the token along with
optional parameters representing additional context that is known by
the protected resource to aid the authorization server in its
response.REQUIRED. The string value of the token. For
access tokens, this is the access_token
value returned from the token endpoint defined in OAuth 2.0, Section 5.1. For refresh tokens,
this is the refresh_token value
returned from the token endpoint as defined in OAuth 2.0, Section 5.1. Other token types
are outside the scope of this specification.OPTIONAL. A hint about the type of
the token submitted for introspection. The protected resource MAY
pass this parameter to help the authorization server optimize
the token lookup. If the server is unable to locate the token
using the given hint, it MUST extend its search across 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 the "OAuth
Token Type Hints" registry defined in OAuth
Token Revocation.The introspection endpoint MAY accept
other OPTIONAL parameters to provide further context to the query. For
instance, an authorization server may desire to know the IP address of
the client accessing the protected resource to determine if the
correct client is likely to be presenting the token. The definition of
this or any other parameters are outside the scope of this
specification, to be defined by service documentation or extensions to
this specification. If the authorization server is unable to determine
the state of the token without additional information, it SHOULD
return an introspection response indicating the token is not active as
described in .To prevent token scanning attacks, the
endpoint MUST also require some form of authorization to access this
endpoint, such as client authentication as described in OAuth 2.0 or a separate OAuth 2.0 access token
such as the bearer token described in OAuth 2.0
Bearer Token Usage. The methods of managing and validating
these authentication credentials are out of scope of this
specification.For example, the following 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.In this example, the protected resource uses a client identifier
and client secret to authenticate itself to the introspection endpoint
as well as send a token type hint.The server responds with a JSON
object in application/json format
with the following top-level members.REQUIRED. Boolean indicator of
whether or not the presented token is currently active. The
specifics of a token’s active
state will vary depending on the implementation of the
authorization server and the information it keeps about its
tokens, but a true value return for
the active property will generally
indicate that a given token has been issued by this authorization
server, has not been revoked by the resource owner, and is within
its given time window of validity (e.g., after its issuance time
and before its expiration time). See for
information on implementation of such checks.OPTIONAL. A JSON string containing a
space-separated list of scopes associated with this token, in the
format described in Section 3.3 of OAuth
2.0.OPTIONAL. Client identifier for
the OAuth 2.0 client that requested this token.OPTIONAL. Human-readable
identifier for the resource owner who authorized this token.OPTIONAL. Type of the token as
defined in Section 5.1 of OAuth
2.0.OPTIONAL. Integer timestamp, measured
in the number of seconds since January 1 1970 UTC, indicating when
this token will expire, as defined in JWT.OPTIONAL. Integer timestamp, measured
in the number of seconds since January 1 1970 UTC, indicating when
this token was originally issued, as defined in JWT.OPTIONAL. Integer timestamp, measured
in the number of seconds since January 1 1970 UTC, indicating when
this token is not to be used before, as defined in JWT.OPTIONAL. Subject of the token, as
defined in JWT. Usually a
machine-readable 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, as defined in JWT.OPTIONAL. String representing the
issuer of this token, as defined in JWT.OPTIONAL. String identifier for the
token, as defined in JWT.Specific implementations MAY extend this structure with their own
service-specific response names as top-level members of this JSON
object. Response names intended to be used across domains MUST be
registered in the "OAuth Token Introspection Response" registry defined
in .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 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: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, then 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:If the protected resource uses OAuth 2.0 client credentials to
authenticate to the introspection endpoint and its credentials are
invalid, the authorization server responds with an HTTP 401
(Unauthorized) as described in Section 5.2 of OAuth 2.0 .If the protected resource uses an OAuth 2.0 bearer token to
authorize its call to the introspection endpoint and the token used
for authorization does not contain sufficient privileges or is
otherwise invalid for this request, the authorization server responds
with an HTTP 401 code as described in Section 3 of OAuth 2.0 Bearer Token Usage.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 .This specification establishes the "OAuth Token Introspection
Response" registry.OAuth registration client metadata names and descriptions are
registered by Specification Required
after a two-week review period on the oauth-ext-review@ietf.org
mailing list, on the advice of one or more Designated Experts.
However, to allow for the allocation of names prior to publication,
the Designated Expert(s) may approve registration once they are
satisfied that such a specification will be published.Registration requests sent to the mailing list for review should
use an appropriate subject (e.g., "Request to register OAuth Token
Introspection Response name: example").Within the review period, the Designated Expert(s) will either
approve or deny the registration request, communicating this decision
to the review list and IANA. Denials should include an explanation
and, if applicable, suggestions as to how to make the request
successful.IANA must only accept registry updates from the Designated
Expert(s) and should direct all requests for registration to the
review mailing list. The name requested (e.g.,
"example"). This name is case sensitive. Names that match other
registered names in a case insensitive manner SHOULD NOT be
accepted. Names that match claims registered in the "JSON Web
Token Claims" registry established by
SHOULD have comparable definitions and semantics. Brief description of the
metadata value (e.g., "Example description"). For Standards Track
RFCs, state "IESG". For other documents, give the name of the responsible
party. Other details (e.g., postal address, email address, home
page URI) may also be included. Reference to
the document(s) that specify the token endpoint authorization
method, preferably including a URI that can be used to retrieve
a copy of the document(s). An indication of the relevant
sections may also be included but is not required.The initial contents of the "OAuth Token Introspection Response"
registry are as follows:Name: activeDescription: Token active statusChange Controller: IESGSpecification Document(s): of RFC 7662 (this document).Name: usernameDescription: User identifier of the resource ownerChange Controller: IESGSpecification Document(s): of RFC 7662 (this document).Name: client_idDescription: Client identifier of the clientChange Controller: IESGSpecification Document(s): of RFC 7662 (this document).Name: scopeDescription: Authorized scopes of the tokenChange Controller: IESGSpecification Document(s): of RFC 7662 (this document).Name: token_typeDescription: Type of the tokenChange Controller: IESGSpecification Document(s): of RFC 7662 (this document).Name: expDescription: Expiration timestamp of the tokenChange Controller: IESGSpecification Document(s): of RFC 7662 (this document).Name: iatDescription: Issuance timestamp of the tokenChange Controller: IESGSpecification Document(s): of RFC 7662 (this document).Name: nbfDescription: Timestamp before which the token is not validChange Controller: IESGSpecification Document(s): of RFC 7662 (this document).Name: subDescription: Subject of the tokenChange Controller: IESGSpecification Document(s): of RFC 7662 (this document).Name: audDescription: Audience of the tokenChange Controller: IESGSpecification Document(s): of RFC 7662 (this document).Name: issDescription: Issuer of the tokenChange Controller: IESGSpecification Document(s): of RFC 7662 (this document).Name: jtiDescription: Unique identifier of the tokenChange Controller: IESGSpecification Document(s): of RFC 7662 (this document).Since there are many different and valid ways to implement an OAuth
2.0 system, there are consequently many ways for an authorization server
to determine whether or not a token is currently active.
However, since resource servers using token introspection rely
on the authorization server to determine the state of a token, the
authorization server MUST perform all applicable checks against a
token's state. For instance: If the token can expire, the authorization server MUST determine
whether or not the token has expired.If the token can be issued before it is able to be used, the
authorization server MUST determine whether or not a token's valid
period has started yet.If the token can be revoked after it was issued, the
authorization server MUST determine whether or not such a revocation
has taken place.If the token has been signed, the authorization server MUST
validate the signature.If the token can be used only at certain resource servers, the
authorization server MUST determine whether or not the token can be
used at the resource server making the introspection call.If an authorization server fails to perform any applicable check, the
resource server could make an erroneous security decision based on that
response. Note that not all of these checks will be applicable to all
OAuth 2.0 deployments and it is up to the authorization server to
determine which of these checks (and any other checks) apply.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. To prevent this, the authorization
server MUST require authentication of protected resources that need to
access the introspection endpoint and SHOULD require protected resources
to be specifically authorized to call the introspection endpoint. The
specifics of this authentication credentials are out of scope of this
specification, but commonly these credentials could take the form of any
valid client authentication mechanism used with the token endpoint, an
OAuth 2.0 access token, or other HTTP authorization or authentication
mechanism. A single piece of software acting as both a client and a
protected resource MAY reuse the same credentials between the token
endpoint and the introspection endpoint, though doing so potentially
conflates the activities of the client and protected resource portions
of the software and the authorization server MAY require separate
credentials for each mode.Since the introspection endpoint takes in OAuth 2.0 tokens as
parameters and responds with information used to make authorization
decisions, the server MUST support Transport Layer Security (TLS) 1.2
and MAY support additional transport-layer mechanisms
meeting its security requirements. When using TLS, the client or
protected resource MUST perform a TLS/SSL server certificate check, as
specified in . Implementation
security considerations can be found in Recommendations for Secure Use of TLS and
DTLS.To prevent the values of access tokens from leaking into server-side
logs via query parameters, an authorization server offering token
introspection MAY disallow the use of HTTP GET on the introspection
endpoint and instead require the HTTP POST method to be used at the
introspection endpoint.To avoid disclosing the internal server state, an introspection response
for an inactive token SHOULD NOT contain any additional claims beyond
the required active claim (with its value
set to false).Since a protected resource MAY cache the response of the
introspection endpoint, designers of an OAuth 2.0 system using this
protocol MUST consider the performance and security trade-offs inherent
in caching security information such as this. A less aggressive cache
with a short timeout will provide the protected resource with more
up-to-date information (due to it needing to query the introspection endpoint
more often) at the cost of increased network traffic and load on the
introspection endpoint. A more aggressive cache with a longer duration
will minimize network traffic and load on the introspection endpoint,
but at the risk of stale information about the token. For example, the
token may be revoked while the protected resource is relying on the
value of the cached response to make authorization decisions. This
creates a window during which a revoked token could be used at the
protected resource. Consequently, an acceptable cache validity duration
needs to be carefully considered given the concerns and sensitivities of
the protected resource being accessed and the likelihood of a token
being revoked or invalidated in the interim period. Highly sensitive
environments can opt to disable caching entirely on the protected
resource to eliminate the risk of stale cached information entirely,
again at the cost of increased network traffic and server load. If the
response contains the exp parameter
(expiration), the response MUST NOT be cached beyond the time indicated
therein.An authorization server offering token introspection must be able to
understand the token values being presented to it during this call. The
exact means by which this happens is an implementation detail and
is outside the scope of this specification. For unstructured tokens, this
could take the form of a simple server-side database query against a
data store containing the context information for the token. For
structured tokens, this could take the form of the server parsing the
token, validating its signature or other protection mechanisms, and
returning the information contained in the token back to the protected
resource (allowing the protected resource to be unaware of the token's
contents, much like the client). Note that for tokens carrying encrypted
information that is needed during the introspection process, the
authorization server must be able to decrypt and validate the token to
access this information. Also note that in cases where the authorization
server stores no information about the token and has no means of
accessing information about the token by parsing the token itself, it
cannot likely offer an introspection service.The introspection response may contain privacy-sensitive information
such as user identifiers for resource owners. When this is the case,
measures MUST be taken to prevent disclosure of this information to
unintended parties. One method is to transmit user identifiers as opaque
service-specific strings, potentially returning different identifiers to
each protected resource.If the protected resource sends additional information about the
client's request to the authorization server (such as the client's IP
address) using an extension of this specification, such information
could have additional privacy considerations that the extension should
detail. However, the nature and implications of such extensions are
outside the scope of this specification.Omitting privacy-sensitive information from an introspection response
is the simplest way of minimizing privacy issues.With bearer tokens such as those defined by OAuth 2.0 Bearer Token Usage, the protected
resource will have in its possession the entire secret portion of the
token for submission to the introspection service. However, for
proof-of-possession style tokens, the protected resource will have only
a token identifier used during the request, along with the cryptographic
signature on the request. The protected resource would be able to submit
the token identifier to the authorization server's token endpoint to
obtain the necessary key information needed to validate the signature on
the request. The details of this usage are outside the scope of this
specification and will be defined in an extension to this
specification.Thanks to the OAuth Working Group and the User Managed Access Working
Group for feedback and review of this document, and to the various
implementors of both the client and server components of this
specification. In particular, the author would like to thank Amanda
Anganes, John Bradley, Thomas Broyer, Brian Campbell, George Fletcher,
Paul Freemantle, Thomas Hardjono, Eve Maler, Josh Mandel, Steve Moore,
Mike Schwartz, Prabath Siriwardena, Sarah Squire, and Hannes
Tschofennig.