idnits 2.17.1 draft-jones-oauth-token-exchange-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 (November 3, 2013) is 3827 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 Microsoft 4 Intended status: Standards Track November 3, 2013 5 Expires: May 7, 2014 7 OAuth 2.0 Token Exchange 8 draft-jones-oauth-token-exchange-00 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 May 7, 2014. 34 Copyright Notice 36 Copyright (c) 2013 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 . . . . . . . . . . . 5 58 3. Security Token Response . . . . . . . . . . . . . . . . . . . . 6 59 4. Conveying Eligibility to Act As Another Party . . . . . . . . . 6 60 5. Implementation Considerations . . . . . . . . . . . . . . . . . 7 61 6. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . . 7 62 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7 63 8. Security Considerations . . . . . . . . . . . . . . . . . . . . 8 64 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 65 9.1. Normative References . . . . . . . . . . . . . . . . . . . 8 66 9.2. Informative References . . . . . . . . . . . . . . . . . . 8 67 Appendix A. Document History . . . . . . . . . . . . . . . . . . . 9 68 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 9 70 1. Introduction 72 This specification defines how to request and obtain Security Tokens 73 from OAuth Authorization Servers [RFC6749], including enabling one 74 party to act on behalf of another or enabling one party to delegate 75 authority to another. This functionality is intentionally parallel 76 to the functionality defined by [WS-Trust], including On-Behalf-Of 77 and Act-As. 79 A Security Token is a set of information that facilitates the sharing 80 of identity and security information across security domains. 81 Examples of Security Tokens include JSON Web Tokens (JWTs) [JWT] and 82 SAML Assertions [OASIS.saml-core-2.0-os]. Security Tokens are 83 typically signed to achieve integrity and sometimes also encrypted to 84 achieve confidentiality. Security Tokens are also described as 85 Assertions in [I-D.ietf-oauth-assertions]. 87 This specification defines a new Security Token Request Grant Type 88 used at the Token Endpoint to convey the parameters for a Security 89 Token request and Security Token response parameter used in responses 90 to these requests. The Security Token Request is a JSON Web Token 91 (JWT) [JWT] that is signed by the requesting party that contains 92 parameters of the request as Claims. 94 The Security Tokens obtained could be used in a number of contexts, 95 the specifics of which are beyond the scope of this specification. 96 Examples include using them with the 98 1.1. Requirements Notation and Conventions 100 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 101 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 102 document are to be interpreted as described in RFC 2119 [RFC2119]. 104 1.2. Terminology 106 This specification uses the terms "Authorization Server" "Token 107 Endpoint", "Token Request", and "Token Response" defined by OAuth 2.0 108 [RFC6749], and the terms "Claim" and "JWT Claims Set" defined by JSON 109 Web Token (JWT) [JWT]. 111 1.3. On-Behalf-Of vs. Impersonation Semantics 113 When principal A acts on behalf of principal B, A is given all the 114 rights that B has within some defined rights context. Whereas, with 115 on-behalf-of semantics, principal A still has its own identity 116 separate from B and it is explicitly understood that while B may have 117 delegated its rights to A, any actions taken are being taken by A and 118 not B. In a sense, A is an agent for B. 120 On-behalf-of semantics are therefore different than impersonation 121 semantics, with which it is sometimes confused. When principal A 122 impersonates principal B, then in so far as any entity receiving 123 Claims is concerned, they are actually dealing with B. It is true 124 that some members of the identity system might have awareness that 125 impersonation is going on but it is not a requirement. For all 126 intents and purposes, when A is acting for B, A is B. 128 2. Security Token Request 130 A Security Token Request is sent to the Token Endpoint as a Token 131 Request message using this Grant Type value: 133 security_token_request Grant Type value indicating that this Token 134 Request is a Security Token Request. 136 A Token Request parameter of the same name is used to convey the 137 information contained in Security Token Request as a JWT: 139 security_token_request Token Request parameter whose value is a JWT 140 containing the Security Token Request information. 142 An example Security Token Request (with extra line breaks for display 143 purposes only) follows: 145 POST /token HTTP/1.1 146 Host: server.example.com 147 Content-Type: application/x-www-form-urlencoded 149 grant_type=security_token_request&security_token_request= 150 eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ ... [omitted for brevity] 152 The "security_token_request" parameter value is a JWT with the 153 following members: 155 iss REQUIRED. The issuer of the principal requesting the Security 156 Token. 158 sub REQUIRED. The identifier of the principal requesting the 159 Security Token at the issuer. 161 security_token_type OPTIONAL. An identifier for the type of the 162 requested Security Token. If not present, the default is that a 163 JWT is being requested. A JWT can also be requested with the 164 identifier "urn:ietf:params:oauth:token-type:jwt". 166 scopes OPTIONAL. An array of strings, each of which represents a 167 service context that the requested Security Token is being 168 requested to be used for. The array MUST contain at least one 169 scope value. The definition of these contexts is outside the 170 scope of this specification. (Note: This request element serves 171 the same purpose as the WS-Trust AppliesTo RST element.) 173 The JWT MUST be signed by the issuer so the identity of the 174 requesting party can be validated. 176 The following is an example of a JWT Claims Set for a Security Token 177 Request: 179 { 180 "iss": "https://server.example.com", 181 "sub": "24400320", 182 "scopes": ["example"] 183 } 185 2.1. Act-As Security Token Requests 187 This specification defines the ability to request a Security Token 188 for the requesting party to use to act as the specified party. This 189 is accomplished using this Token Request parameter: 191 act_as This OPTIONAL request parameter indicates that the requested 192 Security Token is expected to contain information about the 193 identity represented by the Security Token that is the value of 194 this parameter, enabling the requesting party to use the returned 195 Security Token to act as this identity. 197 The following is an example of a JWT Claims Set for a Security Token 198 Request using an "act_as" Claim: 200 { 201 "iss": "https://server.example.com", 202 "sub": "24400320", 203 "scopes": ["example"], 204 "act_as": "eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ ..." 205 } 207 2.2. On-Behalf-Of Security Token Requests 209 This specification defines the ability to request a Security Token on 210 behalf of another party. This is accomplished using this Token 211 Request parameter: 213 on_behalf_of This OPTIONAL request parameter indicates that the 214 Security Token is being requested on behalf of another party. The 215 identity of the party upon whose behalf the request is being made 216 is represented by the Security Token that is the value of this 217 parameter. Proof of eligibility to act on behalf of that identity 218 MAY be conveyed by including an "actor" Claim identifying the 219 requesting party in the Security Token, per Section 4, provided 220 the Security Token is a JWT. 222 The following is an example of a JWT Claims Set for a Security Token 223 Request using an "on_behalf_of" Claim: 225 { 226 "iss": "https://server.example.com", 227 "sub": "24400320", 228 "scopes": ["example"], 229 "on_behalf_of": "eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ ..." 230 } 232 3. Security Token Response 234 A Security Token Response is returned from the Token Endpoint as a 235 Token Response message containing these members: 237 security_token The returned Security Token. 239 security_token_type An identifier for the type of the returned 240 Security Token. If the Security Token is a JWT, this identifier 241 is "urn:ietf:params:oauth:token-type:jwt". 243 An example successful response is as follows: 245 HTTP/1.1 200 OK 246 Content-Type: application/json;charset=UTF-8 247 Cache-Control: no-store 248 Pragma: no-cache 250 { 251 "security_token": "eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ ...", 252 "security_token_type": "urn:ietf:params:oauth:token-type:jwt" 253 } 255 4. Conveying Eligibility to Act As Another Party 257 It is useful to be able to make a statement that one party is 258 authorized to act on behalf of another party. This can be done by 259 having the party being acted for sign a Security Token containing a 260 Claim identifying party that will act for it as an authorized actor. 261 This statement can also optionally identify scopes in which the actor 262 is eligible to act through another Claim. The following Claims are 263 defined for use in JWTs for these purposes: 265 actor Security Token that identifies a party who is asserted as 266 being eligible to act for the party identified by the JWT 267 containing this Claim. 269 scopes OPTIONAL. An array of strings, each of which represents a 270 service context for which the actor is asserted as being eligible 271 to act for the party identified by the JWT containing this Claim. 272 The array MUST contain at least one scope value. The definition 273 of these contexts is outside the scope of this specification. 275 5. Implementation Considerations 277 Implementations of the specification MUST implement support for using 278 JWTs as the Security Tokens. Other Security Token types MAY be 279 supported. 281 6. Open Issues 283 The following decisions need to be made and updates this spec 284 performed: 286 o Should we say anything about proof of possession of the target 287 party's key in the On-Behalf-Of case beyond specifying the use of 288 the "actor" Claim? 290 o Revise the text in the On-Behalf-Of vs. Impersonation Semantics 291 section to better align the terminology used with the semantics 292 specified. 294 7. IANA Considerations 296 The "security_token_request" Grant Type is to be registered in the 297 OAuth Parameters registry. 299 The "scopes", "act_as", and "on_behalf_of" Claims are to be 300 registered in the JSON Web Token Claims registry. 302 8. Security Considerations 304 All of the normal security issues, especially in relationship to 305 comparing URIs and dealing with unrecognized values, that are 306 discussed in JWT [JWT] also apply here. 308 In addition, on-behalf-of introduces its own unique security issues. 309 Any time one principal is delegated the rights of another principal, 310 the potential for abuse is always a concern. That is why use of the 311 "scopes" member is suggested. The scope values restrict the contexts 312 in which the delegated rights can be exercised. 314 9. References 316 9.1. Normative References 318 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 319 (JWT)", draft-ietf-oauth-json-web-token (work in 320 progress), October 2013. 322 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 323 Requirement Levels", BCP 14, RFC 2119, March 1997. 325 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", 326 RFC 6749, October 2012. 328 9.2. Informative References 330 [I-D.ietf-oauth-assertions] 331 Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 332 "Assertion Framework for OAuth 2.0 Client Authentication 333 and Authorization Grants", draft-ietf-oauth-assertions 334 (work in progress), July 2013. 336 [OASIS.saml-core-2.0-os] 337 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 338 "Assertions and Protocol for the OASIS Security Assertion 339 Markup Language (SAML) V2.0", OASIS Standard saml-core- 340 2.0-os, March 2005. 342 [WS-Trust] 343 Nadalin, A., Goodner, M., Gudgin, M., Barbir, A., and H. 344 Granqvist, "WS-Trust 1.4", February 2012, . 347 Appendix A. Document History 349 [[ to be removed by the RFC Editor before publication as an RFC ]] 351 -00 353 o Created initial version. 355 Author's Address 357 Michael B. Jones 358 Microsoft 360 Email: mbj@microsoft.com 361 URI: http://self-issued.info/