draft-ietf-oauth-introspection-02.txt   draft-ietf-oauth-introspection-03.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 December 3, 2014 Intended status: Standards Track December 6, 2014
Expires: June 6, 2015 Expires: June 9, 2015
OAuth 2.0 Token Introspection OAuth 2.0 Token Introspection
draft-ietf-oauth-introspection-02 draft-ietf-oauth-introspection-03
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 6, 2015. This Internet-Draft will expire on June 9, 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
skipping to change at page 2, line 21 skipping to change at page 2, line 21
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 . . . . . . . . . . . . . . . . . . 4 2.1. Introspection Request . . . . . . . . . . . . . . . . . . 4
2.2. Introspection Response . . . . . . . . . . . . . . . . . 5 2.2. Introspection Response . . . . . . . . . . . . . . . . . 5
2.3. Error Response . . . . . . . . . . . . . . . . . . . . . 6 2.3. Error Response . . . . . . . . . . . . . . . . . . . . . 6
3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6
4. Security Considerations . . . . . . . . . . . . . . . . . . . 6 4. Security Considerations . . . . . . . . . . . . . . . . . . . 7
5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 7 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 8
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 8
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 8
7.1. Normative References . . . . . . . . . . . . . . . . . . 8 7.1. Normative References . . . . . . . . . . . . . . . . . . 8
7.2. Informative References . . . . . . . . . . . . . . . . . 8 7.2. Informative References . . . . . . . . . . . . . . . . . 9
Appendix A. Document History . . . . . . . . . . . . . . . . . . 9 Appendix A. Document History . . . . . . . . . . . . . . . . . . 9
Appendix B. Non-normative Examples . . . . . . . . . . . . . . . 9 Appendix B. Non-normative Examples . . . . . . . . . . . . . . . 10
Appendix C. Use with Proof of Posession Tokens . . . . . . . . . 11 Appendix C. Use with Proof of Posession Tokens . . . . . . . . . 12
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12
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 4, line 8 skipping to change at page 4, line 8
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 protected resource MUST perform a TLS/SSL server certificate the protected resource MUST perform a TLS/SSL server 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 with parameters sent as "application/x-www- POST [RFC7231] request with parameters sent as "application/x-www-
form-urlencoded" data as defined in [RFC1866]. The authorization form-urlencoded" data as defined in [W3C.REC-html5-20141028]. The
server MAY allow an HTTP GET [RFC2616] request with parameters passed authorization server MAY allow an HTTP GET [RFC7231] request with
in the query string as defined in [RFC1866]. The protected resource parameters passed in the query string as defined in
sends a parameter representing the token along with optional [W3C.REC-html5-20141028]. The protected resource sends a parameter
parameters representing additional context that is known by the representing the token along with optional parameters representing
protected resource to aid the authorization server in its response. additional context that is known by the protected resource to aid the
These parameters authorization server in its response.
token REQUIRED. The string value of the token. For access tokens, token REQUIRED. The string value of the token. For access tokens,
this is the "access_token" value returned from the token endpoint this is the "access_token" value returned from the token endpoint
defined in OAuth 2.0 [RFC6749] section 5.1. For refresh tokens, defined in OAuth 2.0 [RFC6749] section 5.1. For refresh tokens,
this is the "refresh_token" value returned from the token endpoint this is the "refresh_token" value returned from the token endpoint
as defined in OAuth 2.0 [RFC6749] section 5.1. Other token types as defined in OAuth 2.0 [RFC6749] section 5.1. Other token types
are outside the scope of this specification. are outside the scope of this specification.
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 5, line 9 skipping to change at page 5, line 9
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. specification.
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. Several of these json" format with the following top-level members. Several of these
claims are defined as JWT [JWT] claim names and carry the same
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
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
since January 1 1970 UTC, indicating when this token was
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
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.
token_type OPTIONAL. Type of the token as defined in section 5.1 of
OAuth 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 OPTIONAL. Integer timestamp, measured in the number of seconds
since January 1 1970 UTC, indicating when this token will expire.
iat OPTIONAL. Integer timestamp, measured in the number of seconds
since January 1 1970 UTC, indicating when this token was
originally issued.
nbf OPTIONAL. Integer timestamp, measured in the number of seconds
since January 1 1970 UTC, indicating when this token is not to be
used before.
sub OPTIONAL. Subject of the token. Usually a machine-readable
identifier of the resource owner who 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, as identifiers representing the intended audience for this token.
defined in JWT [JWT].
iss OPTIONAL. String representing the issuer of this token, as iss OPTIONAL. String representing the issuer of this token.
defined in JWT [JWT].
token_type OPTIONAL. Type of the token as defined in section 5.1 of jti OPTIONAL. String identifier for the token.
OAuth 2.0 [RFC6749].
Specific implementations MAY extend this structure with their own
service-specific pieces of information.
The response MAY be cached by the protected resource. The response MAY be cached by the protected resource.
The authorization server MAY respond differently to different The authorization server MAY respond differently to different
protected resources making the same request. protected resources making the same request.
Note that in order to avoid disclosing too much of the authorization Note that in order to avoid disclosing too much of the authorization
server's state to a third party, the authorization server SHOULD NOT server's state to a third party, the authorization server SHOULD NOT
include any additional information about an inactive token, including include any additional information about an inactive token, including
why the token is inactive. why the token is inactive.
skipping to change at page 6, line 26 skipping to change at page 6, line 31
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 401 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 will register several claims in the JWT registry. This specification requests IANA to register the following values
]] into the IANA JSON Web Token Claims registry for JWT Claim Names.
o Claim Name: "active"
o Claim Description: Token active status
o Change Controller: IESG
o Specification Document(s): Section 2.2 of [[ this document ]].
o Claim Name: "user_id"
o Claim Description: User identifier of the resource owner
o Change Controller: IESG
o Specification Document(s): Section 2.2 of [[ this document ]].
o Claim Name: "client_id"
o Claim Description: Client identifier of the client
o Change Controller: IESG
o Specification Document(s): Section 2.2 of [[ this document ]].
o Claim Name: "scope"
o Claim Description: Authorized scopes of the token
o Change Controller: IESG
o Specification Document(s): Section 2.2 of [[ this document ]].
o Claim Name: "token_type"
o Claim Description: Type of the token
o Change Controller: IESG
o Specification Document(s): Section 2.2 of [[ this document ]].
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. To prevent this, the token values, fishing for a valid token. To prevent this, the
authorization server MUST require authentication of protected authorization server MUST require authentication of protected
resources that need to access the introspection endpoint and SHOULD resources that need to access the introspection endpoint and SHOULD
require protected resources to be specifically authorized to call the require protected resources to be specifically authorized to call the
introspection endpoint. The specifics of this authentication introspection endpoint. The specifics of this authentication
skipping to change at page 7, line 13 skipping to change at page 7, line 43
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
into server-side logs via query parameters, an authorization server into 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 only to the introspection endpoint. require an HTTP POST method only to the introspection endpoint.
In order to avoid disclosing internal server state, an introspection
response for an inactive token SHOULD NOT contain any additional
claims beyond the required "active" claim (with its value set to
"false").
An authorization server offering token introspection MUST be able to An authorization server offering token introspection MUST be able to
understand the token values being presented to it during this call. understand the token values being presented to it during this call.
The exact means by which this happens is an implementation detail and The exact means by which this happens is an implementation detail and
outside the scope of this specification. For unstructured tokens, outside the scope of this specification. For unstructured tokens,
this could take the form of a simple server-side database query this could take the form of a simple server-side database query
against a data store containing the context information for the against a data store containing the context information for the
token. For structured tokens, this could take the form of the server token. For structured tokens, this could take the form of the server
parsing the token, validating its signature or other protection parsing the token, validating its signature or other protection
mechanisms, and returning the information contained in the token back mechanisms, and returning the information contained in the token back
to the protected resource (allowing the protected resource to be to the protected resource (allowing the protected resource to be
skipping to change at page 8, line 9 skipping to change at page 8, line 42
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.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
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.
[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 8, line 40 skipping to change at page 9, line 23
[RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
Framework: Bearer Token Usage", RFC 6750, October 2012. Framework: Bearer Token Usage", RFC 6750, October 2012.
[RFC7009] Lodderstedt, T., Dronia, S., and M. Scurtescu, "OAuth 2.0 [RFC7009] Lodderstedt, T., Dronia, S., and M. Scurtescu, "OAuth 2.0
Token Revocation", RFC 7009, August 2013. Token Revocation", RFC 7009, August 2013.
[RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, March 2014. Interchange Format", RFC 7159, March 2014.
[RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
(HTTP/1.1): Semantics and Content", RFC 7231, June 2014.
[W3C.REC-html5-20141028]
Hickson, I., Berjon, R., Faulkner, S., Leithead, T.,
Navara, E., O'Connor, E., and S. Pfeiffer, "HTML5",
World Wide Web Consortium Recommendation REC-
html5-20141028, October 2014,
<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 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", draft-ietf-oauth-json-web-token (work in (JWT)", draft-ietf-oauth-json-web-token (work in
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. ]]
- 03
o Updated HTML and HTTP references.
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.
skipping to change at page 11, line 24 skipping to change at page 12, line 24
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
{ {
"active": false "active": false
} }
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 possession
the entire secret portion of the token for submission to the the entire secret portion of the token for submission to the
introspection service. However, for proof-of-posession style tokens, introspection service. However, for proof-of-possession style
the protected resource will have only a token identifier used during tokens, the protected resource will have only a token identifier used
the request, along with the cryptographic signature on the request. during the request, along with the cryptographic signature on the
The protected resource would be able to submit the token identifier request. The protected resource would be able to submit the token
to the authoriation server's token endpoint in order to obtain the identifier to the authorization server's token endpoint in order to
necessary key information needed to validate the signature on the obtain the necessary key information needed to validate the signature
request. The details of this usage are outside the scope of this on the request. The details of this usage are outside the scope of
specification and should be defined in an extension to this this specification and should be defined in an extension to this
specification. specification.
Author's Address Author's Address
Justin Richer (editor) Justin Richer (editor)
The MITRE Corporation The MITRE Corporation
Email: jricher@mitre.org Email: jricher@mitre.org
 End of changes. 22 change blocks. 
57 lines changed or deleted 102 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/