idnits 2.17.1 draft-ietf-oauth-token-exchange-13.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 (April 23, 2018) is 2188 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: October 25, 2018 B. Campbell, Ed. 6 J. Bradley 7 Ping Identity 8 C. Mortimore 9 Salesforce 10 April 23, 2018 12 OAuth 2.0 Token Exchange 13 draft-ietf-oauth-token-exchange-13 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 https://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 October 25, 2018. 39 Copyright Notice 41 Copyright (c) 2018 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 (https://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 . . . . . . . . . . . . . . . . . . . . . . . 6 60 2. Token Exchange Request and Response . . . . . . . . . . . . . 6 61 2.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 6 62 2.1.1. Relationship Between Resource, Audience and Scope . . 8 63 2.2. Response . . . . . . . . . . . . . . . . . . . . . . . . 9 64 2.2.1. Successful Response . . . . . . . . . . . . . . . . . 9 65 2.2.2. Error Response . . . . . . . . . . . . . . . . . . . 10 66 2.3. Example Token Exchange . . . . . . . . . . . . . . . . . 11 67 3. Token Type Identifiers . . . . . . . . . . . . . . . . . . . 13 68 4. JSON Web Token Claims and Introspection Response Parameters . 14 69 4.1. "act" (Actor) Claim . . . . . . . . . . . . . . . . . . . 14 70 4.2. "scope" (Scopes) Claim . . . . . . . . . . . . . . . . . 16 71 4.3. "client_id" (Client Identifier) Claim . . . . . . . . . . 17 72 4.4. "may_act" (May Act For) Claim . . . . . . . . . . . . . . 17 73 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 74 5.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 18 75 5.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 18 76 5.2. OAuth Parameters Registration . . . . . . . . . . . . . . 19 77 5.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 19 78 5.3. OAuth Access Token Type Registration . . . . . . . . . . 20 79 5.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 20 80 5.4. JSON Web Token Claims Registration . . . . . . . . . . . 20 81 5.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 21 82 5.5. OAuth Token Introspection Response Registration . . . . . 21 83 5.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 21 84 5.6. OAuth Extensions Error Registration . . . . . . . . . . . 21 85 5.6.1. Registry Contents . . . . . . . . . . . . . . . . . . 22 86 6. Security Considerations . . . . . . . . . . . . . . . . . . . 22 87 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 22 88 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 22 89 8.1. Normative References . . . . . . . . . . . . . . . . . . 22 90 8.2. Informative References . . . . . . . . . . . . . . . . . 23 91 Appendix A. Additional Token Exchange Examples . . . . . . . . . 24 92 A.1. Impersonation Token Exchange Example . . . . . . . . . . 24 93 A.1.1. Token Exchange Request . . . . . . . . . . . . . . . 24 94 A.1.2. Subject Token Claims . . . . . . . . . . . . . . . . 25 95 A.1.3. Token Exchange Response . . . . . . . . . . . . . . . 25 96 A.1.4. Issued Token Claims . . . . . . . . . . . . . . . . . 26 98 A.2. Delegation Token Exchange Example . . . . . . . . . . . . 26 99 A.2.1. Token Exchange Request . . . . . . . . . . . . . . . 26 100 A.2.2. Subject Token Claims . . . . . . . . . . . . . . . . 27 101 A.2.3. Actor Token Claims . . . . . . . . . . . . . . . . . 28 102 A.2.4. Token Exchange Response . . . . . . . . . . . . . . . 28 103 A.2.5. Issued Token Claims . . . . . . . . . . . . . . . . . 28 104 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 29 105 Appendix C. Document History . . . . . . . . . . . . . . . . . . 29 106 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 33 108 1. Introduction 110 A security token is a set of information that facilitates the sharing 111 of identity and security information in heterogeneous environments or 112 across security domains. Examples of security tokens include JSON 113 Web Tokens (JWTs) [JWT] and SAML 2.0 Assertions 114 [OASIS.saml-core-2.0-os]. Security tokens are typically signed to 115 achieve integrity and sometimes also encrypted to achieve 116 confidentiality. Security tokens are also sometimes described as 117 Assertions, such as in [RFC7521]. 119 A Security Token Service (STS) is a service capable of validating and 120 issuing security tokens, which enables clients to obtain appropriate 121 access credentials for resources in heterogeneous environments or 122 across security domains. Web Service clients have used WS-Trust 123 [WS-Trust] as the protocol to interact with an STS for token 124 exchange. While WS-Trust uses XML and SOAP, the trend in modern Web 125 development has been towards RESTful patterns and JSON. The OAuth 126 2.0 Authorization Framework [RFC6749] and OAuth 2.0 Bearer Tokens 127 [RFC6750] have emerged as popular standards for authorizing third- 128 party applications access to HTTP and RESTful resources. The 129 conventional OAuth 2.0 interaction involves the exchange of some 130 representation of resource owner authorization for an access token, 131 which has proven to be an extremely useful pattern in practice, 132 however, its input and output are somewhat too constrained as is to 133 fully accommodate a security token exchange framework. 135 This specification defines a protocol extending OAuth 2.0 that 136 enables clients to request and obtain security tokens from 137 authorization servers acting in the role of an STS. Similar to OAuth 138 2.0, this specification focuses on client developer simplicity and 139 requires only an HTTP client and JSON parser, which are nearly 140 universally available in modern development environments. The STS 141 protocol defined in this specification is not itself RESTful (an STS 142 doesn't lend itself particularly well to a REST approach) but does 143 utilize communication patterns and data formats that should be 144 familiar to developers accustomed to working with RESTful systems. 146 A new grant type for a token exchange request and the associated 147 specific parameters for such a request to the token endpoint are 148 defined by this specification. A token exchange response is a normal 149 OAuth 2.0 response from the token endpoint with a few additional 150 parameters defined herein to provide information to the client. 152 The entity that makes the request to exchange tokens is considered 153 the client in the context of the token exchange interaction. 154 However, that does not restrict usage of this profile to traditional 155 OAuth clients. An OAuth resource server, for example, might assume 156 the role of the client during token exchange in order to trade an 157 access token, which it received in a protected resource request, for 158 a new token that is appropriate to include in a call to a backend 159 service. The new token might be an access token that is more 160 narrowly scoped for the downstream service or it could be an entirely 161 different kind of token. 163 The scope of this specification is limited to the definition of a 164 basic request and response protocol for an STS-style token exchange 165 utilizing OAuth 2.0. Although a few new JWT claims are defined that 166 enable delegation semantics to be expressed, the specific syntax, 167 semantics and security characteristics of the tokens themselves (both 168 those presented to the authorization server and those obtained by the 169 client) are explicitly out of scope and no requirements are placed on 170 the trust model in which an implementation might be deployed. 171 Additional profiles may provide more detailed requirements around the 172 specific nature of the parties and trust involved, such as whether 173 signing and/or encryption of tokens is needed or if proof-of- 174 possession style tokens will be required or issued; however, such 175 details will often be policy decisions made with respect to the 176 specific needs of individual deployments and will be configured or 177 implemented accordingly. 179 The security tokens obtained may be used in a number of contexts, the 180 specifics of which are also beyond the scope of this specification. 182 1.1. Delegation vs. Impersonation Semantics 184 When principal A impersonates principal B, A is given all the rights 185 that B has within some defined rights context and is 186 indistinguishable from B in that context. Thus, when principal A 187 impersonates principal B, then in so far as any entity receiving such 188 a token is concerned, they are actually dealing with B. It is true 189 that some members of the identity system might have awareness that 190 impersonation is going on, but it is not a requirement. For all 191 intents and purposes, when A is impersonating B, A is B. 193 Delegation semantics are different than impersonation semantics, 194 though the two are closely related. With delegation semantics, 195 principal A still has its own identity separate from B and it is 196 explicitly understood that while B may have delegated some of its 197 rights to A, any actions taken are being taken by A representing B. 198 In a sense, A is an agent for B. 200 Delegation and impersonation are not inclusive of all situations. 201 When a principal is acting directly on its own behalf, for example, 202 neither delegation nor impersonation are in play. They are, however, 203 the more common semantics operating for token exchange and, as such, 204 are given more direct treatment in this specification. 206 Delegation semantics are typically expressed in a token by including 207 information about both the primary subject of the token as well as 208 the actor to whom that subject has delegated some of its rights. 209 Such a token is sometimes referred to as a composite token because it 210 is composed of information about multiple subjects. Typically, in 211 the request, the "subject_token" represents the identity of the party 212 on behalf of whom the token is being requested while the 213 "actor_token" represents the identity of the party to whom the access 214 rights of the issued token are being delegated. A composite token 215 issued by the authorization server will contain information about 216 both parties. When and if a composite token is issued is at the 217 discretion of the authorization server and applicable policy and 218 configuration. 220 The specifics of representing a composite token and even whether or 221 not such a token will be issued depend on the details of the 222 implementation and the kind of token. The representations of 223 composite tokens that are not JWTs are beyond the scope of this 224 specification. The "actor_token" request parameter, however, does 225 provide a means for providing information about the desired actor and 226 the JWT "act" claim can provide a representation of a chain of 227 delegation. 229 1.2. Requirements Notation and Conventions 231 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 232 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 233 "OPTIONAL" in this document are to be interpreted as described in BCP 234 14 [RFC2119] [RFC8174] when, and only when, they appear in all 235 capitals, as shown here. 237 1.3. Terminology 239 This specification uses the terms "access token type", "authorization 240 server", "client", "client identifier", "resource server", "token 241 endpoint", "token request", and "token response" defined by OAuth 2.0 242 [RFC6749], and the terms "Base64url Encoding", "Claim", and "JWT 243 Claims Set" defined by JSON Web Token (JWT) [JWT]. 245 2. Token Exchange Request and Response 247 2.1. Request 249 A client requests a security token by making a token request to the 250 authorization server's token endpoint using the extension grant type 251 mechanism defined in Section 4.5 of OAuth 2.0 [RFC6749]. 253 Client authentication to the authorization server is done using the 254 normal mechanisms provided by OAuth 2.0. Section 2.3.1 of The OAuth 255 2.0 Authorization Framework [RFC6749] defines password-based 256 authentication of the client, however, client authentication is 257 extensible and other mechanisms are possible. For example, [RFC7523] 258 defines client authentication using JSON Web Tokens (JWTs) [JWT]. 259 The supported methods of client authentication and whether or not to 260 allow unauthenticated or unidentified clients are deployment 261 decisions that are at the discretion of the authorization server. 263 The client makes a token exchange request to the token endpoint with 264 an extension grant type by including the following parameters using 265 the "application/x-www-form-urlencoded" format with a character 266 encoding of UTF-8 in the HTTP request entity-body: 268 grant_type 269 REQUIRED. The value "urn:ietf:params:oauth:grant-type:token- 270 exchange" indicates that a token exchange is being performed. 272 resource 273 OPTIONAL. Indicates the location of the target service or 274 resource where the client intends to use the requested security 275 token. This enables the authorization server to apply policy as 276 appropriate for the target, such as determining the type and 277 content of the token to be issued or if and how the token is to be 278 encrypted. In many cases, a client will not have knowledge of the 279 logical organization of the systems with which it interacts and 280 will only know the location of the service where it intends to use 281 the token. The "resource" parameter allows the client to indicate 282 to the authorization server where it intends to use the issued 283 token by providing the location, typically as an https URL, in the 284 token exchange request in the same form that will be used to 285 access that resource. The authorization server will typically 286 have the capability to map from a resource URI value to an 287 appropriate policy. The value of the "resource" parameter MUST be 288 an absolute URI, as specified by Section 4.3 of [RFC3986], which 289 MAY include a query component and MUST NOT include a fragment 290 component. Multiple "resource" parameters may be used to indicate 291 that the issued token is intended to be used at the multiple 292 resources listed. 294 audience 295 OPTIONAL. The logical name of the target service where the client 296 intends to use the requested security token. This serves a 297 purpose similar to the "resource" parameter, but with the client 298 providing a logical name rather than a location. Interpretation 299 of the name requires that the value be something that both the 300 client and the authorization server understand. An OAuth client 301 identifier, a SAML entity identifier [OASIS.saml-core-2.0-os], an 302 OpenID Connect Issuer Identifier [OpenID.Core], or a URI are 303 examples of things that might be used as "audience" parameter 304 values. Multiple "audience" parameters may be used to indicate 305 that the issued token is intended to be used at the multiple 306 audiences listed. The "audience" and "resource" parameters may be 307 used together to indicate multiple target services with a mix of 308 logical names and locations. 310 scope 311 OPTIONAL. A list of space-delimited, case-sensitive strings, as 312 defined in Section 3.3 of [RFC6749], that allow the client to 313 specify the desired scope of the requested security token in the 314 context of the service or resource where the token will be used. 315 The values and associated semantics of scope are service specific 316 and expected to be described in the relevant service 317 documentation. 319 requested_token_type 320 OPTIONAL. An identifier, as described in Section 3, for the type 321 of the requested security token. If the requested type is 322 unspecified, the issued token type is at the discretion of the 323 authorization server and may be dictated by knowledge of the 324 requirements of the service or resource indicated by the 325 "resource" or "audience" parameter. 327 subject_token 328 REQUIRED. A security token that represents the identity of the 329 party on behalf of whom the request is being made. Typically, the 330 subject of this token will be the subject of the security token 331 issued in response to this request. 333 subject_token_type 334 REQUIRED. An identifier, as described in Section 3, that 335 indicates the type of the security token in the "subject_token" 336 parameter. 338 actor_token 339 OPTIONAL. A security token that represents the identity of the 340 acting party. Typically, this will be the party that is 341 authorized to use the requested security token and act on behalf 342 of the subject. 344 actor_token_type 345 An identifier, as described in Section 3, that indicates the type 346 of the security token in the "actor_token" parameter. This is 347 REQUIRED when the "actor_token" parameter is present in the 348 request but MUST NOT be included otherwise. 350 In processing the request, the authorization sever MUST validate the 351 subject token as appropriate for the indicated token type and, if the 352 actor token is present, also validate it according to its token type. 353 The validity criteria and details of any particular token are beyond 354 the scope of this document and are specific to the respective type of 355 token and its content. 357 In the absence of one-time-use or other semantics specific to the 358 token type, the act of performing a token exchange has no impact on 359 the validity of the subject token or actor token. Furthermore, the 360 validity of the subject token or actor token have no impact on the 361 validity of the issued token after the exchange has occurred. 363 2.1.1. Relationship Between Resource, Audience and Scope 365 When requesting a token, the client can indicate the desired target 366 service(s) where it intends to use that token by way of the 367 "audience" and "resource" parameters, as well as indicating the 368 desired scope of the requested token using the "scope" parameter. 369 The semantics of such a request are that the client is asking for a 370 token with the requested scope that is usable at all the requested 371 target services. Effectively, the requested access rights of the 372 token are the cartesian product of all the scopes at all the target 373 services. 375 An authorization server may be unwilling or unable to fulfill any 376 token request but the likelihood of an unfulfillable request is 377 significantly higher when very broad access rights are being 378 solicited. As such, in the absence of specific knowledge about the 379 relationship of systems in a deployment, clients should exercise 380 discretion in the breadth of the access requested, particularly the 381 number of target services. An authorization server can use the 382 "invalid_target" error code, defined in Section 2.2.2, to inform a 383 client that it requested access to too many target services 384 simultaneously. 386 2.2. Response 388 The authorization server responds to a token exchange request with a 389 normal OAuth 2.0 response from the token endpoint, as specified in 390 Section 5 of [RFC6749]. Additional details and explanation are 391 provided in the following subsections. 393 2.2.1. Successful Response 395 If the request is valid and meets all policy and other criteria of 396 the authorization server, a successful token response is constructed 397 by adding the following parameters to the entity-body of the HTTP 398 response using the "application/json" media type, as specified by 399 [RFC7159], and an HTTP 200 status code. The parameters are 400 serialized into a JavaScript Object Notation (JSON) structure by 401 adding each parameter at the top level. Parameter names and string 402 values are included as JSON strings. Numerical values are included 403 as JSON numbers. The order of parameters does not matter and can 404 vary. 406 access_token 407 REQUIRED. The security token issued by the authorization server 408 in response to the token exchange request. The "access_token" 409 parameter from Section 5.1 of [RFC6749] is used here to carry the 410 requested token, which allows this token exchange protocol to use 411 the existing OAuth 2.0 request and response constructs defined for 412 the token endpoint. The identifier "access_token" is used for 413 historical reasons and the issued token need not be an OAuth 414 access token. 416 issued_token_type 417 REQUIRED. An identifier, as described in Section 3, for the 418 representation of the issued security token. 420 token_type 421 REQUIRED. A case-insensitive value specifying the method of using 422 the access token issued, as specified in Section 7.1 of [RFC6749]. 423 It provides the client with information about how to utilize the 424 access token to access protected resources. For example, a value 425 of "Bearer", as specified in [RFC6750], indicates that the 426 security token is a bearer token and the client can simply present 427 it as is without any additional proof of eligibility beyond the 428 contents of the token itself. Note that the meaning of this 429 parameter is different from the meaning of the "issued_token_type" 430 parameter, which declares the representation of the issued 431 security token; the term "token type" is typically used with this 432 meaning, as it is in all "*_token_type" parameters in this 433 specification. If the issued token is not an access token or 434 usable as an access token, then the "token_type" value "N_A" is 435 used to indicate that an OAuth 2.0 "token_type" identifier is not 436 applicable in that context. 438 expires_in 439 RECOMMENDED. The validity lifetime, in seconds, of the token 440 issued by the authorization server. Oftentimes the client will 441 not have the inclination or capability to inspect the content of 442 the token and this parameter provides a consistent and token type 443 agnostic indication of how long the token can be expected to be 444 valid. For example, the value 1800 denotes that the token will 445 expire in thirty minutes from the time the response was generated. 447 scope 448 OPTIONAL, if the scope of the issued security token is identical 449 to the scope requested by the client; otherwise, REQUIRED. 451 refresh_token 452 OPTIONAL. A refresh token will typically not be issued when the 453 exchange is of one temporary credential (the subject_token) for a 454 different temporary credential (the issued token) for use in some 455 other context. A refresh token can be issued in cases where the 456 client of the token exchange needs the ability to access a 457 resource even when the original credential is no longer valid 458 (e.g., user-not-present or offline scenarios where there is no 459 longer any user entertaining an active session with the client). 460 Profiles or deployments of this specification should clearly 461 document the conditions under which a client should expect a 462 refresh token in response to "urn:ietf:params:oauth:grant- 463 type:token-exchange" grant type requests. 465 2.2.2. Error Response 467 IF the request itself is not valid or if either the "subject_token" 468 or "actor_token" are invalid for any reason, or are unacceptable 469 based on policy, the authorization server MUST construct an error 470 response, as specified in Section 5.2 of [RFC6749]. The value of the 471 "error" parameter MUST be the "invalid_request" error code. 473 If the authorization server is unwilling or unable to issue a token 474 for all the target services indicated by the "resource" or "audience" 475 parameters, the "invalid_target" error code SHOULD be used in the 476 error response. 478 The authorization server MAY include additional information regarding 479 the reasons for the error using the "error_description" and/or 480 "error_uri" parameters. 482 Other error codes may also be used, as appropriate. 484 2.3. Example Token Exchange 486 The following example demonstrates a hypothetical token exchange in 487 which an OAuth resource server assumes the role of the client during 488 token exchange in order to trade an access token that it received in 489 a protected resource request for a token that it will use to call to 490 a backend service (extra line breaks and indentation in the examples 491 are for display purposes only). 493 The resource server receives the following request containing an 494 OAuth access token in the Authorization request header, as specified 495 in Section 2.1 of [RFC6750]. 497 GET /resource HTTP/1.1 498 Host: frontend.example.com 499 Authorization: Bearer accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC 501 Figure 1: Protected Resource Request 503 The resource server assumes the role of the client for the token 504 exchange and the access token from the request above is sent to the 505 authorization server using a request as specified in Section 2.1. 506 The value of the "subject_token" parameter carries the access token 507 and the value of the "subject_token_type" parameter indicates that it 508 is an OAuth 2.0 access token. The resource server, acting in the 509 role of the client, uses its identifier and secret to authenticate to 510 the authorization server using the HTTP Basic authentication scheme. 511 The "resource" parameter indicates the location of the backend 512 service, https://backend.example.com/api, where the issued token will 513 be used. 515 POST /as/token.oauth2 HTTP/1.1 516 Host: as.example.com 517 Authorization: Basic cnMwODpsb25nLXNlY3VyZS1yYW5kb20tc2VjcmV0 518 Content-Type: application/x-www-form-urlencoded 520 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 521 &resource=https%3A%2F%2Fbackend.example.com%2Fapi%20 522 &subject_token=accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC 523 &subject_token_type= 524 urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token 526 Figure 2: Token Exchange Request 528 The authorization server validates the client credentials and the 529 "subject_token" presented in the token exchange request. From the 530 "resource" parameter, the authorization server is able to determine 531 the appropriate policy to apply to the request and issues a token 532 suitable for use at https://backend.example.com. The "access_token" 533 parameter of the response contains the new token, which is itself a 534 bearer OAuth access token that is valid for one minute. The token 535 happens to be a JWT; however, its structure and format are opaque to 536 the client so the "issued_token_type" indicates only that it is an 537 access token. 539 HTTP/1.1 200 OK 540 Content-Type: application/json 541 Cache-Control: no-cache, no-store 543 { 544 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQiOiJo 545 dHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2FzLmV 546 4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1MzMsIn 547 N1YiI6ImJjQGV4YW1wbGUuY29tIiwic2NvcGUiOiJhcGkifQ.K4Ik-igqOKi_4C 548 nBu4dG3-gGUObfgv-rJhgXVDNOWW_MHgVwddhgVLLQf_bm3xlpQM6wHrLbMaZC4 549 LicsQC23g", 550 "issued_token_type": 551 "urn:ietf:params:oauth:token-type:access_token", 552 "token_type":"Bearer", 553 "expires_in":60 554 } 556 Figure 3: Token Exchange Response 558 The resource server can then use the newly acquired access token in 559 making a request to the backend server. 561 GET /api HTTP/1.1 562 Host: backend.example.com 563 Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQ 564 iOiJodHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2 565 FzLmV4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1M 566 zMsInN1YiI6ImJjQGV4YW1wbGUuY29tIiwic2NwIjpbImFwaSJdfQ.MXgnpvPMo 567 0nhcePwnQbunD2gw_pDyCFA-Saobl6gyLAdyPbaALFuAOyFc4XTWaPEnHV_LGmX 568 klSTpz0yC7hlSQ 570 Figure 4: Backend Protected Resource Request 572 Additional examples can be found in Appendix A. 574 3. Token Type Identifiers 576 Several parameters in this specification utilize an identifier as the 577 value to describe the token in question. Specifically, they are the 578 "requested_token_type", "subject_token_type", "actor_token_type" 579 parameters of the request and the "issued_token_type" member of the 580 response. Token type identifiers are URIs. Token Exchange can work 581 with both tokens issued by other parties and tokens from the given 582 authorization server. For the former the token type identifier 583 indicates the syntax (e.g., JWT or SAML 2.0) so the authorization 584 server can parse it; for the latter it indicates what the given 585 authorization server issued it for (e.g., access_token or 586 refresh_token). 588 The following token type identifiers are defined by this 589 specification. Other URIs MAY be used to indicate other token types. 591 urn:ietf:params:oauth:token-type:access_token 592 Indicates that the token is an OAuth 2.0 access token issued by 593 the given authorization server. 595 urn:ietf:params:oauth:token-type:refresh_token 596 Indicates that the token is an OAuth 2.0 refreshe token issued by 597 the given authorization server. 599 urn:ietf:params:oauth:token-type:id_token 600 Indicates that the token is an ID Token, as defined in Section 2 601 of [OpenID.Core]. 603 urn:ietf:params:oauth:token-type:saml1 604 Indicates that the token is a base64url-encoded SAML 1.1 605 [OASIS.saml-core-1.1] assertion. 607 urn:ietf:params:oauth:token-type:saml2 608 Indicates that the token is a base64url-encoded SAML 2.0 609 [OASIS.saml-core-2.0-os] assertion. 611 The value "urn:ietf:params:oauth:token-type:jwt", which is defined in 612 Section 9 of [JWT], indicates that the token is a JWT. 614 The distinction between an access token and a JWT is subtle. An 615 access token represents a delegated authorization decision, whereas 616 JWT is a token format. An access token can be formatted as a JWT but 617 doesn't necessarily have to be. And a JWT might well be an access 618 token but not all JWTs are access tokens. The intent of this 619 specification is that "urn:ietf:params:oauth:token-type:access_token" 620 be an indicator that the token is a typical OAuth access token issued 621 by the authorization server in question, opaque to the client, and 622 usable the same manner as any other access token obtained from that 623 authorization server. (It could well be a JWT, but the client isn't 624 and needn't be aware of that fact.) Whereas, 625 "urn:ietf:params:oauth:token-type:jwt" is to indicate specifically 626 that a JWT is being requested or sent (perhaps in a cross-domain use- 627 case where the JWT is used as an authorization grant to obtain an 628 access token from a different authorization server as is facilitated 629 by [RFC7523]). 631 4. JSON Web Token Claims and Introspection Response Parameters 633 It is useful to have defined mechanisms to express delegation within 634 a token as well as to express authorization to delegate or 635 impersonate. Although the token exchange protocol described herein 636 can be used with any type of token, this section defines claims to 637 express such semantics specifically for JWTs and in an OAuth 2.0 638 Token Introspection [RFC7662] response. Similar definitions for 639 other types of tokens are possible but beyond the scope of this 640 specification. 642 Note that the claims not established herein but used in examples and 643 descriptions, such as "iss", "sub", "exp", etc., are defined by 644 [JWT]. 646 4.1. "act" (Actor) Claim 648 The "act" (actor) claim provides a means within a JWT to express that 649 delegation has occurred and identify the acting party to whom 650 authority has been delegated. The "act" claim value is a JSON object 651 and members in the JSON object are claims that identify the actor. 652 The claims that make up the "act" claim identify and possibly provide 653 additional information about the actor. For example, the combination 654 of the two claims "iss" and "sub" might be necessary to uniquely 655 identify an actor. 657 However, claims within the "act" claim pertain only to the identity 658 of the actor and are not relevant to the validity of the containing 659 JWT in the same manner as the top-level claims. Consequently, non- 660 identity claims (e.g., "exp", "nbf", and "aud") are not meaningful 661 when used within an "act" claim, and therefore must not be used. 663 The following example illustrates the "act" (actor) claim within a 664 JWT Claims Set. The claims of the token itself are about 665 user@example.com while the "act" claim indicates that 666 admin@example.com is the current actor. 668 { 669 "aud":"https://consumer.example.com", 670 "iss":"https://issuer.example.com", 671 "exp":1443904177, 672 "nbf":1443904077, 673 "sub":"user@example.com", 674 "act": 675 { 676 "sub":"admin@example.com" 677 } 678 } 680 Figure 5: Actor Claim 682 A chain of delegation can be expressed by nesting one "act" claim 683 within another. The outermost "act" claim represents the current 684 actor while nested "act" claims represent prior actors. The least 685 recent actor is the most deeply nested. 687 The following example illustrates nested "act" (actor) claims within 688 a JWT Claims Set. The claims of the token itself are about 689 user@example.com while the "act" claim indicates that the system 690 consumer.example.com-web-application is the current actor and 691 admin@example.com was a prior actor. Such a token might come about 692 as the result of the web application receiving a token like the one 693 in the previous example and exchanging it for a new token that lists 694 it as the current actor and that can be used at 695 https://backend.example.com. 697 { 698 "aud":"https://backend.example.com", 699 "iss":"https://issuer.example.com", 700 "exp":1443904100, 701 "nbf":1443904000, 702 "sub":"user@example.com", 703 "act": 704 { 705 "sub":"consumer.example.com-web-application", 706 "iss":"https://issuer.example.net", 707 "act": 708 { 709 "sub":"admin@example.com" 710 } 711 } 712 } 714 Figure 6: Nested Actor Claim 716 When included as a top-level member of an OAuth token introspection 717 response, "act" has the same semantics and format as the claim of the 718 same name. 720 4.2. "scope" (Scopes) Claim 722 The value of the "scope" claim is a JSON string containing a space- 723 separated list of scopes associated with the token, in the format 724 described in Section 3.3 of OAuth 2.0 [RFC6749]. 726 The following example illustrates the "scope" claim within a JWT 727 Claims Set. 729 { 730 "aud":"https://consumer.example.com", 731 "iss":"https://issuer.example.com", 732 "exp":1443904177, 733 "nbf":1443904077, 734 "sub":"dgaf4mvfs75Fci_FL3heQA", 735 "scope":"email profile phone address" 736 } 738 Figure 7: Scopes Claim 740 OAuth 2.0 Token Introspection [RFC7662] already defines the "scope" 741 parameter to convey the scopes associated with the token. 743 4.3. "client_id" (Client Identifier) Claim 745 The "client_id" claim carries the client identifier of the OAuth 2.0 746 [RFC6749] client that requested the token. 748 The following example illustrates the "client_id" claim within a JWT 749 Claims Set indicating an OAuth 2.0 client with "s6BhdRkqt3" as its 750 identifier. 752 { 753 "aud":"https://consumer.example.com", 754 "iss":"https://issuer.example.com", 755 "exp":1443904177, 756 "sub":"user@example.com", 757 "client_id":"s6BhdRkqt3" 758 } 760 Figure 8: Client Identifier Claim 762 OAuth 2.0 Token Introspection [RFC7662] already defines the 763 "client_id" parameter as the client identifier for the OAuth 2.0 764 client that requested the token. 766 4.4. "may_act" (May Act For) Claim 768 The "may_act" claim makes a statement that one party is authorized to 769 become the actor and act on behalf of another party. The claim value 770 is a JSON object and members in the JSON object are claims that 771 identify the party that is asserted as being eligible to act for the 772 party identified by the JWT containing the claim. The claims that 773 make up the "may_act" claim identify and possibly provide additional 774 information about the authorized actor. For example, the combination 775 of the two claims "iss" and "sub" are sometimes necessary to uniquely 776 identify an authorized actor, while the "email" claim might be used 777 to provide additional useful information about that party. 779 However, claims within the "may_act" claim pertain only to the 780 identity of that party and are not relevant to the validity of the 781 containing JWT in the same manner as top-level claims. Consequently, 782 claims such as "exp", "nbf", and "aud" are not meaningful when used 783 within a "may_act" claim, and therefore should not be used. 785 The following example illustrates the "may_act" claim within a JWT 786 Claims Set. The claims of the token itself are about 787 user@example.com while the "may_act" claim indicates that 788 admin@example.com is authorized to act on behalf of user@example.com. 790 { 791 "aud":"https://consumer.example.com", 792 "iss":"https://issuer.example.com", 793 "exp":1443904177, 794 "nbf":1443904077, 795 "sub":"user@example.com", 796 "may_act": 797 { 798 "sub":"admin@example.com" 799 } 800 } 802 Figure 9: May Act For Claim 804 When included as a top-level member of an OAuth token introspection 805 response, "may_act" has the same semantics and format as the claim of 806 the same name. 808 5. IANA Considerations 810 5.1. OAuth URI Registration 812 This specification registers the following values in the IANA "OAuth 813 URI" registry [IANA.OAuth.Parameters] established by [RFC6755]. 815 5.1.1. Registry Contents 817 o URN: urn:ietf:params:oauth:grant-type:token-exchange 818 o Common Name: Token exchange grant type for OAuth 2.0 819 o Change controller: IESG 820 o Specification Document: Section 2.1 of [[ this specification ]] 821 o URN: urn:ietf:params:oauth:token-type:access_token 822 o Common Name: Token type URI for an OAuth 2.0 access token 823 o Change controller: IESG 824 o Specification Document: Section 3 of [[this specification]] 826 o URN: urn:ietf:params:oauth:token-type:refresh_token 827 o Common Name: Token type URI for an OAuth 2.0 refresh token 828 o Change controller: IESG 829 o Specification Document: Section 3 of [[this specification]] 831 o URN: urn:ietf:params:oauth:token-type:id_token 832 o Common Name: Token type URI for an ID Token 833 o Change controller: IESG 834 o Specification Document: Section 3 of [[this specification]] 836 o URN: urn:ietf:params:oauth:token-type:saml1 837 o Common Name: Token type URI for a base64url-encoded SAML 1.1 838 assertion 839 o Change Controller: IESG 840 o Specification Document: Section 3 of [[this specification]] 842 o URN: urn:ietf:params:oauth:token-type:saml2 843 o Common Name: Token type URI for a base64url-encoded SAML 2.0 844 assertion 845 o Change Controller: IESG 846 o Specification Document: Section 3 of [[this specification]] 848 5.2. OAuth Parameters Registration 850 This specification registers the following values in the IANA "OAuth 851 Parameters" registry [IANA.OAuth.Parameters] established by 852 [RFC6749]. 854 5.2.1. Registry Contents 856 o Parameter name: resource 857 o Parameter usage location: token request 858 o Change controller: IESG 859 o Specification document(s): Section 2.1 of [[ this specification ]] 861 o Parameter name: audience 862 o Parameter usage location: token request 863 o Change controller: IESG 864 o Specification document(s): Section 2.1 of [[ this specification ]] 866 o Parameter name: requested_token_type 867 o Parameter usage location: token request 868 o Change controller: IESG 869 o Specification document(s): Section 2.1 of [[ this specification ]] 871 o Parameter name: subject_token 872 o Parameter usage location: token request 873 o Change controller: IESG 874 o Specification document(s): Section 2.1 of [[ this specification ]] 876 o Parameter name: subject_token_type 877 o Parameter usage location: token request 878 o Change controller: IESG 879 o Specification document(s): Section 2.1 of [[ this specification ]] 881 o Parameter name: actor_token 882 o Parameter usage location: token request 883 o Change controller: IESG 884 o Specification document(s): Section 2.1 of [[ this specification ]] 886 o Parameter name: actor_token_type 887 o Parameter usage location: token request 888 o Change controller: IESG 889 o Specification document(s): Section 2.1 of [[ this specification ]] 891 o Parameter name: issued_token_type 892 o Parameter usage location: token response 893 o Change controller: IESG 894 o Specification document(s): Section 2.2.1 of [[ this specification 895 ]] 897 5.3. OAuth Access Token Type Registration 899 This specification registers the following access token type in the 900 IANA "OAuth Access Token Types" registry [IANA.OAuth.Parameters] 901 established by [RFC6749]. 903 5.3.1. Registry Contents 905 o Type name: N_A 906 o Additional Token Endpoint Response Parameters: (none) 907 o HTTP Authentication Scheme(s): (none) 908 o Change controller: IESG 909 o Specification document(s): Section 2.2.1 of [[ this specification 910 ]] 912 5.4. JSON Web Token Claims Registration 914 This specification registers the following Claims in the IANA "JSON 915 Web Token Claims" registry [IANA.JWT.Claims] established by [JWT]. 917 5.4.1. Registry Contents 919 o Claim Name: "act" 920 o Claim Description: Actor 921 o Change Controller: IESG 922 o Specification Document(s): Section 4.1 of [[ this specification ]] 924 o Claim Name: "scope" 925 o Claim Description: Scope Values 926 o Change Controller: IESG 927 o Specification Document(s): Section 4.2 of [[ this specification ]] 929 o Claim Name: "client_id" 930 o Claim Description: Client Identifier 931 o Change Controller: IESG 932 o Specification Document(s): Section 4.3 of [[ this specification ]] 934 o Claim Name: "may_act" 935 o Claim Description: May Act For 936 o Change Controller: IESG 937 o Specification Document(s): Section 4.4 of [[ this specification ]] 939 5.5. OAuth Token Introspection Response Registration 941 This specification registers the following values in the IANA "OAuth 942 Token Introspection Response" registry [IANA.OAuth.Parameters] 943 established by [RFC7662]. 945 5.5.1. Registry Contents 947 o Claim Name: "act" 948 o Claim Description: Actor 949 o Change Controller: IESG 950 o Specification Document(s): Section 4.1 of [[ this specification ]] 952 o Claim Name: "may_act" 953 o Claim Description: May Act For 954 o Change Controller: IESG 955 o Specification Document(s): Section 4.4 of [[ this specification ]] 957 5.6. OAuth Extensions Error Registration 959 This specification registers the following values in the IANA "OAuth 960 Extensions Error" registry [IANA.OAuth.Parameters] established by 961 [RFC6749]. 963 5.6.1. Registry Contents 965 o Error Name: "invalid_target" 966 o Error Usage Location: token error response 967 o Related Protocol Extension: OAuth 2.0 Token Exchange 968 o Change Controller: IETF 969 o Specification Document(s): Section 2.2.2 of [[ this specification 970 ]] 972 6. Security Considerations 974 All of the normal security issues that are discussed in [JWT], 975 especially in relationship to comparing URIs and dealing with 976 unrecognized values, also apply here. 978 In addition, both delegation and impersonation introduce unique 979 security issues. Any time one principal is delegated the rights of 980 another principal, the potential for abuse is a concern. The use of 981 the "scope" claim is suggested to mitigate potential for such abuse, 982 as it restricts the contexts in which the delegated rights can be 983 exercised. 985 7. Privacy Considerations 987 Tokens typically carry personal information and their usage in Token 988 Exchange may reveal details of the target services being accessed. 989 As such, tokens should only be requested and sent according to the 990 privacy policies at the respective organizations. 992 8. References 994 8.1. Normative References 996 [IANA.JWT.Claims] 997 IANA, "JSON Web Token Claims", 998 . 1000 [IANA.OAuth.Parameters] 1001 IANA, "OAuth Parameters", 1002 . 1004 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1005 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1006 . 1008 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1009 Requirement Levels", BCP 14, RFC 2119, 1010 DOI 10.17487/RFC2119, March 1997, 1011 . 1013 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1014 Resource Identifier (URI): Generic Syntax", STD 66, 1015 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1016 . 1018 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1019 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1020 . 1022 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1023 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1024 2014, . 1026 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 1027 RFC 7662, DOI 10.17487/RFC7662, October 2015, 1028 . 1030 8.2. Informative References 1032 [OASIS.saml-core-1.1] 1033 Maler, E., Mishra, P., and R. Philpott, "Assertions and 1034 Protocol for the OASIS Security Assertion Markup Language 1035 (SAML) V1.1", OASIS Standard oasis-sstc-saml-core-1.1, 1036 September 2003. 1038 [OASIS.saml-core-2.0-os] 1039 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 1040 "Assertions and Protocol for the OASIS Security Assertion 1041 Markup Language (SAML) V2.0", OASIS Standard saml-core- 1042 2.0-os, March 2005. 1044 [OpenID.Core] 1045 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 1046 C. Mortimore, "OpenID Connect Core 1.0", August 2015, 1047 . 1049 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1050 Framework: Bearer Token Usage", RFC 6750, 1051 DOI 10.17487/RFC6750, October 2012, 1052 . 1054 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 1055 for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, 1056 . 1058 [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 1059 "Assertion Framework for OAuth 2.0 Client Authentication 1060 and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, 1061 May 2015, . 1063 [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 1064 (JWT) Profile for OAuth 2.0 Client Authentication and 1065 Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 1066 2015, . 1068 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1069 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1070 May 2017, . 1072 [WS-Trust] 1073 Nadalin, A., Goodner, M., Gudgin, M., Barbir, A., and H. 1074 Granqvist, "WS-Trust 1.4", February 2012, 1075 . 1078 Appendix A. Additional Token Exchange Examples 1080 Two example token exchanges are provided in the following sections 1081 illustrating impersonation and delegation, respectively (with extra 1082 line breaks and indentation for display purposes only). 1084 A.1. Impersonation Token Exchange Example 1086 A.1.1. Token Exchange Request 1088 In the following token exchange request, a client is requesting a 1089 token with impersonation semantics. The client tells the 1090 authorization server that it needs a token for use at the target 1091 service with the logical name "urn:example:cooperation-context". 1093 POST /as/token.oauth2 HTTP/1.1 1094 Host: as.example.com 1095 Content-Type: application/x-www-form-urlencoded 1097 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 1098 &audience=urn%3Aexample%3Acooperation-context 1099 &subject_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwc 1100 zovL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXI 1101 uZXhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTA2MDAsIm5iZiI6MTQ0MTkwOTAwMCwic 1102 3ViIjoiYmNAZXhhbXBsZS5uZXQiLCJzY29wZSI6Im9yZGVycyBwcm9maWxlIGhpc3R 1103 vcnkifQ.u0slqvbnqU43EvI_itGdFJ11StrAwXlxczYfMYsaR5p4J_gBp019mxljSx 1104 xmD3FfbrjTGyZ4eDh1JKJVpsnnPg 1105 &subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1107 Figure 10: Token Exchange Request 1109 A.1.2. Subject Token Claims 1111 The "subject_token" in the prior request is a JWT and the decoded JWT 1112 Claims Set is shown here. The JWT is intended for consumption by the 1113 authorization server within a specific time window. The subject of 1114 the JWT ("bc@example.net") is the party on behalf of whom the new 1115 token is being requested. 1117 { 1118 "aud":"https://as.example.com", 1119 "iss":"https://original-issuer.example.net", 1120 "exp":1441910600, 1121 "nbf":1441909000, 1122 "sub":"bc@example.net", 1123 "scope":"orders profile history" 1124 } 1126 Figure 11: Subject Token Claims 1128 A.1.3. 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 bearer access 1133 token that expires in an hour. 1135 HTTP/1.1 200 OK 1136 Content-Type: application/json 1137 Cache-Control: no-cache, no-store 1139 { 1140 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm4 1141 6ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5l 1142 eGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic3ViIjoiYmNAZXhhbXBsZS5uZ 1143 XQiLCJzY29wZSI6Im9yZGVycyBwcm9maWxlIGhpc3RvcnkifQ._OnH9oHT2cd0-Sz 1144 OfBrNkVYlRdn48X8kI4_Is3LHeQmtkd-nDdR63IuuQ_GeZd7UafMV3bk8jqUDgi-l 1145 rTfSwA", 1146 "issued_token_type": 1147 "urn:ietf:params:oauth:token-type:access_token", 1148 "token_type":"Bearer", 1149 "expires_in":3600 1150 } 1152 Figure 12: Token Exchange Response 1154 A.1.4. 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 the token 1161 used to make the request, which effectively enables the client to 1162 impersonate that subject at the system entity known by the logical 1163 name of "urn:example:cooperation-context" by using the token. 1165 { 1166 "aud":"urn:example:cooperation-context", 1167 "iss":"https://as.example.com", 1168 "exp":1441913610, 1169 "sub":"bc@example.net", 1170 "scope":"orders profile history" 1171 } 1173 Figure 13: Issued Token Claims 1175 A.2. Delegation Token Exchange Example 1177 A.2.1. Token Exchange Request 1179 In the following token exchange request, a client is requesting a 1180 token and providing both a "subject_token" and an "actor_token". The 1181 client tells the authorization server that it needs a token for use 1182 at the target service with the logical name "urn:example:cooperation- 1183 context". Policy at the authorization server dictates that the 1184 issued token be a composite. 1186 POST /as/token.oauth2 HTTP/1.1 1187 Host: as.example.com 1188 Content-Type: application/x-www-form-urlencoded 1190 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 1191 &audience=urn%3Aexample%3Acooperation-context 1192 &subject_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwc 1193 zovL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXI 1194 uZXhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTAwNjAsInNjb3BlIjoic3RhdHVzIGZlZ 1195 WQiLCJzdWIiOiJ1c2VyQGV4YW1wbGUubmV0IiwibWF5X2FjdCI6eyJzdWIiOiJhZG1 1196 pbkBleGFtcGxlLm5ldCJ9fQ.4rPRSWihQbpMIgAmAoqaJojAxj-p2X8_fAtAGTXrvM 1197 xU-eEZHnXqY0_AOZgLdxw5DyLzua8H_I10MCcckF-Q_g 1198 &subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1199 &actor_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwczo 1200 vL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXIuZ 1201 XhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTAwNjAsInN1YiI6ImFkbWluQGV4YW1wbGU 1202 ubmV0In0.7YQ-3zPfhUvzje5oqw8COCvN5uP6NsKik9CVV6cAOf4QKgM-tKfiOwcgZ 1203 oUuDL2tEs6tqPlcBlMjiSzEjm3yBg 1204 &actor_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1206 Figure 14: Token Exchange Request 1208 A.2.2. Subject Token Claims 1210 The "subject_token" in the prior request is a JWT and the decoded JWT 1211 Claims Set is shown here. The JWT is intended for consumption by the 1212 authorization server before a specific expiration time. The subject 1213 of the JWT ("user@example.net") is the party on behalf of whom the 1214 new token is being requested. 1216 { 1217 "aud":"https://as.example.com", 1218 "iss":"https://original-issuer.example.net", 1219 "exp":1441910060, 1220 "scope":"status feed", 1221 "sub":"user@example.net", 1222 "may_act": 1223 { 1224 "sub":"admin@example.net" 1225 } 1226 } 1228 Figure 15: Subject Token Claims 1230 A.2.3. Actor Token Claims 1232 The "actor_token" in the prior request is a JWT and the decoded JWT 1233 Claims Set is shown here. This JWT is also intended for consumption 1234 by the authorization server before a specific expiration time. The 1235 subject of the JWT ("admin@example.net") is the actor that will wield 1236 the security token being requested. 1238 { 1239 "aud":"https://as.example.com", 1240 "iss":"https://original-issuer.example.net", 1241 "exp":1441910060, 1242 "sub":"admin@example.net" 1243 } 1245 Figure 16: Actor Token Claims 1247 A.2.4. Token Exchange Response 1249 The "access_token" parameter of the token exchange response shown 1250 below contains the new token that the client requested. The other 1251 parameters of the response indicate that the token is a JWT that 1252 expires in an hour and that the access token type is not applicable 1253 since the issued token is not an access token. 1255 HTTP/1.1 200 OK 1256 Content-Type: application/json 1257 Cache-Control: no-cache, no-store 1259 { 1260 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm4 1261 6ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5l 1262 eGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic2NvcGUiOiJzdGF0dXMgZmVlZ 1263 CIsInN1YiI6InVzZXJAZXhhbXBsZS5uZXQiLCJhY3QiOnsic3ViIjoiYWRtaW5AZX 1264 hhbXBsZS5uZXQifX0.3paKl9UySKYB5ng6_cUtQ2qlO8Rc_y7Mea7IwEXTcYbNdwG 1265 9-G1EKCFe5fW3H0hwX-MSZ49Wpcb1SiAZaOQBtw", 1266 "issued_token_type":"urn:ietf:params:oauth:token-type:jwt", 1267 "token_type":"N_A", 1268 "expires_in":3600 1269 } 1271 Figure 17: Token Exchange Response 1273 A.2.5. Issued Token Claims 1275 The decoded JWT Claims Set of the issued token is shown below. The 1276 new JWT is issued by the authorization server and intended for 1277 consumption by a system entity known by the logical name 1278 "urn:example:cooperation-context" any time before its expiration. 1279 The subject ("sub") of the JWT is the same as the subject of the 1280 "subject_token" used to make the request. The actor ("act") of the 1281 JWT is the same as the subject of the "actor_token" used to make the 1282 request. This indicates delegation and identifies 1283 "admin@example.net" as the current actor to whom authority has been 1284 delegated to act on behalf of "user@example.net". 1286 { 1287 "aud":"urn:example:cooperation-context", 1288 "iss":"https://as.example.com", 1289 "exp":1441913610, 1290 "scope":"status feed", 1291 "sub":"user@example.net", 1292 "act": 1293 { 1294 "sub":"admin@example.net" 1295 } 1296 } 1298 Figure 18: Issued Token Claims 1300 Appendix B. Acknowledgements 1302 This specification was developed within the OAuth Working Group, 1303 which includes dozens of active and dedicated participants. It was 1304 produced under the chairmanship of Hannes Tschofenig, Derek Atkins, 1305 and Rifaat Shekh-Yusef with Kathleen Moriarty, Stephen Farrell, and 1306 Eric Rescorla serving as Security Area Directors. The following 1307 individuals contributed ideas, feedback, and wording to this 1308 specification: 1310 Caleb Baker, Vittorio Bertocci, Thomas Broyer, William Denniss, 1311 Vladimir Dzhuvinov, Phil Hunt, Benjamin Kaduk, Jason Keglovitz, 1312 Torsten Lodderstedt, Adam Lewis, James Manger, Nov Matake, Matt 1313 Miller, Matthew Perry, Eric Rescorla, Justin Richer, Rifaat Shekh- 1314 Yusef, Scott Tomilson, and Hannes Tschofenig. 1316 Appendix C. Document History 1318 [[ to be removed by the RFC Editor before publication as an RFC ]] 1320 -13 1322 o Updated the claim name and value syntax for scope to be consistent 1323 with the treatment of scope in RFC 7662 OAuth 2.0 Token 1324 Introspection. 1326 o Updated the client identifier claim name to be consistent with the 1327 treatment of client id in RFC 7662 OAuth 2.0 Token Introspection. 1329 -12 1331 o Updated to use the boilerplate from RFC 8174. 1333 -11 1335 o Added new WG chair and AD to the Acknowledgements. 1336 o Applied clarifications suggested during AD review by EKR. 1338 -10 1340 o Defined token type URIs for base64url-encoded SAML 1.1 and SAML 1341 2.0 assertions. 1342 o Applied editorial fixes. 1344 -09 1346 o Changed "security tokens obtained could be used in a number of 1347 contexts" to "security tokens obtained may be used in a number of 1348 contexts" per a WGLC suggestion. 1349 o Clarified that the validity of the subject or actor token have no 1350 impact on the validity of the issued token after the exchange has 1351 occurred per a WGLC comment. 1352 o Changed use of invalid_target error code to a SHOULD per a WGLC 1353 comment. 1354 o Clarified text about non-identity claims within the "act" claim 1355 being meaningless per a WGLC comment. 1356 o Added brief Privacy Considerations section per WGLC comments. 1358 -08 1360 o Use the bibxml reference for OpenID.Core rather than defining it 1361 inline. 1362 o Added editor role for Campbell. 1363 o Minor clarification of the text for actor_token. 1365 -07 1367 o Fixed typo (desecration -> discretion). 1368 o Added an explanation of the relationship between scope, audience 1369 and resource in the request and added an "invalid_target" error 1370 code enabling the AS to tell the client that the requested 1371 audiences/resources were too broad. 1373 -06 1374 o Drop "An STS for the REST of Us" from the title. 1375 o Drop "heavyweight" and "lightweight" from the abstract and 1376 introduction. 1377 o Clarifications on the language around xxxxxx_token_type. 1378 o Remove the want_composite parameter. 1379 o Add a short mention of proof-of-possession style tokens to the 1380 introduction and remove the respective open issue. 1382 -05 1384 o Defined the JWT claim "cid" to express the OAuth 2.0 client 1385 identifier of the client that requested the token. 1386 o Defined and requested registration for "act" and "may_act" as 1387 Token introspection response parameters (in addition to being JWT 1388 claims). 1389 o Loosen up the language about refresh_token in the response to 1390 OPTIONAL from NOT RECOMMENDED based on feedback form real world 1391 deployment experience. 1392 o Add clarifying text about the distinction between JWT and access 1393 token URIs. 1394 o Close out (remove) some of the Open Issues bullets that have been 1395 resolved. 1397 -04 1399 o Clarified that the "resource" and "audience" request parameters 1400 can be used at the same time (via http://www.ietf.org/mail- 1401 archive/web/oauth/current/msg15335.html). 1402 o Clarified subject/actor token validity after token exchange and 1403 explained a bit more about the recommendation to not issue refresh 1404 tokens (via http://www.ietf.org/mail-archive/web/oauth/current/ 1405 msg15318.html). 1406 o Updated the examples appendix to use an issuer value that doesn't 1407 imply that the client issued and signed the tokens and used 1408 "Bearer" and "urn:ietf:params:oauth:token-type:access_token" in 1409 one of the responses (via http://www.ietf.org/mail- 1410 archive/web/oauth/current/msg15335.html). 1411 o Defined and registered urn:ietf:params:oauth:token-type:id_token, 1412 since some use cases perform token exchanges for ID Tokens and no 1413 URI to indicate that a token is an ID Token had previously been 1414 defined. 1416 -03 1418 o Updated the document editors (adding Campbell, Bradley, and 1419 Mortimore). 1420 o Added to the title. 1421 o Added to the abstract and introduction. 1423 o Updated the format of the request to use application/x-www-form- 1424 urlencoded request parameters and the response to use the existing 1425 token endpoint JSON parameters defined in OAuth 2.0. 1426 o Changed the grant type identifier to urn:ietf:params:oauth:grant- 1427 type:token-exchange. 1428 o Added RFC 6755 registration requests for 1429 urn:ietf:params:oauth:token-type:refresh_token, 1430 urn:ietf:params:oauth:token-type:access_token, and 1431 urn:ietf:params:oauth:grant-type:token-exchange. 1432 o Added RFC 6749 registration requests for request/response 1433 parameters. 1434 o Removed the Implementation Considerations and the requirement to 1435 support JWTs. 1436 o Clarified many aspects of the text. 1437 o Changed "on_behalf_of" to "subject_token", 1438 "on_behalf_of_token_type" to "subject_token_type", "act_as" to 1439 "actor_token", and "act_as_token_type" to "actor_token_type". 1440 o Added an "audience" request parameter used to indicate the logical 1441 names of the target services at which the client intends to use 1442 the requested security token. 1443 o Added a "want_composite" request parameter used to indicate the 1444 desire for a composite token rather than trying to infer it from 1445 the presence/absence of token(s) in the request. 1446 o Added a "resource" request parameter used to indicate the URLs of 1447 resources at which the client intends to use the requested 1448 security token. 1449 o Specified that multiple "audience" and "resource" request 1450 parameter values may be used. 1451 o Defined the JWT claim "act" (actor) to express the current actor 1452 or delegation principal. 1453 o Defined the JWT claim "may_act" to express that one party is 1454 authorized to act on behalf of another party. 1455 o Defined the JWT claim "scp" (scopes) to express OAuth 2.0 scope- 1456 token values. 1457 o Added the "N_A" (not applicable) OAuth Access Token Type 1458 definition for use in contexts in which the token exchange syntax 1459 requires a "token_type" value, but in which the token being issued 1460 is not an access token. 1461 o Added examples. 1463 -02 1465 o Enabled use of Security Token types other than JWTs for "act_as" 1466 and "on_behalf_of" request values. 1467 o Referenced the JWT and OAuth Assertions RFCs. 1469 -01 1470 o Updated references. 1472 -00 1474 o Created initial working group draft from draft-jones-oauth-token- 1475 exchange-01. 1477 Authors' Addresses 1479 Michael B. Jones 1480 Microsoft 1482 Email: mbj@microsoft.com 1483 URI: http://self-issued.info/ 1485 Anthony Nadalin 1486 Microsoft 1488 Email: tonynad@microsoft.com 1490 Brian Campbell (editor) 1491 Ping Identity 1493 Email: brian.d.campbell@gmail.com 1495 John Bradley 1496 Ping Identity 1498 Email: ve7jtb@ve7jtb.com 1500 Chuck Mortimore 1501 Salesforce 1503 Email: cmortimore@salesforce.com