draft-ietf-oauth-introspection-06.txt   draft-ietf-oauth-introspection-07.txt 
OAuth Working Group J. Richer, Ed. OAuth Working Group J. Richer, Ed.
Internet-Draft March 23, 2015 Internet-Draft March 27, 2015
Intended status: Standards Track Intended status: Standards Track
Expires: September 24, 2015 Expires: September 28, 2015
OAuth 2.0 Token Introspection OAuth 2.0 Token Introspection
draft-ietf-oauth-introspection-06 draft-ietf-oauth-introspection-07
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 September 24, 2015. This Internet-Draft will expire on September 28, 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 17 skipping to change at page 2, line 17
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. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
2. Introspection Endpoint . . . . . . . . . . . . . . . . . . . 3 2. Introspection Endpoint . . . . . . . . . . . . . . . . . . . 3
2.1. Introspection Request . . . . . . . . . . . . . . . . . . 3 2.1. Introspection Request . . . . . . . . . . . . . . . . . . 4
2.2. Introspection Response . . . . . . . . . . . . . . . . . 5 2.2. Introspection Response . . . . . . . . . . . . . . . . . 5
2.3. Error Response . . . . . . . . . . . . . . . . . . . . . 8 2.3. Error Response . . . . . . . . . . . . . . . . . . . . . 8
3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
4. Security Considerations . . . . . . . . . . . . . . . . . . . 9 3.1. OAuth Token Introspection Response Registry . . . . . . . 8
5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 11 3.1.1. Registration Template . . . . . . . . . . . . . . . . 9
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 3.1.2. Initial Registry Contents . . . . . . . . . . . . . . 9
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 4. Security Considerations . . . . . . . . . . . . . . . . . . . 11
7.1. Normative References . . . . . . . . . . . . . . . . . . 12 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 13
7.2. Informative References . . . . . . . . . . . . . . . . . 12 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 13
Appendix A. Use with Proof of Posession Tokens . . . . . . . . . 13 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 13
Appendix B. Document History . . . . . . . . . . . . . . . . . . 13 7.1. Normative References . . . . . . . . . . . . . . . . . . 13
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 14 7.2. Informative References . . . . . . . . . . . . . . . . . 14
Appendix A. Use with Proof of Posession Tokens . . . . . . . . . 14
Appendix B. Document History . . . . . . . . . . . . . . . . . . 15
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
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
but not yet expired). See Section 4 for information on but not yet expired). 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].
The response MAY include any claims defined as JWT [JWT] claim names
and carry the same semantics and syntax, such as the following:
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].
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. originally issued, as defined in JWT [JWT].
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. used before, as defined in JWT [JWT].
sub sub
OPTIONAL. Subject of the token. Usually a machine-readable OPTIONAL. Subject of the token, as defined in JWT [JWT]. Usually
identifier of the resource owner who authorized this token a machine-readable identifier of the resource owner who 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. identifiers representing the intended audience for this token, as
defined in JWT [JWT].
iss iss
OPTIONAL. String representing the issuer of this token. OPTIONAL. String representing the issuer of this token, as
defined in JWT [JWT].
jti jti
OPTIONAL. String identifier for the token. OPTIONAL. String identifier for the token, as defined in JWT
[JWT].
Specific implementations MAY extend this structure with their own Specific implementations MAY extend this structure with their own
service-specific pieces of information as top-level members of this service-specific response names as top-level members of this JSON
JSON object. object. Response names intended to be used across domains MUST be
registered in the OAuth Token Introspection Response registry defined
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 for authorization server MAY limit which scopes from a given token are
each protected resources in order to prevent protected resources from returned for each protected resource in order to prevent protected
learning more about the larger network than is necessary for their resources from learning more about the larger network than is
function. necessary for their function.
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 8, line 37 skipping to change at page 8, line 28
Note that a properly formed and authorized query for an inactive or Note that a properly formed and authorized query for an inactive or
otherwise invalid token (or a token the protected resource is not otherwise invalid token (or a token the protected resource is not
allowed to know about) is not considered an error response by this allowed to know about) is not considered an error response by this
specification. In these cases, the authorization server MUST instead specification. In these cases, the authorization server MUST instead
respond with an introspection response with the "active" field set to respond with an introspection response with the "active" field set to
"false" as described in Section 2.2. "false" as described in Section 2.2.
3. IANA Considerations 3. IANA Considerations
This specification requests IANA to register the following values 3.1. OAuth Token Introspection Response Registry
into the IANA JSON Web Token Claims registry for JWT Claim Names.
o Claim Name: "active" This specification establishes the OAuth Token Introspection Response
o Claim Description: Token active status registry.
OAuth registration client metadata names and descriptions are
registered with a Specification Required ([RFC5226]) after a two-week
review period on the oauth-ext-review@ietf.org mailing list, on the
advice of one or more Designated Experts. However, to allow for the
allocation of names prior to publication, the Designated Expert(s)
may approve registration once they are satisfied that such a
specification will be published.
Registration requests sent to the mailing list for review should use
an appropriate subject (e.g., "Request to register OAuth Token
Introspection Response name: example").
Within the review period, the Designated Expert(s) will either
approve or deny the registration request, communicating this decision
to the review list and IANA. Denials should include an explanation
and, if applicable, suggestions as to how to make the request
successful.
IANA must only accept registry updates from the Designated Expert(s)
and should direct all requests for registration to the review mailing
list.
3.1.1. Registration Template
Name:
The name requested (e.g., "example"). This name is case
sensitive. Names that match other registered names in a case
insensitive manner SHOULD NOT be accepted. Names that match
claims registered in the JSON Web Token Claims registry
established by [JWT] SHOULD have comparable definitions and
semantics.
Description:
Brief description of the metadata value (e.g., "Example
description").
Change controller:
For Standards Track RFCs, state "IESG". For others, give the name
of the responsible party. Other details (e.g., postal address,
email address, home page URI) may also be included.
Specification document(s):
Reference to the document(s) that specify the token endpoint
authorization method, preferably including a URI that can be used
to retrieve a copy of the document(s). An indication of the
relevant sections may also be included but is not required.
3.1.2. Initial Registry Contents
The initial contents of the OAuth Token Introspection Response
registry are:
o Name: "active"
o Description: Token active status
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 2.2 of [[ this document ]]. o Specification Document(s): Section 2.2 of [[ this document ]].
o Claim Name: "username" o Name: "username"
o Claim Description: User identifier of the resource owner o Description: User identifier of the resource owner
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 2.2 of [[ this document ]]. o Specification Document(s): Section 2.2 of [[ this document ]].
o Claim Name: "client_id" o Name: "client_id"
o Claim Description: Client identifier of the client o Description: Client identifier of the client
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 2.2 of [[ this document ]]. o Specification Document(s): Section 2.2 of [[ this document ]].
o Claim Name: "scope" o Name: "scope"
o Claim Description: Authorized scopes of the token o Description: Authorized scopes of the token
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 2.2 of [[ this document ]]. o Specification Document(s): Section 2.2 of [[ this document ]].
o Claim Name: "token_type" o Name: "token_type"
o Claim Description: Type of the token o Description: Type of the token
o Change Controller: IESG
o Specification Document(s): Section 2.2 of [[ this document ]].
o Name: "exp"
o Description: Expiration timestamp of the token
o Change Controller: IESG
o Specification Document(s): Section 2.2 of [[ this document ]].
o Name: "iat"
o Description: Issuance timestamp of the token
o Change Controller: IESG
o Specification Document(s): Section 2.2 of [[ this document ]].
o Name: "nbf"
o Description: Timestamp which the token is not valid before
o Change Controller: IESG
o Specification Document(s): Section 2.2 of [[ this document ]].
o Name: "sub"
o Description: Subject of the token
o Change Controller: IESG
o Specification Document(s): Section 2.2 of [[ this document ]].
o Name: "aud"
o Description: Audience of the token
o Change Controller: IESG
o Specification Document(s): Section 2.2 of [[ this document ]].
o Name: "iss"
o Description: Issuer of the token
o Change Controller: IESG
o Specification Document(s): Section 2.2 of [[ this document ]].
o Name: "jti"
o Description: Unique identifier of the token
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 2.2 of [[ this document ]]. o Specification Document(s): Section 2.2 of [[ this document ]].
4. Security Considerations 4. Security Considerations
Since there are many different and valid ways to implement an OAuth Since there are many different and valid ways to implement an OAuth
2.0 system, there are consequently many ways for an authorization 2.0 system, there are consequently many ways for an authorization
server to determine whether or not a token is currently "active" or server to determine whether or not a token is currently "active" or
not. However, since resource servers using token introspection rely not. However, since resource servers using token introspection rely
on the authorization server to determine the state of a token, the on the authorization server to determine the state of a token, the
skipping to change at page 12, line 12 skipping to change at page 13, line 39
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
[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
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008.
[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.
[RFC6125] Saint-Andre, P. and J. Hodges, "Representation and [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and
Verification of Domain-Based Application Service Identity Verification of Domain-Based Application Service Identity
within Internet Public Key Infrastructure Using X.509 within Internet Public Key Infrastructure Using X.509
(PKIX) Certificates in the Context of Transport Layer (PKIX) Certificates in the Context of Transport Layer
Security (TLS)", RFC 6125, March 2011. Security (TLS)", RFC 6125, March 2011.
[RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC
skipping to change at page 13, line 24 skipping to change at page 15, line 9
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. ]]
-07
o Created a separate IANA registry for introspection responses,
importing the values from JWT.
-06 -06
o Clarified relationship between AS and RS in introduction. o Clarified relationship between AS and RS in introduction.
o Used updated TLS text imported from Dyn-Reg drafts. o Used updated TLS text imported from Dyn-Reg drafts.
o Clarified definition of active state. o Clarified definition of active state.
o Added some advice on caching responses. o Added some advice on caching responses.
o Added security considerations on active state implementation. o Added security considerations on active state implementation.
o Changed user_id to username based on WG feedback. o Changed user_id to username based on WG feedback.
-05 -05
o Typo fix. o Typo fix.
o Updated author information. o Updated author information.
o Removed extraneous "linewrap" note from examples. o Removed extraneous "linewrap" note from examples.
- 04 - 04
o Removed "resource_id" from request. o Removed "resource_id" from request.
o Added examples. o Added examples.
- 03 - 03
o Updated HTML and HTTP references.
o Updated HTML and HTTP references.
o Call for registration of parameters in the JWT registry. o Call for registration of parameters in the JWT registry.
- 02 - 02
o Removed SAML pointer. o Removed SAML pointer.
o Clarified what an "active" token could be. o Clarified what an "active" token could be.
o Explicitly declare introspection request as x-www-form-urlencoded o Explicitly declare introspection request as x-www-form-urlencoded
format. format.
o Added extended example. o Added extended example.
o Made protected resource authentication a MUST. 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.
Author's Address Author's Address
Justin Richer (editor) Justin Richer (editor)
 End of changes. 44 change blocks. 
69 lines changed or deleted 149 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/