idnits 2.17.1 draft-richer-oauth-chain-00.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 (September 07, 2012) is 4250 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) == Unused Reference: 'InfRef' is defined on line 289, but no explicit reference was found in the text Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Richer 3 Internet-Draft The MITRE Corporation 4 Intended status: Standards Track September 07, 2012 5 Expires: March 11, 2013 7 A Method of Bearer Token Redelegation and Chaining for OAuth 2 8 draft-richer-oauth-chain-00 10 Abstract 12 This document provides a method for a resource server to present a 13 token that it has received from a client back to its authorization 14 server for the purposes of receiving a derivative token for use on 15 another resource server in order to chain together service requests. 17 Requirements Language 19 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 20 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 21 document are to be interpreted as described in RFC 2119 [RFC2119]. 23 Status of this Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on March 11, 2013. 40 Copyright Notice 42 Copyright (c) 2012 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Service Chaining . . . . . . . . . . . . . . . . . . . . . . . 3 58 1.1. Abbreviations Used In This Document . . . . . . . . . . . . 3 59 2. Protocol Description . . . . . . . . . . . . . . . . . . . . . 4 60 3. Redelegation Grant Type . . . . . . . . . . . . . . . . . . . . 5 61 3.1. Redelegate Request . . . . . . . . . . . . . . . . . . . . 6 62 3.2. Access Token Response . . . . . . . . . . . . . . . . . . . 6 63 3.3. Error Response . . . . . . . . . . . . . . . . . . . . . . 6 64 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7 65 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 7 66 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 7 67 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7 68 7.1. Normative References . . . . . . . . . . . . . . . . . . . 7 69 7.2. Informative References . . . . . . . . . . . . . . . . . . 7 70 Appendix A. Standardization of Scopes . . . . . . . . . . . . . . 7 71 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 8 73 1. Service Chaining 75 The OAuth2 Authorization protocol provides methods for clients to 76 request tokens from authorization servers on behalf of resource 77 owners for use at resource servers. However, there are no provisions 78 for a resource server to act as a client itself for another resource 79 server, a practice known generally as service chaining. Typically, 80 the services involved in the chain are within a single security 81 domain, and with OAuth they would be using a single Authorization 82 Server. 84 For services using the OAuth2 Bearer token profile, it is possible 85 for anyone holding the token to call any other service that accepts 86 the token. While this is functional, it is bad practice since the 87 token is knowingly being re-used by someone other than the client to 88 which it was issued. Since the same token is used in each step, this 89 approach also does not allow for attenuation of rights as the chain 90 progresses. 92 Using a new form of grant_type, this specification presents such 93 chained resource servers with an alternative approach that takes 94 advantage of the simplicity and structure of the OAuth protocol by 95 providing a means for any resource server to present the token it has 96 been accessed with back to the authorization server in order to 97 exchange it for a token of equal or lesser strength for use with 98 another resource server. In this way, the original access token 99 which has been delegated to the client can be redelegated to a 100 secondary service. 102 This approach differs slightly from the Refresh Token described in 103 the OAuth 2 Core. With a Refresh Token, the Client presents the 104 token to the authorization server to get a new Access Token without 105 involving the Resource Owner. With a redelegated Access Token, as 106 described in this document, the Resource Server presents the Access 107 Token which was provided to it by a Client in order to get a 108 secondary Access Token. 110 1.1. Abbreviations Used In This Document 112 AS Authorization Server 114 C Client 116 RO Resource Owner 117 RS1 Primary Resource Server, initially called by C on behalf of RO 119 RS2 Chained Resource Server, called by RS1 to fulfill request from C 121 AT1 Bearer Access Token granted by AS to C to access RS1 on behalf 122 of RO 124 AT2 Bearer Access Token granted by AS to RS1 to access RS2 on behalf 125 of RO 127 2. Protocol Description 129 The process begins with any standard OAuth2 protocol flow, where the 130 client obtains AT1 from the AS. 132 The beginning of the process is standard OAuth2 S.1.2 using any legal 133 OAuth2 grant type to obtain the AT1. 135 +--------+ +-------------+ 136 | |--(A)->| Resource | 137 | | | Owner | 138 | |<-(B)--| (RO) | 139 | | +-------------+ 140 | | 141 | | +---------------+ 142 | |--(C)----------------------->| Authorization | 143 | Client | | Server | 144 | |<-(D)------------------------| (AS) | 145 | | | | 146 | | | | 147 | | +-------------+ | | 148 | |--(E)->| Primary |--(F)->| | 149 | | | Resource | | | 150 | | | Server |<-(G)--| | 151 | | | (RS1) | +---------------+ 152 | | | | 153 | | | | +---------------+ 154 | | | |--(H)->| Chained | 155 | | | | | Resource | 156 | | | | | Server | 157 | | | |<-(I)--| (RS2) | 158 | |<-(J)--| | +---------------+ 159 +--------+ +-------------+ 161 (A) Client requests authorization from Resource Owner 163 (B) Client receives authorization from the Resource Owner using any 164 valid OAuth2 grant type 166 (C) Client requests AT1 from the AS by authenticating with the AS 167 and presenting the authorization grant obtained in (B) 169 (D) AS authenticates the Client and issues access token AT1 for use 170 at RS1 172 (E) Client presents access token AT1 to RS1 to access a protected 173 resource 175 (F) RS1 needs to access RS2 to fulfill this request, makes a call to 176 the Token Endpoint on the AS using the redelegate grant_type 178 (G) AS validates AT1 and issues a token AT2 for use by RS1 against 179 RS2, where the rights assigned to AT2 are a subset of those 180 assigned to AT1 182 (H) RS1 presents AT2 to RS2 to access a protected resource 184 (I) RS2 validates token AT2 and returns the protected resource to 185 RS1 187 (J) Client receives protected resource from RS1, including 188 information sourced from RS2 190 Steps A-E and J are standard OAuth2 and OAuth2 Bearer tokens 191 involving token AT1. As such, the Client MAY make use of any OAuth2 192 grant type, such as authorization_code, implicit, client_credentials, 193 password, assertion, or even the redelegation protocol defined in 194 this document. Steps F-G are described in section 3 of this 195 document. Steps H-I are standard OAuth2 Bearer token usage, but 196 using the delegated token AT2. 198 The means by which the Resource Servers validate the Access Tokens is 199 out of scope of this specification. At the time of this writing, 200 there are two main approaches found in practice: token introspection 201 and structured tokens. 203 3. Redelegation Grant Type 205 The Resource Server RS1 makes a request using the Access Token that 206 was presented to it in order to obtain a new Access Token. 208 3.1. Redelegate Request 210 To access RS2, RS1 makes a POST request to the Authorization Server's 211 Token Endpoint with the following parameters: 213 grant_type REQUIRED. Value MUST be set to 214 "urn:ietf:params:oauth:grant_type:redelegate". 216 token REQUIRED The token that was presented to the resource server 217 by the client, referred to as AT1 in the protocol flow, an OAuth2 218 Bearer token 220 scope OPTIONAL a space-separated list of strings as described in 221 OAuth 2. If present, this scope list MUST be equal to or lesser 222 than the scopes incorporated in AT1. The AS MUST issue a token of 223 equal or lesser scope than the token above. 225 The Authorization Server MAY require RS1 to have registered as a 226 client on its own behalf. In this case, RS1 MUST present its client 227 credentials as described in OAuth2 Core. 229 3.2. Access Token Response 231 If the request is valid and authorized, the AS issues an access 232 token, referred to as AT2 in the protocol flow, as described in 233 OAuth2 Core. As this access token is bound to an existing access 234 token, the authorization server MUST NOT issue a refresh token. If 235 the request failed, the authorization server returns an error 236 response as described in OAuth2 Core. 238 HTTP/1.1 200 OK 239 Content-Type: application/json;charset=UTF-8 240 Cache-Control: no-store 241 Pragma: no-cache 243 { 244 "access_token":"2YotnFZFEjr1zCsicMWpAA", 245 "token_type":"example", 246 "expires_in":3600, 247 "example_parameter":"example_value" 248 } 250 3.3. Error Response 252 If the token request is not valid, such as the access token presented 253 does not allow for redelegation, the AS returns an error response as 254 described in OAuth2 Core. 256 4. IANA Considerations 258 [Registration into the OAuth registry for 259 urn:ietf:params:oauth:grant_type:redelegate] 261 Note to RFC Editor: this section may be removed on publication as an 262 RFC. 264 5. Security Considerations 266 A resource server engaging in service chaining and token redelegation 267 SHOULD request a redelegated token with only the minimum set of 268 scopes necessary for calling downstream services. 270 A resource server MUST indicate in service documentation the full set 271 of scopes required for accessing the full service chain. A 272 redelegation request MUST NOT request escalated privileges without 273 involving the resource owner in a new authorization grant. 275 6. Acknowledgements 277 This work has grown from discussions with Paul Nguyen and Stephen 278 Moore, both of MITRE. 280 7. References 282 7.1. Normative References 284 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 285 Requirement Levels", BCP 14, RFC 2119, March 1997. 287 7.2. Informative References 289 [InfRef] "", 2004. 291 Appendix A. Standardization of Scopes 293 The OAuth2 specification explicitly leaves the definition of scopes 294 to the Authorization Server and Protected Resource to agree upon. 295 However, in the course of redelegation, it is sometimes desirable to 296 have a scope value related to the redelegation permission itself. It 297 is RECOMMENDED to use a scope value of "redelegate" if possible. 299 Author's Address 301 Justin Richer 302 The MITRE Corporation 303 202 Burlington Rd. 304 Bedford, Massachusetts 01821 305 USA 307 Phone: +1-781-271-8176 308 Fax: 309 Email: jricher@mitre.org