draft-ietf-oauth-introspection-09.txt   draft-ietf-oauth-introspection-10.txt 
OAuth Working Group J. Richer, Ed. OAuth Working Group J. Richer, Ed.
Internet-Draft May 28, 2015 Internet-Draft June 22, 2015
Intended status: Standards Track Intended status: Standards Track
Expires: November 29, 2015 Expires: December 24, 2015
OAuth 2.0 Token Introspection OAuth 2.0 Token Introspection
draft-ietf-oauth-introspection-09 draft-ietf-oauth-introspection-10
Abstract Abstract
This specification defines a method for a protected resource to query This specification defines a method for a protected resource to query
an OAuth 2.0 authorization server to determine the active state of an 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 token and to determine meta-information about this token.
OAuth 2.0 deployments can use this method to convey information about OAuth 2.0 deployments can use this method to convey information about
the authorization context of the token from the authorization server the authorization context of the token from the authorization server
to the protected resource. to the protected resource.
skipping to change at page 1, line 41 skipping to change at page 1, line 41
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 29, 2015. This Internet-Draft will expire on December 24, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3
2. Introspection Endpoint . . . . . . . . . . . . . . . . . . . 3 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
2. Introspection Endpoint . . . . . . . . . . . . . . . . . . . 4
2.1. Introspection Request . . . . . . . . . . . . . . . . . . 4 2.1. Introspection Request . . . . . . . . . . . . . . . . . . 4
2.2. Introspection Response . . . . . . . . . . . . . . . . . 5 2.2. Introspection Response . . . . . . . . . . . . . . . . . 6
2.3. Error Response . . . . . . . . . . . . . . . . . . . . . 8 2.3. Error Response . . . . . . . . . . . . . . . . . . . . . 8
3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
3.1. OAuth Token Introspection Response Registry . . . . . . . 8 3.1. OAuth Token Introspection Response Registry . . . . . . . 9
3.1.1. Registration Template . . . . . . . . . . . . . . . . 9 3.1.1. Registration Template . . . . . . . . . . . . . . . . 9
3.1.2. Initial Registry Contents . . . . . . . . . . . . . . 9 3.1.2. Initial Registry Contents . . . . . . . . . . . . . . 10
4. Security Considerations . . . . . . . . . . . . . . . . . . . 11 4. Security Considerations . . . . . . . . . . . . . . . . . . . 11
5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 13 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 14
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 13 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 14
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 14
7.1. Normative References . . . . . . . . . . . . . . . . . . 14 7.1. Normative References . . . . . . . . . . . . . . . . . . 14
7.2. Informative References . . . . . . . . . . . . . . . . . 15 7.2. Informative References . . . . . . . . . . . . . . . . . 15
Appendix A. Use with Proof of Posession Tokens . . . . . . . . . 15 Appendix A. Use with Proof of Posession Tokens . . . . . . . . . 15
Appendix B. Document History . . . . . . . . . . . . . . . . . . 15 Appendix B. Document History . . . . . . . . . . . . . . . . . . 16
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 17
1. Introduction 1. Introduction
In OAuth 2.0, the contents of tokens are opaque to clients. This 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 means that the client does not need to know anything about the
content or structure of the token itself, if there is any. However, 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 there is still a large amount of metadata that may be attached to a
token, such as its current validity, approved scopes, and information token, such as its current validity, approved scopes, and information
about the context in which the token was issued. These pieces of about the context in which the token was issued. These pieces of
information are often vital to protected resources making information are often vital to protected resources making
authorization decisions based on the tokens being presented. Since authorization decisions based on the tokens being presented. Since
OAuth 2.0 [RFC6749] does not define a protocol for the resource OAuth 2.0 [RFC6749] does not define a protocol for the resource
server to learn meta-information about a token that is has received server to learn meta-information about a token that is has received
from an authorization server, several different approaches have been from an authorization server, several different approaches have been
developed to bridge this gap. These include using structured token developed to bridge this gap. These include using structured token
formats such as JWT [RFC7519] or proprietary inter-service formats such as JWT [RFC7519] or proprietary inter-service
communication mechanisms (such as shared databases and protected communication mechanisms (such as shared databases and protected
enterprise service buses) that convey token information. enterprise service buses) that convey token information.
This specification defines an interoperable web API that allows This specification defines a protocol that allows authorized
authorized protected resources to query the authorization server to protected resources to query the authorization server to determine
determine the set of metadata for a given token that was presented to the set of metadata for a given token that was presented to them by
them by an OAuth 2.0 client. This metadata includes whether or not an OAuth 2.0 client. This metadata includes whether or not the token
the token is currently active (or if it has expired or otherwise been is currently active (or if it has expired or otherwise been revoked),
revoked), what rights of access the token carries (usually conveyed what rights of access the token carries (usually conveyed through
through OAuth 2.0 scopes), and the authorization context in which the OAuth 2.0 scopes), and the authorization context in which the token
token was granted (including who authorized the token and which was granted (including who authorized the token and which client it
client it was issued to). Token introspection allows a protected was issued to). Token introspection allows a protected resource to
resource to query this information regardless of whether or not it is query this information regardless of whether or not it is carried in
carried in the token itself, allowing this method to be used along the token itself, allowing this method to be used along with or
with or independently of structured token values. Additionally, a independently of structured token values. Additionally, a protected
protected resource can use the mechanism described in this resource can use the mechanism described in this specification to
specification to introspect the token in a particular authorization introspect the token in a particular authorization decision context
decision context and ascertain the relevant metadata about the token and ascertain the relevant metadata about the token to make this
in order to make this authorization decision appropriately. authorization decision appropriately.
1.1. Terminology 1.1. Notational Conventions
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 [RFC2119].
Unless otherwise noted, all the protocol parameter names and values
are case sensitive.
1.2. Terminology
This section defines the terminology used by this specification. This section defines the terminology used by this specification.
This section is a normative portion of this specification, imposing This section is a normative portion of this specification, imposing
requirements upon implementations. requirements upon implementations.
This specification uses the terms "access token", "authorization This specification uses the terms "access token", "authorization
endpoint", "authorization grant", "authorization server", "client", endpoint", "authorization grant", "authorization server", "client",
"client identifier", "protected resource", "refresh token", "resource "client identifier", "protected resource", "refresh token", "resource
owner", "resource server", and "token endpoint" defined by OAuth 2.0 owner", "resource server", and "token endpoint" defined by OAuth 2.0
[RFC6749], and the terms "claim names" and "claim values" defined by [RFC6749], and the terms "claim names" and "claim values" defined by
JSON Web Token (JWT) [RFC7519]. JSON Web Token (JWT) [RFC7519].
This specification defines the following terms:
Token Introspection
The act of inquiring about the current state of an OAuth 2.0 token
through use of the network protocol defined in this document.
Introspection Endpoint
The OAuth 2.0 endpoint through which the token introspection
operation is accomplished..
2. Introspection Endpoint 2. Introspection Endpoint
The introspection endpoint is an OAuth 2.0 endpoint that takes a The introspection endpoint is an OAuth 2.0 endpoint that takes a
parameter representing an OAuth 2.0 token and returns a JSON parameter representing an OAuth 2.0 token and returns a JSON
[RFC7159] document representing the meta information surrounding the [RFC7159] document representing the meta information surrounding the
token, including whether this token is currently active. The token, including whether this token is currently active. The
definition of an active token is up to the authorization server, but definition of an active token is dependent upon the authorization
this is commonly a token that has been issued by this authorization server, but this is commonly a token that has been issued by this
server, is not expired, has not been revoked, and is within the authorization server, is not expired, has not been revoked, and valid
purview of the protected resource making the introspection call. for use at the protected resource making the introspection call.
The introspection endpoint MUST be protected by a transport-layer The introspection endpoint MUST be protected by a transport-layer
security mechanism as described in Section 4. security mechanism as described in Section 4. The means by which the
protected resource discovers the location of the introspection
endpoint are outside the scope of this specification.
2.1. Introspection Request 2.1. Introspection Request
The protected resource calls the introspection endpoint using an HTTP The protected resource calls the introspection endpoint using an HTTP
POST [RFC7231] request with parameters sent as "application/x-www- POST [RFC7231] request with parameters sent as "application/x-www-
form-urlencoded" data as defined in [W3C.REC-html5-20141028]. The form-urlencoded" data as defined in [W3C.REC-html5-20141028]. The
authorization server MAY allow an HTTP GET [RFC7231] request with protected resource sends a parameter representing the token along
parameters passed in the query string as defined in with optional parameters representing additional context that is
[W3C.REC-html5-20141028]. The protected resource sends a parameter known by the protected resource to aid the authorization server in
representing the token along with optional parameters representing its response.
additional context that is known by the protected resource to aid the
authorization server in its response.
token REQUIRED. The string value of the token. For access tokens, token REQUIRED. The string value of the token. For access tokens,
this is the "access_token" value returned from the token endpoint this is the "access_token" value returned from the token endpoint
defined in OAuth 2.0 [RFC6749] section 5.1. For refresh tokens, defined in OAuth 2.0 [RFC6749] section 5.1. For refresh tokens,
this is the "refresh_token" value returned from the token endpoint this is the "refresh_token" value returned from the token endpoint
as defined in OAuth 2.0 [RFC6749] section 5.1. Other token types as defined in OAuth 2.0 [RFC6749] section 5.1. Other token types
are outside the scope of this specification. are outside the scope of this specification.
token_type_hint OPTIONAL. A hint about the type of the token token_type_hint OPTIONAL. A hint about the type of the token
submitted for introspection. The protected resource MAY pass this submitted for introspection. The protected resource MAY pass this
parameter in order to help the authorization server to optimize parameter to help the authorization server to optimize the token
the token lookup. If the server is unable to locate the token lookup. If the server is unable to locate the token using the
using the given hint, it MUST extend its search across all of its given hint, it MUST extend its search across all of its supported
supported token types. An authorization server MAY ignore this token types. An authorization server MAY ignore this parameter,
parameter, particularly if it is able to detect the token type particularly if it is able to detect the token type automatically.
automatically. Values for this field are defined in OAuth Token Values for this field are defined in the OAuth Token Type Hints
Revocation [RFC7009]. registry defined in OAuth Token Revocation [RFC7009].
The endpoint MAY allow other parameters to provide further context to The endpoint MAY accept other OPTIONAL parameters to provide further
the query. For instance, an authorization service may need to know context to the query. For instance, an authorization server may
the IP address of the client accessing the protected resource in desire to know the IP address of the client accessing the protected
order to determine the appropriateness of the token being presented. resource to determine the appropriateness of the token being
presented. The definition of 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 Section 2.2.
To prevent unauthorized token scanning attacks, the endpoint MUST To prevent token scanning attacks, the endpoint MUST also require
also require some form of authorization to access this endpoint, such some form of authorization to access this endpoint, such as client
as client authentication as described in OAuth 2.0 [RFC6749] or a authentication as described in OAuth 2.0 [RFC6749] or a separate
separate OAuth 2.0 access token such as the bearer token described in OAuth 2.0 access token such as the bearer token described in OAuth
OAuth 2.0 Bearer Token Usage [RFC6750]. The methods of managing and 2.0 Bearer Token Usage [RFC6750]. The methods of managing and
validating these authentication credentials are out of scope of this validating these authentication credentials are out of scope of this
specification. specification.
For example, the following example shows a protected resource calling For example, the following example shows a protected resource calling
the token introspection endpoint to query about an OAuth 2.0 bearer. 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 token. The protected resource is using a separate OAuth 2.0 bearer
authorize this call. token to authorize this call.
Following is a non-normative example request: Following is a non-normative example request:
POST /introspect HTTP/1.1 POST /introspect HTTP/1.1
Host: server.example.com Host: server.example.com
Accept: application/json Accept: application/json
Content-Type: application/x-www-form-urlencoded Content-Type: application/x-www-form-urlencoded
Authorization: Bearer 23410913-abewfq.123483 Authorization: Bearer 23410913-abewfq.123483
token=2YotnFZFEjr1zCsicMWpAA token=2YotnFZFEjr1zCsicMWpAA
skipping to change at page 5, line 47 skipping to change at page 6, line 23
will vary depending on the implementation of the authorization will vary depending on the implementation of the authorization
server, and the information it keeps about its tokens, but a server, and the information it keeps about its tokens, but a
"true" value return for the "active" property will generally "true" value return for the "active" property will generally
indicate that a given token has been issued by this authorization indicate that a given token has been issued by this authorization
server, has not been revoked by the resource owner, and is within server, has not been revoked by the resource owner, and is within
its given time window of validity (e.g. after its issuance time its given time window of validity (e.g. after its issuance time
and before its expiration time). See Section 4 for information on and before its expiration time). See Section 4 for information on
implementation of such checks. implementation of such checks.
scope scope
OPTIONAL. A space-separated list of strings representing the OPTIONAL. A JSON string containing a space-separated list of
scopes associated with this token, in the format described in scopes associated with this token, in the format described in
section 3.3 of OAuth 2.0 [RFC6749]. section 3.3 of OAuth 2.0 [RFC6749].
client_id client_id
OPTIONAL. Client identifier for the OAuth 2.0 client that OPTIONAL. Client identifier for the OAuth 2.0 client that
requested this token. requested this token.
username username
OPTIONAL. Human-readable identifier for the resource owner who OPTIONAL. Human-readable identifier for the resource owner who
authorized this token. authorized this token.
skipping to change at page 7, line 10 skipping to change at page 7, line 32
Specific implementations MAY extend this structure with their own Specific implementations MAY extend this structure with their own
service-specific response names as top-level members of this JSON service-specific response names as top-level members of this JSON
object. Response names intended to be used across domains MUST be object. Response names intended to be used across domains MUST be
registered in the OAuth Token Introspection Response registry defined registered in the OAuth Token Introspection Response registry defined
in Section 3.1. in Section 3.1.
The authorization server MAY respond differently to different The authorization server MAY respond differently to different
protected resources making the same request. For instance, an protected resources making the same request. For instance, an
authorization server MAY limit which scopes from a given token are authorization server MAY limit which scopes from a given token are
returned for each protected resource in order to prevent protected returned for each protected resource to prevent protected resources
resources from learning more about the larger network than is from learning more about the larger network than is necessary for its
necessary for their function. operation.
The response MAY be cached by the protected resource to improve The response MAY be cached by the protected resource to improve
performance and reduce load on the introspection endpoint, but at the performance and reduce load on the introspection endpoint, but at the
cost of liveness of the information used by the protected resource. cost of liveness of the information used by the protected resource.
See Section 4 for more information regarding the trade off when the See Section 4 for more information regarding the trade off when the
response is cached. response is cached.
For example, the following response contains a set of information For example, the following response contains a set of information
about an active token: about an active token:
skipping to change at page 7, line 45 skipping to change at page 8, line 27
"iss": "https://server.example.com/", "iss": "https://server.example.com/",
"exp": 1419356238, "exp": 1419356238,
"iat": 1419350238, "iat": 1419350238,
"extension_field": "twenty-seven" "extension_field": "twenty-seven"
} }
If the introspection call is properly authorized but the token is not If the introspection call is properly authorized but the token is not
active, does not exist on this server, or the protected resource is active, does not exist on this server, or the protected resource is
not allowed to introspect this particular token, the authorization not allowed to introspect this particular token, the authorization
server MUST return an introspection response with the active field server MUST return an introspection response with the active field
set to false. Note that in order to avoid disclosing too much of the set to false. Note that to avoid disclosing too much of the
authorization server's state to a third party, the authorization authorization server's state to a third party, the authorization
server SHOULD NOT include any additional information about an server SHOULD NOT include any additional information about an
inactive token, including why the token is inactive. For example, inactive token, including why the token is inactive. For example,
the response for a token that has been revoked or is otherwise the response for a token that has been revoked or is otherwise
invalid would look like the following: invalid would look like the following:
Following is a non-normative example response: Following is a non-normative example response:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
skipping to change at page 11, line 31 skipping to change at page 12, line 15
o If the token can expire, the authorization server MUST determine o If the token can expire, the authorization server MUST determine
whether or not the token has expired. whether or not the token has expired.
o If the token can be issued before it is able to be used, the o 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 authorization server MUST determine whether or not a token's valid
period has started yet. period has started yet.
o If the token can be revoked after it was issued, the authorization o If the token can be revoked after it was issued, the authorization
server MUST determine whether or not such a revocation has taken server MUST determine whether or not such a revocation has taken
place. place.
o If the token has been signed, the authorization server MUST o If the token has been signed, the authorization server MUST
validate the signature. validate the signature.
o 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 If an authorization server fails to perform any applicable check, the
resource server could make an errant security decision based on that resource server could make an erroneous security decision based on
response. Note that not all of these checks will be applicable to that response. Note that not all of these checks will be applicable
all OAuth 2.0 deployments and it is up to the authorization server to to all OAuth 2.0 deployments and it is up to the authorization server
determine which of these checks (and any other checks) apply. to determine which of these checks (and any other checks) apply.
If left unprotected and un-throttled, the introspection endpoint If left unprotected and un-throttled, the introspection endpoint
could present a means for an attacker to poll a series of possible could present a means for an attacker to poll a series of possible
token values, fishing for a valid token. To prevent this, the token values, fishing for a valid token. To prevent this, the
authorization server MUST require authentication of protected authorization server MUST require authentication of protected
resources that need to access the introspection endpoint and SHOULD resources that need to access the introspection endpoint and SHOULD
require protected resources to be specifically authorized to call the require protected resources to be specifically authorized to call the
introspection endpoint. The specifics of this authentication introspection endpoint. The specifics of this authentication
credentials are out of scope of this specification, but commonly credentials are out of scope of this specification, but commonly
these credentials could take the form of any valid client these credentials could take the form of any valid client
skipping to change at page 12, line 13 skipping to change at page 12, line 48
endpoint and the introspection endpoint, though doing so potentially endpoint and the introspection endpoint, though doing so potentially
conflates the activities of the client and protected resource conflates the activities of the client and protected resource
portions of the software and the authorization server MAY require portions of the software and the authorization server MAY require
separate credentials for each mode. separate credentials for each mode.
Since the introspection endpoint takes in OAuth 2.0 tokens as Since the introspection endpoint takes in OAuth 2.0 tokens as
parameters and responds with information used to make authorization parameters and responds with information used to make authorization
decisions, the server MUST support TLS 1.2 RFC 5246 [RFC5246] and MAY decisions, the server MUST support TLS 1.2 RFC 5246 [RFC5246] and MAY
support additional transport-layer mechanisms meeting its security support additional transport-layer mechanisms meeting its security
requirements. When using TLS, the client or protected resource MUST requirements. When using TLS, the client or protected resource MUST
perform a TLS/SSL server certificate check, per RFC 6125 [RFC6125]. perform a TLS/SSL server certificate check, as specified in RFC 6125
Implementation security considerations can be found in [RFC6125]. Implementation security considerations can be found in
Recommendations for Secure Use of TLS and DTLS [TLS.BCP]. Recommendations for Secure Use of TLS and DTLS [TLS.BCP].
In order to prevent the values of access tokens from leaking into To prevent the values of access tokens from leaking into server-side
server-side logs via query parameters, an authorization server logs via query parameters, an authorization server offering token
offering token introspection MAY disallow HTTP GET and instead introspection MAY disallow the use of HTTP GET on the introspection
require an HTTP POST method to be used at the introspection endpoint. endpoint and instead require the HTTP POST method to be used at the
introspection endpoint.
In order to avoid disclosing internal server state, an introspection To avoid disclosing internal server state, an introspection response
response for an inactive token SHOULD NOT contain any additional for an inactive token SHOULD NOT contain any additional claims beyond
claims beyond the required "active" claim (with its value set to the required "active" claim (with its value set to "false").
"false").
Since a protected resource MAY cache the response of the Since a protected resource MAY cache the response of the
introspection endpoint, designers of an OAuth 2.0 system using this introspection endpoint, designers of an OAuth 2.0 system using this
protocol MUST consider the performance and security trade-offs protocol MUST consider the performance and security trade-offs
inherent in caching security information such as this. A less inherent in caching security information such as this. A less
aggressive cache with a short timeout will provide the protected aggressive cache with a short timeout will provide the protected
resource with more up to date information (due to it needing to query resource with more up to date information (due to it needing to query
the introspection endpoint more often) at the cost of increased the introspection endpoint more often) at the cost of increased
network traffic and load on the introspection endpoint. A more network traffic and load on the introspection endpoint. A more
aggressive cache with a longer duration will minimize network traffic aggressive cache with a longer duration will minimize network traffic
and load on the introspection endpoint, but at the risk of stale and load on the introspection endpoint, but at the risk of stale
information about the token. For example, the token may be revoked information about the token. For example, the token may be revoked
while the protected resource is relying on the value of the cached while the protected resource is relying on the value of the cached
response to make authorization decisions. This creates a window response to make authorization decisions. This creates a window
during which a revoked token could be used at the protected resource. during which a revoked token could be used at the protected resource.
Consequently, an acceptable cache validity duration needs to be Consequently, an acceptable cache validity duration needs to be
carefully considered given the concerns and sensitivities of the carefully considered given the concerns and sensitivities of the
protected resource being accessed and the likelihood of a token being protected resource being accessed and the likelihood of a token being
revoked or invalidated in the interim period. Highly sensitive revoked or invalidated in the interim period. Highly sensitive
environments can opt to disable caching entirely on the protected environments can opt to disable caching entirely on the protected
resource in order to eliminate the risk of stale cached information resource to eliminate the risk of stale cached information entirely,
entirely, again at the cost of increased network traffic and server again at the cost of increased network traffic and server load. If
load. 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 An authorization server offering token introspection must be able to
understand the token values being presented to it during this call. understand the token values being presented to it during this call.
The exact means by which this happens is an implementation detail and The exact means by which this happens is an implementation detail and
outside the scope of this specification. For unstructured tokens, outside the scope of this specification. For unstructured tokens,
this could take the form of a simple server-side database query this could take the form of a simple server-side database query
against a data store containing the context information for the against a data store containing the context information for the
token. For structured tokens, this could take the form of the server token. For structured tokens, this could take the form of the server
parsing the token, validating its signature or other protection parsing the token, validating its signature or other protection
mechanisms, and returning the information contained in the token back mechanisms, and returning the information contained in the token back
to the protected resource (allowing the protected resource to be to the protected resource (allowing the protected resource to be
unaware of the token's contents, much like the client). unaware of the token's contents, much like the client). Note that
for tokens carrying encrypted information that is needed during the
Note that for tokens carrying encrypted information that is needed introspection process, the authorization server must be able to
during the introspection process, the authorization server MUST be decrypt and validate the token to access this information. Also note
able to decrypt and validate the token in order to access this that in cases where the authorization server stores no information
information. Also note that in cases where the authorization server about the token and has no means of accessing information about the
stores no information about the token and has no means of accessing token by parsing the token itself, it can not likely offer an
information about the token by parsing the token itself, it can not introspection service.
likely offer an introspection service.
5. Privacy Considerations 5. Privacy Considerations
The introspection response may contain privacy-sensitive information The introspection response may contain privacy-sensitive information
such as user identifiers for resource owners. When this is the case, such as user identifiers for resource owners. When this is the case,
measures MUST be taken to prevent disclosure of this information to measures MUST be taken to prevent disclosure of this information to
unintended parties. One way to limit disclosure is to require unintended parties. One method is to transmit user identifiers as
authorization to call the introspection endpoint and to limit calls opaque service-specific strings, potentially returning different
to only registered and trusted protected resource servers. Another identifiers to each protected resource.
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 If the protected resource sends additional information about the
client's request to the authorization server (such as the client's IP client's request to the authorization server (such as the client's IP
address) using an extension of this specification, such information address) using an extension of this specification, such information
could have additional privacy considerations. However, the nature could have additional privacy considerations. However, the nature
and implications of such extensions are outside the scope of this and implications of such extensions are outside the scope of this
specification. specification.
Omitting privacy-sensitive information from an introspection response Omitting privacy-sensitive information from an introspection response
is the simplest way of minimizing privacy issues. is the simplest way of minimizing privacy issues.
skipping to change at page 14, line 42 skipping to change at page 15, line 26
[RFC7009] Lodderstedt, T., Dronia, S., and M. Scurtescu, "OAuth 2.0 [RFC7009] Lodderstedt, T., Dronia, S., and M. Scurtescu, "OAuth 2.0
Token Revocation", RFC 7009, August 2013. Token Revocation", RFC 7009, August 2013.
[RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, March 2014. Interchange Format", RFC 7159, March 2014.
[RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
(HTTP/1.1): Semantics and Content", RFC 7231, June 2014. (HTTP/1.1): Semantics and Content", RFC 7231, June 2014.
[RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", RFC 7519, May 2015.
[W3C.REC-html5-20141028] [W3C.REC-html5-20141028]
Hickson, I., Berjon, R., Faulkner, S., Leithead, T., Hickson, I., Berjon, R., Faulkner, S., Leithead, T.,
Navara, E., O'Connor, E., and S. Pfeiffer, "HTML5", Navara, E., O'Connor, E., and S. Pfeiffer, "HTML5",
World Wide Web Consortium Recommendation REC- World Wide Web Consortium Recommendation REC-
html5-20141028, October 2014, html5-20141028, October 2014,
<http://www.w3.org/TR/2014/REC-html5-20141028>. <http://www.w3.org/TR/2014/REC-html5-20141028>.
7.2. Informative References 7.2. Informative References
[RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", RFC 7519, May 2015.
[TLS.BCP] Sheffer, Y., Holz, R., and P. Saint-Andre, [TLS.BCP] Sheffer, Y., Holz, R., and P. Saint-Andre,
"Recommendations for Secure Use of TLS and DTLS", November "Recommendations for Secure Use of TLS and DTLS", November
2014. 2014.
Appendix A. Use with Proof of Posession Tokens Appendix A. Use with Proof of Posession Tokens
With bearer tokens such as those defined by OAuth 2.0 Bearer Token With bearer tokens such as those defined by OAuth 2.0 Bearer Token
Usage [RFC6750], the protected resource will have in its possession Usage [RFC6750], the protected resource will have in its possession
the entire secret portion of the token for submission to the the entire secret portion of the token for submission to the
introspection service. However, for proof-of-possession style introspection service. However, for proof-of-possession style
tokens, the protected resource will have only a token identifier used tokens, the protected resource will have only a token identifier used
during the request, along with the cryptographic signature on the during the request, along with the cryptographic signature on the
request. The protected resource would be able to submit the token request. The protected resource would be able to submit the token
identifier to the authorization server's token endpoint in order to identifier to the authorization server's token endpoint to obtain the
obtain the necessary key information needed to validate the signature necessary key information needed to validate the signature on the
on the request. The details of this usage are outside the scope of request. The details of this usage are outside the scope of this
this specification and will be defined in an extension to this specification and will be defined in an extension to this
specification. specification.
Appendix B. Document History Appendix B. Document History
[[ To be removed by the RFC Editor. ]] [[ To be removed by the RFC Editor. ]]
-10
o Added missing 2119 section to terminology.
o Removed optional HTTP GET at introspection endpoint.
o Added terminology.
o Renamed this "a protocol" instead of "web API".
o Moved JWT to normative reference.
o Reworded definition of "scope" value.
o Clarified extensibility of input parameters.
o Noted that discover is out of scope.
o Fixed several typos and imprecise references.
-09 -09
o Updated JOSE, JWT, and OAuth Assertion draft references to final o Updated JOSE, JWT, and OAuth Assertion draft references to final
RFC numbers. RFC numbers.
-08 -08
o Added privacy considerations note about extensions. o Added privacy considerations note about extensions.
o Added acknowledgements (finally). o Added acknowledgements (finally).
 End of changes. 37 change blocks. 
107 lines changed or deleted 144 lines changed or added

This html diff was produced by rfcdiff 1.42. The latest version is available from http://tools.ietf.org/tools/rfcdiff/