idnits 2.17.1 draft-ietf-oauth-token-exchange-03.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 (December 12, 2015) is 3051 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) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) Summary: 1 error (**), 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: June 14, 2016 B. Campbell 6 J. Bradley 7 Ping Identity 8 C. Mortimore 9 Salesforce 10 December 12, 2015 12 OAuth 2.0 Token Exchange: An STS for the REST of Us 13 draft-ietf-oauth-token-exchange-03 15 Abstract 17 This specification defines a protocol for a lightweight HTTP- and 18 JSON- based Security Token Service (STS) by defining how to request 19 and obtain security tokens from OAuth 2.0 authorization servers, 20 including security tokens employing impersonation and delegation. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on June 14, 2016. 39 Copyright Notice 41 Copyright (c) 2015 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 1.1. Delegation vs. Impersonation Semantics . . . . . . . . . 4 58 1.2. Requirements Notation and Conventions . . . . . . . . . . 5 59 1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 60 2. Token Exchange Request and Response . . . . . . . . . . . . . 5 61 2.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 5 62 2.2. Response . . . . . . . . . . . . . . . . . . . . . . . . 8 63 2.3. Example Token Exchange . . . . . . . . . . . . . . . . . 9 64 3. Token Type Identifiers . . . . . . . . . . . . . . . . . . . 11 65 4. JSON Web Token Claims . . . . . . . . . . . . . . . . . . . . 12 66 4.1. "act" (Actor) Claim . . . . . . . . . . . . . . . . . . . 12 67 4.2. "scp" (Scopes) Claim . . . . . . . . . . . . . . . . . . 14 68 4.3. "may_act" (May Act For) Claim . . . . . . . . . . . . . . 15 69 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 70 5.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 16 71 5.2. OAuth Parameters Registration . . . . . . . . . . . . . . 16 72 5.3. OAuth Access Token Type Registration . . . . . . . . . . 18 73 5.4. JSON Web Token Claims Registration . . . . . . . . . . . 18 74 6. Security Considerations . . . . . . . . . . . . . . . . . . . 18 75 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 76 7.1. Normative References . . . . . . . . . . . . . . . . . . 19 77 7.2. Informative References . . . . . . . . . . . . . . . . . 19 78 Appendix A. Additional Token Exchange Examples . . . . . . . . . 20 79 A.1. Impersonation Token Exchange Example . . . . . . . . . . 20 80 A.2. Delegation Token Exchange Example . . . . . . . . . . . . 22 81 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 25 82 Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . 25 83 Appendix D. Document History . . . . . . . . . . . . . . . . . . 26 84 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28 86 1. Introduction 88 A security token is a set of information that facilitates the sharing 89 of identity and security information in heterogeneous environments or 90 across security domains. Examples of security tokens include JSON 91 Web Tokens (JWTs) [JWT] and SAML Assertions [OASIS.saml-core-2.0-os]. 92 Security tokens are typically signed to achieve integrity and 93 sometimes also encrypted to achieve confidentiality. Security tokens 94 are also sometimes described as Assertions, such as in [RFC7521]. 96 A Security Token Service (STS) is a service capable of validating and 97 issuing security tokens, which enables clients to obtain appropriate 98 access credentials for resources in heterogeneous environments or 99 across security domains. Web Service clients have used WS-Trust 100 [WS-Trust] as the protocol to interact with an STS for token 101 exchange, however WS-Trust is a fairly heavyweight protocol, which 102 uses XML, SOAP, etc. Whereas, the trend in modern Web development 103 has been towards lightweight services utilizing RESTful patterns and 104 JSON. The OAuth 2.0 Authorization Framework [RFC6749] and OAuth 2.0 105 Bearer Tokens [RFC6750] have emerged as popular standards for 106 authorizing and securing access to HTTP and RESTful resources but do 107 not provide everything necessary to facilitate token exchange 108 interactions. 110 This specification defines a lightweight protocol extending OAuth 2.0 111 that enables clients to request and obtain security tokens from 112 authorization servers acting in the role of an STS. Similar to OAuth 113 2.0, this specification focuses on client developer simplicity and 114 requires only an HTTP client and JSON parser, which are nearly 115 universally available in modern development environments. The STS 116 protocol defined in this specification is not itself RESTful (an STS 117 doesn't lend itself particularly well to a REST approach) but does 118 utilize communication patterns and data formats that should be 119 familiar to developers accustomed to working with RESTful systems. 121 A new grant type for a token exchange request and the associated 122 specific parameters for such a request to the token endpoint are 123 defined by this specification. A token exchange response is a normal 124 OAuth 2.0 response from the token endpoint with a few additional 125 parameters defined herein to provide information to the client. 127 The entity that makes the request to exchange tokens is considered 128 the client in the context of the token exchange interaction. 129 However, that does not restrict usage of this profile to traditional 130 OAuth clients. An OAuth resource server, for example, might assume 131 the role of the client during token exchange in order to trade an 132 access token, which it received in a protected resource request, for 133 a new token that is appropriate to include in a call to a backend 134 service. The new token might be an access token that is more 135 narrowly scoped for the downstream service or it could be an entirely 136 different kind of token. 138 The scope of this specification is limited to the definition of a 139 basic request and response protocol for an STS-style token exchange 140 utilizing OAuth 2.0. Although a few new JWT claims are defined that 141 enable delegation semantics to be expressed, the specific syntax, 142 semantics and security characteristics of the tokens themselves (both 143 those presented to the AS and those obtained by the client) are 144 explicitly out of scope and no requirements are placed on the trust 145 model in which an implementation might be deployed. Additional 146 profiles may provide more detailed requirements around the specific 147 nature of the parties and trust involved, such as whether signing 148 and/or encryption of tokens is required; however, such details will 149 often be policy decisions made with respect to the specific needs of 150 individual deployments and will be configured or implemented 151 accordingly. 153 The security tokens obtained could be used in a number of contexts, 154 the specifics of which are also beyond the scope of this 155 specification. 157 1.1. Delegation vs. Impersonation Semantics 159 When principal A impersonates principal B, A is given all the rights 160 that B has within some defined rights context and is 161 indistinguishable from B in that context. Thus, when principal A 162 impersonates principal B, then in so far as any entity receiving such 163 a token is concerned, they are actually dealing with B. It is true 164 that some members of the identity system might have awareness that 165 impersonation is going on, but it is not a requirement. For all 166 intents and purposes, when A is impersonating B, A is B. 168 Delegation semantics are different than impersonation semantics, 169 though the two are closely related. With delegation semantics, 170 principal A still has its own identity separate from B and it is 171 explicitly understood that while B may have delegated some of its 172 rights to A, any actions taken are being taken by A representing B. 173 In a sense, A is an agent for B. 175 Delegation and impersonation are not inclusive of all situations. 176 When a principal is acting directly on its own behalf, for example, 177 neither delegation nor impersonation are in play. They are, however, 178 the more common semantics operating for token exchange and, as such, 179 are given more direct treatment in this specification. 181 Delegation semantics are typically expressed in a token by including 182 information about both the primary subject of the token as well as 183 the actor to whom that subject has delegated some of its rights. 184 Such a token is sometimes referred to as a composite token because it 185 is composed of information about multiple subjects. A client can 186 indicate the desire for a composite token by including a 187 "want_composite" parameter in the request with the value "true". 188 Typically, in the request, the "subject_token" represents the 189 identity of the party on behalf of whom the token is being requested 190 while the "actor_token" represents the identity of the party to whom 191 the access rights of the issued token are being delegated. A 192 composite token issued by the authorization server will contain 193 information about both parties. 195 The specifics of representing a composite token and even whether or 196 not such a token will be issued depend on the details of the 197 implementation and the kind of token. The representations of 198 composite tokens that are not JWTs are beyond the scope of this 199 specification. The Section 4.1 request parameter, however, does 200 provide a means for providing information about the desired actor 201 though the representation of a chain of delegation using the JWT 202 "act" claim. 204 1.2. Requirements Notation and Conventions 206 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 207 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 208 "OPTIONAL" in this document are to be interpreted as described in RFC 209 2119 [RFC2119]. 211 1.3. Terminology 213 This specification uses the terms "access token type", "authorization 214 server", "client", "client identifier", "resource server", "token 215 endpoint", "token request", and "token response" defined by OAuth 2.0 216 [RFC6749], and the terms "Claim" and "JWT Claims Set" defined by JSON 217 Web Token (JWT) [JWT]. 219 2. Token Exchange Request and Response 221 2.1. Request 223 A client requests a security token by making a token request to the 224 authorization server's token endpoint using the extension grant type 225 mechanism defined in Section 4.5 of OAuth 2.0 [RFC6749]. 227 Client authentication to the authorization server is done using the 228 normal mechanisms provided by OAuth 2.0. Section 2.3.1 of The OAuth 229 2.0 Authorization Framework [RFC6749] defines password-based 230 authentication of the client, however, client authentication is 231 extensible and other mechanisms are possible. For example, [RFC7523] 232 defines client authentication using JSON Web Tokens (JWTs) [JWT]. 233 The supported methods of client authentication and whether or not to 234 allow unauthenticated or unidentified clients are deployment 235 decisions that are at the discretion of the authorization server. 237 The client makes a token exchange request to the token endpoint with 238 an extension grant type by including the following parameters using 239 the "application/x-www-form-urlencoded" format with a character 240 encoding of UTF-8 in the HTTP request entity-body: 242 grant_type 243 REQUIRED. The value "urn:ietf:params:oauth:grant-type:token- 244 exchange" indicates that a token exchange is being performed. 246 resource 247 OPTIONAL. Indicates the physical location of the target service 248 or resource where the client intends to use the requested security 249 token. This enables the authorization server to apply policy as 250 appropriate for the target, such as determining the type and 251 content of the token to be issued or if and how the token is to be 252 encrypted. In many cases, a client will not have knowledge of the 253 logical organization of the systems with which it interacts and 254 will only know the location of the service where it intends to use 255 the token. The "resource" parameter allows the client to indicate 256 to the authorization server where it intends to use the issued 257 token by providing the location, typically as an https URL, in the 258 token exchange request in the same form that will be used to 259 access that resource. The authorization server will typically 260 have the capability to map from a resource URI value to an 261 appropriate policy. The value of the "resource" parameter MUST be 262 an absolute URI, as specified by Section 4.3 of [RFC3986], which 263 MAY include a query component and MUST NOT include a fragment 264 component. Multiple "resource" parameters may be used to indicate 265 that the issued token is intended to be used at the multiple 266 resources listed. 268 audience 269 OPTIONAL. The logical name of the target service where the client 270 intends to use the requested security token. This serves a 271 purpose similar to the "resource" parameter, but with the client 272 providing a logical name rather than a physical location. 273 Interpretation of the name requires that the value be something 274 that both the client and the authorization server understand. An 275 OAuth client identifier, a SAML entity identifier 276 [OASIS.saml-core-2.0-os], an OpenID Connect Issuer Identifier 277 [OpenID.Core], or a URI are examples of things that might be used 278 as "audience" parameter values. Multiple "audience" parameters 279 may be used to indicate that the issued token is intended to be 280 used at the multiple audiences listed. 282 scope 283 OPTIONAL. A list of space-delimited, case-sensitive strings that 284 allow the client to specify the desired scope of the requested 285 security token in the context of the service or resource where the 286 token will be used. 288 requested_token_type 289 OPTIONAL. An identifier, as described in Section 3, for the type 290 of the requested security token. For example, a JWT can be 291 requested with the identifier "urn:ietf:params:oauth:token- 292 type:jwt". If the requested type is unspecified, the issued token 293 type is at the discretion of the authorization server and may be 294 dictated by knowledge of the requirements of the service or 295 resource indicated by the "resource" or "audience" parameter. 297 subject_token 298 REQUIRED. A security token that represents the identity of the 299 party on behalf of whom the request is being made. Typically the 300 subject of this token will be the subject of the security token 301 issued in response to this request. 303 subject_token_type 304 REQUIRED. An identifier, as described in Section 3, that 305 indicates the type of the security token in the "subject_token" 306 parameter. For example, a value of "urn:ietf:params:oauth:token- 307 type:jwt", would indicate that the token is a JWT and a value of 308 "urn:ietf:params:oauth:token-type:access_token" would indicate 309 that the token is an OAuth access token. 311 actor_token 312 OPTIONAL. A security token that represents the identity of the 313 party that is authorized to use the requested security token and 314 act on behalf of the subject. 316 actor_token_type 317 An identifier, as described in Section 3, that indicates the type 318 of the security token in the "actor_token" parameter. This is 319 REQUIRED when the "actor_token" parameter is present in the 320 request but MUST NOT be included otherwise. 322 want_composite 323 OPTIONAL. When the value of this parameter is "true", it 324 indicates the client's desire for a composite security token to be 325 issued, which contains claims about both the main subject of the 326 token as well as about the party who is authorized to act on 327 behalf of that subject. Note that this parameter only provides a 328 means for the client to indicate its preference. The 329 authorization server is not required to honor the stated 330 preference and the nature of the tokens it issues are ultimately 331 at its discretion. 333 2.2. Response 335 The authorization server responds to a token exchange request with a 336 normal OAuth 2.0 response from the token endpoint, as specified in 337 Section 5 of [RFC6749]. Additional details and explanation are 338 provided in the following subsections. 340 2.2.1. Successful Response 342 If the request is valid and meets all policy and other criteria of 343 the authorization server, a successful token response is constructed 344 by adding the following parameters to the entity-body of the HTTP 345 response using the "application/json" media type, as specified by 346 [RFC7159], and an HTTP 200 status code. The parameters are 347 serialized into a JavaScript Object Notation (JSON) structure by 348 adding each parameter at the top level. Parameter names and string 349 values are included as JSON strings. Numerical values are included 350 as JSON numbers. The order of parameters does not matter and can 351 vary. 353 access_token 354 REQUIRED. The security token issued by the authorization server 355 in response to the token exchange request. The "access_token" 356 parameter from Section 5.1 of [RFC6749] is used here to carry the 357 requested token, which allows this token exchange protocol to use 358 the existing OAuth 2.0 request and response constructs defined for 359 the token endpoint. The identifier "access_token" is used for 360 historical reasons and the issued token need not be an OAuth 361 access token. 363 issued_token_type 364 REQUIRED. An identifier, as described in Section 3, for the 365 representation of the issued security token. For example, a value 366 of "urn:ietf:params:oauth:token-type:access_token" indicates that 367 the issued token is an access token and a value of 368 "urn:ietf:params:oauth:token-type:jwt" indicates that it is a JWT. 370 token_type 371 REQUIRED. A case-insensitive value specifying the method of using 372 of the access token issued, as specified in Section 7.1 of 373 [RFC6749]. It provides the client with information about how to 374 utilize the access token to access protected resources. For 375 example, a value of "Bearer", as specified in [RFC6750], indicates 376 that the security token is a bearer token and the client can 377 simply present it as is without any additional proof of 378 eligibility beyond the contents of the token itself. Note that 379 the meaning of this parameter is different from the meaning of the 380 "issued_token_type" parameter, which declares the representation 381 of the issued security token; the term "token type" is typically 382 used with this meaning, as it is in all "*_token_type" parameters 383 in this specification. If the issued token is not an access token 384 or usable as an access token, then the "token_type" value "N_A" is 385 used to indicate that an OAuth 2.0 "token_type" identifier is not 386 applicable in that context. 388 expires_in 389 RECOMMENDED. The validity lifetime, in seconds, of the token 390 issued by the authorization server. Oftentimes the client will 391 not have the inclination or capability to inspect the content of 392 the token and this parameter provides a consistent and token type 393 agnostic indication of how long the token can be expected to be 394 valid. For example, the value 1800 denotes that the token will 395 expire in thirty minutes from the time the response was generated. 397 scope 398 OPTIONAL, if the scope of the issued security token is identical 399 to the scope requested by the client; otherwise, REQUIRED. 401 refresh_token 402 NOT RECOMMENDED. Refresh tokens will typically not be issued in 403 response to "urn:ietf:params:oauth:grant-type:token-exchange" 404 grant type requests. Profiles or deployments of this 405 specification that do issue refresh tokens SHOULD clearly document 406 the conditions and reasons for doing so. 408 2.2.2. Error Response 410 If either the "subject_token" or "actor_token" are invalid for any 411 reason, or are unacceptable based on policy, the authorization server 412 MUST construct an error response, as specified in Section 5.2 of 413 [RFC6749]. The value of the "error" parameter MUST be the 414 "invalid_request" error code. The authorization server MAY include 415 additional information regarding the reasons for the error using the 416 "error_description" and/or "error_uri" parameters. Other error codes 417 may also be used, as appropriate. 419 2.3. Example Token Exchange 421 The following example demonstrates a hypothetical token exchange in 422 which an OAuth resource server assumes the role of the client during 423 token exchange in order to trade an access token that it received in 424 a request for a token that it will use to call to a backend service 425 (extra line breaks and indentation in the examples are for display 426 purposes only). 428 The resource server receives the following request containing an 429 OAuth access token in the Authorization request header, as specified 430 in Section 2.1 of [RFC6750]. 432 GET /resource HTTP/1.1 433 Host: frontend.example.com 434 Authorization: Bearer accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC 436 Figure 1: Protected Resource Request 438 The resource server assumes the role of the client for the token 439 exchange and the access token from the request above is sent to the 440 authorization server using a request as specified in Section 2.1. 441 The value of the "subject_token" parameter carries the access token 442 and the value of the "subject_token_type" parameter indicates that it 443 is an OAuth 2.0 access token. The resource server, acting as the 444 client, uses its identifier and secret to authenticate to the 445 authorization server using the HTTP Basic authentication scheme. The 446 "resource" parameter indicates the location of the backend service, 447 https://backend.example.com/api, where the issued token will be used. 449 POST /as/token.oauth2 HTTP/1.1 450 Host: as.example.com 451 Authorization: Basic cnMwODpsb25nLXNlY3VyZS1yYW5kb20tc2VjcmV0 452 Content-Type: application/x-www-form-urlencoded 454 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 455 &resource=https%3A%2F%2Fbackend.example.com%2Fapi%20 456 &subject_token=accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC 457 &subject_token_type= 458 urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token 460 Figure 2: Token Exchange Request 462 The authorization server validates the client credentials and the 463 "subject_token" presented in the token exchange request. From the 464 "resource" parameter, the authorization server is able to determine 465 the appropriate policy to apply to the request and issues a token 466 suitable for use at https://backend.example.com. The "access_token" 467 parameter of the response contains the new token, which is itself a 468 bearer OAuth access token that is valid for one minute. The token 469 happens to be a JWT; however, its structure and format are opaque to 470 the client so the "issued_token_type" indicates only that it is an 471 access token. 473 HTTP/1.1 200 OK 474 Content-Type: application/json 475 Cache-Control: no-cache, no-store 477 { 478 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQiOiJo 479 dHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2FzLmV 480 4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1MzMsIm 481 F6cCI6InJzMDgiLCJzdWIiOiJiY0BleGFtcGxlLmNvbSIsInNjcCI6WyJhcGkiX 482 X0.vHJKtJ-zFIN75Tk7qGlmQsWPlvnChb2uSaGwPLvlWl64ts7-vvfwYDaVoXIQ 483 e_HkTVdljIzavVlPT60_b_9pDQ", 484 "issued_token_type": 485 "urn:ietf:params:oauth:token-type:access_token", 486 "token_type":"Bearer", 487 "expires_in":60 488 } 490 Figure 3: Token Exchange Response 492 The resource server can then use the newly acquired access token in 493 making a request to the backend server. 495 GET /api HTTP/1.1 496 Host: backend.example.com 497 Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQ 498 iOiJodHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2 499 FzLmV4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1M 500 zMsImF6cCI6InJzMDgiLCJzdWIiOiJiY0BleGFtcGxlLmNvbSIsInNjcCI6WyJh 501 cGkiXX0.vHJKtJ-zFIN75Tk7qGlmQsWPlvnChb2uSaGwPLvlWl64ts7-vvfwYDa 502 VoXIQe_HkTVdljIzavVlPT60_b_9pDQ 504 Figure 4: Backend Protected Resource Request 506 Additional examples can be found in Appendix A. 508 3. Token Type Identifiers 510 Several parameters in this specification utilize an identifier as the 511 value to describe the type of token in question. Specifically, they 512 are the "requested_token_type", "subject_token_type", 513 "actor_token_type" parameters of the request and the 514 "issued_token_type" member of the response. Token type identifiers 515 are URIs. 517 This specification defines the token type identifiers 518 "urn:ietf:params:oauth:token-type:access_token" and 519 "urn:ietf:params:oauth:token-type:refresh_token" to indicate that the 520 token is an OAuth 2.0 access token or refresh token, respectively. 522 The value "urn:ietf:params:oauth:token-type:jwt" defined in Section 9 523 of [JWT] indicates that the token is a JWT. Other URIs to indicate 524 other token types MAY be used. 526 4. JSON Web Token Claims 528 It is useful to have defined mechanisms to express delegation within 529 a token as well as to express authorization to delegate or 530 impersonate. Although the token exchange protocol described herein 531 can be used with any type of token, this section defines claims to 532 express such semantics specifically for JWTs. Similar definitions 533 for other types of tokens are possible but beyond the scope of this 534 specification. 536 4.1. "act" (Actor) Claim 538 The "act" (actor) claim provides a means within a JWT to express that 539 delegation has occurred and identify the acting party to whom 540 authority has been delegated. The "act" claim value is a JSON object 541 and members in the JSON object are claims that identify the actor. 542 The claims that make up the "act" claim identify and possibly provide 543 additional information about the actor. For example, the combination 544 of the two claims "iss" and "sub" might be necessary to uniquely 545 identify an actor. 547 However, claims within the "act" claim pertain only to the identity 548 of the actor and are not relevant to the validity of the containing 549 JWT in the same manner as the top-level claims. Consequently, claims 550 such as "exp", "nbf", and "aud" are not meaningful when used within 551 an "act" claim, and therefore should not be used. 553 The following example illustrates the "act" (actor) claim within a 554 JWT Claims Set. The claims of the token itself are about 555 user@example.com while the "act" claim indicates that 556 admin@example.com is the current actor. 558 { 559 "aud":"https://consumer.example.com", 560 "iss":"https://issuer.example.com", 561 "exp":1443904177, 562 "nbf":1443904077, 563 "sub":"user@example.com", 564 "act": 565 { 566 "sub":"admin@example.com" 567 } 568 } 570 Figure 5: Actor Claim 572 A chain of delegation can be expressed by nesting one "act" claim 573 within another. The outermost "act" claim represents the current 574 actor while nested "act" claims represent prior actors. The least 575 recent actor is the most deeply nested. 577 The following example illustrates nested "act" (actor) claims within 578 a JWT Claims Set. The claims of the token itself are about 579 user@example.com while the "act" claim indicates that the system 580 consumer.example.com-web-application is the current actor and 581 admin@example.com was a prior actor. Such a token might come about 582 as the result of the web application receiving a token like the one 583 in the previous example and exchanging it for a new token that lists 584 it as the current actor and that can be used at 585 https://backend.example.com. 587 { 588 "aud":"https://backend.example.com", 589 "iss":"https://issuer.example.com", 590 "exp":1443904100, 591 "nbf":1443904000, 592 "sub":"user@example.com", 593 "act": 594 { 595 "sub":"consumer.example.com-web-application", 596 "iss":"https://issuer.example.net", 597 "act": 598 { 599 "sub":"admin@example.com" 600 } 601 } 602 } 604 Figure 6: Nested Actor Claim 606 4.2. "scp" (Scopes) Claim 608 The "scp" claim is an array of strings, each of which represents an 609 OAuth scope granted for the issued security token. Each array entry 610 of the claim value is a scope-token, as defined in Section 3.3 of 611 OAuth 2.0 [RFC6749]. 613 The following example illustrates the "scp" claim within a JWT Claims 614 Set with four scope-tokens. 616 { 617 "aud":"https://consumer.example.com", 618 "iss":"https://issuer.example.com", 619 "exp":1443904177, 620 "nbf":1443904077, 621 "sub":"dgaf4mvfs75Fci_FL3heQA", 622 "scp":["email","address","profile","phone"] 623 } 625 Figure 7: Scopes Claim 627 4.3. "may_act" (May Act For) Claim 629 The "may_act" claim makes a statement that one party is authorized to 630 become the actor and act on behalf of another party. The claim value 631 is a JSON object and members in the JSON object are claims that 632 identify the party that is asserted as being eligible to act for the 633 party identified by the JWT containing the claim. The claims that 634 make up the "may_act" claim identify and possibly provide additional 635 information about the authorized actor. For example, the combination 636 of the two claims "iss" and "sub" are sometimes necessary to uniquely 637 identify an authorized actor, while the "email" claim might be used 638 to provide additional useful information about that party. 640 However, claims within the "may_act" claim pertain only to the 641 identity of that party and are not relevant to the validity of the 642 containing JWT in the same manner as top level claims. Consequently, 643 claims such as "exp", "nbf", and "aud" are not meaningful when used 644 within a "may_act" claim, and therefore should not be used. 646 The following example illustrates the "may_act" claim within a JWT 647 Claims Set. The claims of the token itself are about 648 user@example.com while the "may_act" claim indicates that 649 admin@example.com is authorized to act on behalf of user@example.com. 651 { 652 "aud":"https://consumer.example.com", 653 "iss":"https://issuer.example.com", 654 "exp":1443904177, 655 "nbf":1443904077, 656 "sub":"user@example.com", 657 "may_act": 658 { 659 "sub":"admin@example.com" 660 } 661 } 663 Figure 8: May Act For Claim 665 5. IANA Considerations 667 5.1. OAuth URI Registration 669 This specification registers the following values in the IANA "OAuth 670 URI" registry [IANA.OAuth.Parameters] established by [RFC6755]. 672 5.1.1. Registry Contents 674 o URN: urn:ietf:params:oauth:grant-type:token-exchange 675 o Common Name: Token exchange grant type for OAuth 2.0 676 o Change controller: IESG 677 o Specification Document: Section 2.1 of [[ this specification ]] 679 o URN: urn:ietf:params:oauth:token-type:access_token 680 o Common Name: Token type URI for an OAuth 2.0 access token 681 o Change controller: IESG 682 o Specification Document: Section 3 of [[this specification]] 684 o URN: urn:ietf:params:oauth:token-type:refresh_token 685 o Common Name: Token Type URI for an OAuth 2.0 refresh token 686 o Change controller: IESG 687 o Specification Document: Section 3 of [[this specification]] 689 5.2. OAuth Parameters Registration 691 This specification registers the following values in the IANA "OAuth 692 Parameters" registry [IANA.OAuth.Parameters] established by 693 [RFC6749]. 695 5.2.1. Registry Contents 697 o Parameter name: resource 698 o Parameter usage location: token request 699 o Change controller: IESG 700 o Specification document(s): Section 2.1 of [[ this specification ]] 702 o Parameter name: audience 703 o Parameter usage location: token request 704 o Change controller: IESG 705 o Specification document(s): Section 2.1 of [[ this specification ]] 707 o Parameter name: requested_token_type 708 o Parameter usage location: token request 709 o Change controller: IESG 710 o Specification document(s): Section 2.1 of [[ this specification ]] 712 o Parameter name: subject_token 713 o Parameter usage location: token request 714 o Change controller: IESG 715 o Specification document(s): Section 2.1 of [[ this specification ]] 717 o Parameter name: subject_token_type 718 o Parameter usage location: token request 719 o Change controller: IESG 720 o Specification document(s): Section 2.1 of [[ this specification ]] 722 o Parameter name: actor_token 723 o Parameter usage location: token request 724 o Change controller: IESG 725 o Specification document(s): Section 2.1 of [[ this specification ]] 727 o Parameter name: actor_token_type 728 o Parameter usage location: token request 729 o Change controller: IESG 730 o Specification document(s): Section 2.1 of [[ this specification ]] 732 o Parameter name: want_composite 733 o Parameter usage location: token request 734 o Change controller: IESG 735 o Specification document(s): Section 2.1 of [[ this specification ]] 737 o Parameter name: issued_token_type 738 o Parameter usage location: token response 739 o Change controller: IESG 740 o Specification document(s): Section 2.2.1 of [[ this specification 741 ]] 743 5.3. OAuth Access Token Type Registration 745 This specification registers the following access token type in the 746 IANA "OAuth Access Token Types" registry [IANA.OAuth.Parameters] 747 established by [RFC6749]. 749 5.3.1. Registry Contents 751 o Type name: N_A 752 o Additional Token Endpoint Response Parameters: (none) 753 o HTTP Authentication Scheme(s): (none) 754 o Change controller: IESG 755 o Specification document(s): Section 2.2.1 of [[ this specification 756 ]] 758 5.4. JSON Web Token Claims Registration 760 This specification registers the following Claims in the IANA "JSON 761 Web Token Claims" registry [IANA.JWT.Claims] established by [JWT]. 763 5.4.1. Registry Contents 765 o Claim Name: "act" 766 o Claim Description: Actor 767 o Change Controller: IESG 768 o Specification Document(s): Section 4.1 of [[ this specification ]] 770 o Claim Name: "scp" 771 o Claim Description: Scope Values 772 o Change Controller: IESG 773 o Specification Document(s): Section 4.2 of [[ this specification ]] 775 o Claim Name: "may_act" 776 o Claim Description: May Act For 777 o Change Controller: IESG 778 o Specification Document(s): Section 4.3 of [[ this specification ]] 780 6. Security Considerations 782 All of the normal security issues that are discussed in [JWT], 783 especially in relationship to comparing URIs and dealing with 784 unrecognized values, also apply here. 786 In addition, both delegation and impersonation introduce unique 787 security issues. Any time one principal is delegated the rights of 788 another principal, the potential for abuse is a concern. The use of 789 the "scp" claim is suggested to mitigate potential for such abuse, as 790 it restricts the contexts in which the delegated rights can be 791 exercised. 793 7. References 795 7.1. Normative References 797 [IANA.JWT.Claims] 798 IANA, "JSON Web Token Claims", 799 . 801 [IANA.OAuth.Parameters] 802 IANA, "OAuth Parameters", 803 . 805 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 806 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 807 . 809 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 810 Requirement Levels", BCP 14, RFC 2119, 811 DOI 10.17487/RFC2119, March 1997, 812 . 814 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 815 Resource Identifier (URI): Generic Syntax", STD 66, 816 RFC 3986, DOI 10.17487/RFC3986, January 2005, 817 . 819 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 820 RFC 6749, DOI 10.17487/RFC6749, October 2012, 821 . 823 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 824 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 825 2014, . 827 7.2. Informative References 829 [OASIS.saml-core-2.0-os] 830 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 831 "Assertions and Protocol for the OASIS Security Assertion 832 Markup Language (SAML) V2.0", OASIS Standard saml-core- 833 2.0-os, March 2005. 835 [OpenID.Core] 836 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 837 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 838 . 840 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 841 Framework: Bearer Token Usage", RFC 6750, 842 DOI 10.17487/RFC6750, October 2012, 843 . 845 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 846 for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, 847 . 849 [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 850 "Assertion Framework for OAuth 2.0 Client Authentication 851 and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, 852 May 2015, . 854 [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 855 (JWT) Profile for OAuth 2.0 Client Authentication and 856 Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 857 2015, . 859 [WS-Trust] 860 Nadalin, A., Goodner, M., Gudgin, M., Barbir, A., and H. 861 Granqvist, "WS-Trust 1.4", February 2012, 862 . 865 Appendix A. Additional Token Exchange Examples 867 Two example token exchanges are provided in the following sections 868 illustrating impersonation and delegation, respectively (with extra 869 line breaks and indentation for display purposes only). 871 A.1. Impersonation Token Exchange Example 873 A.1.1. Token Exchange Request 875 In the following token exchange request, an anonymous client is 876 requesting a token with impersonation semantics. The client tells 877 the authorization server that it needs a token for use at the target 878 service with the logical name "urn:example:cooperation-context". 880 POST /as/token.oauth2 HTTP/1.1 881 Host: as.example.com 882 Content-Type: application/x-www-form-urlencoded 884 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 885 &audience=urn%3Aexample%3Acooperation-context 886 &subject_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwc 887 zovL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9jbGllbnQuZXhhbXBsZS5 888 uZXQiLCJleHAiOjE0NDE5MTA2MDAsIm5iZiI6MTQ0MTkwOTAwMCwic3ViIjoiYmNAZ 889 XhhbXBsZS5uZXQiLCJzY3AiOlsib3JkZXJzIiwicHJvZmlsZSIsImhpc3RvcnkiXX0 890 .F1EZzN9j3LwyrLkDD8pjR7fzHqdYl1ly-jEILfmgKY_0hNuT3_fmUChu9oQdBNjHj 891 wu58iLSmagZl-5_9-ilzw 892 &subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 894 Figure 9: Token Exchange Request 896 A.1.2. Subject Token Claims 898 The "subject_token" in the prior request is a JWT and the decoded JWT 899 Claims Set is shown here. The JWT is intended for consumption by the 900 authorization server within a specific time window. The subject of 901 the JWT ("bc@example.net") is the party on behalf of whom the new 902 token is being requested. 904 { 905 "aud":"https://as.example.com", 906 "iss":"https://client.example.net", 907 "exp":1441910600, 908 "nbf":1441909000, 909 "sub":"bc@example.net", 910 "scp":["orders","profile","history"] 911 } 913 Figure 10: Subject Token Claims 915 A.1.3. Token Exchange Response 917 The "access_token" parameter of the token exchange response shown 918 below contains the new token that the client requested. The other 919 parameters of the response indicate that the token is a JWT that 920 expires in an hour and that the access token type is not applicable 921 since the issued token is not an access token. 923 HTTP/1.1 200 OK 924 Content-Type: application/json 925 Cache-Control: no-cache, no-store 927 { 928 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm4 929 6ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5l 930 eGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic3ViIjoiYmNAZXhhbXBsZS5uZ 931 XQiLCJzY3AiOlsib3JkZXJzIiwiaGlzdG9yeSIsInByb2ZpbGUiXX0.YQHuLmI1YD 932 TugbfEvgGY2gaGBmMyj9BepZSECCBE9j9ogqZv2qx6VQQPrbT1k7vBYGLNMOkkpmm 933 JkxZDS0YV7g", 934 "issued_token_type":"urn:ietf:params:oauth:token-type:jwt", 935 "token_type":"N_A", 936 "expires_in":3600 937 } 939 Figure 11: Token Exchange Response 941 A.1.4. Issued Token Claims 943 The decoded JWT Claims Set of the issued token is shown below. The 944 new JWT is issued by the authorization server and intended for 945 consumption by a system entity known by the logical name 946 "urn:example:cooperation-context" any time before its expiration. 947 The subject ("sub") of the JWT is the same as the subject the token 948 used to make the request, which effectively enables the client to 949 impersonate that subject at the system entity known by the logical 950 name of "urn:example:cooperation-context" by using the token. 952 { 953 "aud":"urn:example:cooperation-context", 954 "iss":"https://as.example.com", 955 "exp":1441913610, 956 "sub":"bc@example.net", 957 "scp":["orders","history","profile"] 958 } 960 Figure 12: Issued Token Claims 962 A.2. Delegation Token Exchange Example 964 A.2.1. Token Exchange Request 966 In the following token exchange request, an anonymous client is 967 requesting a token with delegation semantics, which is indicated by 968 the inclusion of the "want_composite" parameter. The client tells 969 the authorization server that it needs a token for use at the target 970 service with the logical name "urn:example:cooperation-context". 972 POST /as/token.oauth2 HTTP/1.1 973 Host: as.example.com 974 Content-Type: application/x-www-form-urlencoded 976 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 977 &audience=urn%3Aexample%3Acooperation-context 978 &want_composite=true 979 &subject_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwc 980 zovL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9jbGllbnQuZXhhbXBsZS5 981 uZXQiLCJleHAiOjE0NDE5MTAwNjAsInNjcCI6WyJzdGF0dXMiLCJmZWVkIl0sInN1Y 982 iI6InVzZXJAZXhhbXBsZS5uZXQiLCJtYXlfYWN0Ijp7InN1YiI6ImFkbWluQGV4YW1 983 wbGUubmV0In19.cklRpQMYzs9AYoJ3DMht1OnMhAF_0YeQgV35rp7J7ErkvnPm1gr_ 984 OeQD1wTbnbburbyC7nwKdK5Jrn31aQPxUg 985 &subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 986 &actor_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwczo 987 vL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9jbGllbnQuZXhhbXBsZS5uZ 988 XQiLCJleHAiOjE0NDE5MTAwNjAsInN1YiI6ImFkbWluQGV4YW1wbGUubmV0In0.X15 989 8zUsO55Fo0humOUCUCy582BQRAWbMsIKbxT1mJRrQrk2cpU6r6CWeI4ukQoQRe6RTr 990 Esk4wX2lMf8sELxaA 991 &actor_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 993 Figure 13: Token Exchange Request 995 A.2.2. Subject Token Claims 997 The "subject_token" in the prior request is a JWT and the decoded JWT 998 Claims Set is shown here. The JWT is intended for consumption by the 999 authorization server before a specific expiration time. The subject 1000 of the JWT ("user@example.net") is the party on behalf of whom the 1001 new token is being requested. 1003 { 1004 "aud":"https://as.example.com", 1005 "iss":"https://client.example.net", 1006 "exp":1441910060, 1007 "scp":["status","feed"], 1008 "sub":"user@example.net", 1009 "may_act": 1010 { 1011 "sub":"admin@example.net" 1012 } 1013 } 1015 Figure 14: Subject Token Claims 1017 A.2.3. Actor Token Claims 1019 The "actor_token" in the prior request is a JWT and the decoded JWT 1020 Claims Set is shown here. This JWT is also intended for consumption 1021 by the authorization server before a specific expiration time. The 1022 subject of the JWT ("admin@example.net") is the actor that will wield 1023 the security token being requested. 1025 { 1026 "aud":"https://as.example.com", 1027 "iss":"https://client.example.net", 1028 "exp":1441910060, 1029 "sub":"admin@example.net" 1030 } 1032 Figure 15: Actor Token Claims 1034 A.2.4. Token Exchange Response 1036 The "access_token" parameter of the token exchange response shown 1037 below contains the new token that the client requested. The other 1038 parameters of the response indicate that the token is a JWT that 1039 expires in an hour and that the access token type is not applicable 1040 since the issued token is not an access token. 1042 HTTP/1.1 200 OK 1043 Content-Type: application/json 1044 Cache-Control: no-cache, no-store 1046 { 1047 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm4 1048 6ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5l 1049 eGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic2NwIjpbInN0YXR1cyIsImZlZ 1050 WQiXSwic3ViIjoidXNlckBleGFtcGxlLm5ldCIsImFjdCI6eyJzdWIiOiJhZG1pbk 1051 BleGFtcGxlLm5ldCJ9fQ._qjM7Ij_HcrC78omT4jiZTFJOuzsAj1wPo31ymQS-Suq 1052 r64S1jCp6pfQR-in_OOAosAGamEg4jyPsht6kMAiYA", 1053 "issued_token_type":"urn:ietf:params:oauth:token-type:jwt", 1054 "token_type":"N_A", 1055 "expires_in":3600 1056 } 1058 Figure 16: Token Exchange Response 1060 A.2.5. Issued Token Claims 1062 The decoded JWT Claims Set of the issued token is shown below. The 1063 new JWT is issued by the authorization server and intended for 1064 consumption by a system entity known by the logical name 1065 "urn:example:cooperation-context" any time before its expiration. 1066 The subject ("sub") of the JWT is the same as the subject of the 1067 "subject_token" used to make the request. The actor ("act") of the 1068 JWT is the same as the subject of the "actor_token" used to make the 1069 request. This indicates delegation and identifies 1070 "admin@example.net" as the current actor to whom authority has been 1071 delegated to act on behalf of "user@example.net". 1073 { 1074 "aud":"urn:example:cooperation-context", 1075 "iss":"https://as.example.com", 1076 "exp":1441913610, 1077 "scp":["status","feed"], 1078 "sub":"user@example.net", 1079 "act": 1080 { 1081 "sub":"admin@example.net" 1082 } 1083 } 1085 Figure 17: Issued Token Claims 1087 Appendix B. Acknowledgements 1089 This specification was developed within the OAuth Working Group, 1090 which includes dozens of active and dedicated participants. It was 1091 produced under the chairmanship of Hannes Tschofenig and Derek Atkins 1092 with Kathleen Moriarty and Stephen Farrell serving as Security Area 1093 Directors. The following individuals contributed ideas, feedback, 1094 and wording to this specification: 1096 Caleb Baker, William Denniss, Phil Hunt, Jason Keglovitz, Matt 1097 Miller, Matthew Perry, Justin Richer, Scott Tomilson, and Hannes 1098 Tschofenig. 1100 Appendix C. Open Issues 1102 The following decisions need to be made and updates to this spec 1103 performed: 1105 o Should there be a way to use short names for some common token 1106 type identifiers? URIs are necessary in the general case for 1107 extensibility and vendor/deployment specific types. But short 1108 names like "access_token" and "jwt" are aesthetically appealing 1109 and slightly more efficient in terms of bytes on the wire and url- 1110 encoding. There seemed to be rough consensus in Prague ('No 1111 objection to use the proposed mechanism for a default prefix' from 1112 https://www.ietf.org/proceedings/93/minutes/minutes-93-oauth) for 1113 supporting a shorthand for commonly used types - i.e. when the 1114 value does not contain a ":" character, the value would be treated 1115 as though "urn:ietf:params:oauth:token-type:" were prepended to 1116 it. So, for example, the value "jwt" for "requested_token_type" 1117 would be semantically equivalent to "urn:ietf:params:oauth:token- 1118 type:jwt" and the value "access_token" would be equivalent to 1119 "urn:ietf:params:oauth:token-type:access_token". However, it was 1120 a fairly brief discussion in Prague and it has since been 1121 suggested that making participants handle both syntaxes will 1122 unnecessarily complicate the supporting code. 1124 o Provide a way to include supplementary claims or information in 1125 the request that would/could potentially be included in the issued 1126 token. There are real use cases for this but we would need to 1127 work through what it would look like. 1129 o Understand and define exactly how the presentation of PoP/non- 1130 bearer tokens works. Of course, the specifications defining these 1131 kinds of tokens need to do so first before there is much we can do 1132 in this specification in this regard. 1134 o It seems there may be cases in which it would be desirable for the 1135 authenticated client to be somehow represented in the issued 1136 token, sometimes in addition to the actor, which can already be 1137 represented using the "act" claim. Perhaps with a "client_id" 1138 claim? 1140 Appendix D. Document History 1142 [[ to be removed by the RFC Editor before publication as an RFC ]] 1144 -03 1146 o Updated the document editors (adding Campbell, Bradley, and 1147 Mortimore). 1148 o Added to the title. 1149 o Added to the abstract and introduction. 1150 o Updated the format of the request to use application/x-www-form- 1151 urlencoded request parameters and the response to use the existing 1152 token endpoint JSON parameters defined in OAuth 2.0. 1153 o Changed the grant type identifier to urn:ietf:params:oauth:grant- 1154 type:token-exchange. 1155 o Added RFC 6755 registration requests for 1156 urn:ietf:params:oauth:token-type:refresh_token, 1157 urn:ietf:params:oauth:token-type:access_token, and 1158 urn:ietf:params:oauth:grant-type:token-exchange. 1159 o Added RFC 6749 registration requests for request/response 1160 parameters. 1162 o Removed the Implementation Considerations and the requirement to 1163 support JWTs. 1164 o Clarified many aspects of the text. 1165 o Changed "on_behalf_of" to "subject_token", 1166 "on_behalf_of_token_type" to "subject_token_type", "act_as" to 1167 "actor_token", and "act_as_token_type" to "actor_token_type". 1168 o Added an "audience" request parameter used to indicate the logical 1169 names of the target services at which the client intends to use 1170 the requested security token. 1171 o Added a "want_composite" request parameter used to indicate the 1172 desire for a composite token rather than trying to infer it from 1173 the presence/absence of token(s) in the request. 1174 o Added a "resource" request parameter used to indicate the URLs of 1175 resources at which the client intends to use the requested 1176 security token. 1177 o Specified that multiple "audience" and "resource" request 1178 parameter values may be used. 1179 o Defined the JWT claim "act" (actor) to express the current actor 1180 or delegation principal. 1181 o Defined the JWT claim "may_act" to express that one party is 1182 authorized to act on behalf of another party. 1183 o Defined the JWT claim "scp" (scopes) to express OAuth 2.0 scope- 1184 token values. 1185 o Added the "N_A" (not applicable) OAuth Access Token Type 1186 definition for use in contexts in which the token exchange syntax 1187 requires a "token_type" value, but in which the token being issued 1188 is not an access token. 1189 o Added examples. 1191 -02 1193 o Enabled use of Security Token types other than JWTs for "act_as" 1194 and "on_behalf_of" request values. 1195 o Referenced the JWT and OAuth Assertions RFCs. 1197 -01 1199 o Updated references. 1201 -00 1203 o Created initial working group draft from draft-jones-oauth-token- 1204 exchange-01. 1206 Authors' Addresses 1208 Michael B. Jones 1209 Microsoft 1211 Email: mbj@microsoft.com 1212 URI: http://self-issued.info/ 1214 Anthony Nadalin 1215 Microsoft 1217 Email: tonynad@microsoft.com 1219 Brian Campbell 1220 Ping Identity 1222 Email: brian.d.campbell@gmail.com 1224 John Bradley 1225 Ping Identity 1227 Email: ve7jtb@ve7jtb.com 1229 Chuck Mortimore 1230 Salesforce 1232 Email: cmortimore@salesforce.com