draft-ietf-oauth-introspection-08.txt   draft-ietf-oauth-introspection-09.txt 
OAuth Working Group J. Richer, Ed. OAuth Working Group J. Richer, Ed.
Internet-Draft April 21, 2015 Internet-Draft May 28, 2015
Intended status: Standards Track Intended status: Standards Track
Expires: October 23, 2015 Expires: November 29, 2015
OAuth 2.0 Token Introspection OAuth 2.0 Token Introspection
draft-ietf-oauth-introspection-08 draft-ietf-oauth-introspection-09
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 October 23, 2015. This Internet-Draft will expire on November 29, 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
skipping to change at page 2, line 29 skipping to change at page 2, line 29
2.3. Error Response . . . . . . . . . . . . . . . . . . . . . 8 2.3. Error Response . . . . . . . . . . . . . . . . . . . . . 8
3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
3.1. OAuth Token Introspection Response Registry . . . . . . . 8 3.1. OAuth Token Introspection Response Registry . . . . . . . 8
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 . . . . . . . . . . . . . . 9
4. Security Considerations . . . . . . . . . . . . . . . . . . . 11 4. Security Considerations . . . . . . . . . . . . . . . . . . . 11
5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 13 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 13
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 13 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 13
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 14
7.1. Normative References . . . . . . . . . . . . . . . . . . 14 7.1. Normative References . . . . . . . . . . . . . . . . . . 14
7.2. Informative References . . . . . . . . . . . . . . . . . 14 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 . . . . . . . . . . . . . . . . . . 15
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16
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 [JWT] or proprietary inter-service communication formats such as JWT [RFC7519] or proprietary inter-service
mechanisms (such as shared databases and protected enterprise service communication mechanisms (such as shared databases and protected
buses) that convey token information. 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
skipping to change at page 3, line 33 skipping to change at page 3, line 33
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) [JWT]. JSON Web Token (JWT) [RFC7519].
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 up to the authorization server, but
this is commonly a token that has been issued by this authorization this is commonly a token that has been issued by this authorization
server, is not expired, has not been revoked, and is within the server, is not expired, has not been revoked, and is within the
skipping to change at page 5, line 45 skipping to change at page 5, line 45
REQUIRED. Boolean indicator of whether or not the presented token REQUIRED. Boolean indicator of whether or not the presented token
is currently active. The specifics of a token's "active" state is currently active. The specifics of a token's "active" state
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 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 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.
token_type token_type
OPTIONAL. Type of the token as defined in section 5.1 of OAuth OPTIONAL. Type of the token as defined in section 5.1 of OAuth
2.0 [RFC6749]. 2.0 [RFC6749].
exp exp
OPTIONAL. Integer timestamp, measured in the number of seconds 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]. as defined in JWT [RFC7519].
iat iat
OPTIONAL. Integer timestamp, measured in the number of seconds 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, as defined in JWT [JWT]. originally issued, as defined in JWT [RFC7519].
nbf nbf
OPTIONAL. Integer timestamp, measured in the number of seconds OPTIONAL. Integer timestamp, measured in the number of seconds
since January 1 1970 UTC, indicating when this token is not to be since January 1 1970 UTC, indicating when this token is not to be
used before, as defined in JWT [JWT]. used before, as defined in JWT [RFC7519].
sub sub
OPTIONAL. Subject of the token, as defined in JWT [JWT]. Usually OPTIONAL. Subject of the token, as defined in JWT [RFC7519].
a machine-readable identifier of the resource owner who authorized Usually a machine-readable identifier of the resource owner who
this token. authorized this token.
aud aud
OPTIONAL. Service-specific string identifier or list of string OPTIONAL. Service-specific string identifier or list of string
identifiers representing the intended audience for this token, as identifiers representing the intended audience for this token, as
defined in JWT [JWT]. defined in JWT [RFC7519].
iss iss
OPTIONAL. String representing the issuer of this token, as OPTIONAL. String representing the issuer of this token, as
defined in JWT [JWT]. defined in JWT [RFC7519].
jti jti
OPTIONAL. String identifier for the token, as defined in JWT OPTIONAL. String identifier for the token, as defined in JWT
[JWT]. [RFC7519].
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
skipping to change at page 9, line 16 skipping to change at page 9, line 26
and should direct all requests for registration to the review mailing and should direct all requests for registration to the review mailing
list. list.
3.1.1. Registration Template 3.1.1. Registration Template
Name: Name:
The name requested (e.g., "example"). This name is case The name requested (e.g., "example"). This name is case
sensitive. Names that match other registered names in a case sensitive. Names that match other registered names in a case
insensitive manner SHOULD NOT be accepted. Names that match insensitive manner SHOULD NOT be accepted. Names that match
claims registered in the JSON Web Token Claims registry claims registered in the JSON Web Token Claims registry
established by [JWT] SHOULD have comparable definitions and established by [RFC7519] SHOULD have comparable definitions and
semantics. semantics.
Description: Description:
Brief description of the metadata value (e.g., "Example Brief description of the metadata value (e.g., "Example
description"). description").
Change controller: Change controller:
For Standards Track RFCs, state "IESG". For others, give the name For Standards Track RFCs, state "IESG". For others, give the name
of the responsible party. Other details (e.g., postal address, of the responsible party. Other details (e.g., postal address,
email address, home page URI) may also be included. email address, home page URI) may also be included.
skipping to change at page 13, line 46 skipping to change at page 14, line 5
6. Acknowledgements 6. Acknowledgements
Thanks to the OAuth Working Group and the User Managed Access Working Thanks to the OAuth Working Group and the User Managed Access Working
Group for feedback and review of this document, and to the various Group for feedback and review of this document, and to the various
implementors of both the client and server components of this implementors of both the client and server components of this
specification. In particular, the author would like to thank Amanda specification. In particular, the author would like to thank Amanda
Anganes, John Bradley, Thomas Broyer, Brian Campbell, George Anganes, John Bradley, Thomas Broyer, Brian Campbell, George
Fletcher, Paul Freemantle, Thomas Hardjono, Eve Maler, Josh Mandel, Fletcher, Paul Freemantle, Thomas Hardjono, Eve Maler, Josh Mandel,
Steve Moore, Mike Schwartz, Prabath Siriwardena, Sarah Squire, and Steve Moore, Mike Schwartz, Prabath Siriwardena, Sarah Squire, and
Hannes Tschofennig, Hannes Tschofennig.
7. References 7. References
7.1. Normative References 7.1. Normative References
[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.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226, IANA Considerations Section in RFCs", BCP 26, RFC 5226,
skipping to change at page 14, line 49 skipping to change at page 15, line 7
[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
[JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", draft-ietf-oauth-json-web-token (work in (JWT)", RFC 7519, May 2015.
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. 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
skipping to change at page 15, line 28 skipping to change at page 15, line 33
identifier to the authorization server's token endpoint in order to identifier to the authorization server's token endpoint in order to
obtain the necessary key information needed to validate the signature obtain the necessary key information needed to validate the signature
on the request. The details of this usage are outside the scope of on the request. The details of this usage are outside the scope of
this specification and will be defined in an extension to this 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. ]]
-09
o Updated JOSE, JWT, and OAuth Assertion draft references to final
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).
-07 -07
o Created a separate IANA registry for introspection responses, o Created a separate IANA registry for introspection responses,
importing the values from JWT. importing the values from JWT.
 End of changes. 23 change blocks. 
23 lines changed or deleted 38 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/