OAuth Working Group J. Richer, Ed. Internet-Draft The MITRE Corporation Intended status: Standards Track November 30, 2014 Expires: June 3, 2015 OAuth 2.0 Token Introspection draft-ietf-oauth-introspection-01 Abstract This specification defines a method for a protected resource to query 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 deployments can use this method to convey information about the authorization context of the token from the authorization server to the protected resource. Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119]. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on June 3, 2015. Copyright Notice Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents Richer Expires June 3, 2015 [Page 1] Internet-Draft oauth-introspection November 2014 (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Introspection Endpoint . . . . . . . . . . . . . . . . . . . 3 2.1. Introspection Request . . . . . . . . . . . . . . . . . . 3 2.2. Introspection Response . . . . . . . . . . . . . . . . . 4 2.3. Error Response . . . . . . . . . . . . . . . . . . . . . 5 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 4. Security Considerations . . . . . . . . . . . . . . . . . . . 5 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 7 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 7.1. Normative References . . . . . . . . . . . . . . . . . . 7 7.2. Informative References . . . . . . . . . . . . . . . . . 8 Appendix A. Document History . . . . . . . . . . . . . . . . . . 8 Appendix B. Non-normative Example . . . . . . . . . . . . . . . 8 Appendix C. Use with Proof of Posession Tokens . . . . . . . . . 10 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10 1. Introduction 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 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 token, such as its current validity, approved scopes, and information about the context in which the token was issued. These pieces of information are often vital to protected resources making authorization decisions based on the tokens being presented. Since OAuth 2.0 [RFC6749] defines no direct relationship between the authorization server and the protected resource, only that they must have an agreement on the tokens themselves, there have been many different approaches to bridging this gap. These include using structured token formats such as JWT [JWT] or SAML [[ Editor's Note: Which SAML document should we reference here? ]] and proprietary inter-service communication mechanisms (such as shared databases and protected enterprise service buses) that convey token information. This specification defines an interoperable web API that allows authorized protected resources to query the authorization server to Richer Expires June 3, 2015 [Page 2] Internet-Draft oauth-introspection November 2014 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 the token is currently active (or if it has expired or otherwise been revoked), what rights of access the token carries (usually conveyed through OAuth 2.0 scopes), and the authorization context in which the token was granted (including who authorized the token and which client it was issued to). Token introspection allows a protected resource to query this information regardless of whether or not it is carried in the token itself, allowing this method to be used along with or independently of structured token values. Additionally, a protected resource can use the mechanism described in this specification to introspect the token in a particular authorization decision context and ascertain the relevant metadata about the token in order to make this authorization decision appropriately. 2. Introspection Endpoint The introspection endpoint is an OAuth 2.0 endpoint that takes a parameter representing an OAuth 2.0 token and returns a JSON [RFC7159] document representing the meta information surrounding the token. The introspection endpoint MUST be protected by TLS of at least version 1.2 RFC 5246 [RFC5246] and MAY support additional transport- layer mechanisms meeting its security requirements. When using TLS, the client or protected resource MUST perform a TLS/SSL server certificate check, per RFC 6125 [RFC6125]. Implementation security considerations can be found in Recommendations for Secure Use of TLS and DTLS [TLS.BCP]. 2.1. Introspection Request The protected resource calls the introspection endpoint using an HTTP POST [RFC2616] request (or optionally an HTTP GET request). The protected resource 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. token REQUIRED. The string value of the token. For access tokens, this is the "access_token" value returned from the token endpoint defined in OAuth 2.0 [RFC6749] section 5.1. For refresh tokens, this is the "refresh_token" value returned from the token endpoint as defined in OAuth 2.0 [RFC6749] section 5.1. Other token types are outside the scope of this specification. resource_id OPTIONAL. A service-specific string identifying the resource that the token is being used for. This value allows the Richer Expires June 3, 2015 [Page 3] Internet-Draft oauth-introspection November 2014 protected resource to convey to the authorization server the context in which the token is being used at the protected resource, allowing the authorization server to tailor its response accordingly if desired. token_type_hint OPTIONAL. A hint about the type of the token submitted for introspection. The protected resource re MAY pass this parameter in order to help the authorization server to optimize the token lookup. If the server is unable to locate the token using the given hint, it MUST extend its search across all of its supported token types. An authorization server MAY ignore this parameter, particularly if it is able to detect the token type automatically. Values for this field are defined in OAuth Token Revocation [RFC7009]. The endpoint MAY allow other parameters to provide further context to the query. For instance, an authorization service may need to know the IP address of the client accessing the protected resource in order to determine the appropriateness of the token being presented. To prevent unauthorized token scanning attacks, the endpoint SHOULD also require some form of authorization to access this endpoint, such 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 OAuth 2.0 Bearer Token Usage [RFC6750]. The methods of managing and validating these authentication credentials are out of scope of this specification, though it is RECOMMENDED that these credentials be distinct from those used at an authorization server's token endpoint. 2.2. Introspection Response The server responds with a JSON object [RFC7159] in "application/ json" format with the following top-level members. Specific implementations MAY extend this structure with their own service- specific pieces of information. active REQUIRED. Boolean indicator of whether or not the presented token is currently active. The authorization server determines 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. iat OPTIONAL. Integer timestamp, measured in the number of seconds since January 1 1970 UTC, indicating when this token was originally issued. Richer Expires June 3, 2015 [Page 4] Internet-Draft oauth-introspection November 2014 scope OPTIONAL. A space-separated list of strings representing the scopes associated with this token, in the format described in section 3.3 of OAuth 2.0 [RFC6749]. client_id OPTIONAL. Client identifier for the OAuth 2.0 client that requested this token. sub OPTIONAL. Machine-readable identifier of the resource owner who authorized this token. user_id OPTIONAL. Human-readable identifier for the user who authorized this token. aud OPTIONAL. Service-specific string identifier or list of string identifiers representing the intended audience for this token. iss OPTIONAL. String representing the issuer of this token. token_type OPTIONAL. Type of the token as defined in section 5.1 of OAuth 2.0 [RFC6749]. The response MAY be cached by the protected resource, and the authorization server SHOULD communicate appropriate cache controls using applicable HTTP headers. 2.3. Error Response If the protected resource uses OAuth 2.0 client credentials to authenticate to the introspection endpoint and its credentials are invalid, the authorization server responds with an HTTP 400 (Bad Request) as described in section 5.2 of OAuth 2.0 [RFC6749]. If the protected resource uses an OAuth 2.0 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request, the authorization server responds with an HTTP 400 code as described in section 3 of OAuth 2.0 Bearer Token Usage [RFC6750]. 3. IANA Considerations This document makes no request of IANA. 4. Security Considerations If left unprotected and un-throttled, the introspection endpoint could present a means for an attacker to poll a series of possible token values, fishing for a valid token. The specifics of this Richer Expires June 3, 2015 [Page 5] Internet-Draft oauth-introspection November 2014 authentication credentials are out of scope of this specification, but commonly these credentials could take the form of any valid client authentication mechanism used with the token endpoint, an OAuth 2.0 access token, or other HTTP authorization or authentication mechanism. The authorization server SHOULD issue credentials to any protected resources that need to access the introspection endpoint, SHOULD require protected resources to be specifically authorized to call the introspection endpoint, and SHOULD NOT allow a single piece of software acting as both a client and a protected resource to re- use the same credentials between the token endpoint and the introspection endpoint. Since the introspection endpoint takes in OAuth 2.0 tokens as parameters, the server MUST support TLS 1.2 RFC 5246 [RFC5246] and MAY support additional transport-layer mechanisms meeting its security requirements. When using TLS, the client or protected resource MUST perform a TLS/SSL server certificate check, per RFC 6125 [RFC6125]. Implementation security considerations can be found in Recommendations for Secure Use of TLS and DTLS [TLS.BCP]. In order to prevent the values of access tokens being from leaking into server-side logs via query parameters, an authorization server offering token introspection MAY disallow HTTP GET and instead require an HTTP POST method only to the introspection endpoint. An authorization server offering token introspection MUST be able to understand the token values being presented to it during this call. The exact means by which this happens is an implementation detail and outside the scope of this specification. For unstructured tokens, this could take the form of a simple server-side database query against a data store containing the context information for the token. For structured tokens, this could take the form of the server parsing the token, validating its signature or other protection mechanisms, and returning the information contained in the token back to the protected resource (allowing the protected resource to be unaware of the token's contents, much like the client). Note that for a token carrying encrypted information that is needed during the introspection process, the authorization server MUST be able to decrypt and validate the token in order to access this information. In cases where the authorization server stores no information about the token and has no means of accessing information about the token, it can not likely offer an introspection service. Richer Expires June 3, 2015 [Page 6] Internet-Draft oauth-introspection November 2014 5. Privacy Considerations The introspection response may contain privacy-sensitive information such as user identifiers for resource owners. When this is the case, measures MUST be taken to prevent disclosure of this information to unintended parties. One way to limit disclosure is to require authorization to call the introspection endpoint and to limit calls to only registered and trusted protected resource servers. Another method is to transmit user identifiers as opaque service-specific strings, potentially returning different identifiers to each protected resource. Omitting privacy-sensitive information from an introspection response is the simplest way of minimizing privacy issues. 6. Acknowledgements Thanks to the OAuth Working Group and the UMA Working Group for feedback. 7. References 7.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 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 (TLS) Protocol Version 1.2", RFC 5246, August 2008. [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS)", RFC 6125, March 2011. [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 6749, October 2012. [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, October 2012. [RFC7009] Lodderstedt, T., Dronia, S., and M. Scurtescu, "OAuth 2.0 Token Revocation", RFC 7009, August 2013. Richer Expires June 3, 2015 [Page 7] Internet-Draft oauth-introspection November 2014 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, March 2014. 7.2. Informative References [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", draft-ietf-oauth-json-web-token (work in progress), July 2014. [TLS.BCP] Sheffer, Y., Holz, R., and P. Saint-Andre, "Recommendations for Secure Use of TLS and DTLS", November 2014. Appendix A. Document History [[ To be removed by the RFC Editor. ]] - 01 o Fixed casing and consistent term usage. o Incorporated working group comments. o Clarified that authorization servers need to be able to understand the token if they're to introspect it. o Various editorial cleanups. - 00 o Created initial IETF drafted based on draft-richer-oauth- introspection-06 with no normative changes. Appendix B. Non-normative Example In this non-normative example, a protected resource receives a 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 whether to serve the request given this token, the protected resource then makes the following request to the introspection endpoint of the authorization server. The protected resource authenticates with its own credentials, here re-using the format of client identifier and client secret conveyed as HTTP Basic authentication as per OAuth 2.0 [RFC6749] Section 2.3.1. Richer Expires June 3, 2015 [Page 8] Internet-Draft oauth-introspection November 2014 Following is a non-normative example request: 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 The authorization server validates the protected resource's credentials and looks up the information in the token. If the token is currently active and the authenticated protected resource is authorized to know information about this token, the authorization server returns the following JSON document. Following is a non-normative example active token response (with line wraps for display purposes only): HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store { "active": true, "client_id":"s6BhdRkqt3", "scope": "read write dolphin", "sub": "2309fj32kl", "user_id": "jdoe", "aud": "https://example.org/protected-resource/*", "iss": "https://authserver.example.com/" } If the token presented is not currently active for any reason (for instance, it has been revoked by the resource owner) 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 invalid token (with line wraps for display purposes only): HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store { "active": false } Richer Expires June 3, 2015 [Page 9] Internet-Draft oauth-introspection November 2014 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 With bearer tokens such as those defined by OAuth 2.0 Bearer Token Usage [RFC6750], the protected resource will have in its posession the entire secret portion of the token for submission to the introspection service. However, for proof-of-posession style tokens, the protected resource will have only a token identifier used during the request, along with the cryptographic signature on the request. The protected resource would be able to submit the token identifier to the authoriation server's token endpoint in order to obtain the necessary key information needed to validate the signature on the request. The details of this usage are outside the scope of this specification and should be defined in an extension to this specification. Author's Address Justin Richer (editor) The MITRE Corporation Email: jricher@mitre.org Richer Expires June 3, 2015 [Page 10]