idnits 2.17.1 draft-ietf-oauth-token-exchange-14.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 (June 4, 2018) is 2153 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: December 6, 2018 B. Campbell, Ed. 6 J. Bradley 7 Ping Identity 8 C. Mortimore 9 Salesforce 10 June 4, 2018 12 OAuth 2.0 Token Exchange 13 draft-ietf-oauth-token-exchange-14 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 December 6, 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 For the purpose of applying access control policy, the consumer of a 688 token MUST only consider the token's top-level claims and the party 689 identified as the current actor by the "act" claim. Prior actors 690 identified by any nested "act" claims are informational only and are 691 not to be considered in access control decisions. 693 The following example illustrates nested "act" (actor) claims within 694 a JWT Claims Set. The claims of the token itself are about 695 user@example.com while the "act" claim indicates that the system 696 consumer.example.com-web-application is the current actor and 697 admin@example.com was a prior actor. Such a token might come about 698 as the result of the web application receiving a token like the one 699 in the previous example and exchanging it for a new token that lists 700 it as the current actor and that can be used at 701 https://backend.example.com. 703 { 704 "aud":"https://backend.example.com", 705 "iss":"https://issuer.example.com", 706 "exp":1443904100, 707 "nbf":1443904000, 708 "sub":"user@example.com", 709 "act": 710 { 711 "sub":"consumer.example.com-web-application", 712 "iss":"https://issuer.example.net", 713 "act": 714 { 715 "sub":"admin@example.com" 716 } 717 } 718 } 720 Figure 6: Nested Actor Claim 722 When included as a top-level member of an OAuth token introspection 723 response, "act" has the same semantics and format as the claim of the 724 same name. 726 4.2. "scope" (Scopes) Claim 728 The value of the "scope" claim is a JSON string containing a space- 729 separated list of scopes associated with the token, in the format 730 described in Section 3.3 of OAuth 2.0 [RFC6749]. 732 The following example illustrates the "scope" claim within a JWT 733 Claims Set. 735 { 736 "aud":"https://consumer.example.com", 737 "iss":"https://issuer.example.com", 738 "exp":1443904177, 739 "nbf":1443904077, 740 "sub":"dgaf4mvfs75Fci_FL3heQA", 741 "scope":"email profile phone address" 742 } 744 Figure 7: Scopes Claim 746 OAuth 2.0 Token Introspection [RFC7662] already defines the "scope" 747 parameter to convey the scopes associated with the token. 749 4.3. "client_id" (Client Identifier) Claim 751 The "client_id" claim carries the client identifier of the OAuth 2.0 752 [RFC6749] client that requested the token. 754 The following example illustrates the "client_id" claim within a JWT 755 Claims Set indicating an OAuth 2.0 client with "s6BhdRkqt3" as its 756 identifier. 758 { 759 "aud":"https://consumer.example.com", 760 "iss":"https://issuer.example.com", 761 "exp":1443904177, 762 "sub":"user@example.com", 763 "client_id":"s6BhdRkqt3" 764 } 766 Figure 8: Client Identifier Claim 768 OAuth 2.0 Token Introspection [RFC7662] already defines the 769 "client_id" parameter as the client identifier for the OAuth 2.0 770 client that requested the token. 772 4.4. "may_act" (May Act For) Claim 774 The "may_act" claim makes a statement that one party is authorized to 775 become the actor and act on behalf of another party. The claim value 776 is a JSON object and members in the JSON object are claims that 777 identify the party that is asserted as being eligible to act for the 778 party identified by the JWT containing the claim. The claims that 779 make up the "may_act" claim identify and possibly provide additional 780 information about the authorized actor. For example, the combination 781 of the two claims "iss" and "sub" are sometimes necessary to uniquely 782 identify an authorized actor, while the "email" claim might be used 783 to provide additional useful information about that party. 785 However, claims within the "may_act" claim pertain only to the 786 identity of that party and are not relevant to the validity of the 787 containing JWT in the same manner as top-level claims. Consequently, 788 claims such as "exp", "nbf", and "aud" are not meaningful when used 789 within a "may_act" claim, and therefore should not be used. 791 The following example illustrates the "may_act" claim within a JWT 792 Claims Set. The claims of the token itself are about 793 user@example.com while the "may_act" claim indicates that 794 admin@example.com is authorized to act on behalf of user@example.com. 796 { 797 "aud":"https://consumer.example.com", 798 "iss":"https://issuer.example.com", 799 "exp":1443904177, 800 "nbf":1443904077, 801 "sub":"user@example.com", 802 "may_act": 803 { 804 "sub":"admin@example.com" 805 } 806 } 808 Figure 9: May Act For Claim 810 When included as a top-level member of an OAuth token introspection 811 response, "may_act" has the same semantics and format as the claim of 812 the same name. 814 5. IANA Considerations 816 5.1. OAuth URI Registration 818 This specification registers the following values in the IANA "OAuth 819 URI" registry [IANA.OAuth.Parameters] established by [RFC6755]. 821 5.1.1. Registry Contents 823 o URN: urn:ietf:params:oauth:grant-type:token-exchange 824 o Common Name: Token exchange grant type for OAuth 2.0 825 o Change controller: IESG 826 o Specification Document: Section 2.1 of [[ this specification ]] 827 o URN: urn:ietf:params:oauth:token-type:access_token 828 o Common Name: Token type URI for an OAuth 2.0 access token 829 o Change controller: IESG 830 o Specification Document: Section 3 of [[this specification]] 832 o URN: urn:ietf:params:oauth:token-type:refresh_token 833 o Common Name: Token type URI for an OAuth 2.0 refresh token 834 o Change controller: IESG 835 o Specification Document: Section 3 of [[this specification]] 837 o URN: urn:ietf:params:oauth:token-type:id_token 838 o Common Name: Token type URI for an ID Token 839 o Change controller: IESG 840 o Specification Document: Section 3 of [[this specification]] 842 o URN: urn:ietf:params:oauth:token-type:saml1 843 o Common Name: Token type URI for a base64url-encoded SAML 1.1 844 assertion 845 o Change Controller: IESG 846 o Specification Document: Section 3 of [[this specification]] 848 o URN: urn:ietf:params:oauth:token-type:saml2 849 o Common Name: Token type URI for a base64url-encoded SAML 2.0 850 assertion 851 o Change Controller: IESG 852 o Specification Document: Section 3 of [[this specification]] 854 5.2. OAuth Parameters Registration 856 This specification registers the following values in the IANA "OAuth 857 Parameters" registry [IANA.OAuth.Parameters] established by 858 [RFC6749]. 860 5.2.1. Registry Contents 862 o Parameter name: resource 863 o Parameter usage location: token request 864 o Change controller: IESG 865 o Specification document(s): Section 2.1 of [[ this specification ]] 867 o Parameter name: audience 868 o Parameter usage location: token request 869 o Change controller: IESG 870 o Specification document(s): Section 2.1 of [[ this specification ]] 872 o Parameter name: requested_token_type 873 o Parameter usage location: token request 874 o Change controller: IESG 875 o Specification document(s): Section 2.1 of [[ this specification ]] 877 o Parameter name: subject_token 878 o Parameter usage location: token request 879 o Change controller: IESG 880 o Specification document(s): Section 2.1 of [[ this specification ]] 882 o Parameter name: subject_token_type 883 o Parameter usage location: token request 884 o Change controller: IESG 885 o Specification document(s): Section 2.1 of [[ this specification ]] 887 o Parameter name: actor_token 888 o Parameter usage location: token request 889 o Change controller: IESG 890 o Specification document(s): Section 2.1 of [[ this specification ]] 892 o Parameter name: actor_token_type 893 o Parameter usage location: token request 894 o Change controller: IESG 895 o Specification document(s): Section 2.1 of [[ this specification ]] 897 o Parameter name: issued_token_type 898 o Parameter usage location: token response 899 o Change controller: IESG 900 o Specification document(s): Section 2.2.1 of [[ this specification 901 ]] 903 5.3. OAuth Access Token Type Registration 905 This specification registers the following access token type in the 906 IANA "OAuth Access Token Types" registry [IANA.OAuth.Parameters] 907 established by [RFC6749]. 909 5.3.1. Registry Contents 911 o Type name: N_A 912 o Additional Token Endpoint Response Parameters: (none) 913 o HTTP Authentication Scheme(s): (none) 914 o Change controller: IESG 915 o Specification document(s): Section 2.2.1 of [[ this specification 916 ]] 918 5.4. JSON Web Token Claims Registration 920 This specification registers the following Claims in the IANA "JSON 921 Web Token Claims" registry [IANA.JWT.Claims] established by [JWT]. 923 5.4.1. Registry Contents 925 o Claim Name: "act" 926 o Claim Description: Actor 927 o Change Controller: IESG 928 o Specification Document(s): Section 4.1 of [[ this specification ]] 930 o Claim Name: "scope" 931 o Claim Description: Scope Values 932 o Change Controller: IESG 933 o Specification Document(s): Section 4.2 of [[ this specification ]] 935 o Claim Name: "client_id" 936 o Claim Description: Client Identifier 937 o Change Controller: IESG 938 o Specification Document(s): Section 4.3 of [[ this specification ]] 940 o Claim Name: "may_act" 941 o Claim Description: May Act For 942 o Change Controller: IESG 943 o Specification Document(s): Section 4.4 of [[ this specification ]] 945 5.5. OAuth Token Introspection Response Registration 947 This specification registers the following values in the IANA "OAuth 948 Token Introspection Response" registry [IANA.OAuth.Parameters] 949 established by [RFC7662]. 951 5.5.1. Registry Contents 953 o Claim Name: "act" 954 o Claim Description: Actor 955 o Change Controller: IESG 956 o Specification Document(s): Section 4.1 of [[ this specification ]] 958 o Claim Name: "may_act" 959 o Claim Description: May Act For 960 o Change Controller: IESG 961 o Specification Document(s): Section 4.4 of [[ this specification ]] 963 5.6. OAuth Extensions Error Registration 965 This specification registers the following values in the IANA "OAuth 966 Extensions Error" registry [IANA.OAuth.Parameters] established by 967 [RFC6749]. 969 5.6.1. Registry Contents 971 o Error Name: "invalid_target" 972 o Error Usage Location: token error response 973 o Related Protocol Extension: OAuth 2.0 Token Exchange 974 o Change Controller: IETF 975 o Specification Document(s): Section 2.2.2 of [[ this specification 976 ]] 978 6. Security Considerations 980 All of the normal security issues that are discussed in [JWT], 981 especially in relationship to comparing URIs and dealing with 982 unrecognized values, also apply here. 984 In addition, both delegation and impersonation introduce unique 985 security issues. Any time one principal is delegated the rights of 986 another principal, the potential for abuse is a concern. The use of 987 the "scope" claim is suggested to mitigate potential for such abuse, 988 as it restricts the contexts in which the delegated rights can be 989 exercised. 991 7. Privacy Considerations 993 Tokens typically carry personal information and their usage in Token 994 Exchange may reveal details of the target services being accessed. 995 As such, tokens should only be requested and sent according to the 996 privacy policies at the respective organizations. 998 8. References 1000 8.1. Normative References 1002 [IANA.JWT.Claims] 1003 IANA, "JSON Web Token Claims", 1004 . 1006 [IANA.OAuth.Parameters] 1007 IANA, "OAuth Parameters", 1008 . 1010 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1011 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1012 . 1014 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1015 Requirement Levels", BCP 14, RFC 2119, 1016 DOI 10.17487/RFC2119, March 1997, 1017 . 1019 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1020 Resource Identifier (URI): Generic Syntax", STD 66, 1021 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1022 . 1024 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1025 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1026 . 1028 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1029 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1030 2014, . 1032 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 1033 RFC 7662, DOI 10.17487/RFC7662, October 2015, 1034 . 1036 8.2. Informative References 1038 [OASIS.saml-core-1.1] 1039 Maler, E., Mishra, P., and R. Philpott, "Assertions and 1040 Protocol for the OASIS Security Assertion Markup Language 1041 (SAML) V1.1", OASIS Standard oasis-sstc-saml-core-1.1, 1042 September 2003. 1044 [OASIS.saml-core-2.0-os] 1045 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 1046 "Assertions and Protocol for the OASIS Security Assertion 1047 Markup Language (SAML) V2.0", OASIS Standard saml-core- 1048 2.0-os, March 2005. 1050 [OpenID.Core] 1051 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 1052 C. Mortimore, "OpenID Connect Core 1.0", August 2015, 1053 . 1055 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1056 Framework: Bearer Token Usage", RFC 6750, 1057 DOI 10.17487/RFC6750, October 2012, 1058 . 1060 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 1061 for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, 1062 . 1064 [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 1065 "Assertion Framework for OAuth 2.0 Client Authentication 1066 and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, 1067 May 2015, . 1069 [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 1070 (JWT) Profile for OAuth 2.0 Client Authentication and 1071 Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 1072 2015, . 1074 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1075 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1076 May 2017, . 1078 [WS-Trust] 1079 Nadalin, A., Goodner, M., Gudgin, M., Barbir, A., and H. 1080 Granqvist, "WS-Trust 1.4", February 2012, 1081 . 1084 Appendix A. Additional Token Exchange Examples 1086 Two example token exchanges are provided in the following sections 1087 illustrating impersonation and delegation, respectively (with extra 1088 line breaks and indentation for display purposes only). 1090 A.1. Impersonation Token Exchange Example 1092 A.1.1. Token Exchange Request 1094 In the following token exchange request, a client is requesting a 1095 token with impersonation semantics. The client tells the 1096 authorization server that it needs a token for use at the target 1097 service with the logical name "urn:example:cooperation-context". 1099 POST /as/token.oauth2 HTTP/1.1 1100 Host: as.example.com 1101 Content-Type: application/x-www-form-urlencoded 1103 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 1104 &audience=urn%3Aexample%3Acooperation-context 1105 &subject_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwc 1106 zovL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXI 1107 uZXhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTA2MDAsIm5iZiI6MTQ0MTkwOTAwMCwic 1108 3ViIjoiYmNAZXhhbXBsZS5uZXQiLCJzY29wZSI6Im9yZGVycyBwcm9maWxlIGhpc3R 1109 vcnkifQ.u0slqvbnqU43EvI_itGdFJ11StrAwXlxczYfMYsaR5p4J_gBp019mxljSx 1110 xmD3FfbrjTGyZ4eDh1JKJVpsnnPg 1111 &subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1113 Figure 10: Token Exchange Request 1115 A.1.2. Subject Token Claims 1117 The "subject_token" in the prior request is a JWT and the decoded JWT 1118 Claims Set is shown here. The JWT is intended for consumption by the 1119 authorization server within a specific time window. The subject of 1120 the JWT ("bc@example.net") is the party on behalf of whom the new 1121 token is being requested. 1123 { 1124 "aud":"https://as.example.com", 1125 "iss":"https://original-issuer.example.net", 1126 "exp":1441910600, 1127 "nbf":1441909000, 1128 "sub":"bc@example.net", 1129 "scope":"orders profile history" 1130 } 1132 Figure 11: Subject Token Claims 1134 A.1.3. Token Exchange Response 1136 The "access_token" parameter of the token exchange response shown 1137 below contains the new token that the client requested. The other 1138 parameters of the response indicate that the token is a bearer access 1139 token that expires in an hour. 1141 HTTP/1.1 200 OK 1142 Content-Type: application/json 1143 Cache-Control: no-cache, no-store 1145 { 1146 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm4 1147 6ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5l 1148 eGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic3ViIjoiYmNAZXhhbXBsZS5uZ 1149 XQiLCJzY29wZSI6Im9yZGVycyBwcm9maWxlIGhpc3RvcnkifQ._OnH9oHT2cd0-Sz 1150 OfBrNkVYlRdn48X8kI4_Is3LHeQmtkd-nDdR63IuuQ_GeZd7UafMV3bk8jqUDgi-l 1151 rTfSwA", 1152 "issued_token_type": 1153 "urn:ietf:params:oauth:token-type:access_token", 1154 "token_type":"Bearer", 1155 "expires_in":3600 1156 } 1158 Figure 12: Token Exchange Response 1160 A.1.4. Issued Token Claims 1162 The decoded JWT Claims Set of the issued token is shown below. The 1163 new JWT is issued by the authorization server and intended for 1164 consumption by a system entity known by the logical name 1165 "urn:example:cooperation-context" any time before its expiration. 1166 The subject ("sub") of the JWT is the same as the subject the token 1167 used to make the request, which effectively enables the client to 1168 impersonate that subject at the system entity known by the logical 1169 name of "urn:example:cooperation-context" by using the token. 1171 { 1172 "aud":"urn:example:cooperation-context", 1173 "iss":"https://as.example.com", 1174 "exp":1441913610, 1175 "sub":"bc@example.net", 1176 "scope":"orders profile history" 1177 } 1179 Figure 13: Issued Token Claims 1181 A.2. Delegation Token Exchange Example 1183 A.2.1. Token Exchange Request 1185 In the following token exchange request, a client is requesting a 1186 token and providing both a "subject_token" and an "actor_token". The 1187 client tells the authorization server that it needs a token for use 1188 at the target service with the logical name "urn:example:cooperation- 1189 context". Policy at the authorization server dictates that the 1190 issued token be a composite. 1192 POST /as/token.oauth2 HTTP/1.1 1193 Host: as.example.com 1194 Content-Type: application/x-www-form-urlencoded 1196 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 1197 &audience=urn%3Aexample%3Acooperation-context 1198 &subject_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwc 1199 zovL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXI 1200 uZXhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTAwNjAsInNjb3BlIjoic3RhdHVzIGZlZ 1201 WQiLCJzdWIiOiJ1c2VyQGV4YW1wbGUubmV0IiwibWF5X2FjdCI6eyJzdWIiOiJhZG1 1202 pbkBleGFtcGxlLm5ldCJ9fQ.4rPRSWihQbpMIgAmAoqaJojAxj-p2X8_fAtAGTXrvM 1203 xU-eEZHnXqY0_AOZgLdxw5DyLzua8H_I10MCcckF-Q_g 1204 &subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1205 &actor_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwczo 1206 vL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXIuZ 1207 XhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTAwNjAsInN1YiI6ImFkbWluQGV4YW1wbGU 1208 ubmV0In0.7YQ-3zPfhUvzje5oqw8COCvN5uP6NsKik9CVV6cAOf4QKgM-tKfiOwcgZ 1209 oUuDL2tEs6tqPlcBlMjiSzEjm3yBg 1210 &actor_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1212 Figure 14: Token Exchange Request 1214 A.2.2. Subject Token Claims 1216 The "subject_token" in the prior request is a JWT and the decoded JWT 1217 Claims Set is shown here. The JWT is intended for consumption by the 1218 authorization server before a specific expiration time. The subject 1219 of the JWT ("user@example.net") is the party on behalf of whom the 1220 new token is being requested. 1222 { 1223 "aud":"https://as.example.com", 1224 "iss":"https://original-issuer.example.net", 1225 "exp":1441910060, 1226 "scope":"status feed", 1227 "sub":"user@example.net", 1228 "may_act": 1229 { 1230 "sub":"admin@example.net" 1231 } 1232 } 1234 Figure 15: Subject Token Claims 1236 A.2.3. Actor Token Claims 1238 The "actor_token" in the prior request is a JWT and the decoded JWT 1239 Claims Set is shown here. This JWT is also intended for consumption 1240 by the authorization server before a specific expiration time. The 1241 subject of the JWT ("admin@example.net") is the actor that will wield 1242 the security token being requested. 1244 { 1245 "aud":"https://as.example.com", 1246 "iss":"https://original-issuer.example.net", 1247 "exp":1441910060, 1248 "sub":"admin@example.net" 1249 } 1251 Figure 16: Actor Token Claims 1253 A.2.4. Token Exchange Response 1255 The "access_token" parameter of the token exchange response shown 1256 below contains the new token that the client requested. The other 1257 parameters of the response indicate that the token is a JWT that 1258 expires in an hour and that the access token type is not applicable 1259 since the issued token is not an access token. 1261 HTTP/1.1 200 OK 1262 Content-Type: application/json 1263 Cache-Control: no-cache, no-store 1265 { 1266 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm4 1267 6ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5l 1268 eGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic2NvcGUiOiJzdGF0dXMgZmVlZ 1269 CIsInN1YiI6InVzZXJAZXhhbXBsZS5uZXQiLCJhY3QiOnsic3ViIjoiYWRtaW5AZX 1270 hhbXBsZS5uZXQifX0.3paKl9UySKYB5ng6_cUtQ2qlO8Rc_y7Mea7IwEXTcYbNdwG 1271 9-G1EKCFe5fW3H0hwX-MSZ49Wpcb1SiAZaOQBtw", 1272 "issued_token_type":"urn:ietf:params:oauth:token-type:jwt", 1273 "token_type":"N_A", 1274 "expires_in":3600 1275 } 1277 Figure 17: Token Exchange Response 1279 A.2.5. Issued Token Claims 1281 The decoded JWT Claims Set of the issued token is shown below. The 1282 new JWT is issued by the authorization server and intended for 1283 consumption by a system entity known by the logical name 1284 "urn:example:cooperation-context" any time before its expiration. 1285 The subject ("sub") of the JWT is the same as the subject of the 1286 "subject_token" used to make the request. The actor ("act") of the 1287 JWT is the same as the subject of the "actor_token" used to make the 1288 request. This indicates delegation and identifies 1289 "admin@example.net" as the current actor to whom authority has been 1290 delegated to act on behalf of "user@example.net". 1292 { 1293 "aud":"urn:example:cooperation-context", 1294 "iss":"https://as.example.com", 1295 "exp":1441913610, 1296 "scope":"status feed", 1297 "sub":"user@example.net", 1298 "act": 1299 { 1300 "sub":"admin@example.net" 1301 } 1302 } 1304 Figure 18: Issued Token Claims 1306 Appendix B. Acknowledgements 1308 This specification was developed within the OAuth Working Group, 1309 which includes dozens of active and dedicated participants. It was 1310 produced under the chairmanship of Hannes Tschofenig, Derek Atkins, 1311 and Rifaat Shekh-Yusef with Kathleen Moriarty, Stephen Farrell, and 1312 Eric Rescorla serving as Security Area Directors. The following 1313 individuals contributed ideas, feedback, and wording to this 1314 specification: 1316 Caleb Baker, Vittorio Bertocci, Thomas Broyer, William Denniss, 1317 Vladimir Dzhuvinov, Phil Hunt, Benjamin Kaduk, Jason Keglovitz, 1318 Torsten Lodderstedt, Adam Lewis, James Manger, Nov Matake, Matt 1319 Miller, Matthew Perry, Eric Rescorla, Justin Richer, Rifaat Shekh- 1320 Yusef, Scott Tomilson, and Hannes Tschofenig. 1322 Appendix C. Document History 1324 [[ to be removed by the RFC Editor before publication as an RFC ]] 1326 -14 1328 o Added text in Section 4.1 about the "act" claim stating that only 1329 the top-level claims and the current actor are to be considered in 1330 applying access control decisions. 1332 -13 1334 o Updated the claim name and value syntax for scope to be consistent 1335 with the treatment of scope in RFC 7662 OAuth 2.0 Token 1336 Introspection. 1337 o Updated the client identifier claim name to be consistent with the 1338 treatment of client id in RFC 7662 OAuth 2.0 Token Introspection. 1340 -12 1342 o Updated to use the boilerplate from RFC 8174. 1344 -11 1346 o Added new WG chair and AD to the Acknowledgements. 1347 o Applied clarifications suggested during AD review by EKR. 1349 -10 1351 o Defined token type URIs for base64url-encoded SAML 1.1 and SAML 1352 2.0 assertions. 1353 o Applied editorial fixes. 1355 -09 1357 o Changed "security tokens obtained could be used in a number of 1358 contexts" to "security tokens obtained may be used in a number of 1359 contexts" per a WGLC suggestion. 1360 o Clarified that the validity of the subject or actor token have no 1361 impact on the validity of the issued token after the exchange has 1362 occurred per a WGLC comment. 1363 o Changed use of invalid_target error code to a SHOULD per a WGLC 1364 comment. 1365 o Clarified text about non-identity claims within the "act" claim 1366 being meaningless per a WGLC comment. 1367 o Added brief Privacy Considerations section per WGLC comments. 1369 -08 1371 o Use the bibxml reference for OpenID.Core rather than defining it 1372 inline. 1373 o Added editor role for Campbell. 1374 o Minor clarification of the text for actor_token. 1376 -07 1378 o Fixed typo (desecration -> discretion). 1380 o Added an explanation of the relationship between scope, audience 1381 and resource in the request and added an "invalid_target" error 1382 code enabling the AS to tell the client that the requested 1383 audiences/resources were too broad. 1385 -06 1387 o Drop "An STS for the REST of Us" from the title. 1388 o Drop "heavyweight" and "lightweight" from the abstract and 1389 introduction. 1390 o Clarifications on the language around xxxxxx_token_type. 1391 o Remove the want_composite parameter. 1392 o Add a short mention of proof-of-possession style tokens to the 1393 introduction and remove the respective open issue. 1395 -05 1397 o Defined the JWT claim "cid" to express the OAuth 2.0 client 1398 identifier of the client that requested the token. 1399 o Defined and requested registration for "act" and "may_act" as 1400 Token introspection response parameters (in addition to being JWT 1401 claims). 1402 o Loosen up the language about refresh_token in the response to 1403 OPTIONAL from NOT RECOMMENDED based on feedback form real world 1404 deployment experience. 1405 o Add clarifying text about the distinction between JWT and access 1406 token URIs. 1407 o Close out (remove) some of the Open Issues bullets that have been 1408 resolved. 1410 -04 1412 o Clarified that the "resource" and "audience" request parameters 1413 can be used at the same time (via http://www.ietf.org/mail- 1414 archive/web/oauth/current/msg15335.html). 1415 o Clarified subject/actor token validity after token exchange and 1416 explained a bit more about the recommendation to not issue refresh 1417 tokens (via http://www.ietf.org/mail-archive/web/oauth/current/ 1418 msg15318.html). 1419 o Updated the examples appendix to use an issuer value that doesn't 1420 imply that the client issued and signed the tokens and used 1421 "Bearer" and "urn:ietf:params:oauth:token-type:access_token" in 1422 one of the responses (via http://www.ietf.org/mail- 1423 archive/web/oauth/current/msg15335.html). 1424 o Defined and registered urn:ietf:params:oauth:token-type:id_token, 1425 since some use cases perform token exchanges for ID Tokens and no 1426 URI to indicate that a token is an ID Token had previously been 1427 defined. 1429 -03 1431 o Updated the document editors (adding Campbell, Bradley, and 1432 Mortimore). 1433 o Added to the title. 1434 o Added to the abstract and introduction. 1435 o Updated the format of the request to use application/x-www-form- 1436 urlencoded request parameters and the response to use the existing 1437 token endpoint JSON parameters defined in OAuth 2.0. 1438 o Changed the grant type identifier to urn:ietf:params:oauth:grant- 1439 type:token-exchange. 1440 o Added RFC 6755 registration requests for 1441 urn:ietf:params:oauth:token-type:refresh_token, 1442 urn:ietf:params:oauth:token-type:access_token, and 1443 urn:ietf:params:oauth:grant-type:token-exchange. 1444 o Added RFC 6749 registration requests for request/response 1445 parameters. 1446 o Removed the Implementation Considerations and the requirement to 1447 support JWTs. 1448 o Clarified many aspects of the text. 1449 o Changed "on_behalf_of" to "subject_token", 1450 "on_behalf_of_token_type" to "subject_token_type", "act_as" to 1451 "actor_token", and "act_as_token_type" to "actor_token_type". 1452 o Added an "audience" request parameter used to indicate the logical 1453 names of the target services at which the client intends to use 1454 the requested security token. 1455 o Added a "want_composite" request parameter used to indicate the 1456 desire for a composite token rather than trying to infer it from 1457 the presence/absence of token(s) in the request. 1458 o Added a "resource" request parameter used to indicate the URLs of 1459 resources at which the client intends to use the requested 1460 security token. 1461 o Specified that multiple "audience" and "resource" request 1462 parameter values may be used. 1463 o Defined the JWT claim "act" (actor) to express the current actor 1464 or delegation principal. 1465 o Defined the JWT claim "may_act" to express that one party is 1466 authorized to act on behalf of another party. 1467 o Defined the JWT claim "scp" (scopes) to express OAuth 2.0 scope- 1468 token values. 1469 o Added the "N_A" (not applicable) OAuth Access Token Type 1470 definition for use in contexts in which the token exchange syntax 1471 requires a "token_type" value, but in which the token being issued 1472 is not an access token. 1473 o Added examples. 1475 -02 1476 o Enabled use of Security Token types other than JWTs for "act_as" 1477 and "on_behalf_of" request values. 1478 o Referenced the JWT and OAuth Assertions RFCs. 1480 -01 1482 o Updated references. 1484 -00 1486 o Created initial working group draft from draft-jones-oauth-token- 1487 exchange-01. 1489 Authors' Addresses 1491 Michael B. Jones 1492 Microsoft 1494 Email: mbj@microsoft.com 1495 URI: http://self-issued.info/ 1497 Anthony Nadalin 1498 Microsoft 1500 Email: tonynad@microsoft.com 1502 Brian Campbell (editor) 1503 Ping Identity 1505 Email: brian.d.campbell@gmail.com 1507 John Bradley 1508 Ping Identity 1510 Email: ve7jtb@ve7jtb.com 1512 Chuck Mortimore 1513 Salesforce 1515 Email: cmortimore@salesforce.com