idnits 2.17.1 draft-ietf-oauth-token-exchange-04.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 (March 4, 2016) is 2974 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: September 5, 2016 B. Campbell 6 J. Bradley 7 Ping Identity 8 C. Mortimore 9 Salesforce 10 March 4, 2016 12 OAuth 2.0 Token Exchange: An STS for the REST of Us 13 draft-ietf-oauth-token-exchange-04 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 September 5, 2016. 39 Copyright Notice 41 Copyright (c) 2016 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 . . . . . . . . . . . . . . . . . . . . . . . . 3 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.2.1. Successful Response . . . . . . . . . . . . . . . . . 8 64 2.2.2. Error Response . . . . . . . . . . . . . . . . . . . 10 65 2.3. Example Token Exchange . . . . . . . . . . . . . . . . . 10 66 3. Token Type Identifiers . . . . . . . . . . . . . . . . . . . 12 67 4. JSON Web Token Claims . . . . . . . . . . . . . . . . . . . . 12 68 4.1. "act" (Actor) Claim . . . . . . . . . . . . . . . . . . . 12 69 4.2. "scp" (Scopes) Claim . . . . . . . . . . . . . . . . . . 14 70 4.3. "may_act" (May Act For) Claim . . . . . . . . . . . . . . 15 71 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 72 5.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 16 73 5.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 16 74 5.2. OAuth Parameters Registration . . . . . . . . . . . . . . 17 75 5.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 17 76 5.3. OAuth Access Token Type Registration . . . . . . . . . . 18 77 5.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 18 78 5.4. JSON Web Token Claims Registration . . . . . . . . . . . 18 79 5.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 18 80 6. Security Considerations . . . . . . . . . . . . . . . . . . . 18 81 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 82 7.1. Normative References . . . . . . . . . . . . . . . . . . 19 83 7.2. Informative References . . . . . . . . . . . . . . . . . 19 84 Appendix A. Additional Token Exchange Examples . . . . . . . . . 20 85 A.1. Impersonation Token Exchange Example . . . . . . . . . . 20 86 A.1.1. Token Exchange Request . . . . . . . . . . . . . . . 20 87 A.1.2. Subject Token Claims . . . . . . . . . . . . . . . . 21 88 A.1.3. Token Exchange Response . . . . . . . . . . . . . . . 21 89 A.1.4. Issued Token Claims . . . . . . . . . . . . . . . . . 22 90 A.2. Delegation Token Exchange Example . . . . . . . . . . . . 22 91 A.2.1. Token Exchange Request . . . . . . . . . . . . . . . 22 92 A.2.2. Subject Token Claims . . . . . . . . . . . . . . . . 23 93 A.2.3. Actor Token Claims . . . . . . . . . . . . . . . . . 24 94 A.2.4. Token Exchange Response . . . . . . . . . . . . . . . 24 95 A.2.5. Issued Token Claims . . . . . . . . . . . . . . . . . 24 96 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 25 97 Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . 25 98 Appendix D. Document History . . . . . . . . . . . . . . . . . . 26 99 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28 101 1. Introduction 103 A security token is a set of information that facilitates the sharing 104 of identity and security information in heterogeneous environments or 105 across security domains. Examples of security tokens include JSON 106 Web Tokens (JWTs) [JWT] and SAML Assertions [OASIS.saml-core-2.0-os]. 107 Security tokens are typically signed to achieve integrity and 108 sometimes also encrypted to achieve confidentiality. Security tokens 109 are also sometimes described as Assertions, such as in [RFC7521]. 111 A Security Token Service (STS) is a service capable of validating and 112 issuing security tokens, which enables clients to obtain appropriate 113 access credentials for resources in heterogeneous environments or 114 across security domains. Web Service clients have used WS-Trust 115 [WS-Trust] as the protocol to interact with an STS for token 116 exchange, however WS-Trust is a fairly heavyweight protocol, which 117 uses XML, SOAP, etc. Whereas, the trend in modern Web development 118 has been towards lightweight services utilizing RESTful patterns and 119 JSON. The OAuth 2.0 Authorization Framework [RFC6749] and OAuth 2.0 120 Bearer Tokens [RFC6750] have emerged as popular standards for 121 authorizing and securing access to HTTP and RESTful resources but do 122 not provide everything necessary to facilitate token exchange 123 interactions. 125 This specification defines a lightweight protocol extending OAuth 2.0 126 that enables clients to request and obtain security tokens from 127 authorization servers acting in the role of an STS. Similar to OAuth 128 2.0, this specification focuses on client developer simplicity and 129 requires only an HTTP client and JSON parser, which are nearly 130 universally available in modern development environments. The STS 131 protocol defined in this specification is not itself RESTful (an STS 132 doesn't lend itself particularly well to a REST approach) but does 133 utilize communication patterns and data formats that should be 134 familiar to developers accustomed to working with RESTful systems. 136 A new grant type for a token exchange request and the associated 137 specific parameters for such a request to the token endpoint are 138 defined by this specification. A token exchange response is a normal 139 OAuth 2.0 response from the token endpoint with a few additional 140 parameters defined herein to provide information to the client. 142 The entity that makes the request to exchange tokens is considered 143 the client in the context of the token exchange interaction. 144 However, that does not restrict usage of this profile to traditional 145 OAuth clients. An OAuth resource server, for example, might assume 146 the role of the client during token exchange in order to trade an 147 access token, which it received in a protected resource request, for 148 a new token that is appropriate to include in a call to a backend 149 service. The new token might be an access token that is more 150 narrowly scoped for the downstream service or it could be an entirely 151 different kind of token. 153 The scope of this specification is limited to the definition of a 154 basic request and response protocol for an STS-style token exchange 155 utilizing OAuth 2.0. Although a few new JWT claims are defined that 156 enable delegation semantics to be expressed, the specific syntax, 157 semantics and security characteristics of the tokens themselves (both 158 those presented to the AS and those obtained by the client) are 159 explicitly out of scope and no requirements are placed on the trust 160 model in which an implementation might be deployed. Additional 161 profiles may provide more detailed requirements around the specific 162 nature of the parties and trust involved, such as whether signing 163 and/or encryption of tokens is required; however, such details will 164 often be policy decisions made with respect to the specific needs of 165 individual deployments and will be configured or implemented 166 accordingly. 168 The security tokens obtained could be used in a number of contexts, 169 the specifics of which are also beyond the scope of this 170 specification. 172 1.1. Delegation vs. Impersonation Semantics 174 When principal A impersonates principal B, A is given all the rights 175 that B has within some defined rights context and is 176 indistinguishable from B in that context. Thus, when principal A 177 impersonates principal B, then in so far as any entity receiving such 178 a token is concerned, they are actually dealing with B. It is true 179 that some members of the identity system might have awareness that 180 impersonation is going on, but it is not a requirement. For all 181 intents and purposes, when A is impersonating B, A is B. 183 Delegation semantics are different than impersonation semantics, 184 though the two are closely related. With delegation semantics, 185 principal A still has its own identity separate from B and it is 186 explicitly understood that while B may have delegated some of its 187 rights to A, any actions taken are being taken by A representing B. 188 In a sense, A is an agent for B. 190 Delegation and impersonation are not inclusive of all situations. 191 When a principal is acting directly on its own behalf, for example, 192 neither delegation nor impersonation are in play. They are, however, 193 the more common semantics operating for token exchange and, as such, 194 are given more direct treatment in this specification. 196 Delegation semantics are typically expressed in a token by including 197 information about both the primary subject of the token as well as 198 the actor to whom that subject has delegated some of its rights. 199 Such a token is sometimes referred to as a composite token because it 200 is composed of information about multiple subjects. A client can 201 indicate the desire for a composite token by including a 202 "want_composite" parameter in the request with the value "true". 203 Typically, in the request, the "subject_token" represents the 204 identity of the party on behalf of whom the token is being requested 205 while the "actor_token" represents the identity of the party to whom 206 the access rights of the issued token are being delegated. A 207 composite token issued by the authorization server will contain 208 information about both parties. 210 The specifics of representing a composite token and even whether or 211 not such a token will be issued depend on the details of the 212 implementation and the kind of token. The representations of 213 composite tokens that are not JWTs are beyond the scope of this 214 specification. The Section 4.1 request parameter, however, does 215 provide a means for providing information about the desired actor 216 though the representation of a chain of delegation using the JWT 217 "act" claim. 219 1.2. Requirements Notation and Conventions 221 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 222 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 223 "OPTIONAL" in this document are to be interpreted as described in RFC 224 2119 [RFC2119]. 226 1.3. Terminology 228 This specification uses the terms "access token type", "authorization 229 server", "client", "client identifier", "resource server", "token 230 endpoint", "token request", and "token response" defined by OAuth 2.0 231 [RFC6749], and the terms "Claim" and "JWT Claims Set" defined by JSON 232 Web Token (JWT) [JWT]. 234 2. Token Exchange Request and Response 236 2.1. Request 238 A client requests a security token by making a token request to the 239 authorization server's token endpoint using the extension grant type 240 mechanism defined in Section 4.5 of OAuth 2.0 [RFC6749]. 242 Client authentication to the authorization server is done using the 243 normal mechanisms provided by OAuth 2.0. Section 2.3.1 of The OAuth 244 2.0 Authorization Framework [RFC6749] defines password-based 245 authentication of the client, however, client authentication is 246 extensible and other mechanisms are possible. For example, [RFC7523] 247 defines client authentication using JSON Web Tokens (JWTs) [JWT]. 248 The supported methods of client authentication and whether or not to 249 allow unauthenticated or unidentified clients are deployment 250 decisions that are at the discretion of the authorization server. 252 The client makes a token exchange request to the token endpoint with 253 an extension grant type by including the following parameters using 254 the "application/x-www-form-urlencoded" format with a character 255 encoding of UTF-8 in the HTTP request entity-body: 257 grant_type 258 REQUIRED. The value "urn:ietf:params:oauth:grant-type:token- 259 exchange" indicates that a token exchange is being performed. 261 resource 262 OPTIONAL. Indicates the physical location of the target service 263 or resource where the client intends to use the requested security 264 token. This enables the authorization server to apply policy as 265 appropriate for the target, such as determining the type and 266 content of the token to be issued or if and how the token is to be 267 encrypted. In many cases, a client will not have knowledge of the 268 logical organization of the systems with which it interacts and 269 will only know the location of the service where it intends to use 270 the token. The "resource" parameter allows the client to indicate 271 to the authorization server where it intends to use the issued 272 token by providing the location, typically as an https URL, in the 273 token exchange request in the same form that will be used to 274 access that resource. The authorization server will typically 275 have the capability to map from a resource URI value to an 276 appropriate policy. The value of the "resource" parameter MUST be 277 an absolute URI, as specified by Section 4.3 of [RFC3986], which 278 MAY include a query component and MUST NOT include a fragment 279 component. Multiple "resource" parameters may be used to indicate 280 that the issued token is intended to be used at the multiple 281 resources listed. 283 audience 284 OPTIONAL. The logical name of the target service where the client 285 intends to use the requested security token. This serves a 286 purpose similar to the "resource" parameter, but with the client 287 providing a logical name rather than a physical location. 288 Interpretation of the name requires that the value be something 289 that both the client and the authorization server understand. An 290 OAuth client identifier, a SAML entity identifier 291 [OASIS.saml-core-2.0-os], an OpenID Connect Issuer Identifier 292 [OpenID.Core], or a URI are examples of things that might be used 293 as "audience" parameter values. Multiple "audience" parameters 294 may be used to indicate that the issued token is intended to be 295 used at the multiple audiences listed. The "audience" and 296 "resource" parameters may be used together to indicate multiple 297 target services with a mix of logical names and physical 298 locations. 300 scope 301 OPTIONAL. A list of space-delimited, case-sensitive strings that 302 allow the client to specify the desired scope of the requested 303 security token in the context of the service or resource where the 304 token will be used. 306 requested_token_type 307 OPTIONAL. An identifier, as described in Section 3, for the type 308 of the requested security token. For example, a JWT can be 309 requested with the identifier "urn:ietf:params:oauth:token- 310 type:jwt". If the requested type is unspecified, the issued token 311 type is at the discretion of the authorization server and may be 312 dictated by knowledge of the requirements of the service or 313 resource indicated by the "resource" or "audience" parameter. 315 subject_token 316 REQUIRED. A security token that represents the identity of the 317 party on behalf of whom the request is being made. Typically, the 318 subject of this token will be the subject of the security token 319 issued in response to this request. 321 subject_token_type 322 REQUIRED. An identifier, as described in Section 3, that 323 indicates the type of the security token in the "subject_token" 324 parameter. For example, a value of "urn:ietf:params:oauth:token- 325 type:jwt", would indicate that the token is a JWT and a value of 326 "urn:ietf:params:oauth:token-type:access_token" would indicate 327 that the token is an OAuth access token. 329 actor_token 330 OPTIONAL. A security token that represents the identity of the 331 party that is authorized to use the requested security token and 332 act on behalf of the subject. 334 actor_token_type 335 An identifier, as described in Section 3, that indicates the type 336 of the security token in the "actor_token" parameter. This is 337 REQUIRED when the "actor_token" parameter is present in the 338 request but MUST NOT be included otherwise. 340 want_composite 341 OPTIONAL. When the value of this parameter is "true", it 342 indicates the client's desire for a composite security token to be 343 issued, which contains claims about both the main subject of the 344 token as well as about the party who is authorized to act on 345 behalf of that subject. Note that this parameter only provides a 346 means for the client to indicate its preference. The 347 authorization server is not required to honor the stated 348 preference and the nature of the tokens it issues are ultimately 349 at its discretion. 351 In the absence of one-time-use or other semantics specific to the 352 token type, the act of performing a token exchange has no impact on 353 the validity of the subject token or actor token. 355 2.2. Response 357 The authorization server responds to a token exchange request with a 358 normal OAuth 2.0 response from the token endpoint, as specified in 359 Section 5 of [RFC6749]. Additional details and explanation are 360 provided in the following subsections. 362 2.2.1. Successful Response 364 If the request is valid and meets all policy and other criteria of 365 the authorization server, a successful token response is constructed 366 by adding the following parameters to the entity-body of the HTTP 367 response using the "application/json" media type, as specified by 368 [RFC7159], and an HTTP 200 status code. The parameters are 369 serialized into a JavaScript Object Notation (JSON) structure by 370 adding each parameter at the top level. Parameter names and string 371 values are included as JSON strings. Numerical values are included 372 as JSON numbers. The order of parameters does not matter and can 373 vary. 375 access_token 376 REQUIRED. The security token issued by the authorization server 377 in response to the token exchange request. The "access_token" 378 parameter from Section 5.1 of [RFC6749] is used here to carry the 379 requested token, which allows this token exchange protocol to use 380 the existing OAuth 2.0 request and response constructs defined for 381 the token endpoint. The identifier "access_token" is used for 382 historical reasons and the issued token need not be an OAuth 383 access token. 385 issued_token_type 386 REQUIRED. An identifier, as described in Section 3, for the 387 representation of the issued security token. For example, a value 388 of "urn:ietf:params:oauth:token-type:access_token" indicates that 389 the issued token is an access token and a value of 390 "urn:ietf:params:oauth:token-type:jwt" indicates that it is a JWT. 392 token_type 393 REQUIRED. A case-insensitive value specifying the method of using 394 of the access token issued, as specified in Section 7.1 of 395 [RFC6749]. It provides the client with information about how to 396 utilize the access token to access protected resources. For 397 example, a value of "Bearer", as specified in [RFC6750], indicates 398 that the security token is a bearer token and the client can 399 simply present it as is without any additional proof of 400 eligibility beyond the contents of the token itself. Note that 401 the meaning of this parameter is different from the meaning of the 402 "issued_token_type" parameter, which declares the representation 403 of the issued security token; the term "token type" is typically 404 used with this meaning, as it is in all "*_token_type" parameters 405 in this specification. If the issued token is not an access token 406 or usable as an access token, then the "token_type" value "N_A" is 407 used to indicate that an OAuth 2.0 "token_type" identifier is not 408 applicable in that context. 410 expires_in 411 RECOMMENDED. The validity lifetime, in seconds, of the token 412 issued by the authorization server. Oftentimes the client will 413 not have the inclination or capability to inspect the content of 414 the token and this parameter provides a consistent and token type 415 agnostic indication of how long the token can be expected to be 416 valid. For example, the value 1800 denotes that the token will 417 expire in thirty minutes from the time the response was generated. 419 scope 420 OPTIONAL, if the scope of the issued security token is identical 421 to the scope requested by the client; otherwise, REQUIRED. 423 refresh_token 424 NOT RECOMMENDED. Refresh tokens will typically not be issued in 425 response to "urn:ietf:params:oauth:grant-type:token-exchange" 426 grant type requests. Typically, a token exchange is done to 427 exchange one temporary credential (the subject_token sent in the 428 request) for a different temporary credential (the issued token) 429 that can be used in some other context. Issuing a refresh token 430 would add an additional credential that likely has a much longer 431 lifetime, which undermines the typical model of swapping temporary 432 credentials. Profiles or deployments of this specification that 433 do issue refresh tokens SHOULD clearly document the conditions and 434 reasons for doing so. 436 2.2.2. Error Response 438 If either the "subject_token" or "actor_token" are invalid for any 439 reason, or are unacceptable based on policy, the authorization server 440 MUST construct an error response, as specified in Section 5.2 of 441 [RFC6749]. The value of the "error" parameter MUST be the 442 "invalid_request" error code. The authorization server MAY include 443 additional information regarding the reasons for the error using the 444 "error_description" and/or "error_uri" parameters. Other error codes 445 may also be used, as appropriate. 447 2.3. Example Token Exchange 449 The following example demonstrates a hypothetical token exchange in 450 which an OAuth resource server assumes the role of the client during 451 token exchange in order to trade an access token that it received in 452 a request for a token that it will use to call to a backend service 453 (extra line breaks and indentation in the examples are for display 454 purposes only). 456 The resource server receives the following request containing an 457 OAuth access token in the Authorization request header, as specified 458 in Section 2.1 of [RFC6750]. 460 GET /resource HTTP/1.1 461 Host: frontend.example.com 462 Authorization: Bearer accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC 464 Figure 1: Protected Resource Request 466 The resource server assumes the role of the client for the token 467 exchange and the access token from the request above is sent to the 468 authorization server using a request as specified in Section 2.1. 469 The value of the "subject_token" parameter carries the access token 470 and the value of the "subject_token_type" parameter indicates that it 471 is an OAuth 2.0 access token. The resource server, acting as the 472 client, uses its identifier and secret to authenticate to the 473 authorization server using the HTTP Basic authentication scheme. The 474 "resource" parameter indicates the location of the backend service, 475 https://backend.example.com/api, where the issued token will be used. 477 POST /as/token.oauth2 HTTP/1.1 478 Host: as.example.com 479 Authorization: Basic cnMwODpsb25nLXNlY3VyZS1yYW5kb20tc2VjcmV0 480 Content-Type: application/x-www-form-urlencoded 482 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 483 &resource=https%3A%2F%2Fbackend.example.com%2Fapi%20 484 &subject_token=accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC 485 &subject_token_type= 486 urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token 488 Figure 2: Token Exchange Request 490 The authorization server validates the client credentials and the 491 "subject_token" presented in the token exchange request. From the 492 "resource" parameter, the authorization server is able to determine 493 the appropriate policy to apply to the request and issues a token 494 suitable for use at https://backend.example.com. The "access_token" 495 parameter of the response contains the new token, which is itself a 496 bearer OAuth access token that is valid for one minute. The token 497 happens to be a JWT; however, its structure and format are opaque to 498 the client so the "issued_token_type" indicates only that it is an 499 access token. 501 HTTP/1.1 200 OK 502 Content-Type: application/json 503 Cache-Control: no-cache, no-store 505 { 506 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQiOiJo 507 dHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2FzLmV 508 4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1MzMsIm 509 F6cCI6InJzMDgiLCJzdWIiOiJiY0BleGFtcGxlLmNvbSIsInNjcCI6WyJhcGkiX 510 X0.vHJKtJ-zFIN75Tk7qGlmQsWPlvnChb2uSaGwPLvlWl64ts7-vvfwYDaVoXIQ 511 e_HkTVdljIzavVlPT60_b_9pDQ", 512 "issued_token_type": 513 "urn:ietf:params:oauth:token-type:access_token", 514 "token_type":"Bearer", 515 "expires_in":60 516 } 518 Figure 3: Token Exchange Response 520 The resource server can then use the newly acquired access token in 521 making a request to the backend server. 523 GET /api HTTP/1.1 524 Host: backend.example.com 525 Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQ 526 iOiJodHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2 527 FzLmV4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1M 528 zMsImF6cCI6InJzMDgiLCJzdWIiOiJiY0BleGFtcGxlLmNvbSIsInNjcCI6WyJh 529 cGkiXX0.vHJKtJ-zFIN75Tk7qGlmQsWPlvnChb2uSaGwPLvlWl64ts7-vvfwYDa 530 VoXIQe_HkTVdljIzavVlPT60_b_9pDQ 532 Figure 4: Backend Protected Resource Request 534 Additional examples can be found in Appendix A. 536 3. Token Type Identifiers 538 Several parameters in this specification utilize an identifier as the 539 value to describe the type of token in question. Specifically, they 540 are the "requested_token_type", "subject_token_type", 541 "actor_token_type" parameters of the request and the 542 "issued_token_type" member of the response. Token type identifiers 543 are URIs. 545 This specification defines the token type identifiers 546 "urn:ietf:params:oauth:token-type:access_token" and 547 "urn:ietf:params:oauth:token-type:refresh_token" to indicate that the 548 token is an OAuth 2.0 access token or refresh token, respectively. 549 The value "urn:ietf:params:oauth:token-type:jwt" defined in Section 9 550 of [JWT] indicates that the token is a JWT. This specification also 551 defines the token type identifier "urn:ietf:params:oauth:token- 552 type:id_token" to indicate that the token is an ID Token, as defined 553 in Section 2 of [OpenID.Core]. Other URIs to indicate other token 554 types MAY be used. 556 4. JSON Web Token Claims 558 It is useful to have defined mechanisms to express delegation within 559 a token as well as to express authorization to delegate or 560 impersonate. Although the token exchange protocol described herein 561 can be used with any type of token, this section defines claims to 562 express such semantics specifically for JWTs. Similar definitions 563 for other types of tokens are possible but beyond the scope of this 564 specification. 566 4.1. "act" (Actor) Claim 568 The "act" (actor) claim provides a means within a JWT to express that 569 delegation has occurred and identify the acting party to whom 570 authority has been delegated. The "act" claim value is a JSON object 571 and members in the JSON object are claims that identify the actor. 572 The claims that make up the "act" claim identify and possibly provide 573 additional information about the actor. For example, the combination 574 of the two claims "iss" and "sub" might be necessary to uniquely 575 identify an actor. 577 However, claims within the "act" claim pertain only to the identity 578 of the actor and are not relevant to the validity of the containing 579 JWT in the same manner as the top-level claims. Consequently, claims 580 such as "exp", "nbf", and "aud" are not meaningful when used within 581 an "act" claim, and therefore should not be used. 583 The following example illustrates the "act" (actor) claim within a 584 JWT Claims Set. The claims of the token itself are about 585 user@example.com while the "act" claim indicates that 586 admin@example.com is the current actor. 588 { 589 "aud":"https://consumer.example.com", 590 "iss":"https://issuer.example.com", 591 "exp":1443904177, 592 "nbf":1443904077, 593 "sub":"user@example.com", 594 "act": 595 { 596 "sub":"admin@example.com" 597 } 598 } 600 Figure 5: Actor Claim 602 A chain of delegation can be expressed by nesting one "act" claim 603 within another. The outermost "act" claim represents the current 604 actor while nested "act" claims represent prior actors. The least 605 recent actor is the most deeply nested. 607 The following example illustrates nested "act" (actor) claims within 608 a JWT Claims Set. The claims of the token itself are about 609 user@example.com while the "act" claim indicates that the system 610 consumer.example.com-web-application is the current actor and 611 admin@example.com was a prior actor. Such a token might come about 612 as the result of the web application receiving a token like the one 613 in the previous example and exchanging it for a new token that lists 614 it as the current actor and that can be used at 615 https://backend.example.com. 617 { 618 "aud":"https://backend.example.com", 619 "iss":"https://issuer.example.com", 620 "exp":1443904100, 621 "nbf":1443904000, 622 "sub":"user@example.com", 623 "act": 624 { 625 "sub":"consumer.example.com-web-application", 626 "iss":"https://issuer.example.net", 627 "act": 628 { 629 "sub":"admin@example.com" 630 } 631 } 632 } 634 Figure 6: Nested Actor Claim 636 4.2. "scp" (Scopes) Claim 638 The "scp" claim is an array of strings, each of which represents an 639 OAuth scope granted for the issued security token. Each array entry 640 of the claim value is a scope-token, as defined in Section 3.3 of 641 OAuth 2.0 [RFC6749]. 643 The following example illustrates the "scp" claim within a JWT Claims 644 Set with four scope-tokens. 646 { 647 "aud":"https://consumer.example.com", 648 "iss":"https://issuer.example.com", 649 "exp":1443904177, 650 "nbf":1443904077, 651 "sub":"dgaf4mvfs75Fci_FL3heQA", 652 "scp":["email","address","profile","phone"] 653 } 655 Figure 7: Scopes Claim 657 4.3. "may_act" (May Act For) Claim 659 The "may_act" claim makes a statement that one party is authorized to 660 become the actor and act on behalf of another party. The claim value 661 is a JSON object and members in the JSON object are claims that 662 identify the party that is asserted as being eligible to act for the 663 party identified by the JWT containing the claim. The claims that 664 make up the "may_act" claim identify and possibly provide additional 665 information about the authorized actor. For example, the combination 666 of the two claims "iss" and "sub" are sometimes necessary to uniquely 667 identify an authorized actor, while the "email" claim might be used 668 to provide additional useful information about that party. 670 However, claims within the "may_act" claim pertain only to the 671 identity of that party and are not relevant to the validity of the 672 containing JWT in the same manner as top level claims. Consequently, 673 claims such as "exp", "nbf", and "aud" are not meaningful when used 674 within a "may_act" claim, and therefore should not be used. 676 The following example illustrates the "may_act" claim within a JWT 677 Claims Set. The claims of the token itself are about 678 user@example.com while the "may_act" claim indicates that 679 admin@example.com is authorized to act on behalf of user@example.com. 681 { 682 "aud":"https://consumer.example.com", 683 "iss":"https://issuer.example.com", 684 "exp":1443904177, 685 "nbf":1443904077, 686 "sub":"user@example.com", 687 "may_act": 688 { 689 "sub":"admin@example.com" 690 } 691 } 693 Figure 8: May Act For Claim 695 5. IANA Considerations 697 5.1. OAuth URI Registration 699 This specification registers the following values in the IANA "OAuth 700 URI" registry [IANA.OAuth.Parameters] established by [RFC6755]. 702 5.1.1. Registry Contents 704 o URN: urn:ietf:params:oauth:grant-type:token-exchange 705 o Common Name: Token exchange grant type for OAuth 2.0 706 o Change controller: IESG 707 o Specification Document: Section 2.1 of [[ this specification ]] 709 o URN: urn:ietf:params:oauth:token-type:access_token 710 o Common Name: Token type URI for an OAuth 2.0 access token 711 o Change controller: IESG 712 o Specification Document: Section 3 of [[this specification]] 714 o URN: urn:ietf:params:oauth:token-type:refresh_token 715 o Common Name: Token Type URI for an OAuth 2.0 refresh token 716 o Change controller: IESG 717 o Specification Document: Section 3 of [[this specification]] 719 o URN: urn:ietf:params:oauth:token-type:id_token 720 o Common Name: Token Type URI for an ID Token 721 o Change controller: IESG 722 o Specification Document: Section 3 of [[this specification]] 724 5.2. OAuth Parameters Registration 726 This specification registers the following values in the IANA "OAuth 727 Parameters" registry [IANA.OAuth.Parameters] established by 728 [RFC6749]. 730 5.2.1. Registry Contents 732 o Parameter name: resource 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: audience 738 o Parameter usage location: token request 739 o Change controller: IESG 740 o Specification document(s): Section 2.1 of [[ this specification ]] 742 o Parameter name: requested_token_type 743 o Parameter usage location: token request 744 o Change controller: IESG 745 o Specification document(s): Section 2.1 of [[ this specification ]] 747 o Parameter name: subject_token 748 o Parameter usage location: token request 749 o Change controller: IESG 750 o Specification document(s): Section 2.1 of [[ this specification ]] 752 o Parameter name: subject_token_type 753 o Parameter usage location: token request 754 o Change controller: IESG 755 o Specification document(s): Section 2.1 of [[ this specification ]] 757 o Parameter name: actor_token 758 o Parameter usage location: token request 759 o Change controller: IESG 760 o Specification document(s): Section 2.1 of [[ this specification ]] 762 o Parameter name: actor_token_type 763 o Parameter usage location: token request 764 o Change controller: IESG 765 o Specification document(s): Section 2.1 of [[ this specification ]] 767 o Parameter name: want_composite 768 o Parameter usage location: token request 769 o Change controller: IESG 770 o Specification document(s): Section 2.1 of [[ this specification ]] 771 o Parameter name: issued_token_type 772 o Parameter usage location: token response 773 o Change controller: IESG 774 o Specification document(s): Section 2.2.1 of [[ this specification 775 ]] 777 5.3. OAuth Access Token Type Registration 779 This specification registers the following access token type in the 780 IANA "OAuth Access Token Types" registry [IANA.OAuth.Parameters] 781 established by [RFC6749]. 783 5.3.1. Registry Contents 785 o Type name: N_A 786 o Additional Token Endpoint Response Parameters: (none) 787 o HTTP Authentication Scheme(s): (none) 788 o Change controller: IESG 789 o Specification document(s): Section 2.2.1 of [[ this specification 790 ]] 792 5.4. JSON Web Token Claims Registration 794 This specification registers the following Claims in the IANA "JSON 795 Web Token Claims" registry [IANA.JWT.Claims] established by [JWT]. 797 5.4.1. Registry Contents 799 o Claim Name: "act" 800 o Claim Description: Actor 801 o Change Controller: IESG 802 o Specification Document(s): Section 4.1 of [[ this specification ]] 804 o Claim Name: "scp" 805 o Claim Description: Scope Values 806 o Change Controller: IESG 807 o Specification Document(s): Section 4.2 of [[ this specification ]] 809 o Claim Name: "may_act" 810 o Claim Description: May Act For 811 o Change Controller: IESG 812 o Specification Document(s): Section 4.3 of [[ this specification ]] 814 6. Security Considerations 816 All of the normal security issues that are discussed in [JWT], 817 especially in relationship to comparing URIs and dealing with 818 unrecognized values, also apply here. 820 In addition, both delegation and impersonation introduce unique 821 security issues. Any time one principal is delegated the rights of 822 another principal, the potential for abuse is a concern. The use of 823 the "scp" claim is suggested to mitigate potential for such abuse, as 824 it restricts the contexts in which the delegated rights can be 825 exercised. 827 7. References 829 7.1. Normative References 831 [IANA.JWT.Claims] 832 IANA, "JSON Web Token Claims", 833 . 835 [IANA.OAuth.Parameters] 836 IANA, "OAuth Parameters", 837 . 839 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 840 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 841 . 843 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 844 Requirement Levels", BCP 14, RFC 2119, 845 DOI 10.17487/RFC2119, March 1997, 846 . 848 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 849 Resource Identifier (URI): Generic Syntax", STD 66, 850 RFC 3986, DOI 10.17487/RFC3986, January 2005, 851 . 853 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 854 RFC 6749, DOI 10.17487/RFC6749, October 2012, 855 . 857 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 858 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 859 2014, . 861 7.2. Informative References 863 [OASIS.saml-core-2.0-os] 864 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 865 "Assertions and Protocol for the OASIS Security Assertion 866 Markup Language (SAML) V2.0", OASIS Standard saml-core- 867 2.0-os, March 2005. 869 [OpenID.Core] 870 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 871 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 872 . 874 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 875 Framework: Bearer Token Usage", RFC 6750, 876 DOI 10.17487/RFC6750, October 2012, 877 . 879 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 880 for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, 881 . 883 [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 884 "Assertion Framework for OAuth 2.0 Client Authentication 885 and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, 886 May 2015, . 888 [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 889 (JWT) Profile for OAuth 2.0 Client Authentication and 890 Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 891 2015, . 893 [WS-Trust] 894 Nadalin, A., Goodner, M., Gudgin, M., Barbir, A., and H. 895 Granqvist, "WS-Trust 1.4", February 2012, 896 . 899 Appendix A. Additional Token Exchange Examples 901 Two example token exchanges are provided in the following sections 902 illustrating impersonation and delegation, respectively (with extra 903 line breaks and indentation for display purposes only). 905 A.1. Impersonation Token Exchange Example 907 A.1.1. Token Exchange Request 909 In the following token exchange request, an anonymous client is 910 requesting a token with impersonation semantics. The client tells 911 the authorization server that it needs a token for use at the target 912 service with the logical name "urn:example:cooperation-context". 914 POST /as/token.oauth2 HTTP/1.1 915 Host: as.example.com 916 Content-Type: application/x-www-form-urlencoded 918 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 919 &audience=urn%3Aexample%3Acooperation-context 920 &subject_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwc 921 zovL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXI 922 uZXhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTA2MDAsIm5iZiI6MTQ0MTkwOTAwMCwic 923 3ViIjoiYmNAZXhhbXBsZS5uZXQiLCJzY3AiOlsib3JkZXJzIiwicHJvZmlsZSIsImh 924 pc3RvcnkiXX0.JDe7fZ267iIRXwbFmOugyCt5dmGoy6EeuzNQ3MqDek5cCUlyPhQC6 925 cz9laKjK1bnjMQbLJqWix6ZdBI0isjsTA 926 &subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 928 Figure 9: Token Exchange Request 930 A.1.2. Subject Token Claims 932 The "subject_token" in the prior request is a JWT and the decoded JWT 933 Claims Set is shown here. The JWT is intended for consumption by the 934 authorization server within a specific time window. The subject of 935 the JWT ("bc@example.net") is the party on behalf of whom the new 936 token is being requested. 938 { 939 "aud":"https://as.example.com", 940 "iss":"https://original-issuer.example.net", 941 "exp":1441910600, 942 "nbf":1441909000, 943 "sub":"bc@example.net", 944 "scp":["orders","profile","history"] 945 } 947 Figure 10: Subject Token Claims 949 A.1.3. Token Exchange Response 951 The "access_token" parameter of the token exchange response shown 952 below contains the new token that the client requested. The other 953 parameters of the response indicate that the token is a bearer access 954 token that expires in an hour. 956 HTTP/1.1 200 OK 957 Content-Type: application/json 958 Cache-Control: no-cache, no-store 960 { 961 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm4 962 6ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5l 963 eGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic3ViIjoiYmNAZXhhbXBsZS5uZ 964 XQiLCJzY3AiOlsib3JkZXJzIiwiaGlzdG9yeSIsInByb2ZpbGUiXX0.YQHuLmI1YD 965 TugbfEvgGY2gaGBmMyj9BepZSECCBE9j9ogqZv2qx6VQQPrbT1k7vBYGLNMOkkpmm 966 JkxZDS0YV7g", 967 "issued_token_type": 968 "urn:ietf:params:oauth:token-type:access_token", 969 "token_type":"Bearer", 970 "expires_in":3600 971 } 973 Figure 11: Token Exchange Response 975 A.1.4. Issued Token Claims 977 The decoded JWT Claims Set of the issued token is shown below. The 978 new JWT is issued by the authorization server and intended for 979 consumption by a system entity known by the logical name 980 "urn:example:cooperation-context" any time before its expiration. 981 The subject ("sub") of the JWT is the same as the subject the token 982 used to make the request, which effectively enables the client to 983 impersonate that subject at the system entity known by the logical 984 name of "urn:example:cooperation-context" by using the token. 986 { 987 "aud":"urn:example:cooperation-context", 988 "iss":"https://as.example.com", 989 "exp":1441913610, 990 "sub":"bc@example.net", 991 "scp":["orders","history","profile"] 992 } 994 Figure 12: Issued Token Claims 996 A.2. Delegation Token Exchange Example 998 A.2.1. Token Exchange Request 1000 In the following token exchange request, an anonymous client is 1001 requesting a token with delegation semantics, which is indicated by 1002 the inclusion of the "want_composite" parameter. The client tells 1003 the authorization server that it needs a token for use at the target 1004 service with the logical name "urn:example:cooperation-context". 1006 POST /as/token.oauth2 HTTP/1.1 1007 Host: as.example.com 1008 Content-Type: application/x-www-form-urlencoded 1010 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 1011 &audience=urn%3Aexample%3Acooperation-context 1012 &want_composite=true 1013 &subject_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwc 1014 zovL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXI 1015 uZXhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTAwNjAsInNjcCI6WyJzdGF0dXMiLCJmZ 1016 WVkIl0sInN1YiI6InVzZXJAZXhhbXBsZS5uZXQiLCJtYXlfYWN0Ijp7InN1YiI6ImF 1017 kbWluQGV4YW1wbGUubmV0In19.ut0Ll7wm920VzRvuLGLFoPJLeO5DDElxsax1L_xK 1018 Um2eooiNSfuif-OGa2382hPyFYnddKIa0wmDhQksW018Rw 1019 &subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1020 &actor_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwczo 1021 vL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXIuZ 1022 XhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTAwNjAsInN1YiI6ImFkbWluQGV4YW1wbGU 1023 ubmV0In0.7YQ-3zPfhUvzje5oqw8COCvN5uP6NsKik9CVV6cAOf4QKgM-tKfiOwcgZ 1024 oUuDL2tEs6tqPlcBlMjiSzEjm3yBg 1025 &actor_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1027 Figure 13: Token Exchange Request 1029 A.2.2. Subject Token Claims 1031 The "subject_token" in the prior request is a JWT and the decoded JWT 1032 Claims Set is shown here. The JWT is intended for consumption by the 1033 authorization server before a specific expiration time. The subject 1034 of the JWT ("user@example.net") is the party on behalf of whom the 1035 new token is being requested. 1037 { 1038 "aud":"https://as.example.com", 1039 "iss":"https://original-issuer.example.net", 1040 "exp":1441910060, 1041 "scp":["status","feed"], 1042 "sub":"user@example.net", 1043 "may_act": 1044 { 1045 "sub":"admin@example.net" 1046 } 1047 } 1049 Figure 14: Subject Token Claims 1051 A.2.3. Actor Token Claims 1053 The "actor_token" in the prior request is a JWT and the decoded JWT 1054 Claims Set is shown here. This JWT is also intended for consumption 1055 by the authorization server before a specific expiration time. The 1056 subject of the JWT ("admin@example.net") is the actor that will wield 1057 the security token being requested. 1059 { 1060 "aud":"https://as.example.com", 1061 "iss":"https://original-issuer.example.net", 1062 "exp":1441910060, 1063 "sub":"admin@example.net" 1064 } 1066 Figure 15: Actor Token Claims 1068 A.2.4. Token Exchange Response 1070 The "access_token" parameter of the token exchange response shown 1071 below contains the new token that the client requested. The other 1072 parameters of the response indicate that the token is a JWT that 1073 expires in an hour and that the access token type is not applicable 1074 since the issued token is not an access token. 1076 HTTP/1.1 200 OK 1077 Content-Type: application/json 1078 Cache-Control: no-cache, no-store 1080 { 1081 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm4 1082 6ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5l 1083 eGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic2NwIjpbInN0YXR1cyIsImZlZ 1084 WQiXSwic3ViIjoidXNlckBleGFtcGxlLm5ldCIsImFjdCI6eyJzdWIiOiJhZG1pbk 1085 BleGFtcGxlLm5ldCJ9fQ._qjM7Ij_HcrC78omT4jiZTFJOuzsAj1wPo31ymQS-Suq 1086 r64S1jCp6pfQR-in_OOAosAGamEg4jyPsht6kMAiYA", 1087 "issued_token_type":"urn:ietf:params:oauth:token-type:jwt", 1088 "token_type":"N_A", 1089 "expires_in":3600 1090 } 1092 Figure 16: Token Exchange Response 1094 A.2.5. Issued Token Claims 1096 The decoded JWT Claims Set of the issued token is shown below. The 1097 new JWT is issued by the authorization server and intended for 1098 consumption by a system entity known by the logical name 1099 "urn:example:cooperation-context" any time before its expiration. 1100 The subject ("sub") of the JWT is the same as the subject of the 1101 "subject_token" used to make the request. The actor ("act") of the 1102 JWT is the same as the subject of the "actor_token" used to make the 1103 request. This indicates delegation and identifies 1104 "admin@example.net" as the current actor to whom authority has been 1105 delegated to act on behalf of "user@example.net". 1107 { 1108 "aud":"urn:example:cooperation-context", 1109 "iss":"https://as.example.com", 1110 "exp":1441913610, 1111 "scp":["status","feed"], 1112 "sub":"user@example.net", 1113 "act": 1114 { 1115 "sub":"admin@example.net" 1116 } 1117 } 1119 Figure 17: Issued Token Claims 1121 Appendix B. Acknowledgements 1123 This specification was developed within the OAuth Working Group, 1124 which includes dozens of active and dedicated participants. It was 1125 produced under the chairmanship of Hannes Tschofenig and Derek Atkins 1126 with Kathleen Moriarty and Stephen Farrell serving as Security Area 1127 Directors. The following individuals contributed ideas, feedback, 1128 and wording to this specification: 1130 Caleb Baker, William Denniss, Vladimir Dzhuvinov, Phil Hunt, Jason 1131 Keglovitz, Nov Matake, Matt Miller, Matthew Perry, Justin Richer, 1132 Rifaat Shekh-Yusef, Scott Tomilson, and Hannes Tschofenig. 1134 Appendix C. Open Issues 1136 The following decisions need to be made and updates to this spec 1137 performed: 1139 o Should there be a way to use short names for some common token 1140 type identifiers? URIs are necessary in the general case for 1141 extensibility and vendor/deployment specific types. But short 1142 names like "access_token" and "jwt" are aesthetically appealing 1143 and slightly more efficient in terms of bytes on the wire and url- 1144 encoding. There seemed to be rough consensus in Prague ('No 1145 objection to use the proposed mechanism for a default prefix' from 1146 https://www.ietf.org/proceedings/93/minutes/minutes-93-oauth) for 1147 supporting a shorthand for commonly used types - i.e. when the 1148 value does not contain a ":" character, the value would be treated 1149 as though "urn:ietf:params:oauth:token-type:" were prepended to 1150 it. So, for example, the value "jwt" for "requested_token_type" 1151 would be semantically equivalent to "urn:ietf:params:oauth:token- 1152 type:jwt" and the value "access_token" would be equivalent to 1153 "urn:ietf:params:oauth:token-type:access_token". However, it was 1154 a fairly brief discussion in Prague and it has since been 1155 suggested that making participants handle both syntaxes will 1156 unnecessarily complicate the supporting code. 1158 o Provide a way to include supplementary claims or information in 1159 the request that would/could potentially be included in the issued 1160 token. There are real use cases for this but we would need to 1161 work through what it would look like. 1163 o Understand and define exactly how the presentation of PoP/non- 1164 bearer tokens works. Of course, the specifications defining these 1165 kinds of tokens need to do so first before there is much we can do 1166 in this specification in this regard. 1168 o It seems there may be cases in which it would be desirable for the 1169 authenticated client to be somehow represented in the issued 1170 token, sometimes in addition to the actor, which can already be 1171 represented using the "act" claim. Perhaps with a "client_id" 1172 claim? 1174 Appendix D. Document History 1176 [[ to be removed by the RFC Editor before publication as an RFC ]] 1178 -04 1180 o Clarified that the "resource" and "audience" request parameters 1181 can be used at the same time (via http://www.ietf.org/mail- 1182 archive/web/oauth/current/msg15335.html). 1183 o Clarified subject/actor token validity after token exchange and 1184 explained a bit more about the recommendation to not issue refresh 1185 tokens (via http://www.ietf.org/mail-archive/web/oauth/current/ 1186 msg15318.html). 1187 o Updated the examples appendix to use an issuer value that doesn't 1188 imply that the client issued and signed the tokens and used 1189 "Bearer" and "urn:ietf:params:oauth:token-type:access_token" in 1190 one of the responses (via http://www.ietf.org/mail- 1191 archive/web/oauth/current/msg15335.html). 1192 o Defined and registered urn:ietf:params:oauth:token-type:id_token, 1193 since some use cases perform token exchanges for ID Tokens and no 1194 URI to indicate that a token is an ID Token had previously been 1195 defined. 1197 -03 1199 o Updated the document editors (adding Campbell, Bradley, and 1200 Mortimore). 1201 o Added to the title. 1202 o Added to the abstract and introduction. 1203 o Updated the format of the request to use application/x-www-form- 1204 urlencoded request parameters and the response to use the existing 1205 token endpoint JSON parameters defined in OAuth 2.0. 1206 o Changed the grant type identifier to urn:ietf:params:oauth:grant- 1207 type:token-exchange. 1208 o Added RFC 6755 registration requests for 1209 urn:ietf:params:oauth:token-type:refresh_token, 1210 urn:ietf:params:oauth:token-type:access_token, and 1211 urn:ietf:params:oauth:grant-type:token-exchange. 1212 o Added RFC 6749 registration requests for request/response 1213 parameters. 1214 o Removed the Implementation Considerations and the requirement to 1215 support JWTs. 1216 o Clarified many aspects of the text. 1217 o Changed "on_behalf_of" to "subject_token", 1218 "on_behalf_of_token_type" to "subject_token_type", "act_as" to 1219 "actor_token", and "act_as_token_type" to "actor_token_type". 1220 o Added an "audience" request parameter used to indicate the logical 1221 names of the target services at which the client intends to use 1222 the requested security token. 1223 o Added a "want_composite" request parameter used to indicate the 1224 desire for a composite token rather than trying to infer it from 1225 the presence/absence of token(s) in the request. 1226 o Added a "resource" request parameter used to indicate the URLs of 1227 resources at which the client intends to use the requested 1228 security token. 1229 o Specified that multiple "audience" and "resource" request 1230 parameter values may be used. 1231 o Defined the JWT claim "act" (actor) to express the current actor 1232 or delegation principal. 1233 o Defined the JWT claim "may_act" to express that one party is 1234 authorized to act on behalf of another party. 1235 o Defined the JWT claim "scp" (scopes) to express OAuth 2.0 scope- 1236 token values. 1237 o Added the "N_A" (not applicable) OAuth Access Token Type 1238 definition for use in contexts in which the token exchange syntax 1239 requires a "token_type" value, but in which the token being issued 1240 is not an access token. 1241 o Added examples. 1243 -02 1245 o Enabled use of Security Token types other than JWTs for "act_as" 1246 and "on_behalf_of" request values. 1247 o Referenced the JWT and OAuth Assertions RFCs. 1249 -01 1251 o Updated references. 1253 -00 1255 o Created initial working group draft from draft-jones-oauth-token- 1256 exchange-01. 1258 Authors' Addresses 1260 Michael B. Jones 1261 Microsoft 1263 Email: mbj@microsoft.com 1264 URI: http://self-issued.info/ 1266 Anthony Nadalin 1267 Microsoft 1269 Email: tonynad@microsoft.com 1271 Brian Campbell 1272 Ping Identity 1274 Email: brian.d.campbell@gmail.com 1276 John Bradley 1277 Ping Identity 1279 Email: ve7jtb@ve7jtb.com 1281 Chuck Mortimore 1282 Salesforce 1284 Email: cmortimore@salesforce.com