idnits 2.17.1 draft-ietf-oauth-token-exchange-06.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 (October 28, 2016) is 2737 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: May 1, 2017 B. Campbell 6 J. Bradley 7 Ping Identity 8 C. Mortimore 9 Salesforce 10 October 28, 2016 12 OAuth 2.0 Token Exchange 13 draft-ietf-oauth-token-exchange-06 15 Abstract 17 This specification defines a protocol for an HTTP- and JSON- based 18 Security Token Service (STS) by defining how to request and obtain 19 security tokens from OAuth 2.0 authorization servers, including 20 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 May 1, 2017. 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 . . . . . . . . . . . . . . . . . . . . . . . . . 6 62 2.2. Response . . . . . . . . . . . . . . . . . . . . . . . . 8 63 2.2.1. Successful Response . . . . . . . . . . . . . . . . . 8 64 2.2.2. Error Response . . . . . . . . . . . . . . . . . . . 9 65 2.3. Example Token Exchange . . . . . . . . . . . . . . . . . 10 66 3. Token Type Identifiers . . . . . . . . . . . . . . . . . . . 12 67 4. JSON Web Token Claims and Introspection Response Parameters . 12 68 4.1. "act" (Actor) Claim . . . . . . . . . . . . . . . . . . . 13 69 4.2. "scp" (Scopes) Claim . . . . . . . . . . . . . . . . . . 14 70 4.3. "cid" (Client Identifier) Claim . . . . . . . . . . . . . 15 71 4.4. "may_act" (May Act For) Claim . . . . . . . . . . . . . . 15 72 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 73 5.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 16 74 5.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 16 75 5.2. OAuth Parameters Registration . . . . . . . . . . . . . . 17 76 5.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 17 77 5.3. OAuth Access Token Type Registration . . . . . . . . . . 18 78 5.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 18 79 5.4. JSON Web Token Claims Registration . . . . . . . . . . . 18 80 5.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 18 81 5.5. OAuth Token Introspection Response Registration . . . . . 19 82 5.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 19 83 6. Security Considerations . . . . . . . . . . . . . . . . . . . 19 84 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 85 7.1. Normative References . . . . . . . . . . . . . . . . . . 19 86 7.2. Informative References . . . . . . . . . . . . . . . . . 20 87 Appendix A. Additional Token Exchange Examples . . . . . . . . . 21 88 A.1. Impersonation Token Exchange Example . . . . . . . . . . 21 89 A.1.1. Token Exchange Request . . . . . . . . . . . . . . . 21 90 A.1.2. Subject Token Claims . . . . . . . . . . . . . . . . 22 91 A.1.3. Token Exchange Response . . . . . . . . . . . . . . . 22 92 A.1.4. Issued Token Claims . . . . . . . . . . . . . . . . . 23 93 A.2. Delegation Token Exchange Example . . . . . . . . . . . . 23 94 A.2.1. Token Exchange Request . . . . . . . . . . . . . . . 23 95 A.2.2. Subject Token Claims . . . . . . . . . . . . . . . . 24 96 A.2.3. Actor Token Claims . . . . . . . . . . . . . . . . . 25 97 A.2.4. Token Exchange Response . . . . . . . . . . . . . . . 25 98 A.2.5. Issued Token Claims . . . . . . . . . . . . . . . . . 25 99 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 26 100 Appendix C. Document History . . . . . . . . . . . . . . . . . . 26 101 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 29 103 1. Introduction 105 A security token is a set of information that facilitates the sharing 106 of identity and security information in heterogeneous environments or 107 across security domains. Examples of security tokens include JSON 108 Web Tokens (JWTs) [JWT] and SAML Assertions [OASIS.saml-core-2.0-os]. 109 Security tokens are typically signed to achieve integrity and 110 sometimes also encrypted to achieve confidentiality. Security tokens 111 are also sometimes described as Assertions, such as in [RFC7521]. 113 A Security Token Service (STS) is a service capable of validating and 114 issuing security tokens, which enables clients to obtain appropriate 115 access credentials for resources in heterogeneous environments or 116 across security domains. Web Service clients have used WS-Trust 117 [WS-Trust] as the protocol to interact with an STS for token 118 exchange. While WS-Trust uses XML and SOAP, the trend in modern Web 119 development has been towards RESTful patterns and JSON. The OAuth 120 2.0 Authorization Framework [RFC6749] and OAuth 2.0 Bearer Tokens 121 [RFC6750] have emerged as popular standards for authorizing and 122 securing access to HTTP and RESTful resources but do not provide 123 everything necessary to facilitate token exchange interactions. 125 This specification defines a protocol extending OAuth 2.0 that 126 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 needed or if proof-of-possession style 164 tokens will be required or issued; however, such details will often 165 be policy decisions made with respect to the specific needs of 166 individual deployments and will be configured or implemented 167 accordingly. 169 The security tokens obtained could be used in a number of contexts, 170 the specifics of which are also beyond the scope of this 171 specification. 173 1.1. Delegation vs. Impersonation Semantics 175 When principal A impersonates principal B, A is given all the rights 176 that B has within some defined rights context and is 177 indistinguishable from B in that context. Thus, when principal A 178 impersonates principal B, then in so far as any entity receiving such 179 a token is concerned, they are actually dealing with B. It is true 180 that some members of the identity system might have awareness that 181 impersonation is going on, but it is not a requirement. For all 182 intents and purposes, when A is impersonating B, A is B. 184 Delegation semantics are different than impersonation semantics, 185 though the two are closely related. With delegation semantics, 186 principal A still has its own identity separate from B and it is 187 explicitly understood that while B may have delegated some of its 188 rights to A, any actions taken are being taken by A representing B. 189 In a sense, A is an agent for B. 191 Delegation and impersonation are not inclusive of all situations. 192 When a principal is acting directly on its own behalf, for example, 193 neither delegation nor impersonation are in play. They are, however, 194 the more common semantics operating for token exchange and, as such, 195 are given more direct treatment in this specification. 197 Delegation semantics are typically expressed in a token by including 198 information about both the primary subject of the token as well as 199 the actor to whom that subject has delegated some of its rights. 200 Such a token is sometimes referred to as a composite token because it 201 is composed of information about multiple subjects. Typically, in 202 the request, the "subject_token" represents the identity of the party 203 on behalf of whom the token is being requested while the 204 "actor_token" represents the identity of the party to whom the access 205 rights of the issued token are being delegated. A composite token 206 issued by the authorization server will contain information about 207 both parties. When and if a composite token is issued is at the 208 desecration of the authorization server and applicable policy and 209 configuration. 211 The specifics of representing a composite token and even whether or 212 not such a token will be issued depend on the details of the 213 implementation and the kind of token. The representations of 214 composite tokens that are not JWTs are beyond the scope of this 215 specification. The "actor_token" request parameter, however, does 216 provide a means for providing information about the desired actor and 217 the JWT "act" claim can provide a representation of a chain of 218 delegation. 220 1.2. Requirements Notation and Conventions 222 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 223 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 224 "OPTIONAL" in this document are to be interpreted as described in RFC 225 2119 [RFC2119]. 227 1.3. Terminology 229 This specification uses the terms "access token type", "authorization 230 server", "client", "client identifier", "resource server", "token 231 endpoint", "token request", and "token response" defined by OAuth 2.0 232 [RFC6749], and the terms "Claim" and "JWT Claims Set" defined by JSON 233 Web Token (JWT) [JWT]. 235 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. If the requested type is 309 unspecified, the issued token type is at the discretion of the 310 authorization server and may be dictated by knowledge of the 311 requirements of the service or resource indicated by the 312 "resource" or "audience" parameter. 314 subject_token 315 REQUIRED. A security token that represents the identity of the 316 party on behalf of whom the request is being made. Typically, the 317 subject of this token will be the subject of the security token 318 issued in response to this request. 320 subject_token_type 321 REQUIRED. An identifier, as described in Section 3, that 322 indicates the type of the security token in the "subject_token" 323 parameter. 325 actor_token 326 OPTIONAL. A security token that represents the identity of the 327 party that is authorized to use the requested security token and 328 act on behalf of the subject. 330 actor_token_type 331 An identifier, as described in Section 3, that indicates the type 332 of the security token in the "actor_token" parameter. This is 333 REQUIRED when the "actor_token" parameter is present in the 334 request but MUST NOT be included otherwise. 336 In the absence of one-time-use or other semantics specific to the 337 token type, the act of performing a token exchange has no impact on 338 the validity of the subject token or actor token. 340 2.2. Response 342 The authorization server responds to a token exchange request with a 343 normal OAuth 2.0 response from the token endpoint, as specified in 344 Section 5 of [RFC6749]. Additional details and explanation are 345 provided in the following subsections. 347 2.2.1. Successful Response 349 If the request is valid and meets all policy and other criteria of 350 the authorization server, a successful token response is constructed 351 by adding the following parameters to the entity-body of the HTTP 352 response using the "application/json" media type, as specified by 353 [RFC7159], and an HTTP 200 status code. The parameters are 354 serialized into a JavaScript Object Notation (JSON) structure by 355 adding each parameter at the top level. Parameter names and string 356 values are included as JSON strings. Numerical values are included 357 as JSON numbers. The order of parameters does not matter and can 358 vary. 360 access_token 361 REQUIRED. The security token issued by the authorization server 362 in response to the token exchange request. The "access_token" 363 parameter from Section 5.1 of [RFC6749] is used here to carry the 364 requested token, which allows this token exchange protocol to use 365 the existing OAuth 2.0 request and response constructs defined for 366 the token endpoint. The identifier "access_token" is used for 367 historical reasons and the issued token need not be an OAuth 368 access token. 370 issued_token_type 371 REQUIRED. An identifier, as described in Section 3, for the 372 representation of the issued security token. 374 token_type 375 REQUIRED. A case-insensitive value specifying the method of using 376 of the access token issued, as specified in Section 7.1 of 377 [RFC6749]. It provides the client with information about how to 378 utilize the access token to access protected resources. For 379 example, a value of "Bearer", as specified in [RFC6750], indicates 380 that the security token is a bearer token and the client can 381 simply present it as is without any additional proof of 382 eligibility beyond the contents of the token itself. Note that 383 the meaning of this parameter is different from the meaning of the 384 "issued_token_type" parameter, which declares the representation 385 of the issued security token; the term "token type" is typically 386 used with this meaning, as it is in all "*_token_type" parameters 387 in this specification. If the issued token is not an access token 388 or usable as an access token, then the "token_type" value "N_A" is 389 used to indicate that an OAuth 2.0 "token_type" identifier is not 390 applicable in that context. 392 expires_in 393 RECOMMENDED. The validity lifetime, in seconds, of the token 394 issued by the authorization server. Oftentimes the client will 395 not have the inclination or capability to inspect the content of 396 the token and this parameter provides a consistent and token type 397 agnostic indication of how long the token can be expected to be 398 valid. For example, the value 1800 denotes that the token will 399 expire in thirty minutes from the time the response was generated. 401 scope 402 OPTIONAL, if the scope of the issued security token is identical 403 to the scope requested by the client; otherwise, REQUIRED. 405 refresh_token 406 OPTIONAL. A refresh token will typically not be issued when the 407 the exchange is of one temporary credential (the subject_token) 408 for a different temporary credential (the issued token) for use in 409 some other context. A refresh token can be issued in cases where 410 the client of the token exchange needs the ability to access a 411 resource even when the original credential is no longer valid 412 (e.g. user-not-present or offline scenarios where there is no 413 longer any user entertaining an active session with the client). 414 Profiles or deployments of this specification should clearly 415 document the conditions under which a client should expect a 416 refresh token in response to "urn:ietf:params:oauth:grant- 417 type:token-exchange" grant type requests. 419 2.2.2. Error Response 421 If either the "subject_token" or "actor_token" are invalid for any 422 reason, or are unacceptable based on policy, the authorization server 423 MUST construct an error response, as specified in Section 5.2 of 424 [RFC6749]. The value of the "error" parameter MUST be the 425 "invalid_request" error code. The authorization server MAY include 426 additional information regarding the reasons for the error using the 427 "error_description" and/or "error_uri" parameters. Other error codes 428 may also be used, as appropriate. 430 2.3. Example Token Exchange 432 The following example demonstrates a hypothetical token exchange in 433 which an OAuth resource server assumes the role of the client during 434 token exchange in order to trade an access token that it received in 435 a protected resource request for a token that it will use to call to 436 a backend service (extra line breaks and indentation in the examples 437 are for display purposes only). 439 The resource server receives the following request containing an 440 OAuth access token in the Authorization request header, as specified 441 in Section 2.1 of [RFC6750]. 443 GET /resource HTTP/1.1 444 Host: frontend.example.com 445 Authorization: Bearer accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC 447 Figure 1: Protected Resource Request 449 The resource server assumes the role of the client for the token 450 exchange and the access token from the request above is sent to the 451 authorization server using a request as specified in Section 2.1. 452 The value of the "subject_token" parameter carries the access token 453 and the value of the "subject_token_type" parameter indicates that it 454 is an OAuth 2.0 access token. The resource server, acting in the 455 roll of the client, uses its identifier and secret to authenticate to 456 the authorization server using the HTTP Basic authentication scheme. 457 The "resource" parameter indicates the location of the backend 458 service, https://backend.example.com/api, where the issued token will 459 be used. 461 POST /as/token.oauth2 HTTP/1.1 462 Host: as.example.com 463 Authorization: Basic cnMwODpsb25nLXNlY3VyZS1yYW5kb20tc2VjcmV0 464 Content-Type: application/x-www-form-urlencoded 466 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 467 &resource=https%3A%2F%2Fbackend.example.com%2Fapi%20 468 &subject_token=accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC 469 &subject_token_type= 470 urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token 472 Figure 2: Token Exchange Request 474 The authorization server validates the client credentials and the 475 "subject_token" presented in the token exchange request. From the 476 "resource" parameter, the authorization server is able to determine 477 the appropriate policy to apply to the request and issues a token 478 suitable for use at https://backend.example.com. The "access_token" 479 parameter of the response contains the new token, which is itself a 480 bearer OAuth access token that is valid for one minute. The token 481 happens to be a JWT; however, its structure and format are opaque to 482 the client so the "issued_token_type" indicates only that it is an 483 access token. 485 HTTP/1.1 200 OK 486 Content-Type: application/json 487 Cache-Control: no-cache, no-store 489 { 490 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQiOiJo 491 dHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2FzLmV 492 4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1MzMsIn 493 N1YiI6ImJjQGV4YW1wbGUuY29tIiwic2NwIjpbImFwaSJdfQ.MXgnpvPMo0nhce 494 PwnQbunD2gw_pDyCFA-Saobl6gyLAdyPbaALFuAOyFc4XTWaPEnHV_LGmXklSTp 495 z0yC7hlSQ", 496 "issued_token_type": 497 "urn:ietf:params:oauth:token-type:access_token", 498 "token_type":"Bearer", 499 "expires_in":60 500 } 502 Figure 3: Token Exchange Response 504 The resource server can then use the newly acquired access token in 505 making a request to the backend server. 507 GET /api HTTP/1.1 508 Host: backend.example.com 509 Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQ 510 iOiJodHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2 511 FzLmV4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1M 512 zMsInN1YiI6ImJjQGV4YW1wbGUuY29tIiwic2NwIjpbImFwaSJdfQ.MXgnpvPMo 513 0nhcePwnQbunD2gw_pDyCFA-Saobl6gyLAdyPbaALFuAOyFc4XTWaPEnHV_LGmX 514 klSTpz0yC7hlSQ 516 Figure 4: Backend Protected Resource Request 518 Additional examples can be found in Appendix A. 520 3. Token Type Identifiers 522 Several parameters in this specification utilize an identifier as the 523 value to describe the token in question. Specifically, they are the 524 "requested_token_type", "subject_token_type", "actor_token_type" 525 parameters of the request and the "issued_token_type" member of the 526 response. Token type identifiers are URIs. Token Exchange can work 527 with both tokens issued by other parties and tokens from the given 528 authorization server. For the former the token type identifier 529 indicates the syntax (e.g. JWT or SAML) so the AS can parse it; for 530 the latter it indicates what the AS issued it for (e.g. access_token 531 or refresh_token). 533 This specification defines the token type identifiers 534 "urn:ietf:params:oauth:token-type:access_token" and 535 "urn:ietf:params:oauth:token-type:refresh_token" to indicate that the 536 token is an OAuth 2.0 access token or refresh token, respectively. 537 The value "urn:ietf:params:oauth:token-type:jwt" defined in Section 9 538 of [JWT] indicates that the token is a JWT. This specification also 539 defines the token type identifier "urn:ietf:params:oauth:token- 540 type:id_token" to indicate that the token is an ID Token, as defined 541 in Section 2 of [OpenID.Core]. Other URIs to indicate other token 542 types MAY be used. 544 The distinction between an access token and a JWT is subtle. An 545 access token represents a delegated authorization decision, whereas 546 JWT is a token format. An access token can be formatted as a JWT but 547 doesn't necessarily have to be. And a JWT might well be an access 548 token but not all JWTs are access tokens. The intent of this 549 specification is that "urn:ietf:params:oauth:token-type:access_token" 550 be an indicator that the token is a typical OAuth access token issued 551 by the authorization server in question, opaque to the client, and 552 usable the same manner as any other access token obtained from that 553 authorization server (it could well be a JWT but the client isn't and 554 needn't be aware of that fact). Whereas 555 "urn:ietf:params:oauth:token-type:jwt" is to indicate specifically 556 that a JWT is being requested or sent (perhaps in a cross-domain use- 557 case where the JWT is used as an authorization grant to obtain an 558 access token from a different authorization server as is facilitated 559 by [RFC7523]). 561 4. JSON Web Token Claims and Introspection Response Parameters 563 It is useful to have defined mechanisms to express delegation within 564 a token as well as to express authorization to delegate or 565 impersonate. Although the token exchange protocol described herein 566 can be used with any type of token, this section defines claims to 567 express such semantics specifically for JWTs and in an OAuth 2.0 568 Token Introspection [RFC7662] response. Similar definitions for 569 other types of tokens are possible but beyond the scope of this 570 specification. 572 4.1. "act" (Actor) Claim 574 The "act" (actor) claim provides a means within a JWT to express that 575 delegation has occurred and identify the acting party to whom 576 authority has been delegated. The "act" claim value is a JSON object 577 and members in the JSON object are claims that identify the actor. 578 The claims that make up the "act" claim identify and possibly provide 579 additional information about the actor. For example, the combination 580 of the two claims "iss" and "sub" might be necessary to uniquely 581 identify an actor. 583 However, claims within the "act" claim pertain only to the identity 584 of the actor and are not relevant to the validity of the containing 585 JWT in the same manner as the top-level claims. Consequently, claims 586 such as "exp", "nbf", and "aud" are not meaningful when used within 587 an "act" claim, and therefore should not be used. 589 The following example illustrates the "act" (actor) claim within a 590 JWT Claims Set. The claims of the token itself are about 591 user@example.com while the "act" claim indicates that 592 admin@example.com is the current actor. 594 { 595 "aud":"https://consumer.example.com", 596 "iss":"https://issuer.example.com", 597 "exp":1443904177, 598 "nbf":1443904077, 599 "sub":"user@example.com", 600 "act": 601 { 602 "sub":"admin@example.com" 603 } 604 } 606 Figure 5: Actor Claim 608 A chain of delegation can be expressed by nesting one "act" claim 609 within another. The outermost "act" claim represents the current 610 actor while nested "act" claims represent prior actors. The least 611 recent actor is the most deeply nested. 613 The following example illustrates nested "act" (actor) claims within 614 a JWT Claims Set. The claims of the token itself are about 615 user@example.com while the "act" claim indicates that the system 616 consumer.example.com-web-application is the current actor and 617 admin@example.com was a prior actor. Such a token might come about 618 as the result of the web application receiving a token like the one 619 in the previous example and exchanging it for a new token that lists 620 it as the current actor and that can be used at 621 https://backend.example.com. 623 { 624 "aud":"https://backend.example.com", 625 "iss":"https://issuer.example.com", 626 "exp":1443904100, 627 "nbf":1443904000, 628 "sub":"user@example.com", 629 "act": 630 { 631 "sub":"consumer.example.com-web-application", 632 "iss":"https://issuer.example.net", 633 "act": 634 { 635 "sub":"admin@example.com" 636 } 637 } 638 } 640 Figure 6: Nested Actor Claim 642 When included as a top-level member of an OAuth token introspection 643 response, "act" has the same semantics and format as the the claim of 644 the same name. 646 4.2. "scp" (Scopes) Claim 648 The "scp" claim is an array of strings, each of which represents an 649 OAuth scope granted for the issued security token. Each array entry 650 of the claim value is a scope-token, as defined in Section 3.3 of 651 OAuth 2.0 [RFC6749]. 653 The following example illustrates the "scp" claim within a JWT Claims 654 Set with four scope-tokens. 656 { 657 "aud":"https://consumer.example.com", 658 "iss":"https://issuer.example.com", 659 "exp":1443904177, 660 "nbf":1443904077, 661 "sub":"dgaf4mvfs75Fci_FL3heQA", 662 "scp":["email","address","profile","phone"] 663 } 665 Figure 7: Scopes Claim 667 OAuth 2.0 Token Introspection [RFC7662] defines the "scope" parameter 668 to convey the scopes associated with the token. 670 4.3. "cid" (Client Identifier) Claim 672 The "cid" claim carries the client identifier of the OAuth 2.0 673 [RFC6749] client that requested the token. 675 The following example illustrates the "cid" claim within a JWT Claims 676 Set indicating an OAuth 2.0 client with "s6BhdRkqt3" as its 677 identifier. 679 { 680 "aud":"https://consumer.example.com", 681 "iss":"https://issuer.example.com", 682 "exp":1443904177, 683 "sub":"user@example.com", 684 "cid":"s6BhdRkqt3" 685 } 687 Figure 8: Client Identifier Claim 689 OAuth 2.0 Token Introspection [RFC7662] defines the "client_id" 690 parameter as the client identifier for the OAuth 2.0 client that 691 requested the token. 693 4.4. "may_act" (May Act For) Claim 695 The "may_act" claim makes a statement that one party is authorized to 696 become the actor and act on behalf of another party. The claim value 697 is a JSON object and members in the JSON object are claims that 698 identify the party that is asserted as being eligible to act for the 699 party identified by the JWT containing the claim. The claims that 700 make up the "may_act" claim identify and possibly provide additional 701 information about the authorized actor. For example, the combination 702 of the two claims "iss" and "sub" are sometimes necessary to uniquely 703 identify an authorized actor, while the "email" claim might be used 704 to provide additional useful information about that party. 706 However, claims within the "may_act" claim pertain only to the 707 identity of that party and are not relevant to the validity of the 708 containing JWT in the same manner as top level claims. Consequently, 709 claims such as "exp", "nbf", and "aud" are not meaningful when used 710 within a "may_act" claim, and therefore should not be used. 712 The following example illustrates the "may_act" claim within a JWT 713 Claims Set. The claims of the token itself are about 714 user@example.com while the "may_act" claim indicates that 715 admin@example.com is authorized to act on behalf of user@example.com. 717 { 718 "aud":"https://consumer.example.com", 719 "iss":"https://issuer.example.com", 720 "exp":1443904177, 721 "nbf":1443904077, 722 "sub":"user@example.com", 723 "may_act": 724 { 725 "sub":"admin@example.com" 726 } 727 } 729 Figure 9: May Act For Claim 731 When included as a top-level member of an OAuth token introspection 732 response, "may_act" has the same semantics and format as the the 733 claim of the same name. 735 5. IANA Considerations 737 5.1. OAuth URI Registration 739 This specification registers the following values in the IANA "OAuth 740 URI" registry [IANA.OAuth.Parameters] established by [RFC6755]. 742 5.1.1. Registry Contents 744 o URN: urn:ietf:params:oauth:grant-type:token-exchange 745 o Common Name: Token exchange grant type for OAuth 2.0 746 o Change controller: IESG 747 o Specification Document: Section 2.1 of [[ this specification ]] 748 o URN: urn:ietf:params:oauth:token-type:access_token 749 o Common Name: Token type URI for an OAuth 2.0 access token 750 o Change controller: IESG 751 o Specification Document: Section 3 of [[this specification]] 753 o URN: urn:ietf:params:oauth:token-type:refresh_token 754 o Common Name: Token Type URI for an OAuth 2.0 refresh token 755 o Change controller: IESG 756 o Specification Document: Section 3 of [[this specification]] 758 o URN: urn:ietf:params:oauth:token-type:id_token 759 o Common Name: Token Type URI for an ID Token 760 o Change controller: IESG 761 o Specification Document: Section 3 of [[this specification]] 763 5.2. OAuth Parameters Registration 765 This specification registers the following values in the IANA "OAuth 766 Parameters" registry [IANA.OAuth.Parameters] established by 767 [RFC6749]. 769 5.2.1. Registry Contents 771 o Parameter name: resource 772 o Parameter usage location: token request 773 o Change controller: IESG 774 o Specification document(s): Section 2.1 of [[ this specification ]] 776 o Parameter name: audience 777 o Parameter usage location: token request 778 o Change controller: IESG 779 o Specification document(s): Section 2.1 of [[ this specification ]] 781 o Parameter name: requested_token_type 782 o Parameter usage location: token request 783 o Change controller: IESG 784 o Specification document(s): Section 2.1 of [[ this specification ]] 786 o Parameter name: subject_token 787 o Parameter usage location: token request 788 o Change controller: IESG 789 o Specification document(s): Section 2.1 of [[ this specification ]] 791 o Parameter name: subject_token_type 792 o Parameter usage location: token request 793 o Change controller: IESG 794 o Specification document(s): Section 2.1 of [[ this specification ]] 795 o Parameter name: actor_token 796 o Parameter usage location: token request 797 o Change controller: IESG 798 o Specification document(s): Section 2.1 of [[ this specification ]] 800 o Parameter name: actor_token_type 801 o Parameter usage location: token request 802 o Change controller: IESG 803 o Specification document(s): Section 2.1 of [[ this specification ]] 805 o Parameter name: issued_token_type 806 o Parameter usage location: token response 807 o Change controller: IESG 808 o Specification document(s): Section 2.2.1 of [[ this specification 809 ]] 811 5.3. OAuth Access Token Type Registration 813 This specification registers the following access token type in the 814 IANA "OAuth Access Token Types" registry [IANA.OAuth.Parameters] 815 established by [RFC6749]. 817 5.3.1. Registry Contents 819 o Type name: N_A 820 o Additional Token Endpoint Response Parameters: (none) 821 o HTTP Authentication Scheme(s): (none) 822 o Change controller: IESG 823 o Specification document(s): Section 2.2.1 of [[ this specification 824 ]] 826 5.4. JSON Web Token Claims Registration 828 This specification registers the following Claims in the IANA "JSON 829 Web Token Claims" registry [IANA.JWT.Claims] established by [JWT]. 831 5.4.1. Registry Contents 833 o Claim Name: "act" 834 o Claim Description: Actor 835 o Change Controller: IESG 836 o Specification Document(s): Section 4.1 of [[ this specification ]] 838 o Claim Name: "scp" 839 o Claim Description: Scope Values 840 o Change Controller: IESG 841 o Specification Document(s): Section 4.2 of [[ this specification ]] 842 o Claim Name: "cid" 843 o Claim Description: Client Identifier 844 o Change Controller: IESG 845 o Specification Document(s): Section 4.3 of [[ this specification ]] 847 o Claim Name: "may_act" 848 o Claim Description: May Act For 849 o Change Controller: IESG 850 o Specification Document(s): Section 4.4 of [[ this specification ]] 852 5.5. OAuth Token Introspection Response Registration 854 This specification registers the following values in the IANA "OAuth 855 Token Introspection Response" registry [IANA.OAuth.Parameters] 856 established by [RFC7662]. 858 5.5.1. Registry Contents 860 o Claim Name: "act" 861 o Claim Description: Actor 862 o Change Controller: IESG 863 o Specification Document(s): Section 4.1 of [[ this specification ]] 865 o Claim Name: "may_act" 866 o Claim Description: May Act For 867 o Change Controller: IESG 868 o Specification Document(s): Section 4.4 of [[ this specification ]] 870 6. Security Considerations 872 All of the normal security issues that are discussed in [JWT], 873 especially in relationship to comparing URIs and dealing with 874 unrecognized values, also apply here. 876 In addition, both delegation and impersonation introduce unique 877 security issues. Any time one principal is delegated the rights of 878 another principal, the potential for abuse is a concern. The use of 879 the "scp" claim is suggested to mitigate potential for such abuse, as 880 it restricts the contexts in which the delegated rights can be 881 exercised. 883 7. References 885 7.1. Normative References 887 [IANA.JWT.Claims] 888 IANA, "JSON Web Token Claims", 889 . 891 [IANA.OAuth.Parameters] 892 IANA, "OAuth Parameters", 893 . 895 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 896 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 897 . 899 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 900 Requirement Levels", BCP 14, RFC 2119, 901 DOI 10.17487/RFC2119, March 1997, 902 . 904 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 905 Resource Identifier (URI): Generic Syntax", STD 66, 906 RFC 3986, DOI 10.17487/RFC3986, January 2005, 907 . 909 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 910 RFC 6749, DOI 10.17487/RFC6749, October 2012, 911 . 913 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 914 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 915 2014, . 917 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 918 RFC 7662, DOI 10.17487/RFC7662, October 2015, 919 . 921 7.2. Informative References 923 [OASIS.saml-core-2.0-os] 924 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 925 "Assertions and Protocol for the OASIS Security Assertion 926 Markup Language (SAML) V2.0", OASIS Standard saml-core- 927 2.0-os, March 2005. 929 [OpenID.Core] 930 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 931 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 932 . 934 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 935 Framework: Bearer Token Usage", RFC 6750, 936 DOI 10.17487/RFC6750, October 2012, 937 . 939 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 940 for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, 941 . 943 [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 944 "Assertion Framework for OAuth 2.0 Client Authentication 945 and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, 946 May 2015, . 948 [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 949 (JWT) Profile for OAuth 2.0 Client Authentication and 950 Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 951 2015, . 953 [WS-Trust] 954 Nadalin, A., Goodner, M., Gudgin, M., Barbir, A., and H. 955 Granqvist, "WS-Trust 1.4", February 2012, 956 . 959 Appendix A. Additional Token Exchange Examples 961 Two example token exchanges are provided in the following sections 962 illustrating impersonation and delegation, respectively (with extra 963 line breaks and indentation for display purposes only). 965 A.1. Impersonation Token Exchange Example 967 A.1.1. Token Exchange Request 969 In the following token exchange request, a client is requesting a 970 token with impersonation semantics. The client tells the 971 authorization server that it needs a token for use at the target 972 service with the logical name "urn:example:cooperation-context". 974 POST /as/token.oauth2 HTTP/1.1 975 Host: as.example.com 976 Content-Type: application/x-www-form-urlencoded 978 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 979 &audience=urn%3Aexample%3Acooperation-context 980 &subject_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwc 981 zovL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXI 982 uZXhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTA2MDAsIm5iZiI6MTQ0MTkwOTAwMCwic 983 3ViIjoiYmNAZXhhbXBsZS5uZXQiLCJzY3AiOlsib3JkZXJzIiwicHJvZmlsZSIsImh 984 pc3RvcnkiXX0.JDe7fZ267iIRXwbFmOugyCt5dmGoy6EeuzNQ3MqDek5cCUlyPhQC6 985 cz9laKjK1bnjMQbLJqWix6ZdBI0isjsTA 986 &subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 988 Figure 10: Token Exchange Request 990 A.1.2. Subject Token Claims 992 The "subject_token" in the prior request is a JWT and the decoded JWT 993 Claims Set is shown here. The JWT is intended for consumption by the 994 authorization server within a specific time window. The subject of 995 the JWT ("bc@example.net") is the party on behalf of whom the new 996 token is being requested. 998 { 999 "aud":"https://as.example.com", 1000 "iss":"https://original-issuer.example.net", 1001 "exp":1441910600, 1002 "nbf":1441909000, 1003 "sub":"bc@example.net", 1004 "scp":["orders","profile","history"] 1005 } 1007 Figure 11: Subject Token Claims 1009 A.1.3. Token Exchange Response 1011 The "access_token" parameter of the token exchange response shown 1012 below contains the new token that the client requested. The other 1013 parameters of the response indicate that the token is a bearer access 1014 token that expires in an hour. 1016 HTTP/1.1 200 OK 1017 Content-Type: application/json 1018 Cache-Control: no-cache, no-store 1020 { 1021 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm4 1022 6ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5l 1023 eGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic3ViIjoiYmNAZXhhbXBsZS5uZ 1024 XQiLCJzY3AiOlsib3JkZXJzIiwiaGlzdG9yeSIsInByb2ZpbGUiXX0.YQHuLmI1YD 1025 TugbfEvgGY2gaGBmMyj9BepZSECCBE9j9ogqZv2qx6VQQPrbT1k7vBYGLNMOkkpmm 1026 JkxZDS0YV7g", 1027 "issued_token_type": 1028 "urn:ietf:params:oauth:token-type:access_token", 1029 "token_type":"Bearer", 1030 "expires_in":3600 1031 } 1033 Figure 12: Token Exchange Response 1035 A.1.4. Issued Token Claims 1037 The decoded JWT Claims Set of the issued token is shown below. The 1038 new JWT is issued by the authorization server and intended for 1039 consumption by a system entity known by the logical name 1040 "urn:example:cooperation-context" any time before its expiration. 1041 The subject ("sub") of the JWT is the same as the subject the token 1042 used to make the request, which effectively enables the client to 1043 impersonate that subject at the system entity known by the logical 1044 name of "urn:example:cooperation-context" by using the token. 1046 { 1047 "aud":"urn:example:cooperation-context", 1048 "iss":"https://as.example.com", 1049 "exp":1441913610, 1050 "sub":"bc@example.net", 1051 "scp":["orders","history","profile"] 1052 } 1054 Figure 13: Issued Token Claims 1056 A.2. Delegation Token Exchange Example 1058 A.2.1. Token Exchange Request 1060 In the following token exchange request, a client is requesting a 1061 token and providing both a "subject_token" and an "actor_token". The 1062 client tells the authorization server that it needs a token for use 1063 at the target service with the logical name "urn:example:cooperation- 1064 context". Policy at the authorization server dictates that the 1065 issued token be a composite. 1067 POST /as/token.oauth2 HTTP/1.1 1068 Host: as.example.com 1069 Content-Type: application/x-www-form-urlencoded 1071 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 1072 &audience=urn%3Aexample%3Acooperation-context 1073 &subject_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwc 1074 zovL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXI 1075 uZXhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTAwNjAsInNjcCI6WyJzdGF0dXMiLCJmZ 1076 WVkIl0sInN1YiI6InVzZXJAZXhhbXBsZS5uZXQiLCJtYXlfYWN0Ijp7InN1YiI6ImF 1077 kbWluQGV4YW1wbGUubmV0In19.ut0Ll7wm920VzRvuLGLFoPJLeO5DDElxsax1L_xK 1078 Um2eooiNSfuif-OGa2382hPyFYnddKIa0wmDhQksW018Rw 1079 &subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1080 &actor_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwczo 1081 vL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXIuZ 1082 XhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTAwNjAsInN1YiI6ImFkbWluQGV4YW1wbGU 1083 ubmV0In0.7YQ-3zPfhUvzje5oqw8COCvN5uP6NsKik9CVV6cAOf4QKgM-tKfiOwcgZ 1084 oUuDL2tEs6tqPlcBlMjiSzEjm3yBg 1085 &actor_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1087 Figure 14: Token Exchange Request 1089 A.2.2. Subject Token Claims 1091 The "subject_token" in the prior request is a JWT and the decoded JWT 1092 Claims Set is shown here. The JWT is intended for consumption by the 1093 authorization server before a specific expiration time. The subject 1094 of the JWT ("user@example.net") is the party on behalf of whom the 1095 new token is being requested. 1097 { 1098 "aud":"https://as.example.com", 1099 "iss":"https://original-issuer.example.net", 1100 "exp":1441910060, 1101 "scp":["status","feed"], 1102 "sub":"user@example.net", 1103 "may_act": 1104 { 1105 "sub":"admin@example.net" 1106 } 1107 } 1109 Figure 15: Subject Token Claims 1111 A.2.3. Actor Token Claims 1113 The "actor_token" in the prior request is a JWT and the decoded JWT 1114 Claims Set is shown here. This JWT is also intended for consumption 1115 by the authorization server before a specific expiration time. The 1116 subject of the JWT ("admin@example.net") is the actor that will wield 1117 the security token being requested. 1119 { 1120 "aud":"https://as.example.com", 1121 "iss":"https://original-issuer.example.net", 1122 "exp":1441910060, 1123 "sub":"admin@example.net" 1124 } 1126 Figure 16: Actor Token Claims 1128 A.2.4. Token Exchange Response 1130 The "access_token" parameter of the token exchange response shown 1131 below contains the new token that the client requested. The other 1132 parameters of the response indicate that the token is a JWT that 1133 expires in an hour and that the access token type is not applicable 1134 since the issued token is not an access token. 1136 HTTP/1.1 200 OK 1137 Content-Type: application/json 1138 Cache-Control: no-cache, no-store 1140 { 1141 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm4 1142 6ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5l 1143 eGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic2NwIjpbInN0YXR1cyIsImZlZ 1144 WQiXSwic3ViIjoidXNlckBleGFtcGxlLm5ldCIsImFjdCI6eyJzdWIiOiJhZG1pbk 1145 BleGFtcGxlLm5ldCJ9fQ._qjM7Ij_HcrC78omT4jiZTFJOuzsAj1wPo31ymQS-Suq 1146 r64S1jCp6pfQR-in_OOAosAGamEg4jyPsht6kMAiYA", 1147 "issued_token_type":"urn:ietf:params:oauth:token-type:jwt", 1148 "token_type":"N_A", 1149 "expires_in":3600 1150 } 1152 Figure 17: Token Exchange Response 1154 A.2.5. Issued Token Claims 1156 The decoded JWT Claims Set of the issued token is shown below. The 1157 new JWT is issued by the authorization server and intended for 1158 consumption by a system entity known by the logical name 1159 "urn:example:cooperation-context" any time before its expiration. 1160 The subject ("sub") of the JWT is the same as the subject of the 1161 "subject_token" used to make the request. The actor ("act") of the 1162 JWT is the same as the subject of the "actor_token" used to make the 1163 request. This indicates delegation and identifies 1164 "admin@example.net" as the current actor to whom authority has been 1165 delegated to act on behalf of "user@example.net". 1167 { 1168 "aud":"urn:example:cooperation-context", 1169 "iss":"https://as.example.com", 1170 "exp":1441913610, 1171 "scp":["status","feed"], 1172 "sub":"user@example.net", 1173 "act": 1174 { 1175 "sub":"admin@example.net" 1176 } 1177 } 1179 Figure 18: Issued Token Claims 1181 Appendix B. Acknowledgements 1183 This specification was developed within the OAuth Working Group, 1184 which includes dozens of active and dedicated participants. It was 1185 produced under the chairmanship of Hannes Tschofenig and Derek Atkins 1186 with Kathleen Moriarty and Stephen Farrell serving as Security Area 1187 Directors. The following individuals contributed ideas, feedback, 1188 and wording to this specification: 1190 Caleb Baker, Vittorio Bertocci, Thomas Broyer, William Denniss, 1191 Vladimir Dzhuvinov, Phil Hunt, Jason Keglovitz, Adam Lewis, James 1192 Manger, Nov Matake, Matt Miller, Matthew Perry, Justin Richer, Rifaat 1193 Shekh-Yusef, Scott Tomilson, and Hannes Tschofenig. 1195 Appendix C. Document History 1197 [[ to be removed by the RFC Editor before publication as an RFC ]] 1199 -06 1201 o Drop "An STS for the REST of Us" from the title. 1202 o Drop "heavyweight" and "lightweight" from the abstract and 1203 introduction. 1204 o Clarifications on the language around xxxxxx_token_type. 1205 o Remove the want_composite parameter. 1207 o Add a short mention of proof-of-possession style tokens to the 1208 introduction and remove the respective open issue. 1210 -05 1212 o Defined the JWT claim "cid" to express the OAuth 2.0 client 1213 identifier of the client that requested the token. 1214 o Defined and requested registration for "act" and "may_act" as 1215 Token introspection response parameters (in addition to being JWT 1216 claims). 1217 o Loosen up the language about refresh_token in the response to 1218 OPTIONAL from NOT RECOMMENDED based on feedback form real world 1219 deployment experience. 1220 o Add clarifying text about the distinction between JWT and access 1221 token URIs. 1222 o Close out (remove) some of the Open Issues bullets that have been 1223 resolved. 1225 -04 1227 o Clarified that the "resource" and "audience" request parameters 1228 can be used at the same time (via http://www.ietf.org/mail- 1229 archive/web/oauth/current/msg15335.html). 1230 o Clarified subject/actor token validity after token exchange and 1231 explained a bit more about the recommendation to not issue refresh 1232 tokens (via http://www.ietf.org/mail-archive/web/oauth/current/ 1233 msg15318.html). 1234 o Updated the examples appendix to use an issuer value that doesn't 1235 imply that the client issued and signed the tokens and used 1236 "Bearer" and "urn:ietf:params:oauth:token-type:access_token" in 1237 one of the responses (via http://www.ietf.org/mail- 1238 archive/web/oauth/current/msg15335.html). 1239 o Defined and registered urn:ietf:params:oauth:token-type:id_token, 1240 since some use cases perform token exchanges for ID Tokens and no 1241 URI to indicate that a token is an ID Token had previously been 1242 defined. 1244 -03 1246 o Updated the document editors (adding Campbell, Bradley, and 1247 Mortimore). 1248 o Added to the title. 1249 o Added to the abstract and introduction. 1250 o Updated the format of the request to use application/x-www-form- 1251 urlencoded request parameters and the response to use the existing 1252 token endpoint JSON parameters defined in OAuth 2.0. 1253 o Changed the grant type identifier to urn:ietf:params:oauth:grant- 1254 type:token-exchange. 1256 o Added RFC 6755 registration requests for 1257 urn:ietf:params:oauth:token-type:refresh_token, 1258 urn:ietf:params:oauth:token-type:access_token, and 1259 urn:ietf:params:oauth:grant-type:token-exchange. 1260 o Added RFC 6749 registration requests for request/response 1261 parameters. 1262 o Removed the Implementation Considerations and the requirement to 1263 support JWTs. 1264 o Clarified many aspects of the text. 1265 o Changed "on_behalf_of" to "subject_token", 1266 "on_behalf_of_token_type" to "subject_token_type", "act_as" to 1267 "actor_token", and "act_as_token_type" to "actor_token_type". 1268 o Added an "audience" request parameter used to indicate the logical 1269 names of the target services at which the client intends to use 1270 the requested security token. 1271 o Added a "want_composite" request parameter used to indicate the 1272 desire for a composite token rather than trying to infer it from 1273 the presence/absence of token(s) in the request. 1274 o Added a "resource" request parameter used to indicate the URLs of 1275 resources at which the client intends to use the requested 1276 security token. 1277 o Specified that multiple "audience" and "resource" request 1278 parameter values may be used. 1279 o Defined the JWT claim "act" (actor) to express the current actor 1280 or delegation principal. 1281 o Defined the JWT claim "may_act" to express that one party is 1282 authorized to act on behalf of another party. 1283 o Defined the JWT claim "scp" (scopes) to express OAuth 2.0 scope- 1284 token values. 1285 o Added the "N_A" (not applicable) OAuth Access Token Type 1286 definition for use in contexts in which the token exchange syntax 1287 requires a "token_type" value, but in which the token being issued 1288 is not an access token. 1289 o Added examples. 1291 -02 1293 o Enabled use of Security Token types other than JWTs for "act_as" 1294 and "on_behalf_of" request values. 1295 o Referenced the JWT and OAuth Assertions RFCs. 1297 -01 1299 o Updated references. 1301 -00 1302 o Created initial working group draft from draft-jones-oauth-token- 1303 exchange-01. 1305 Authors' Addresses 1307 Michael B. Jones 1308 Microsoft 1310 Email: mbj@microsoft.com 1311 URI: http://self-issued.info/ 1313 Anthony Nadalin 1314 Microsoft 1316 Email: tonynad@microsoft.com 1318 Brian Campbell 1319 Ping Identity 1321 Email: brian.d.campbell@gmail.com 1323 John Bradley 1324 Ping Identity 1326 Email: ve7jtb@ve7jtb.com 1328 Chuck Mortimore 1329 Salesforce 1331 Email: cmortimore@salesforce.com