idnits 2.17.1 draft-ietf-oauth-token-exchange-02.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 6, 2015) is 3216 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 Microsoft 5 Expires: January 7, 2016 July 6, 2015 7 OAuth 2.0 Token Exchange 8 draft-ietf-oauth-token-exchange-02 10 Abstract 12 This specification defines how to request and obtain Security Tokens 13 from OAuth Authorization Servers, including enabling one party to act 14 on behalf of another or enabling one party to delegate authority to 15 another. 17 Status of this Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on January 7, 2016. 34 Copyright Notice 36 Copyright (c) 2015 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 52 1.1. Requirements Notation and Conventions . . . . . . . . . . 3 53 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 54 1.3. On-Behalf-Of vs. Impersonation Semantics . . . . . . . . . 3 55 2. Security Token Request . . . . . . . . . . . . . . . . . . . . 4 56 2.1. Act-As Security Token Requests . . . . . . . . . . . . . . 5 57 2.2. On-Behalf-Of Security Token Requests . . . . . . . . . . . 6 58 3. Security Token Response . . . . . . . . . . . . . . . . . . . 7 59 4. Conveying Eligibility to Act As Another Party . . . . . . . . 7 60 5. Implementation Considerations . . . . . . . . . . . . . . . . 8 61 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 62 7. Security Considerations . . . . . . . . . . . . . . . . . . . 8 63 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 64 8.1. Normative References . . . . . . . . . . . . . . . . . . . 8 65 8.2. Informative References . . . . . . . . . . . . . . . . . . 9 66 Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . . 9 67 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 10 68 Appendix C. Document History . . . . . . . . . . . . . . . . . . 10 69 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10 71 1. Introduction 73 This specification defines how to request and obtain Security Tokens 74 from OAuth Authorization Servers [RFC6749], including enabling one 75 party to act on behalf of another or enabling one party to delegate 76 authority to another. The functionality defined and the terminology 77 used in this specification are intentionally parallel to the 78 functionality and terminology defined by [WS-Trust], including On- 79 Behalf-Of and Act-As. 81 A Security Token is a set of information that facilitates the sharing 82 of identity and security information across security domains. 83 Examples of Security Tokens include JSON Web Tokens (JWTs) [JWT] and 84 SAML Assertions [OASIS.saml-core-2.0-os]. Security Tokens are 85 typically signed to achieve integrity and sometimes also encrypted to 86 achieve confidentiality. Security Tokens are also described as 87 Assertions in [RFC7521]. 89 This specification defines a new Security Token Request Grant Type 90 used at the Token Endpoint to convey the parameters for a Security 91 Token request and Security Token response parameter used in responses 92 to these requests. The Security Token Request is a JSON Web Token 93 (JWT) [JWT] that is issued by the requesting party that contains 94 parameters of the request as Claims. 96 The Security Tokens obtained could be used in a number of contexts, 97 the specifics of which are beyond the scope of this specification. 98 Examples include using them with the 100 1.1. Requirements Notation and Conventions 102 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 103 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 104 document are to be interpreted as described in RFC 2119 [RFC2119]. 106 1.2. Terminology 108 This specification uses the terms "Authorization Server" "Token 109 Endpoint", "Token Request", and "Token Response" defined by OAuth 2.0 110 [RFC6749], and the terms "Claim" and "JWT Claims Set" defined by JSON 111 Web Token (JWT) [JWT]. 113 1.3. On-Behalf-Of vs. Impersonation Semantics 115 When principal A acts on behalf of principal B, A is given all the 116 rights that B has within some defined rights context. Whereas, with 117 on-behalf-of semantics, principal A still has its own identity 118 separate from B and it is explicitly understood that while B may have 119 delegated its rights to A, any actions taken are being taken by A and 120 not B. In a sense, A is an agent for B. 122 On-behalf-of semantics are therefore different than impersonation 123 semantics, with which it is sometimes confused. When principal A 124 impersonates principal B, then in so far as any entity receiving 125 Claims is concerned, they are actually dealing with B. It is true 126 that some members of the identity system might have awareness that 127 impersonation is going on but it is not a requirement. For all 128 intents and purposes, when A is acting for B, A is B. 130 2. Security Token Request 132 A Security Token Request is sent to the Token Endpoint as a Token 133 Request message using this Grant Type value: 135 urn:ietf:params:oauth:grant-type:security-token-request 136 Grant Type value indicating that this Token Request is a Security 137 Token Request. 139 A Token Request parameter with a related name is used to convey the 140 information contained in Security Token Request as a JWT: 142 security_token_request 143 Token Request parameter whose value is a JWT containing the 144 Security Token Request information. 146 An example Security Token Request (with extra line breaks for display 147 purposes only) follows: 149 POST /token HTTP/1.1 150 Host: server.example.com 151 Content-Type: application/x-www-form-urlencoded 153 grant_type=urn:ietf:params:oauth:grant-type:security-token-request 154 &security_token_request=eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ ... 155 [omitted for brevity] 157 The "security_token_request" parameter value is a JWT with the 158 following members: 160 iss 161 REQUIRED. Issuer of the principal requesting the Security Token. 163 sub 164 REQUIRED. Identifier of the principal requesting the Security 165 Token at the issuer. 167 security_token_type 168 OPTIONAL. Identifier for the type of the requested Security 169 Token. If not present, the default is that a JWT is being 170 requested. A JWT can also be requested with the identifier 171 "urn:ietf:params:oauth:token-type:jwt". 173 scopes 174 OPTIONAL. Array of strings, each of which represents a service 175 context that the requested Security Token is being requested to be 176 used for. The array MUST contain at least one scope value. The 177 definition of these contexts is outside the scope of this 178 specification. (Note: This request element serves the same 179 purpose as the WS-Trust AppliesTo RST element.) 181 The request JWT MUST be signed by the issuer so the identity of the 182 requesting party can be validated unless the identity of the 183 requesting party is known to the Authorization Server by other means; 184 in that case, the JWT can use the "alg" value "none". 186 The following is an example of a JWT Claims Set for a Security Token 187 Request: 189 { 190 "iss": "https://server.example.com", 191 "sub": "24400320", 192 "scopes": ["example"] 193 } 195 2.1. Act-As Security Token Requests 197 This specification defines the ability to request a Security Token 198 for the requesting party to use to act as the specified party. This 199 is accomplished using this Token Request parameter: 201 act_as 202 This OPTIONAL request parameter indicates that the requested 203 Security Token is expected to contain information about the 204 identity represented by the Security Token that is the value of 205 this parameter, enabling the requesting party to use the returned 206 Security Token to act as this identity. Unless the "act_as_type" 207 parameter is also included and specifies a different token type, 208 the "act_as" parameter MUST contain a Security Token that is a 209 JWT. 211 act_as_type 212 This OPTIONAL request parameter declares the type of the Security 213 Token in the "act_as" parameter. If the Security Token is a JWT, 214 this identifier is "urn:ietf:params:oauth:token-type:jwt". 216 The following is an example of a JWT Claims Set for a Security Token 217 Request using an "act_as" Claim: 219 { 220 "iss": "https://server.example.com", 221 "sub": "24400320", 222 "scopes": ["example"], 223 "act_as": "eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ ..." 224 } 226 2.2. On-Behalf-Of Security Token Requests 228 This specification defines the ability to request a Security Token on 229 behalf of another party. This is accomplished using this Token 230 Request parameter: 232 on_behalf_of 233 This OPTIONAL request parameter indicates that the Security Token 234 is being requested on behalf of another party. The identity of 235 the party upon whose behalf the request is being made is 236 represented by the Security Token that is the value of this 237 parameter. Proof of eligibility to act on behalf of that identity 238 MAY be conveyed by including an "actor" Claim identifying the 239 requesting party in the Security Token, per Section 4, provided 240 the Security Token is a JWT. Unless the "on_behalf_of_type" 241 parameter is also included and specifies a different token type, 242 the "on_behalf_of" parameter MUST contain a Security Token that is 243 a JWT. 245 on_behalf_of_type 246 This OPTIONAL request parameter declares the type of the Security 247 Token in the "on_behalf_of" parameter. If the Security Token is a 248 JWT, this identifier is "urn:ietf:params:oauth:token-type:jwt". 250 The following is an example of a JWT Claims Set for a Security Token 251 Request using an "on_behalf_of" Claim: 253 { 254 "iss": "https://server.example.com", 255 "sub": "24400320", 256 "scopes": ["example"], 257 "on_behalf_of": "eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ ..." 258 } 260 3. Security Token Response 262 A Security Token Response is returned from the Token Endpoint as a 263 Token Response message containing these members: 265 security_token 266 Returned Security Token. 268 security_token_type 269 Identifier for the type of the returned Security Token. If the 270 Security Token is a JWT, this identifier is 271 "urn:ietf:params:oauth:token-type:jwt". 273 An example successful response is as follows: 275 HTTP/1.1 200 OK 276 Content-Type: application/json;charset=UTF-8 277 Cache-Control: no-store 278 Pragma: no-cache 280 { 281 "security_token": "eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ ...", 282 "security_token_type": "urn:ietf:params:oauth:token-type:jwt" 283 } 285 4. Conveying Eligibility to Act As Another Party 287 It is useful to be able to make a statement that one party is 288 authorized to act on behalf of another party. This can be done by 289 having the party being acted for issue a Security Token containing a 290 Claim identifying the party that will act for it as an authorized 291 actor. This statement can also optionally identify scopes in which 292 the actor is eligible to act through another Claim. The following 293 Claims are defined for use in JWTs for these purposes: 295 actor 296 Security Token that identifies a party that is asserted as being 297 eligible to act for the party identified by the JWT containing 298 this Claim. 300 scopes 301 OPTIONAL. Array of strings, each of which represents a service 302 context for which the actor is asserted as being eligible to act 303 for the party identified by the JWT containing this Claim. The 304 array MUST contain at least one scope value. The definition of 305 these contexts is outside the scope of this specification. 307 The JWT issued by the party being acted for MUST be signed so the 308 identity of the party being acted for can be validated unless the 309 identity of the party being acted for is known to the Authorization 310 Server by other means; in that case, the JWT can use the "alg" value 311 "none". 313 5. Implementation Considerations 315 Implementations of the specification MUST implement support for using 316 JWTs as the Security Tokens. Other Security Token types MAY be 317 supported. 319 6. IANA Considerations 321 The "urn:ietf:params:oauth:grant-type:security-token-request" Grant 322 Type is to be registered in the "OAuth URI" registry established by 323 "An IETF URN Sub-Namespace for OAuth" [RFC6755]. 325 The "scopes", "act_as", "act_as_type", "on_behalf_of", and 326 "on_behalf_of_type" Claims are to be registered in the IANA "JSON Web 327 Token Claims" registry established by [JWT]. 329 7. Security Considerations 331 All of the normal security issues, especially in relationship to 332 comparing URIs and dealing with unrecognized values, that are 333 discussed in JWT [JWT] also apply here. 335 In addition, on-behalf-of introduces its own unique security issues. 336 Any time one principal is delegated the rights of another principal, 337 the potential for abuse is always a concern. That is why use of the 338 "scopes" member is suggested. The scope values restrict the contexts 339 in which the delegated rights can be exercised. 341 8. References 343 8.1. Normative References 345 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 346 (JWT)", RFC 7519, May 2015, 347 . 349 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 350 Requirement Levels", BCP 14, RFC 2119, March 1997. 352 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", 353 RFC 6749, October 2012. 355 8.2. Informative References 357 [OASIS.saml-core-2.0-os] 358 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 359 "Assertions and Protocol for the OASIS Security Assertion 360 Markup Language (SAML) V2.0", OASIS Standard saml-core- 361 2.0-os, March 2005. 363 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 364 for OAuth", RFC 6755, October 2012. 366 [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 367 "Assertion Framework for OAuth 2.0 Client Authentication 368 and Authorization Grants", RFC 7521, May 2015, 369 . 371 [WS-Trust] 372 Nadalin, A., Goodner, M., Gudgin, M., Barbir, A., and H. 373 Granqvist, "WS-Trust 1.4", February 2012, . 376 Appendix A. Open Issues 378 The following decisions need to be made and updates on this spec 379 performed: 381 o Should we say anything about proof of possession of the target 382 party's key in the On-Behalf-Of case beyond specifying the use of 383 the "actor" Claim? 385 o Revise the text in the On-Behalf-Of vs. Impersonation Semantics 386 section to better align the terminology used with the semantics 387 specified. 389 o Address the sources of potential terminological confusion 390 discussed in John Bradley's review comments. 392 o Add examples illustrating concrete uses of act-as and 393 on-behalf-of. 395 Appendix B. Acknowledgements 397 The authors wish to thank Brian Campbell and John Bradley for their 398 reviews of the specification. 400 Appendix C. Document History 402 [[ to be removed by the RFC Editor before publication as an RFC ]] 404 -02 406 o Enabled use of Security Token types other than JWTs for "act_as" 407 and "on_behalf_of" request values. 409 o Referenced the JWT and OAuth Assertions RFCs. 411 -01 413 o Updated references. 415 -00 417 o Created initial working group draft from 418 draft-jones-oauth-token-exchange-01. 420 Authors' Addresses 422 Michael B. Jones 423 Microsoft 425 Email: mbj@microsoft.com 426 URI: http://self-issued.info/ 428 Anthony Nadalin 429 Microsoft 431 Email: tonynad@microsoft.com