INTERNET-DRAFT Phil Hunt Intended Status: Standards Track Oracle Corporation Expires: June 1, 2013 November 28, 2012 Chain Grant Type for OAuth2 draft-hunt-oauth-chain-01.txt Abstract This specification defines a method by which an OAuth protected service, can use a received oauth token from its client, to in turn, act as a client and access another OAuth protected service in a 'chained' profile. Status of this Memo This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79. 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 September 2, 2011. Copyright and License Notice Copyright (c) 2012 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 (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 Phil Hunt Expires June 1, 2013 [Page 1] INTERNET DRAFT Chain Grant Type for OAuth 2 November 28, 2012 described in the Simplified BSD License. Phil Hunt Expires June 1, 2013 [Page 2] INTERNET DRAFT Chain Grant Type for OAuth 2 November 28, 2012 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1 Notational Conventions . . . . . . . . . . . . . . . . . . 5 2. Chained OAuth token Request . . . . . . . . . . . . . . . . . 5 2.1 Client Requests OAuth token . . . . . . . . . . . . . . . . 6 2.2 Processing Requirements . . . . . . . . . . . . . . . . . . 7 2.3 Error Response . . . . . . . . . . . . . . . . . . . . . . 7 2.4 Example (non-normative) . . . . . . . . . . . . . . . . . . 8 3. Security Considerations . . . . . . . . . . . . . . . . . . . 8 3.1 Single Domain . . . . . . . . . . . . . . . . . . . . . . . 8 3.2 Multi-Domain . . . . . . . . . . . . . . . . . . . . . . . 8 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 5. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 5.1 Normative References . . . . . . . . . . . . . . . . . . . 9 5.2 Informative References . . . . . . . . . . . . . . . . . . 9 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . . 9 Appendix B. Document History . . . . . . . . . . . . . . . . . . . 9 Author's Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10 Phil Hunt Expires June 1, 2013 [Page 3] INTERNET DRAFT Chain Grant Type for OAuth 2 November 28, 2012 1. Introduction OAuth 2.0 Authorization Protocol [I-D.ietf.oauth-v2] provides a method for making authenticated HTTP requests to a resource or service using an OAuth token issued to third-party clients. OAuth tokens are issued through a number of grant types defined in the specification. OAuth supports the ability to support new grant types via definition of new extension grant types. This specification defines an extension grant type that enables "chained" authorization between separate OAuth infrastructures or "domains". Figure 1, shows a "chained authorization" where by an OAuth protected resource provider (Server A) to in turn, act as an OAuth client to another OAuth resource provider (Server B). Server A (OAuth Domain A) requests an OAuth token from Server B by presenting its own client credential to Server B's token service along with the OAuth token used by the "Originating Client" to access Server A. In response, Server B's token service provides Server A an OAuth token for Server B. +-----------+ +------------------+ +-----------------+ |Originating| | OAuth Protected | | OAuth Protected | | Client |--------->| Server A |-------->| Server B | | | | (Domain A) | | (Domain B) | +-----------+ +------------------+ +-----------------+ Figure 1: Typical Chain Scenario While this scenario could be solved through the use of bearer tokens or other similar technologies, "Chained Authorization" enables pair- wise trust and client credential validation when transactions are happening in a series of connected steps (similar in nature to a message bus). When exchanging tokens between separate OAuth "domains", each domain is able to use different token types and set different client credential requirements for each pair-wise relationship. This specification uses the terminology defined in [I-D.ietf-oauth- v2]. Please discuss this draft on the oauth@ietf.org mailing list. Phil Hunt Expires June 1, 2013 [Page 4] INTERNET DRAFT Chain Grant Type for OAuth 2 November 28, 2012 1.1 Notational Conventions 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]. Unless otherwise noted, all protocol parameter names and values are case sensitive. 2. Chained OAuth token Request An OAuth protected service (the chain requestor), wishes to in turn act as a client to another OAuth protected service. In doing so, the chain requestor is utilizing the existing authorization relationship with the originating client to access another service on the originating client's behalf along with its own client credential. For the purpose of this specification, an OAuth "domain" is defined as a set of one or more resource servers whose authorization is managed by a common OAuth token server. Chained OAuth token requests MAY occur between OAuth domains, OR MAY occur with in a single domain with a common OAuth token service. The process by which the originating client obtains an OAuth token is defined by the OAuth 2.0 Authorization Protocol [I-D.ietf.oauth-v2]. +-----------+ +------------------+ +---------------+ |Originating| | OAuth Protected |--(B)-AT1-->| OAuth Token | | Client |-(A)AT1-->| Service & Client | | Server | | | | (Domain A) |<-(C)-AT2---| (Domain B) | +-----------+ +------------------+ +---------------+ | | +---------------+ +------(D)-AT2-->|OAuth Protected| | Server | | (Domain B) | +---------------+ Figure 2: Chain OAuth Token Request The request/response flow illustrated in Figure 2 includes: (A) The originating client requests a resource from the OAuth Protected Service (Domain A). In doing so, it presents OAuth token AT1 (previously issued) as per the normal OAuth resource access request [I-D.ietf.oauth-v2]. Phil Hunt Expires June 1, 2013 [Page 5] INTERNET DRAFT Chain Grant Type for OAuth 2 November 28, 2012 (B) The OAuth Protected Service & Client (the chain requestor) requests an OAuth token that includes the received OAuth token AT1 and a grant_type of "http://oauth.net/grant_type/chain". (C) The target Token Server (Domain B) validates the client credentials of the chain requestor and the token AT1 provided per the processing rules defined in this specification and issues a new OAuth token (AT2) valid the current domain (Domain B). (D) The chain requestor accesses the "chained" OAuth Protected Server in Domain B with the new OAuth token (AT2). Note that in a single domain scenario, the Token Server (Domain B) MAY be the same token server for the OAuth Protected Server (Domain A). 2.1 Client Requests OAuth token The client (the chain requestor) makes a request to a token endpoint and includes the received OAuth token. The core details of which are defined in OAuth [I-D.ietf.oauth-v2], by specifying "http://oauth.net/grant_type/chain" as the absolute URI value of the "grant_type" parameter and by adding the following parameter: oauth_token REQUIED. The value of the oauth_token parameter MUST contain a single OAuth token previously issued by an OAuth server. The token server MAY choose to interpret scope encoded within the provided OAuth token. The format of the oauth_token value is corresponds to the value used in an HTTP "Authorization" header when accessing a resource as defined in section 7 of the OAuth specification [I- D.ietf.oauth-v2]. scope OPTIONAL. The scope of the access request expressed as a list of space-delimited strings. The value is defined by the token server. If the value contains multiple space- delimited strings, their order does not matter, and each string adds an additional access range to the requested scope. Where scope is available in both the provided oauth_token and the scope parameter, the token endpoint MAY choose to interpret and prioritize scope values from either the parameter or the OAuth token in any way it deems appropriate to its domain. Phil Hunt Expires June 1, 2013 [Page 6] INTERNET DRAFT Chain Grant Type for OAuth 2 November 28, 2012 Token servers SHOULD issue OAuth tokens with a limited lifetime and require clients to refresh them by requesting a new OAuth token using the same originating oauth_token, if it is still valid, or with a new originating oauth_token. The token server SHOULD NOT issue refresh tokens. 2.2 Processing Requirements Prior to issuing an OAuth token response as described in [I- D.ietf.oauth-v2], the token server MUST validate the provided oauth_token according to the following criteria. If present, the token server MUST also validate the client credentials of the requesting client. Application of additional restrictions and policy are at the discretion of the token server. o If the oauth_token denotes an identifier used to retrieve authorization information, the authorizing server MUST be able query the issuing server for the purpose of validation and to retrieve authorization information. The method for which this is done are beyond the scope of this specification and is defined by companion OAuth token specifications. o If the oauth_token can be parsed and self-contains authorization information, then the authorizing server MUST validate the token and obtain necessary authorizing information. The method by which this is done is beyond the scope of this specification and is defined by companion OAuth token specifications. o The token server MUST validate that received oauth_token is still valid either by parsing the token itself, or by confirming validity with the token server (which is out of the scope of this specification). 2.3 Error Response If the oauth_token is not valid, or authorization information requirements cannot be met, the token server MUST construct an error response as defined in [I-D.ietf.oauth-v2]. The value of the error parameter MUST be the "invalid_grant" error code. The token server MAY include additional information regarding the reasons the OAuth token was considered invalid using the error_description or error_uri parameters. Phil Hunt Expires June 1, 2013 [Page 7] INTERNET DRAFT Chain Grant Type for OAuth 2 November 28, 2012 Example error: HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store { "error":"invalid_grant", "error_description":"Audience validation failed" } 2.4 Example (non-normative) Though non-normative, the following examples illustrate what a conforming token request would look like. Note: Line breaks are for readability purposes only. POST /token.oauth2 HTTP/1.1 Host: authz.example.net Content-Type: application/x-www-form-urlencoded grant_type=http%3A%2F%2Foauth.net%2Fgrant_type%2Fchain oauth_token=MAC+token%3D%22h480djs93hd8%22 %2Ctimestamp%3D%22137131200%22%2Cnonce%3D%22dj83hs9s%22 %2Csignature%3D%22kDZvddkndxvhGRXZhvuDjEWhGeE%3D%22 3. Security Considerations The specification builds on considerations described within the OAuth 2.0 Authorization Protocol [I-D.ietf.oauth-v2]. [[Other considerations TBD]] 3.1 Single Domain OAuth protected servers within the same domain, using the same Token server, MAY request new OAuth tokens for the purpose of binding the original user context with the new client credential. 3.2 Multi-Domain When issuing tokens between OAuth domains, the token server MUST be able to determine the submitted oauth_token's issuer. The token server SHOULD have a method of establishing trust with the issuer of the received OAuth token. Phil Hunt Expires June 1, 2013 [Page 8] INTERNET DRAFT Chain Grant Type for OAuth 2 November 28, 2012 The token server MUST define a method of mapping received credentials received via the received OAuth token. 4. IANA Considerations The following is a parameter registration request, as defined in The OAuth Parameters Registry of The OAuth 2.0 Authorization Protocol [I- D.ietf.oauth-v2], for the "oauth_token" parameter: o Parameter name: oauth_token o Parameter usage: token request o Change controller: IETF o Specification document(s): draft-hunt-oauth-chain 5. References 5.1 Normative References [I-D.ietf.oauth-v2] Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, "The OAuth 2.0 Authorization Protocol", ID draft-ietf-oauth- v2-13 (work in progress), Feb 2011. [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. 5.2 Informative References [I-D.ietf.oauth.saml2.bearer] Campbell, B., and Mortimore, C., "SAML 2.0 Bearer Assertion Grant Type Profile for OAuth 2.0", ID draft- ietf-oauth-saml2-bearer-03 (work in progress), Feb 2011. Appendix A. Contributors The current draft was based in part on the SAML 2.0 Bearer Assertion Grant Type profile [I-D.ietf.oauth.saml2.bearer], by B. Campbell and C. Mortimore. Appendix B. Document History [[ to be removed by RFC editor before publication as an RFC ]] Phil Hunt Expires June 1, 2013 [Page 9] INTERNET DRAFT Chain Grant Type for OAuth 2 November 28, 2012 draft-hunt-oauth-chain-00 o Initial draft draft-hunt-oauth-chain-01 o Document refreshed for OAuth WG discussion Author's Addresses Phil Hunt (editor) Oracle Corporation EMail: phil.hunt@yahoo.com Phil Hunt Expires June 1, 2013 [Page 10]