idnits 2.17.1 draft-jones-oauth-token-exchange-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 (July 4, 2014) is 3577 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 OAuth Working Group M. Jones 3 Internet-Draft A. Nadalin 4 Intended status: Standards Track C. Baker 5 Expires: January 5, 2015 Microsoft 6 July 4, 2014 8 OAuth 2.0 Token Exchange 9 draft-jones-oauth-token-exchange-01 11 Abstract 13 This specification defines how to request and obtain Security Tokens 14 from OAuth Authorization Servers, including enabling one party to act 15 on behalf of another or enabling one party to delegate authority to 16 another. 18 Status of this Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at 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 January 5, 2015. 35 Copyright Notice 37 Copyright (c) 2014 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 . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 1.1. Requirements Notation and Conventions . . . . . . . . . . 3 54 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 55 1.3. On-Behalf-Of vs. Impersonation Semantics . . . . . . . . . 3 56 2. Security Token Request . . . . . . . . . . . . . . . . . . . . 4 57 2.1. Act-As Security Token Requests . . . . . . . . . . . . . . 5 58 2.2. On-Behalf-Of Security Token Requests . . . . . . . . . . . 6 59 3. Security Token Response . . . . . . . . . . . . . . . . . . . 6 60 4. Conveying Eligibility to Act As Another Party . . . . . . . . 7 61 5. Implementation Considerations . . . . . . . . . . . . . . . . 8 62 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 63 7. Security Considerations . . . . . . . . . . . . . . . . . . . 8 64 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 65 8.1. Normative References . . . . . . . . . . . . . . . . . . . 8 66 8.2. Informative References . . . . . . . . . . . . . . . . . . 8 67 Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . . 9 68 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 9 69 Appendix C. Document History . . . . . . . . . . . . . . . . . . 9 70 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10 72 1. Introduction 74 This specification defines how to request and obtain Security Tokens 75 from OAuth Authorization Servers [RFC6749], including enabling one 76 party to act on behalf of another or enabling one party to delegate 77 authority to another. The functionality defined and the terminology 78 used in this specification are intentionally parallel to the 79 functionality and terminology defined by [WS-Trust], including On- 80 Behalf-Of and Act-As. 82 A Security Token is a set of information that facilitates the sharing 83 of identity and security information across security domains. 84 Examples of Security Tokens include JSON Web Tokens (JWTs) [JWT] and 85 SAML Assertions [OASIS.saml-core-2.0-os]. Security Tokens are 86 typically signed to achieve integrity and sometimes also encrypted to 87 achieve confidentiality. Security Tokens are also described as 88 Assertions in [I-D.ietf-oauth-assertions]. 90 This specification defines a new Security Token Request Grant Type 91 used at the Token Endpoint to convey the parameters for a Security 92 Token request and Security Token response parameter used in responses 93 to these requests. The Security Token Request is a JSON Web Token 94 (JWT) [JWT] that is issued by the requesting party that contains 95 parameters of the request as Claims. 97 The Security Tokens obtained could be used in a number of contexts, 98 the specifics of which are beyond the scope of this specification. 99 Examples include using them with the 101 1.1. Requirements Notation and Conventions 103 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 104 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 105 document are to be interpreted as described in RFC 2119 [RFC2119]. 107 1.2. Terminology 109 This specification uses the terms "Authorization Server" "Token 110 Endpoint", "Token Request", and "Token Response" defined by OAuth 2.0 111 [RFC6749], and the terms "Claim" and "JWT Claims Set" defined by JSON 112 Web Token (JWT) [JWT]. 114 1.3. On-Behalf-Of vs. Impersonation Semantics 116 When principal A acts on behalf of principal B, A is given all the 117 rights that B has within some defined rights context. Whereas, with 118 on-behalf-of semantics, principal A still has its own identity 119 separate from B and it is explicitly understood that while B may have 120 delegated its rights to A, any actions taken are being taken by A and 121 not B. In a sense, A is an agent for B. 123 On-behalf-of semantics are therefore different than impersonation 124 semantics, with which it is sometimes confused. When principal A 125 impersonates principal B, then in so far as any entity receiving 126 Claims is concerned, they are actually dealing with B. It is true 127 that some members of the identity system might have awareness that 128 impersonation is going on but it is not a requirement. For all 129 intents and purposes, when A is acting for B, A is B. 131 2. Security Token Request 133 A Security Token Request is sent to the Token Endpoint as a Token 134 Request message using this Grant Type value: 136 urn:ietf:params:oauth:grant-type:security-token-request 137 Grant Type value indicating that this Token Request is a Security 138 Token Request. 140 A Token Request parameter with a related name is used to convey the 141 information contained in Security Token Request as a JWT: 143 security_token_request 144 Token Request parameter whose value is a JWT containing the 145 Security Token Request information. 147 An example Security Token Request (with extra line breaks for display 148 purposes only) follows: 150 POST /token HTTP/1.1 151 Host: server.example.com 152 Content-Type: application/x-www-form-urlencoded 154 grant_type=urn:ietf:params:oauth:grant-type:security-token-request 155 &security_token_request=eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ ... 156 [omitted for brevity] 158 The "security_token_request" parameter value is a JWT with the 159 following members: 161 iss 162 REQUIRED. Issuer of the principal requesting the Security Token. 164 sub 165 REQUIRED. Identifier of the principal requesting the Security 166 Token at the issuer. 168 security_token_type 169 OPTIONAL. Identifier for the type of the requested Security 170 Token. If not present, the default is that a JWT is being 171 requested. A JWT can also be requested with the identifier 172 "urn:ietf:params:oauth:token-type:jwt". 174 scopes 175 OPTIONAL. Array of strings, each of which represents a service 176 context that the requested Security Token is being requested to be 177 used for. The array MUST contain at least one scope value. The 178 definition of these contexts is outside the scope of this 179 specification. (Note: This request element serves the same 180 purpose as the WS-Trust AppliesTo RST element.) 182 The request JWT MUST be signed by the issuer so the identity of the 183 requesting party can be validated unless the identity of the 184 requesting party is known to the Authorization Server by other means; 185 in that case, the JWT can use the "alg" value "none". 187 The following is an example of a JWT Claims Set for a Security Token 188 Request: 190 { 191 "iss": "https://server.example.com", 192 "sub": "24400320", 193 "scopes": ["example"] 194 } 196 2.1. Act-As Security Token Requests 198 This specification defines the ability to request a Security Token 199 for the requesting party to use to act as the specified party. This 200 is accomplished using this Token Request parameter: 202 act_as 203 This OPTIONAL request parameter indicates that the requested 204 Security Token is expected to contain information about the 205 identity represented by the Security Token that is the value of 206 this parameter, enabling the requesting party to use the returned 207 Security Token to act as this identity. 209 The following is an example of a JWT Claims Set for a Security Token 210 Request using an "act_as" Claim: 212 { 213 "iss": "https://server.example.com", 214 "sub": "24400320", 215 "scopes": ["example"], 216 "act_as": "eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ ..." 217 } 219 2.2. On-Behalf-Of Security Token Requests 221 This specification defines the ability to request a Security Token on 222 behalf of another party. This is accomplished using this Token 223 Request parameter: 225 on_behalf_of 226 This OPTIONAL request parameter indicates that the Security Token 227 is being requested on behalf of another party. The identity of 228 the party upon whose behalf the request is being made is 229 represented by the Security Token that is the value of this 230 parameter. Proof of eligibility to act on behalf of that identity 231 MAY be conveyed by including an "actor" Claim identifying the 232 requesting party in the Security Token, per Section 4, provided 233 the Security Token is a JWT. 235 The following is an example of a JWT Claims Set for a Security Token 236 Request using an "on_behalf_of" Claim: 238 { 239 "iss": "https://server.example.com", 240 "sub": "24400320", 241 "scopes": ["example"], 242 "on_behalf_of": "eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ ..." 243 } 245 3. Security Token Response 247 A Security Token Response is returned from the Token Endpoint as a 248 Token Response message containing these members: 250 security_token 251 Returned Security Token. 253 security_token_type 254 Identifier for the type of the returned Security Token. If the 255 Security Token is a JWT, this identifier is 256 "urn:ietf:params:oauth:token-type:jwt". 258 An example successful response is as follows: 260 HTTP/1.1 200 OK 261 Content-Type: application/json;charset=UTF-8 262 Cache-Control: no-store 263 Pragma: no-cache 265 { 266 "security_token": "eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ ...", 267 "security_token_type": "urn:ietf:params:oauth:token-type:jwt" 268 } 270 4. Conveying Eligibility to Act As Another Party 272 It is useful to be able to make a statement that one party is 273 authorized to act on behalf of another party. This can be done by 274 having the party being acted for issue a Security Token containing a 275 Claim identifying the party that will act for it as an authorized 276 actor. This statement can also optionally identify scopes in which 277 the actor is eligible to act through another Claim. The following 278 Claims are defined for use in JWTs for these purposes: 280 actor 281 Security Token that identifies a party who is asserted as being 282 eligible to act for the party identified by the JWT containing 283 this Claim. 285 scopes 286 OPTIONAL. Array of strings, each of which represents a service 287 context for which the actor is asserted as being eligible to act 288 for the party identified by the JWT containing this Claim. The 289 array MUST contain at least one scope value. The definition of 290 these contexts is outside the scope of this specification. 292 The JWT issued by the party being acted for MUST be signed so the 293 identity of the party being acted for can be validated unless the 294 identity of the party being acted for is known to the Authorization 295 Server by other means; in that case, the JWT can use the "alg" value 296 "none". 298 5. Implementation Considerations 300 Implementations of the specification MUST implement support for using 301 JWTs as the Security Tokens. Other Security Token types MAY be 302 supported. 304 6. IANA Considerations 306 The "urn:ietf:params:oauth:grant-type:security-token-request" Grant 307 Type is to be registered in the IANA urn:ietf:params:oauth registry 308 established in An IETF URN Sub-Namespace for OAuth [RFC6755]. 310 The "scopes", "act_as", and "on_behalf_of" Claims are to be 311 registered in the JSON Web Token Claims registry. 313 7. Security Considerations 315 All of the normal security issues, especially in relationship to 316 comparing URIs and dealing with unrecognized values, that are 317 discussed in JWT [JWT] also apply here. 319 In addition, on-behalf-of introduces its own unique security issues. 320 Any time one principal is delegated the rights of another principal, 321 the potential for abuse is always a concern. That is why use of the 322 "scopes" member is suggested. The scope values restrict the contexts 323 in which the delegated rights can be exercised. 325 8. References 327 8.1. Normative References 329 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 330 (JWT)", draft-ietf-oauth-json-web-token (work in 331 progress), July 2014. 333 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 334 Requirement Levels", BCP 14, RFC 2119, March 1997. 336 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", 337 RFC 6749, October 2012. 339 8.2. Informative References 341 [I-D.ietf-oauth-assertions] 342 Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 343 "Assertion Framework for OAuth 2.0 Client Authentication 344 and Authorization Grants", draft-ietf-oauth-assertions 345 (work in progress), April 2014. 347 [OASIS.saml-core-2.0-os] 348 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 349 "Assertions and Protocol for the OASIS Security Assertion 350 Markup Language (SAML) V2.0", OASIS Standard saml-core- 351 2.0-os, March 2005. 353 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 354 for OAuth", RFC 6755, October 2012. 356 [WS-Trust] 357 Nadalin, A., Goodner, M., Gudgin, M., Barbir, A., and H. 358 Granqvist, "WS-Trust 1.4", February 2012, . 361 Appendix A. Open Issues 363 The following decisions need to be made and updates on this spec 364 performed: 366 o Should we say anything about proof of possession of the target 367 party's key in the On-Behalf-Of case beyond specifying the use of 368 the "actor" Claim? 370 o Revise the text in the On-Behalf-Of vs. Impersonation Semantics 371 section to better align the terminology used with the semantics 372 specified. 374 o Address the sources of potential terminological confusion 375 discussed in John Bradley's review comments. 377 o Add examples illustrating concrete uses of act-as and 378 on-behalf-of. 380 Appendix B. Acknowledgements 382 The authors wish to thank Brian Campbell and John Bradley for reviews 383 of the specification. 385 Appendix C. Document History 387 [[ to be removed by the RFC Editor before publication as an RFC ]] 388 -01 390 o Updated the draft to allow JWTs to be unsigned in cases where the 391 trust model permits it. 393 o Indicated that the functionality defined and the terminology used 394 in this specification are intentionally parallel to the 395 functionality and terminology defined by WS-Trust, including On- 396 Behalf-Of and Act-As. 398 o Renamed the "security_token_request" grant type to 399 "urn:ietf:params:oauth:grant-type:security-token-request". 401 -00 403 o Created initial version. 405 Authors' Addresses 407 Michael B. Jones 408 Microsoft 410 Email: mbj@microsoft.com 411 URI: http://self-issued.info/ 413 Anthony Nadalin 414 Microsoft 416 Email: tonynad@microsoft.com 418 Caleb Baker 419 Microsoft 421 Email: calebb@microsoft.com