draft-ietf-oauth-introspection-01.txt   draft-ietf-oauth-introspection-02.txt 
OAuth Working Group J. Richer, Ed. OAuth Working Group J. Richer, Ed.
Internet-Draft The MITRE Corporation Internet-Draft The MITRE Corporation
Intended status: Standards Track November 30, 2014 Intended status: Standards Track December 3, 2014
Expires: June 3, 2015 Expires: June 6, 2015
OAuth 2.0 Token Introspection OAuth 2.0 Token Introspection
draft-ietf-oauth-introspection-01 draft-ietf-oauth-introspection-02
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 June 3, 2015. This Internet-Draft will expire on June 6, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2014 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
2. Introspection Endpoint . . . . . . . . . . . . . . . . . . . 3 2. Introspection Endpoint . . . . . . . . . . . . . . . . . . . 3
2.1. Introspection Request . . . . . . . . . . . . . . . . . . 3 2.1. Introspection Request . . . . . . . . . . . . . . . . . . 4
2.2. Introspection Response . . . . . . . . . . . . . . . . . 4 2.2. Introspection Response . . . . . . . . . . . . . . . . . 5
2.3. Error Response . . . . . . . . . . . . . . . . . . . . . 5 2.3. Error Response . . . . . . . . . . . . . . . . . . . . . 6
3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6
4. Security Considerations . . . . . . . . . . . . . . . . . . . 5 4. Security Considerations . . . . . . . . . . . . . . . . . . . 6
5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 7 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 7
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 8
7.1. Normative References . . . . . . . . . . . . . . . . . . 7 7.1. Normative References . . . . . . . . . . . . . . . . . . 8
7.2. Informative References . . . . . . . . . . . . . . . . . 8 7.2. Informative References . . . . . . . . . . . . . . . . . 8
Appendix A. Document History . . . . . . . . . . . . . . . . . . 8 Appendix A. Document History . . . . . . . . . . . . . . . . . . 9
Appendix B. Non-normative Example . . . . . . . . . . . . . . . 8 Appendix B. Non-normative Examples . . . . . . . . . . . . . . . 9
Appendix C. Use with Proof of Posession Tokens . . . . . . . . . 10 Appendix C. Use with Proof of Posession Tokens . . . . . . . . . 11
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11
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] defines no direct relationship between the OAuth 2.0 [RFC6749] defines no direct relationship between the
authorization server and the protected resource, only that they must authorization server and the protected resource, only that they must
have an agreement on the tokens themselves, there have been many have an agreement on the tokens themselves, there have been many
different approaches to bridging this gap. These include using different approaches to bridging this gap. These include using
structured token formats such as JWT [JWT] or SAML [[ Editor's Note: structured token formats such as JWT [JWT] or proprietary inter-
Which SAML document should we reference here? ]] and proprietary service communication mechanisms (such as shared databases and
inter-service communication mechanisms (such as shared databases and
protected enterprise service buses) that convey token information. protected enterprise service buses) that convey token information.
This specification defines an interoperable web API that allows This specification defines an interoperable web API that allows
authorized protected resources to query the authorization server to authorized protected resources to query the authorization server to
determine the set of metadata for a given token that was presented 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 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 the token is currently active (or if it has expired or otherwise been
revoked), what rights of access the token carries (usually conveyed revoked), what rights of access the token carries (usually conveyed
through OAuth 2.0 scopes), and the authorization context in which the through OAuth 2.0 scopes), and the authorization context in which the
token was granted (including who authorized the token and which token was granted (including who authorized the token and which
client it was issued to). Token introspection allows a protected client it was issued to). Token introspection allows a protected
resource to query this information regardless of whether or not it is resource to query this information regardless of whether or not it is
carried in the token itself, allowing this method to be used along carried in the token itself, allowing this method to be used along
with or independently of structured token values. Additionally, a with or independently of structured token values. Additionally, a
protected resource can use the mechanism described in this protected resource can use the mechanism described in this
specification to introspect the token in a particular authorization specification to introspect the token in a particular authorization
decision context and ascertain the relevant metadata about the token decision context and ascertain the relevant metadata about the token
in order to make this authorization decision appropriately. in order to make this authorization decision appropriately.
1.1. Terminology
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
[RFC6749], and the terms "claim names" and "claim values" defined by
JSON Web Token (JWT) [JWT].
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. 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.
The introspection endpoint MUST be protected by TLS of at least The introspection endpoint MUST be protected by TLS of at least
version 1.2 RFC 5246 [RFC5246] and MAY support additional transport- version 1.2 RFC 5246 [RFC5246] and MAY support additional transport-
layer mechanisms meeting its security requirements. When using TLS, layer mechanisms meeting its security requirements. When using TLS,
the client or protected resource MUST perform a TLS/SSL server the protected resource MUST perform a TLS/SSL server certificate
certificate check, per RFC 6125 [RFC6125]. Implementation security check, per RFC 6125 [RFC6125]. Implementation security
considerations can be found in Recommendations for Secure Use of TLS considerations can be found in Recommendations for Secure Use of TLS
and DTLS [TLS.BCP]. and DTLS [TLS.BCP].
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 [RFC2616] request (or optionally an HTTP GET request). The POST [RFC2616] request with parameters sent as "application/x-www-
protected resource sends a parameter representing the token along form-urlencoded" data as defined in [RFC1866]. The authorization
with optional parameters representing additional context that is server MAY allow an HTTP GET [RFC2616] request with parameters passed
known by the protected resource to aid the authorization server in in the query string as defined in [RFC1866]. The protected resource
its response. 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.
These parameters
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.
resource_id OPTIONAL. A service-specific string identifying the resource_id OPTIONAL. A service-specific string identifying the
resource that the token is being used for. This value allows the resource that the token is being used for. This value allows the
skipping to change at page 4, line 24 skipping to change at page 4, line 46
of its supported token types. An authorization server MAY ignore of its supported token types. An authorization server MAY ignore
this parameter, particularly if it is able to detect the token this parameter, particularly if it is able to detect the token
type automatically. Values for this field are defined in OAuth type automatically. Values for this field are defined in OAuth
Token Revocation [RFC7009]. Token Revocation [RFC7009].
The endpoint MAY allow other parameters to provide further context to The endpoint MAY allow other parameters to provide further context to
the query. For instance, an authorization service may need to know the query. For instance, an authorization service may need to know
the IP address of the client accessing the protected resource in the IP address of the client accessing the protected resource in
order to determine the appropriateness of the token being presented. order to determine the appropriateness of the token being presented.
To prevent unauthorized token scanning attacks, the endpoint SHOULD To prevent unauthorized token scanning attacks, the endpoint MUST
also require some form of authorization to access this endpoint, such also require some form of authorization to access this endpoint, such
as client authentication as described in OAuth 2.0 [RFC6749] or a as client authentication as described in OAuth 2.0 [RFC6749] or a
separate OAuth 2.0 access token such as the bearer token described in separate OAuth 2.0 access token such as the bearer token described in
OAuth 2.0 Bearer Token Usage [RFC6750]. The methods of managing and OAuth 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, though it is RECOMMENDED that these credentials be specification.
distinct from those used at an authorization server's token endpoint.
2.2. Introspection Response 2.2. Introspection Response
The server responds with a JSON object [RFC7159] in "application/ The server responds with a JSON object [RFC7159] in "application/
json" format with the following top-level members. Specific json" format with the following top-level members. Several of these
implementations MAY extend this structure with their own service- claims are defined as JWT [JWT] claim names and carry the same
specific pieces of information. semantics and syntax. Specific implementations MAY extend this
structure with their own service-specific pieces of information.
active REQUIRED. Boolean indicator of whether or not the presented active REQUIRED. Boolean indicator of whether or not the presented
token is currently active. The authorization server determines token is currently active. The authorization server determines
whether and when a given token is in an active state. whether and when a given token is in an active state.
exp OPTIONAL. Integer timestamp, measured in the number of seconds exp OPTIONAL. Integer timestamp, measured in the number of seconds
since January 1 1970 UTC, indicating when this token will expire. since January 1 1970 UTC, indicating when this token will expire,
as defined in JWT [JWT].
iat OPTIONAL. Integer timestamp, measured in the number of seconds iat OPTIONAL. Integer timestamp, measured in the number of seconds
since January 1 1970 UTC, indicating when this token was since January 1 1970 UTC, indicating when this token was
originally issued. originally issued, as defined in JWT [JWT].
scope OPTIONAL. A space-separated list of strings representing the scope OPTIONAL. A space-separated list of strings representing the
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 OPTIONAL. Client identifier for the OAuth 2.0 client that client_id OPTIONAL. Client identifier for the OAuth 2.0 client that
requested this token. requested this token.
sub OPTIONAL. Machine-readable identifier of the resource owner who sub OPTIONAL. Machine-readable identifier of the resource owner who
authorized this token. authorized this token, as defined in JWT [JWT].
user_id OPTIONAL. Human-readable identifier for the user who user_id OPTIONAL. Human-readable identifier for the user who
authorized this token. authorized this token.
aud OPTIONAL. Service-specific string identifier or list of string aud OPTIONAL. Service-specific string identifier or list of string
identifiers representing the intended audience for this token. identifiers representing the intended audience for this token, as
defined in JWT [JWT].
iss OPTIONAL. String representing the issuer of this token. iss OPTIONAL. String representing the issuer of this token, as
defined in JWT [JWT].
token_type OPTIONAL. Type of the token as defined in section 5.1 of token_type OPTIONAL. Type of the token as defined in section 5.1 of
OAuth 2.0 [RFC6749]. OAuth 2.0 [RFC6749].
The response MAY be cached by the protected resource, and the The response MAY be cached by the protected resource.
authorization server SHOULD communicate appropriate cache controls
using applicable HTTP headers. The authorization server MAY respond differently to different
protected resources making the same request.
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.
2.3. Error Response 2.3. Error Response
If the protected resource uses OAuth 2.0 client credentials to If the protected resource uses OAuth 2.0 client credentials to
authenticate to the introspection endpoint and its credentials are authenticate to the introspection endpoint and its credentials are
invalid, the authorization server responds with an HTTP 400 (Bad invalid, the authorization server responds with an HTTP 401
Request) as described in section 5.2 of OAuth 2.0 [RFC6749]. (Unauthorized) as described in section 5.2 of OAuth 2.0 [RFC6749].
If the protected resource uses an OAuth 2.0 bearer token to authorize If the protected resource uses an OAuth 2.0 bearer token to authorize
its call to the introspection endpoint and the token used for its call to the introspection endpoint and the token used for
authorization does not contain sufficient privileges or is otherwise authorization does not contain sufficient privileges or is otherwise
invalid for this request, the authorization server responds with an invalid for this request, the authorization server responds with an
HTTP 400 code as described in section 3 of OAuth 2.0 Bearer Token HTTP 401 code as described in section 3 of OAuth 2.0 Bearer Token
Usage [RFC6750]. Usage [RFC6750].
3. IANA Considerations 3. IANA Considerations
This document makes no request of IANA. [[ This document will register several claims in the JWT registry.
]]
4. Security Considerations 4. Security Considerations
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. The specifics of this token values, fishing for a valid token. To prevent this, the
authentication credentials are out of scope of this specification, authorization server MUST require authentication of protected
but commonly these credentials could take the form of any valid resources that need to access the introspection endpoint and SHOULD
client authentication mechanism used with the token endpoint, an require protected resources to be specifically authorized to call the
OAuth 2.0 access token, or other HTTP authorization or authentication introspection endpoint. The specifics of this authentication
mechanism. The authorization server SHOULD issue credentials to any credentials are out of scope of this specification, but commonly
protected resources that need to access the introspection endpoint, these credentials could take the form of any valid client
SHOULD require protected resources to be specifically authorized to authentication mechanism used with the token endpoint, an OAuth 2.0
call the introspection endpoint, and SHOULD NOT allow a single piece access token, or other HTTP authorization or authentication
of software acting as both a client and a protected resource to re- mechanism. A single piece of software acting as both a client and a
use the same credentials between the token endpoint and the protected resource MAY re-use the same credentials between the token
introspection endpoint. 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 Since the introspection endpoint takes in OAuth 2.0 tokens as
parameters, the server MUST support TLS 1.2 RFC 5246 [RFC5246] and parameters, the server MUST support TLS 1.2 RFC 5246 [RFC5246] and
MAY support additional transport-layer mechanisms meeting its MAY support additional transport-layer mechanisms meeting its
security requirements. When using TLS, the client or protected security requirements. When using TLS, the client or protected
resource MUST perform a TLS/SSL server certificate check, per RFC resource MUST perform a TLS/SSL server certificate check, per RFC
6125 [RFC6125]. Implementation security considerations can be found 6125 [RFC6125]. Implementation security considerations can be found
in Recommendations for Secure Use of TLS and DTLS [TLS.BCP]. in Recommendations for Secure Use of TLS and DTLS [TLS.BCP].
In order to prevent the values of access tokens being from leaking In order to prevent the values of access tokens being from leaking
skipping to change at page 6, line 41 skipping to change at page 7, line 25
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 a token carrying encrypted information that is needed Note that for tokens carrying encrypted information that is needed
during the introspection process, the authorization server MUST be during the introspection process, the authorization server MUST be
able to decrypt and validate the token in order to access this able to decrypt and validate the token in order to access this
information. In cases where the authorization server stores no information. Also note that in cases where the authorization server
information about the token and has no means of accessing information stores no information about the token and has no means of accessing
about the token, it can not likely offer an introspection service. information about the token by parsing the token itself, it can not
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 way to limit disclosure is to require
authorization to call the introspection endpoint and to limit calls authorization to call the introspection endpoint and to limit calls
to only registered and trusted protected resource servers. Another to only registered and trusted protected resource servers. Another
method is to transmit user identifiers as opaque service-specific method is to transmit user identifiers as opaque service-specific
skipping to change at page 7, line 28 skipping to change at page 8, line 9
6. Acknowledgements 6. Acknowledgements
Thanks to the OAuth Working Group and the UMA Working Group for Thanks to the OAuth Working Group and the UMA Working Group for
feedback. feedback.
7. References 7. References
7.1. Normative References 7.1. Normative References
[RFC1866] Berners-Lee, T. and D. Connolly, "Hypertext Markup
Language - 2.0", RFC 1866, November 1995.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, August 2008. (TLS) Protocol Version 1.2", RFC 5246, August 2008.
skipping to change at page 8, line 22 skipping to change at page 9, line 9
progress), July 2014. progress), July 2014.
[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. Document History Appendix A. Document History
[[ To be removed by the RFC Editor. ]] [[ To be removed by the RFC Editor. ]]
- 02
o Removed SAML pointer.
o Clarified what an "active" token could be.
o Explicitly declare introspection request as x-www-form-urlencoded
format.
o Added extended example.
o Made protected resource authentication a MUST.
- 01 - 01
o Fixed casing and consistent term usage. o Fixed casing and consistent term usage.
o Incorporated working group comments. o Incorporated working group comments.
o Clarified that authorization servers need to be able to understand o Clarified that authorization servers need to be able to understand
the token if they're to introspect it. the token if they're to introspect it.
o Various editorial cleanups. o Various editorial cleanups.
- 00 - 00
o Created initial IETF drafted based on draft-richer-oauth- o Created initial IETF drafted based on draft-richer-oauth-
introspection-06 with no normative changes. introspection-06 with no normative changes.
Appendix B. Non-normative Example Appendix B. Non-normative Examples
In this non-normative example, a protected resource receives a In this non-normative example, a protected resource receives a
request from a client carrying an OAuth 2.0 bearer token as defined request from a client carrying an OAuth 2.0 bearer token as defined
in OAuth 2.0 Bearer Token Usage [RFC6750]. In order to know how and in OAuth 2.0 Bearer Token Usage [RFC6750]. In order to know how and
whether to serve the request given this token, the protected resource whether to serve the request given this token, the protected resource
then makes the following request to the introspection endpoint of the then makes the following request to the introspection endpoint of the
authorization server. The protected resource authenticates with its authorization server. The protected resource authenticates with its
own credentials, here re-using the format of client identifier and own credentials, here re-using the format of client identifier and
client secret conveyed as HTTP Basic authentication as per OAuth 2.0 client secret conveyed as HTTP Basic authentication as per OAuth 2.0
[RFC6749] Section 2.3.1. [RFC6749] Section 2.3.1.
skipping to change at page 9, line 15 skipping to change at page 10, line 15
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: authserver.example.com Host: authserver.example.com
Content-type: application/x-www-form-urlencoded Content-type: application/x-www-form-urlencoded
Accept: application/json Accept: application/json
Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3
token=X3241Affw.4233-99JXJ token=X3241Affw.4233-99JXJ
In this non-normative example, the protected resource also sends a
resource identifier and token type hint to the authorization server
to aid the authorization server's response:
Following is a non-normative example request (with line wraps for
display purposes only):
POST /introspect HTTP/1.1
Host: authserver.example.com
Content-type: application/x-www-form-urlencoded
Accept: application/json
Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3
token=X3241Affw.4233-99JXJ
&resource_id=rsid-2348e.2381k3
&token_type_hint=access_token
The authorization server validates the protected resource's The authorization server validates the protected resource's
credentials and looks up the information in the token. If the token credentials and looks up the information in the token. If the token
is currently active and the authenticated protected resource is is currently active and the authenticated protected resource is
authorized to know information about this token, the authorization authorized to know information about this token, the authorization
server returns the following JSON document. server returns the following JSON document.
Following is a non-normative example active token response (with line Following is a non-normative example active token response (with line
wraps for display purposes only): wraps for display purposes only):
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store
{ {
"active": true, "active": true,
"client_id":"s6BhdRkqt3", "client_id":"s6BhdRkqt3",
"scope": "read write dolphin", "scope": "read write dolphin",
"sub": "2309fj32kl", "sub": "2309fj32kl",
"user_id": "jdoe", "user_id": "jdoe",
"aud": "https://example.org/protected-resource/*", "aud": "https://example.org/protected-resource/*",
"iss": "https://authserver.example.com/" "iss": "https://authserver.example.com/"
} }
skipping to change at page 9, line 37 skipping to change at page 11, line 4
{ {
"active": true, "active": true,
"client_id":"s6BhdRkqt3", "client_id":"s6BhdRkqt3",
"scope": "read write dolphin", "scope": "read write dolphin",
"sub": "2309fj32kl", "sub": "2309fj32kl",
"user_id": "jdoe", "user_id": "jdoe",
"aud": "https://example.org/protected-resource/*", "aud": "https://example.org/protected-resource/*",
"iss": "https://authserver.example.com/" "iss": "https://authserver.example.com/"
} }
If the token presented is not currently active for any reason (for If the token presented is not currently active for any reason (for
instance, it has been revoked by the resource owner) but the instance, it has been revoked by the resource owner, it has expired,
authorization presented during the request is otherwise valid, the or the protected resource is not allowed to ask about this particular
authorization server returns the following JSON document. token) but the authorization presented during the request is
otherwise valid, the authorization server returns the following JSON
document.
Following is a non-normative example response to an inactive or Following is a non-normative example response to an inactive or
invalid token (with line wraps for display purposes only): invalid token (with line wraps for display purposes only):
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store
{ {
"active": false "active": 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.
Appendix C. Use with Proof of Posession Tokens Appendix C. 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 posession Usage [RFC6750], the protected resource will have in its posession
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-posession style tokens, introspection service. However, for proof-of-posession style tokens,
the protected resource will have only a token identifier used during the protected resource will have only a token identifier used during
the request, along with the cryptographic signature on the request. the request, along with the cryptographic signature on the request.
The protected resource would be able to submit the token identifier The protected resource would be able to submit the token identifier
 End of changes. 36 change blocks. 
70 lines changed or deleted 133 lines changed or added

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