idnits 2.17.1 draft-hunt-oauth-chain-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 28, 2012) is 4166 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT Phil Hunt 3 Intended Status: Standards Track Oracle Corporation 4 Expires: June 1, 2013 November 28, 2012 6 Chain Grant Type for OAuth2 7 draft-hunt-oauth-chain-01.txt 9 Abstract 11 This specification defines a method by which an OAuth protected 12 service, can use a received oauth token from its client, to in turn, 13 act as a client and access another OAuth protected service in a 14 'chained' profile. 16 Status of this Memo 18 This Internet-Draft is submitted to IETF in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. Internet-Drafts are working 23 documents of the Internet Engineering Task Force (IETF). Note that 24 other groups may also distribute working documents as Internet- 25 Drafts. The list of current Internet-Drafts is at 26 http://datatracker.ietf.org/drafts/current. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on September 2, 2011. 35 Copyright and License Notice 37 Copyright (c) 2012 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 53 1.1 Notational Conventions . . . . . . . . . . . . . . . . . . 5 54 2. Chained OAuth token Request . . . . . . . . . . . . . . . . . 5 55 2.1 Client Requests OAuth token . . . . . . . . . . . . . . . . 6 56 2.2 Processing Requirements . . . . . . . . . . . . . . . . . . 7 57 2.3 Error Response . . . . . . . . . . . . . . . . . . . . . . 7 58 2.4 Example (non-normative) . . . . . . . . . . . . . . . . . . 8 59 3. Security Considerations . . . . . . . . . . . . . . . . . . . 8 60 3.1 Single Domain . . . . . . . . . . . . . . . . . . . . . . . 8 61 3.2 Multi-Domain . . . . . . . . . . . . . . . . . . . . . . . 8 62 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 63 5. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 64 5.1 Normative References . . . . . . . . . . . . . . . . . . . 9 65 5.2 Informative References . . . . . . . . . . . . . . . . . . 9 66 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . . 9 67 Appendix B. Document History . . . . . . . . . . . . . . . . . . . 9 68 Author's Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10 70 1. Introduction 72 OAuth 2.0 Authorization Protocol [I-D.ietf.oauth-v2] provides a 73 method for making authenticated HTTP requests to a resource or 74 service using an OAuth token issued to third-party clients. OAuth 75 tokens are issued through a number of grant types defined in the 76 specification. 78 OAuth supports the ability to support new grant types via definition 79 of new extension grant types. This specification defines an extension 80 grant type that enables "chained" authorization between separate 81 OAuth infrastructures or "domains". 83 Figure 1, shows a "chained authorization" where by an OAuth protected 84 resource provider (Server A) to in turn, act as an OAuth client to 85 another OAuth resource provider (Server B). 87 Server A (OAuth Domain A) requests an OAuth token from Server B by 88 presenting its own client credential to Server B's token service 89 along with the OAuth token used by the "Originating Client" to access 90 Server A. In response, Server B's token service provides Server A an 91 OAuth token for Server B. 93 +-----------+ +------------------+ +-----------------+ 94 |Originating| | OAuth Protected | | OAuth Protected | 95 | Client |--------->| Server A |-------->| Server B | 96 | | | (Domain A) | | (Domain B) | 97 +-----------+ +------------------+ +-----------------+ 99 Figure 1: Typical Chain Scenario 101 While this scenario could be solved through the use of bearer tokens 102 or other similar technologies, "Chained Authorization" enables pair- 103 wise trust and client credential validation when transactions are 104 happening in a series of connected steps (similar in nature to a 105 message bus). 107 When exchanging tokens between separate OAuth "domains", each domain 108 is able to use different token types and set different client 109 credential requirements for each pair-wise relationship. 111 This specification uses the terminology defined in [I-D.ietf-oauth- 112 v2]. 114 Please discuss this draft on the oauth@ietf.org mailing list. 116 1.1 Notational Conventions 118 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 119 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 120 document are to be interpreted as described in RFC 2119 [RFC2119]. 122 Unless otherwise noted, all protocol parameter names and values are 123 case sensitive. 125 2. Chained OAuth token Request 127 An OAuth protected service (the chain requestor), wishes to in turn 128 act as a client to another OAuth protected service. In doing so, the 129 chain requestor is utilizing the existing authorization relationship 130 with the originating client to access another service on the 131 originating client's behalf along with its own client credential. 133 For the purpose of this specification, an OAuth "domain" is defined 134 as a set of one or more resource servers whose authorization is 135 managed by a common OAuth token server. Chained OAuth token requests 136 MAY occur between OAuth domains, OR MAY occur with in a single domain 137 with a common OAuth token service. 139 The process by which the originating client obtains an OAuth token is 140 defined by the OAuth 2.0 Authorization Protocol [I-D.ietf.oauth-v2]. 142 +-----------+ +------------------+ +---------------+ 143 |Originating| | OAuth Protected |--(B)-AT1-->| OAuth Token | 144 | Client |-(A)AT1-->| Service & Client | | Server | 145 | | | (Domain A) |<-(C)-AT2---| (Domain B) | 146 +-----------+ +------------------+ +---------------+ 147 | 148 | +---------------+ 149 +------(D)-AT2-->|OAuth Protected| 150 | Server | 151 | (Domain B) | 152 +---------------+ 154 Figure 2: Chain OAuth Token Request 156 The request/response flow illustrated in Figure 2 includes: 158 (A) The originating client requests a resource from the OAuth 159 Protected Service (Domain A). In doing so, it presents OAuth 160 token AT1 (previously issued) as per the normal OAuth resource 161 access request [I-D.ietf.oauth-v2]. 163 (B) The OAuth Protected Service & Client (the chain requestor) 164 requests an OAuth token that includes the received OAuth token 165 AT1 and a grant_type of "http://oauth.net/grant_type/chain". 167 (C) The target Token Server (Domain B) validates the client 168 credentials of the chain requestor and the token AT1 provided 169 per the processing rules defined in this specification and 170 issues a new OAuth token (AT2) valid the current domain (Domain 171 B). 173 (D) The chain requestor accesses the "chained" OAuth Protected 174 Server in Domain B with the new OAuth token (AT2). 176 Note that in a single domain scenario, the Token Server (Domain 177 B) MAY be the same token server for the OAuth Protected Server 178 (Domain A). 180 2.1 Client Requests OAuth token 182 The client (the chain requestor) makes a request to a token endpoint 183 and includes the received OAuth token. The core details of which are 184 defined in OAuth [I-D.ietf.oauth-v2], by specifying 185 "http://oauth.net/grant_type/chain" as the absolute URI value of the 186 "grant_type" parameter and by adding the following parameter: 188 oauth_token 189 REQUIED. The value of the oauth_token parameter MUST contain a 190 single OAuth token previously issued by an OAuth server. The 191 token server MAY choose to interpret scope encoded within the 192 provided OAuth token. 194 The format of the oauth_token value is corresponds to the value 195 used in an HTTP "Authorization" header when accessing a resource 196 as defined in section 7 of the OAuth specification [I- 197 D.ietf.oauth-v2]. 199 scope 200 OPTIONAL. The scope of the access request expressed as a list of 201 space-delimited strings. The value is defined by the token 202 server. If the value contains multiple space- delimited strings, 203 their order does not matter, and each string adds an additional 204 access range to the requested scope. 206 Where scope is available in both the provided oauth_token and 207 the scope parameter, the token endpoint MAY choose to interpret 208 and prioritize scope values from either the parameter or the 209 OAuth token in any way it deems appropriate to its domain. 211 Token servers SHOULD issue OAuth tokens with a limited lifetime and 212 require clients to refresh them by requesting a new OAuth token using 213 the same originating oauth_token, if it is still valid, or with a new 214 originating oauth_token. The token server SHOULD NOT issue refresh 215 tokens. 217 2.2 Processing Requirements 219 Prior to issuing an OAuth token response as described in [I- 220 D.ietf.oauth-v2], the token server MUST validate the provided 221 oauth_token according to the following criteria. If present, the 222 token server MUST also validate the client credentials of the 223 requesting client. Application of additional restrictions and policy 224 are at the discretion of the token server. 226 o If the oauth_token denotes an identifier used to retrieve 227 authorization information, the authorizing server MUST be able 228 query the issuing server for the purpose of validation and to 229 retrieve authorization information. The method for which this is 230 done are beyond the scope of this specification and is defined by 231 companion OAuth token specifications. 233 o If the oauth_token can be parsed and self-contains authorization 234 information, then the authorizing server MUST validate the token 235 and obtain necessary authorizing information. The method by which 236 this is done is beyond the scope of this specification and is 237 defined by companion OAuth token specifications. 239 o The token server MUST validate that received oauth_token is still 240 valid either by parsing the token itself, or by confirming 241 validity with the token server (which is out of the scope of this 242 specification). 244 2.3 Error Response 246 If the oauth_token is not valid, or authorization information 247 requirements cannot be met, the token server MUST construct an error 248 response as defined in [I-D.ietf.oauth-v2]. The value of the error 249 parameter MUST be the "invalid_grant" error code. The token server 250 MAY include additional information regarding the reasons the OAuth 251 token was considered invalid using the error_description or error_uri 252 parameters. 254 Example error: 256 HTTP/1.1 400 Bad Request 257 Content-Type: application/json 258 Cache-Control: no-store 260 { 261 "error":"invalid_grant", 262 "error_description":"Audience validation failed" 263 } 265 2.4 Example (non-normative) 267 Though non-normative, the following examples illustrate what a 268 conforming token request would look like. Note: Line breaks are for 269 readability purposes only. 271 POST /token.oauth2 HTTP/1.1 272 Host: authz.example.net 273 Content-Type: application/x-www-form-urlencoded 275 grant_type=http%3A%2F%2Foauth.net%2Fgrant_type%2Fchain 276 oauth_token=MAC+token%3D%22h480djs93hd8%22 277 %2Ctimestamp%3D%22137131200%22%2Cnonce%3D%22dj83hs9s%22 278 %2Csignature%3D%22kDZvddkndxvhGRXZhvuDjEWhGeE%3D%22 280 3. Security Considerations 282 The specification builds on considerations described within the OAuth 283 2.0 Authorization Protocol [I-D.ietf.oauth-v2]. 285 [[Other considerations TBD]] 287 3.1 Single Domain 289 OAuth protected servers within the same domain, using the same Token 290 server, MAY request new OAuth tokens for the purpose of binding the 291 original user context with the new client credential. 293 3.2 Multi-Domain 295 When issuing tokens between OAuth domains, the token server MUST be 296 able to determine the submitted oauth_token's issuer. 298 The token server SHOULD have a method of establishing trust with the 299 issuer of the received OAuth token. 301 The token server MUST define a method of mapping received credentials 302 received via the received OAuth token. 304 4. IANA Considerations 306 The following is a parameter registration request, as defined in The 307 OAuth Parameters Registry of The OAuth 2.0 Authorization Protocol [I- 308 D.ietf.oauth-v2], for the "oauth_token" parameter: 310 o Parameter name: oauth_token 312 o Parameter usage: token request 314 o Change controller: IETF 316 o Specification document(s): draft-hunt-oauth-chain 318 5. References 320 5.1 Normative References 322 [I-D.ietf.oauth-v2] 323 Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, "The 324 OAuth 2.0 Authorization Protocol", ID draft-ietf-oauth- 325 v2-13 (work in progress), Feb 2011. 327 [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate 328 Requirement Levels", BCP 14, RFC 2119, March 1997. 330 5.2 Informative References 332 [I-D.ietf.oauth.saml2.bearer] 333 Campbell, B., and Mortimore, C., "SAML 2.0 Bearer 334 Assertion Grant Type Profile for OAuth 2.0", ID draft- 335 ietf-oauth-saml2-bearer-03 (work in progress), Feb 2011. 337 Appendix A. Contributors 339 The current draft was based in part on the SAML 2.0 Bearer Assertion 340 Grant Type profile [I-D.ietf.oauth.saml2.bearer], by B. Campbell and 341 C. Mortimore. 343 Appendix B. Document History 345 [[ to be removed by RFC editor before publication as an RFC ]] 346 o Initial draft 348 draft-hunt-oauth-chain-01 349 o Document refreshed for OAuth WG discussion 351 Author's Addresses 353 Phil Hunt (editor) 354 Oracle Corporation 356 EMail: phil.hunt@yahoo.com