draft-ietf-oauth-introspection-07.txt   draft-ietf-oauth-introspection-08.txt 
OAuth Working Group J. Richer, Ed. OAuth Working Group J. Richer, Ed.
Internet-Draft March 27, 2015 Internet-Draft April 21, 2015
Intended status: Standards Track Intended status: Standards Track
Expires: September 28, 2015 Expires: October 23, 2015
OAuth 2.0 Token Introspection OAuth 2.0 Token Introspection
draft-ietf-oauth-introspection-07 draft-ietf-oauth-introspection-08
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 28, 2015. This Internet-Draft will expire on October 23, 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 27 skipping to change at page 2, line 27
2.1. Introspection Request . . . . . . . . . . . . . . . . . . 4 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
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 . . . . . . . . . . . . . . . . . . . . . . . . . 13 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 14
7.1. Normative References . . . . . . . . . . . . . . . . . . 13 7.1. Normative References . . . . . . . . . . . . . . . . . . 14
7.2. Informative References . . . . . . . . . . . . . . . . . 14 7.2. Informative References . . . . . . . . . . . . . . . . . 14
Appendix A. Use with Proof of Posession Tokens . . . . . . . . . 14 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
skipping to change at page 5, line 42 skipping to change at page 5, line 42
json" format with the following top-level members. json" format with the following top-level members.
active active
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 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
skipping to change at page 12, line 10 skipping to change at page 12, line 10
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, per RFC 6125 [RFC6125].
Implementation security considerations can be found in 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 being from leaking In order to prevent the values of access tokens from leaking into
into server-side logs via query parameters, an authorization server server-side logs via query parameters, an authorization server
offering token introspection MAY disallow HTTP GET and instead offering token introspection MAY disallow HTTP GET and instead
require an HTTP POST method to be used at the introspection endpoint. require an HTTP POST method to be used at the introspection endpoint.
In order to avoid disclosing internal server state, an introspection In order to avoid disclosing internal server state, an introspection
response for an inactive token SHOULD NOT contain any additional response for an inactive token SHOULD NOT contain any additional
claims beyond the required "active" claim (with its value set to claims beyond 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 cost of liveness and load on the introspection endpoint, but at the risk of stale
of information about the token. For example, the token may be information about the token. For example, the token may be revoked
revoked while the protected resource is relying on the value of the while the protected resource is relying on the value of the cached
cached response to make authorization decisions. This creates a response to make authorization decisions. This creates a window
window during which a revoked token could be used at the protected during which a revoked token could be used at the protected resource.
resource. Consequently, an acceptable cache validity duration needs Consequently, an acceptable cache validity duration needs to be
to be carefully considered given the concerns and sensitivities of carefully considered given the concerns and sensitivities of the
the protected resource being accessed and the likelihood of a token protected resource being accessed and the likelihood of a token being
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 maximize liveness of information. resource in order to eliminate the risk of stale cached information
entirely, again at the cost of increased network traffic and server
load.
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
skipping to change at page 13, line 23 skipping to change at page 13, line 25
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
strings, potentially returning different identifiers to each strings, potentially returning different identifiers to each
protected resource. Omitting privacy-sensitive information from an protected resource.
introspection response is the simplest way of minimizing privacy
issues. If the protected resource sends additional information about the
client's request to the authorization server (such as the client's IP
address) using an extension of this specification, such information
could have additional privacy considerations. However, the nature
and implications of such extensions are outside the scope of this
specification.
Omitting privacy-sensitive information from an introspection response
is the simplest way of minimizing privacy issues.
6. Acknowledgements 6. Acknowledgements
Thanks to the OAuth Working Group and the UMA Working Group for Thanks to the OAuth Working Group and the User Managed Access Working
feedback. Group for feedback and review of this document, and to the various
implementors of both the client and server components of this
specification. In particular, the author would like to thank Amanda
Anganes, John Bradley, Thomas Broyer, Brian Campbell, George
Fletcher, Paul Freemantle, Thomas Hardjono, Eve Maler, Josh Mandel,
Steve Moore, Mike Schwartz, Prabath Siriwardena, Sarah Squire, and
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 15, line 9 skipping to change at page 15, line 28
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. ]]
-08
o Added privacy considerations note about extensions.
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.
-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.
 End of changes. 13 change blocks. 
26 lines changed or deleted 47 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/