One document matched: draft-ietf-oauth-introspection-04.xml
<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="3"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="std" docName="draft-ietf-oauth-introspection-04"
ipr="trust200902">
<front>
<title abbrev="oauth-introspection">OAuth 2.0 Token Introspection</title>
<author fullname="Justin Richer" initials="J." role="editor"
surname="Richer">
<organization>The MITRE Corporation</organization>
<address>
<email>jricher@mitre.org</email>
</address>
</author>
<date day="23" month="December" year="2014"/>
<area>Security</area>
<workgroup>OAuth Working Group</workgroup>
<abstract>
<t>This 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.</t>
</abstract>
<note title="Requirements Language">
<t>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 <xref
target="RFC2119">RFC 2119</xref>.</t>
</note>
</front>
<middle>
<section anchor="introduction" title="Introduction">
<t>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 <xref target="RFC6749">OAuth
2.0</xref> 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. These include using structured token formats such as
<xref target="JWT">JWT</xref> or proprietary inter-service communication
mechanisms (such as shared databases and protected enterprise service
buses) that convey token information.</t>
<t>This specification defines an interoperable web API 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 in order to make this
authorization decision appropriately.</t>
<section title="Terminology">
<t>This section defines the terminology used by this specification.
This section is a normative portion of this specification, imposing
requirements upon implementations.</t>
<t>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 <xref
target="RFC6749">OAuth 2.0</xref>, and the terms "claim names" and
"claim values" defined by <xref target="JWT">JSON Web Token
(JWT)</xref>.</t>
</section>
</section>
<section anchor="IntrospectionEndpoint" title="Introspection Endpoint">
<t hangText="instance_name">The introspection endpoint is an OAuth 2.0
endpoint that takes a parameter representing an OAuth 2.0 token and
returns a <xref target="RFC7159">JSON</xref> document representing the
meta information surrounding the token, including whether this token is
currently active. The definition of an active token is up to 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 within the purview of the protected resource making the introspection
call.</t>
<t hangText="instance_name">The introspection endpoint MUST be protected
by TLS of at least version 1.2 <xref target="RFC5246">RFC 5246</xref>
and MAY support additional transport-layer mechanisms meeting its
security requirements. When using TLS, the protected resource MUST
perform a TLS/SSL server certificate check, per <xref
target="RFC6125">RFC 6125</xref>. Implementation security considerations
can be found in <xref target="TLS.BCP">Recommendations for Secure Use of
TLS and DTLS</xref>.</t>
<section anchor="IntrospectionRequest" title="Introspection Request">
<t hangText="instance_name">The protected resource calls the
introspection endpoint using an <xref target="RFC7231">HTTP
POST</xref> request with parameters sent as <spanx style="verb">application/x-www-form-urlencoded</spanx>
data as defined in <xref target="W3C.REC-html5-20141028"/>. The
authorization server MAY allow an <xref target="RFC7231">HTTP
GET</xref> request with parameters passed in the query string as
defined in <xref target="W3C.REC-html5-20141028"/>. 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.</t>
<t hangText="instance_name"><list style="hanging">
<t hangText="token">REQUIRED. The string value of the token. For
access tokens, this is the <spanx style="verb">access_token</spanx>
value returned from the token endpoint defined in <xref
target="RFC6749">OAuth 2.0</xref> section 5.1. For refresh tokens,
this is the <spanx style="verb">refresh_token</spanx> value
returned from the token endpoint as defined in <xref
target="RFC6749">OAuth 2.0</xref> section 5.1. Other token types
are outside the scope of this specification.</t>
<t hangText="token_type_hint">OPTIONAL. A hint about the type of
the token submitted for introspection. The protected resource re
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 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
<xref target="RFC7009">OAuth Token Revocation</xref>.</t>
</list></t>
<t hangText="instance_name">The endpoint MAY allow other parameters to
provide further context to the query. For instance, an authorization
service may need to know the IP address of the client accessing the
protected resource in order to determine the appropriateness of the
token being presented.</t>
<t hangText="instance_name">To prevent unauthorized token scanning
attacks, the endpoint MUST also require some form of authorization to
access this endpoint, such as client authentication as described in
<xref target="RFC6749">OAuth 2.0</xref> or a separate OAuth 2.0 access
token such as the bearer token described in <xref
target="RFC6750">OAuth 2.0 Bearer Token Usage</xref>. The methods of
managing and validating these authentication credentials are out of
scope of this specification.</t>
<t>For example, the following example shows a protected resource
calling the token introspection endpoint to query about an OAuth 2.0
bearer. The protected resource is using a separate OAuth 2.0 bearer
token to authorize this call.</t>
<figure>
<preamble>Following is a non-normative example request (with line
wraps for display purposes only):</preamble>
<artwork><![CDATA[
POST /introspect HTTP/1.1
Host: server.example.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer 23410913-abewfq.123483
token=2YotnFZFEjr1zCsicMWpAA
]]></artwork>
</figure>
<t>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.</t>
<figure>
<preamble>Following is a non-normative example request (with line
wraps for display purposes only):</preamble>
<artwork><![CDATA[
POST /introspect HTTP/1.1
Host: server.example.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
token=mF_9.B5f-4.1JqM&token_type_hint=access_token
]]></artwork>
</figure>
</section>
<section anchor="IntrospectionResponse" title="Introspection Response">
<t>The server responds with a <xref target="RFC7159">JSON
object</xref> in <spanx style="verb">application/json</spanx> format
with the following top-level members.</t>
<t><list style="hanging">
<t hangText="active"><vspace/>REQUIRED. Boolean indicator of
whether or not the presented token is currently active. The
authorization server determines whether and when a given token is
in an active state.</t>
<t hangText="scope"><vspace/>OPTIONAL. A space-separated list of
strings representing the scopes associated with this token, in the
format described in section 3.3 of <xref target="RFC6749">OAuth
2.0</xref>.</t>
<t hangText="client_id"><vspace/>OPTIONAL. Client identifier for
the OAuth 2.0 client that requested this token.</t>
<t hangText="user_id"><vspace/>OPTIONAL. Human-readable identifier
for the user who authorized this token.</t>
<t hangText="token_type"><vspace/>OPTIONAL. Type of the token as
defined in section 5.1 of <xref target="RFC6749">OAuth
2.0</xref>.</t>
</list></t>
<t>The response MAY include any claims defined as <xref
target="JWT">JWT</xref> claim names and carry the same semantics and
syntax, such as the following:</t>
<t><list style="hanging">
<t hangText="exp"><vspace/>OPTIONAL. Integer timestamp, measured
in the number of seconds since January 1 1970 UTC, indicating when
this token will expire.</t>
<t hangText="iat"><vspace/>OPTIONAL. Integer timestamp, measured
in the number of seconds since January 1 1970 UTC, indicating when
this token was originally issued.</t>
<t hangText="nbf"><vspace/>OPTIONAL. Integer timestamp, measured
in the number of seconds since January 1 1970 UTC, indicating when
this token is not to be used before.</t>
<t hangText="sub"><vspace/>OPTIONAL. Subject of the token. Usually
a machine-readable identifier of the resource owner who authorized
this token</t>
<t hangText="aud"><vspace/>OPTIONAL. Service-specific string
identifier or list of string identifiers representing the intended
audience for this token.</t>
<t hangText="iss"><vspace/>OPTIONAL. String representing the
issuer of this token.</t>
<t hangText="jti"><vspace/>OPTIONAL. String identifier for the
token.</t>
</list></t>
<t>Specific implementations MAY extend this structure with their own
service-specific pieces of information as top-level members of this
JSON object.</t>
<t>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 for
each protected resources in order to prevent protected resources from
learning more about the larger network than is necessary for their
function.</t>
<t>The response MAY be cached by the protected resource.</t>
<t>For example, the following response contains a set of information
about an active token:</t>
<figure>
<preamble>Following is a non-normative example response:</preamble>
<artwork><![CDATA[
HTTP/1.1 200 OK
Content-Type: application/json
{
"active": true,
"client_id": "l238j323ds-23ij4",
"user_id": "jdoe",
"scope": "read write dolphin",
"sub": "Z5O3upPC88QrAjx00dis",
"aud": "https://protected.example.net/resource",
"iss": "https://server.example.com/",
"exp": 1419356238,
"iat": 1419350238,
"extension_field": "twenty-seven"
}
]]></artwork>
</figure>
<t/>
<t>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, the authorization
server MUST return an introspection response with the active field set
to false. Note that in order 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:</t>
<figure>
<preamble>Following is a non-normative example response:</preamble>
<artwork><![CDATA[
HTTP/1.1 200 OK
Content-Type: application/json
{
"active": false
}
]]></artwork>
</figure>
</section>
<section anchor="ErrorResponse" title="Error Response">
<t>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 <xref
target="RFC6749">OAuth 2.0 </xref>.</t>
<t>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 <xref
target="RFC6750">OAuth 2.0 Bearer Token Usage</xref>.</t>
<t>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 <spanx style="verb">active</spanx>
field set to <spanx style="verb">false</spanx> as described in <xref
target="IntrospectionResponse"/>.</t>
</section>
</section>
<section anchor="IANA" title="IANA Considerations">
<t>This specification requests IANA to register the following values
into the IANA JSON Web Token Claims registry for JWT Claim Names.</t>
<t><?rfc subcompact="yes"?><list style="symbols">
<t>Claim Name: <spanx style="verb">active</spanx></t>
<t>Claim Description: Token active status</t>
<t>Change Controller: IESG</t>
<t>Specification Document(s): <xref target="IntrospectionResponse"/>
of [[ this document ]].</t>
</list><list style="symbols">
<t>Claim Name: <spanx style="verb">user_id</spanx></t>
<t>Claim Description: User identifier of the resource owner</t>
<t>Change Controller: IESG</t>
<t>Specification Document(s): <xref target="IntrospectionResponse"/>
of [[ this document ]].</t>
</list><list style="symbols">
<t>Claim Name: <spanx style="verb">client_id</spanx></t>
<t>Claim Description: Client identifier of the client</t>
<t>Change Controller: IESG</t>
<t>Specification Document(s): <xref target="IntrospectionResponse"/>
of [[ this document ]].</t>
</list><list style="symbols">
<t>Claim Name: <spanx style="verb">scope</spanx></t>
<t>Claim Description: Authorized scopes of the token</t>
<t>Change Controller: IESG</t>
<t>Specification Document(s): <xref target="IntrospectionResponse"/>
of [[ this document ]].</t>
</list><list style="symbols">
<t>Claim Name: <spanx style="verb">token_type</spanx></t>
<t>Claim Description: Type of the token</t>
<t>Change Controller: IESG</t>
<t>Specification Document(s): <xref target="IntrospectionResponse"/>
of [[ this document ]].</t>
</list><?rfc subcompact="no"?></t>
</section>
<section anchor="Security" title="Security Considerations">
<t>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 re-use 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.</t>
<t>Since the introspection endpoint takes in OAuth 2.0 tokens as
parameters, the server MUST support TLS 1.2 <xref target="RFC5246">RFC
5246</xref> 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, per
<xref target="RFC6125">RFC 6125</xref>. Implementation security
considerations can be found in <xref target="TLS.BCP">Recommendations
for Secure Use of TLS and DTLS</xref>.</t>
<t>In order to prevent the values of access tokens being from leaking
into server-side logs via query parameters, an authorization server
offering token introspection MAY disallow HTTP GET and instead require
an HTTP POST method only to the introspection endpoint.</t>
<t>In order to avoid disclosing internal server state, an introspection
response for an inactive token SHOULD NOT contain any additional claims
beyond the required <spanx style="verb">active</spanx> claim (with its
value set to <spanx style="verb">false</spanx>).</t>
<t>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
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).</t>
<t>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 in order 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 can not likely offer an
introspection service.</t>
</section>
<section anchor="Privacy" title="Privacy Considerations">
<t>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 way to limit disclosure is to require
authorization to call the introspection endpoint and to limit calls to
only registered and trusted protected resource servers. Another method
is to transmit user identifiers as opaque service-specific strings,
potentially returning different identifiers to each protected resource.
Omitting privacy-sensitive information from an introspection response is
the simplest way of minimizing privacy issues.</t>
</section>
<section title="Acknowledgements">
<t>Thanks to the OAuth Working Group and the UMA Working Group for
feedback.</t>
</section>
</middle>
<back>
<references title="Normative References">
<?rfc include='http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml'?>
<?rfc include='http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5246.xml'?>
<?rfc include='http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6125.xml'?>
<?rfc include='http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6749.xml'?>
<?rfc include='http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6750.xml'?>
<?rfc include='http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7009.xml'?>
<?rfc include='http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7159.xml'?>
<?rfc include='http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7231.xml'?>
<?rfc include='http://xml2rfc.ietf.org/public/rfc/bibxml4/reference.W3C.REC-html5-20141028.xml'?>
</references>
<references title="Informative References">
<reference anchor="JWT">
<front>
<title>JSON Web Token (JWT)</title>
<author fullname="Michael B. Jones" initials="M.B." surname="Jones">
<organization>Microsoft</organization>
<address>
<email>mbj@microsoft.com</email>
<uri>http://self-issued.info/</uri>
</address>
</author>
<author fullname="John Bradley" initials="J." surname="Bradley">
<organization abbrev="Ping Identity">Ping Identity</organization>
<address>
<email>ve7jtb@ve7jtb.com</email>
<uri>http://www.thread-safe.com/</uri>
</address>
</author>
<author fullname="Nat Sakimura" initials="N." surname="Sakimura">
<organization abbrev="NRI">Nomura Research
Institute</organization>
<address>
<email>n-sakimura@nri.co.jp</email>
<uri>http://nat.sakimura.org/</uri>
</address>
</author>
<date day="4" month="July" year="2014"/>
</front>
<seriesInfo name="Internet-Draft"
value="draft-ietf-oauth-json-web-token"/>
<format target="http://tools.ietf.org/html/draft-ietf-oauth-json-web-token"
type="HTML"/>
</reference>
<reference anchor="TLS.BCP">
<front>
<title>Recommendations for Secure Use of TLS and DTLS</title>
<author fullname="Yaron Sheffer" initials="Y." surname="Sheffer">
<organization>Porticor</organization>
<address>
<postal>
<street>29 HaHarash St.</street>
<city>Hod HaSharon</city>
<region/>
<code>4501303</code>
<country>Israel</country>
</postal>
<email>yaronf.ietf@gmail.com</email>
</address>
</author>
<author fullname="Ralph Holz" initials="R." surname="Holz">
<organization>Technische Universitaet Muenchen</organization>
<address>
<postal>
<street>Boltzmannstr. 3</street>
<city>Garching</city>
<region/>
<code>85748</code>
<country>Germany</country>
</postal>
<email>ralph.ietf@gmail.com</email>
</address>
</author>
<author fullname="Peter Saint-Andre" initials="P."
surname="Saint-Andre">
<organization>&yet</organization>
<address>
<email>peter@andyet.com</email>
<uri>https://andyet.com/</uri>
</address>
</author>
<date day="11" month="November" year="2014"/>
</front>
</reference>
</references>
<section title="Document History">
<t>[[ To be removed by the RFC Editor. ]]</t>
<t>- 04</t>
<t><list style="symbols">
<t>Removed <spanx style="verb">resource_id</spanx> from request.</t>
<t>Added examples.</t>
</list></t>
<t>- 03</t>
<t><list style="symbols">
<t>Updated HTML and HTTP references.</t>
<t>Call for registration of parameters in the JWT registry.</t>
</list></t>
<t>- 02</t>
<t><list style="symbols">
<t>Removed SAML pointer.</t>
<t>Clarified what an "active" token could be.</t>
<t>Explicitly declare introspection request as x-www-form-urlencoded
format.</t>
<t>Added extended example.</t>
<t>Made protected resource authentication a MUST.</t>
</list></t>
<t>- 01</t>
<t><list style="symbols">
<t>Fixed casing and consistent term usage.</t>
<t>Incorporated working group comments.</t>
<t>Clarified that authorization servers need to be able to
understand the token if they're to introspect it.</t>
<t>Various editorial cleanups.</t>
</list></t>
<t>- 00</t>
<t><list style="symbols">
<t>Created initial IETF drafted based on
draft-richer-oauth-introspection-06 with no normative changes.</t>
</list></t>
</section>
<section anchor="PoP" title="Use with Proof of Posession Tokens">
<t>With bearer tokens such as those defined by <xref
target="RFC6750">OAuth 2.0 Bearer Token Usage</xref>, 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 in
order 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 should be defined in an extension to
this specification.</t>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 08:40:44 |