idnits 2.17.1 draft-ietf-oauth-token-exchange-16.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 19, 2018) is 2016 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: April 22, 2019 B. Campbell, Ed. 6 J. Bradley 7 Ping Identity 8 C. Mortimore 9 Salesforce 10 October 19, 2018 12 OAuth 2.0 Token Exchange 13 draft-ietf-oauth-token-exchange-16 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 April 22, 2019. 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. Security Considerations . . . . . . . . . . . . . . . . . . . 18 74 6. Privacy Considerations . . . . . . . . . . . . . . . . . . . 19 75 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 76 7.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 19 77 7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 19 78 7.2. OAuth Parameters Registration . . . . . . . . . . . . . . 20 79 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 20 80 7.3. OAuth Access Token Type Registration . . . . . . . . . . 21 81 7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 21 82 7.4. JSON Web Token Claims Registration . . . . . . . . . . . 21 83 7.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 21 84 7.5. OAuth Token Introspection Response Registration . . . . . 22 85 7.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 22 86 7.6. OAuth Extensions Error Registration . . . . . . . . . . . 22 87 7.6.1. Registry Contents . . . . . . . . . . . . . . . . . . 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 https://service16.example.com is the current actor and 697 https://service77.example.com was a prior actor. Such a token might 698 come about as the result of service16 receiving a token in a call 699 from service77 and exchanging it for a token suitable to call 700 service26 while the authorization server notes the situation in the 701 newly issued token. 703 { 704 "aud":"https://service26.example.com", 705 "iss":"https://issuer.example.com", 706 "exp":1443904100, 707 "nbf":1443904000, 708 "sub":"user@example.com", 709 "act": 710 { 711 "sub":"https://service16.example.com", 712 "act": 713 { 714 "sub":"https://service77.example.com", 715 } 716 } 717 } 719 Figure 6: Nested Actor Claim 721 When included as a top-level member of an OAuth token introspection 722 response, "act" has the same semantics and format as the claim of the 723 same name. 725 4.2. "scope" (Scopes) Claim 727 The value of the "scope" claim is a JSON string containing a space- 728 separated list of scopes associated with the token, in the format 729 described in Section 3.3 of OAuth 2.0 [RFC6749]. 731 The following example illustrates the "scope" claim within a JWT 732 Claims Set. 734 { 735 "aud":"https://consumer.example.com", 736 "iss":"https://issuer.example.com", 737 "exp":1443904177, 738 "nbf":1443904077, 739 "sub":"dgaf4mvfs75Fci_FL3heQA", 740 "scope":"email profile phone address" 741 } 743 Figure 7: Scopes Claim 745 OAuth 2.0 Token Introspection [RFC7662] already defines the "scope" 746 parameter to convey the scopes associated with the token. 748 4.3. "client_id" (Client Identifier) Claim 750 The "client_id" claim carries the client identifier of the OAuth 2.0 751 [RFC6749] client that requested the token. 753 The following example illustrates the "client_id" claim within a JWT 754 Claims Set indicating an OAuth 2.0 client with "s6BhdRkqt3" as its 755 identifier. 757 { 758 "aud":"https://consumer.example.com", 759 "iss":"https://issuer.example.com", 760 "exp":1443904177, 761 "sub":"user@example.com", 762 "client_id":"s6BhdRkqt3" 763 } 765 Figure 8: Client Identifier Claim 767 OAuth 2.0 Token Introspection [RFC7662] already defines the 768 "client_id" parameter as the client identifier for the OAuth 2.0 769 client that requested the token. 771 4.4. "may_act" (May Act For) Claim 773 The "may_act" claim makes a statement that one party is authorized to 774 become the actor and act on behalf of another party. The claim value 775 is a JSON object and members in the JSON object are claims that 776 identify the party that is asserted as being eligible to act for the 777 party identified by the JWT containing the claim. The claims that 778 make up the "may_act" claim identify and possibly provide additional 779 information about the authorized actor. For example, the combination 780 of the two claims "iss" and "sub" are sometimes necessary to uniquely 781 identify an authorized actor, while the "email" claim might be used 782 to provide additional useful information about that party. 784 However, claims within the "may_act" claim pertain only to the 785 identity of that party and are not relevant to the validity of the 786 containing JWT in the same manner as top-level claims. Consequently, 787 claims such as "exp", "nbf", and "aud" are not meaningful when used 788 within a "may_act" claim, and therefore should not be used. 790 The following example illustrates the "may_act" claim within a JWT 791 Claims Set. The claims of the token itself are about 792 user@example.com while the "may_act" claim indicates that 793 admin@example.com is authorized to act on behalf of user@example.com. 795 { 796 "aud":"https://consumer.example.com", 797 "iss":"https://issuer.example.com", 798 "exp":1443904177, 799 "nbf":1443904077, 800 "sub":"user@example.com", 801 "may_act": 802 { 803 "sub":"admin@example.com" 804 } 805 } 807 Figure 9: May Act For Claim 809 When included as a top-level member of an OAuth token introspection 810 response, "may_act" has the same semantics and format as the claim of 811 the same name. 813 5. Security Considerations 815 All of the normal security issues that are discussed in [JWT], 816 especially in relationship to comparing URIs and dealing with 817 unrecognized values, also apply here. 819 In addition, both delegation and impersonation introduce unique 820 security issues. Any time one principal is delegated the rights of 821 another principal, the potential for abuse is a concern. The use of 822 the "scope" claim is suggested to mitigate potential for such abuse, 823 as it restricts the contexts in which the delegated rights can be 824 exercised. 826 6. Privacy Considerations 828 Tokens employed in the context of the functionality described herein 829 may contain privacy-sensitive information and, to prevent disclosure 830 of such information to unintended parties, should only be transmitted 831 over encrypted channels, such as Transport Layer Security (TLS). In 832 cases where it is desirable to prevent disclosure of certain 833 information to the client, the token should be encrypted to its 834 intended recipient. Deployments should determine the minimally 835 necessary amount of data and only include such information in issued 836 tokens. In some cases, data minimization may include representing 837 only an anonymous or pseudonymous user. 839 7. IANA Considerations 841 7.1. OAuth URI Registration 843 This specification registers the following values in the IANA "OAuth 844 URI" registry [IANA.OAuth.Parameters] established by [RFC6755]. 846 7.1.1. Registry Contents 848 o URN: urn:ietf:params:oauth:grant-type:token-exchange 849 o Common Name: Token exchange grant type for OAuth 2.0 850 o Change controller: IESG 851 o Specification Document: Section 2.1 of [[ this specification ]] 853 o URN: urn:ietf:params:oauth:token-type:access_token 854 o Common Name: Token type URI for an OAuth 2.0 access token 855 o Change controller: IESG 856 o Specification Document: Section 3 of [[this specification]] 858 o URN: urn:ietf:params:oauth:token-type:refresh_token 859 o Common Name: Token type URI for an OAuth 2.0 refresh token 860 o Change controller: IESG 861 o Specification Document: Section 3 of [[this specification]] 863 o URN: urn:ietf:params:oauth:token-type:id_token 864 o Common Name: Token type URI for an ID Token 865 o Change controller: IESG 866 o Specification Document: Section 3 of [[this specification]] 868 o URN: urn:ietf:params:oauth:token-type:saml1 869 o Common Name: Token type URI for a base64url-encoded SAML 1.1 870 assertion 871 o Change Controller: IESG 872 o Specification Document: Section 3 of [[this specification]] 873 o URN: urn:ietf:params:oauth:token-type:saml2 874 o Common Name: Token type URI for a base64url-encoded SAML 2.0 875 assertion 876 o Change Controller: IESG 877 o Specification Document: Section 3 of [[this specification]] 879 7.2. OAuth Parameters Registration 881 This specification registers the following values in the IANA "OAuth 882 Parameters" registry [IANA.OAuth.Parameters] established by 883 [RFC6749]. 885 7.2.1. Registry Contents 887 o Parameter name: resource 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: audience 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: requested_token_type 898 o Parameter usage location: token request 899 o Change controller: IESG 900 o Specification document(s): Section 2.1 of [[ this specification ]] 902 o Parameter name: subject_token 903 o Parameter usage location: token request 904 o Change controller: IESG 905 o Specification document(s): Section 2.1 of [[ this specification ]] 907 o Parameter name: subject_token_type 908 o Parameter usage location: token request 909 o Change controller: IESG 910 o Specification document(s): Section 2.1 of [[ this specification ]] 912 o Parameter name: actor_token 913 o Parameter usage location: token request 914 o Change controller: IESG 915 o Specification document(s): Section 2.1 of [[ this specification ]] 917 o Parameter name: actor_token_type 918 o Parameter usage location: token request 919 o Change controller: IESG 920 o Specification document(s): Section 2.1 of [[ this specification ]] 921 o Parameter name: issued_token_type 922 o Parameter usage location: token response 923 o Change controller: IESG 924 o Specification document(s): Section 2.2.1 of [[ this specification 925 ]] 927 7.3. OAuth Access Token Type Registration 929 This specification registers the following access token type in the 930 IANA "OAuth Access Token Types" registry [IANA.OAuth.Parameters] 931 established by [RFC6749]. 933 7.3.1. Registry Contents 935 o Type name: N_A 936 o Additional Token Endpoint Response Parameters: (none) 937 o HTTP Authentication Scheme(s): (none) 938 o Change controller: IESG 939 o Specification document(s): Section 2.2.1 of [[ this specification 940 ]] 942 7.4. JSON Web Token Claims Registration 944 This specification registers the following Claims in the IANA "JSON 945 Web Token Claims" registry [IANA.JWT.Claims] established by [JWT]. 947 7.4.1. Registry Contents 949 o Claim Name: "act" 950 o Claim Description: Actor 951 o Change Controller: IESG 952 o Specification Document(s): Section 4.1 of [[ this specification ]] 954 o Claim Name: "scope" 955 o Claim Description: Scope Values 956 o Change Controller: IESG 957 o Specification Document(s): Section 4.2 of [[ this specification ]] 959 o Claim Name: "client_id" 960 o Claim Description: Client Identifier 961 o Change Controller: IESG 962 o Specification Document(s): Section 4.3 of [[ this specification ]] 964 o Claim Name: "may_act" 965 o Claim Description: May Act For 966 o Change Controller: IESG 967 o Specification Document(s): Section 4.4 of [[ this specification ]] 969 7.5. OAuth Token Introspection Response Registration 971 This specification registers the following values in the IANA "OAuth 972 Token Introspection Response" registry [IANA.OAuth.Parameters] 973 established by [RFC7662]. 975 7.5.1. Registry Contents 977 o Claim Name: "act" 978 o Claim Description: Actor 979 o Change Controller: IESG 980 o Specification Document(s): Section 4.1 of [[ this specification ]] 982 o Claim Name: "may_act" 983 o Claim Description: May Act For 984 o Change Controller: IESG 985 o Specification Document(s): Section 4.4 of [[ this specification ]] 987 7.6. OAuth Extensions Error Registration 989 This specification registers the following values in the IANA "OAuth 990 Extensions Error" registry [IANA.OAuth.Parameters] established by 991 [RFC6749]. 993 7.6.1. Registry Contents 995 o Error Name: "invalid_target" 996 o Error Usage Location: token error response 997 o Related Protocol Extension: OAuth 2.0 Token Exchange 998 o Change Controller: IETF 999 o Specification Document(s): Section 2.2.2 of [[ this specification 1000 ]] 1002 8. References 1004 8.1. Normative References 1006 [IANA.JWT.Claims] 1007 IANA, "JSON Web Token Claims", 1008 . 1010 [IANA.OAuth.Parameters] 1011 IANA, "OAuth Parameters", 1012 . 1014 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1015 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1016 . 1018 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1019 Requirement Levels", BCP 14, RFC 2119, 1020 DOI 10.17487/RFC2119, March 1997, 1021 . 1023 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1024 Resource Identifier (URI): Generic Syntax", STD 66, 1025 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1026 . 1028 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1029 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1030 . 1032 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1033 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1034 2014, . 1036 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 1037 RFC 7662, DOI 10.17487/RFC7662, October 2015, 1038 . 1040 8.2. Informative References 1042 [OASIS.saml-core-1.1] 1043 Maler, E., Mishra, P., and R. Philpott, "Assertions and 1044 Protocol for the OASIS Security Assertion Markup Language 1045 (SAML) V1.1", OASIS Standard oasis-sstc-saml-core-1.1, 1046 September 2003. 1048 [OASIS.saml-core-2.0-os] 1049 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 1050 "Assertions and Protocol for the OASIS Security Assertion 1051 Markup Language (SAML) V2.0", OASIS Standard saml-core- 1052 2.0-os, March 2005. 1054 [OpenID.Core] 1055 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 1056 C. Mortimore, "OpenID Connect Core 1.0", August 2015, 1057 . 1059 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1060 Framework: Bearer Token Usage", RFC 6750, 1061 DOI 10.17487/RFC6750, October 2012, 1062 . 1064 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 1065 for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, 1066 . 1068 [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 1069 "Assertion Framework for OAuth 2.0 Client Authentication 1070 and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, 1071 May 2015, . 1073 [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 1074 (JWT) Profile for OAuth 2.0 Client Authentication and 1075 Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 1076 2015, . 1078 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1079 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1080 May 2017, . 1082 [WS-Trust] 1083 Nadalin, A., Goodner, M., Gudgin, M., Barbir, A., and H. 1084 Granqvist, "WS-Trust 1.4", February 2012, 1085 . 1088 Appendix A. Additional Token Exchange Examples 1090 Two example token exchanges are provided in the following sections 1091 illustrating impersonation and delegation, respectively (with extra 1092 line breaks and indentation for display purposes only). 1094 A.1. Impersonation Token Exchange Example 1096 A.1.1. Token Exchange Request 1098 In the following token exchange request, a client is requesting a 1099 token with impersonation semantics. The client tells the 1100 authorization server that it needs a token for use at the target 1101 service with the logical name "urn:example:cooperation-context". 1103 POST /as/token.oauth2 HTTP/1.1 1104 Host: as.example.com 1105 Content-Type: application/x-www-form-urlencoded 1107 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 1108 &audience=urn%3Aexample%3Acooperation-context 1109 &subject_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwc 1110 zovL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXI 1111 uZXhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTA2MDAsIm5iZiI6MTQ0MTkwOTAwMCwic 1112 3ViIjoiYmNAZXhhbXBsZS5uZXQiLCJzY29wZSI6Im9yZGVycyBwcm9maWxlIGhpc3R 1113 vcnkifQ.u0slqvbnqU43EvI_itGdFJ11StrAwXlxczYfMYsaR5p4J_gBp019mxljSx 1114 xmD3FfbrjTGyZ4eDh1JKJVpsnnPg 1115 &subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1117 Figure 10: Token Exchange Request 1119 A.1.2. Subject Token Claims 1121 The "subject_token" in the prior request is a JWT and the decoded JWT 1122 Claims Set is shown here. The JWT is intended for consumption by the 1123 authorization server within a specific time window. The subject of 1124 the JWT ("bc@example.net") is the party on behalf of whom the new 1125 token is being requested. 1127 { 1128 "aud":"https://as.example.com", 1129 "iss":"https://original-issuer.example.net", 1130 "exp":1441910600, 1131 "nbf":1441909000, 1132 "sub":"bc@example.net", 1133 "scope":"orders profile history" 1134 } 1136 Figure 11: Subject Token Claims 1138 A.1.3. Token Exchange Response 1140 The "access_token" parameter of the token exchange response shown 1141 below contains the new token that the client requested. The other 1142 parameters of the response indicate that the token is a bearer access 1143 token that expires in an hour. 1145 HTTP/1.1 200 OK 1146 Content-Type: application/json 1147 Cache-Control: no-cache, no-store 1149 { 1150 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm4 1151 6ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5l 1152 eGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic3ViIjoiYmNAZXhhbXBsZS5uZ 1153 XQiLCJzY29wZSI6Im9yZGVycyBwcm9maWxlIGhpc3RvcnkifQ._OnH9oHT2cd0-Sz 1154 OfBrNkVYlRdn48X8kI4_Is3LHeQmtkd-nDdR63IuuQ_GeZd7UafMV3bk8jqUDgi-l 1155 rTfSwA", 1156 "issued_token_type": 1157 "urn:ietf:params:oauth:token-type:access_token", 1158 "token_type":"Bearer", 1159 "expires_in":3600 1160 } 1162 Figure 12: Token Exchange Response 1164 A.1.4. Issued Token Claims 1166 The decoded JWT Claims Set of the issued token is shown below. The 1167 new JWT is issued by the authorization server and intended for 1168 consumption by a system entity known by the logical name 1169 "urn:example:cooperation-context" any time before its expiration. 1170 The subject ("sub") of the JWT is the same as the subject the token 1171 used to make the request, which effectively enables the client to 1172 impersonate that subject at the system entity known by the logical 1173 name of "urn:example:cooperation-context" by using the token. 1175 { 1176 "aud":"urn:example:cooperation-context", 1177 "iss":"https://as.example.com", 1178 "exp":1441913610, 1179 "sub":"bc@example.net", 1180 "scope":"orders profile history" 1181 } 1183 Figure 13: Issued Token Claims 1185 A.2. Delegation Token Exchange Example 1187 A.2.1. Token Exchange Request 1189 In the following token exchange request, a client is requesting a 1190 token and providing both a "subject_token" and an "actor_token". The 1191 client tells the authorization server that it needs a token for use 1192 at the target service with the logical name "urn:example:cooperation- 1193 context". Policy at the authorization server dictates that the 1194 issued token be a composite. 1196 POST /as/token.oauth2 HTTP/1.1 1197 Host: as.example.com 1198 Content-Type: application/x-www-form-urlencoded 1200 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 1201 &audience=urn%3Aexample%3Acooperation-context 1202 &subject_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwc 1203 zovL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXI 1204 uZXhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTAwNjAsInNjb3BlIjoic3RhdHVzIGZlZ 1205 WQiLCJzdWIiOiJ1c2VyQGV4YW1wbGUubmV0IiwibWF5X2FjdCI6eyJzdWIiOiJhZG1 1206 pbkBleGFtcGxlLm5ldCJ9fQ.4rPRSWihQbpMIgAmAoqaJojAxj-p2X8_fAtAGTXrvM 1207 xU-eEZHnXqY0_AOZgLdxw5DyLzua8H_I10MCcckF-Q_g 1208 &subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1209 &actor_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwczo 1210 vL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXIuZ 1211 XhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTAwNjAsInN1YiI6ImFkbWluQGV4YW1wbGU 1212 ubmV0In0.7YQ-3zPfhUvzje5oqw8COCvN5uP6NsKik9CVV6cAOf4QKgM-tKfiOwcgZ 1213 oUuDL2tEs6tqPlcBlMjiSzEjm3yBg 1214 &actor_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1216 Figure 14: Token Exchange Request 1218 A.2.2. Subject Token Claims 1220 The "subject_token" in the prior request is a JWT and the decoded JWT 1221 Claims Set is shown here. The JWT is intended for consumption by the 1222 authorization server before a specific expiration time. The subject 1223 of the JWT ("user@example.net") is the party on behalf of whom the 1224 new token is being requested. 1226 { 1227 "aud":"https://as.example.com", 1228 "iss":"https://original-issuer.example.net", 1229 "exp":1441910060, 1230 "scope":"status feed", 1231 "sub":"user@example.net", 1232 "may_act": 1233 { 1234 "sub":"admin@example.net" 1235 } 1236 } 1238 Figure 15: Subject Token Claims 1240 A.2.3. Actor Token Claims 1242 The "actor_token" in the prior request is a JWT and the decoded JWT 1243 Claims Set is shown here. This JWT is also intended for consumption 1244 by the authorization server before a specific expiration time. The 1245 subject of the JWT ("admin@example.net") is the actor that will wield 1246 the security token being requested. 1248 { 1249 "aud":"https://as.example.com", 1250 "iss":"https://original-issuer.example.net", 1251 "exp":1441910060, 1252 "sub":"admin@example.net" 1253 } 1255 Figure 16: Actor Token Claims 1257 A.2.4. Token Exchange Response 1259 The "access_token" parameter of the token exchange response shown 1260 below contains the new token that the client requested. The other 1261 parameters of the response indicate that the token is a JWT that 1262 expires in an hour and that the access token type is not applicable 1263 since the issued token is not an access token. 1265 HTTP/1.1 200 OK 1266 Content-Type: application/json 1267 Cache-Control: no-cache, no-store 1269 { 1270 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm4 1271 6ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5l 1272 eGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic2NvcGUiOiJzdGF0dXMgZmVlZ 1273 CIsInN1YiI6InVzZXJAZXhhbXBsZS5uZXQiLCJhY3QiOnsic3ViIjoiYWRtaW5AZX 1274 hhbXBsZS5uZXQifX0.3paKl9UySKYB5ng6_cUtQ2qlO8Rc_y7Mea7IwEXTcYbNdwG 1275 9-G1EKCFe5fW3H0hwX-MSZ49Wpcb1SiAZaOQBtw", 1276 "issued_token_type":"urn:ietf:params:oauth:token-type:jwt", 1277 "token_type":"N_A", 1278 "expires_in":3600 1279 } 1281 Figure 17: Token Exchange Response 1283 A.2.5. Issued Token Claims 1285 The decoded JWT Claims Set of the issued token is shown below. The 1286 new JWT is issued by the authorization server and intended for 1287 consumption by a system entity known by the logical name 1288 "urn:example:cooperation-context" any time before its expiration. 1289 The subject ("sub") of the JWT is the same as the subject of the 1290 "subject_token" used to make the request. The actor ("act") of the 1291 JWT is the same as the subject of the "actor_token" used to make the 1292 request. This indicates delegation and identifies 1293 "admin@example.net" as the current actor to whom authority has been 1294 delegated to act on behalf of "user@example.net". 1296 { 1297 "aud":"urn:example:cooperation-context", 1298 "iss":"https://as.example.com", 1299 "exp":1441913610, 1300 "scope":"status feed", 1301 "sub":"user@example.net", 1302 "act": 1303 { 1304 "sub":"admin@example.net" 1305 } 1306 } 1308 Figure 18: Issued Token Claims 1310 Appendix B. Acknowledgements 1312 This specification was developed within the OAuth Working Group, 1313 which includes dozens of active and dedicated participants. It was 1314 produced under the chairmanship of Hannes Tschofenig, Derek Atkins, 1315 and Rifaat Shekh-Yusef with Kathleen Moriarty, Stephen Farrell, Eric 1316 Rescorla, and Benjamin Kaduk serving as Security Area Directors. The 1317 following individuals contributed ideas, feedback, and wording to 1318 this specification: 1320 Caleb Baker, Vittorio Bertocci, Thomas Broyer, William Denniss, 1321 Vladimir Dzhuvinov, Phil Hunt, Benjamin Kaduk, Jason Keglovitz, 1322 Torsten Lodderstedt, Adam Lewis, James Manger, Nov Matake, Matt 1323 Miller, Hilarie Orman, Matthew Perry, Eric Rescorla, Justin Richer, 1324 Rifaat Shekh-Yusef, Scott Tomilson, and Hannes Tschofenig. 1326 Appendix C. Document History 1328 [[ to be removed by the RFC Editor before publication as an RFC ]] 1330 -16 1332 o Fixed typo and added an AD to Acknowledgements. 1334 -15 1335 o Updated the nested actor claim example to (hopefully) be more 1336 straightforward. 1337 o Reworked Privacy Considerations to say to use TLS in transit, 1338 minimize the amount of information in the token, and encrypt the 1339 token if disclosure of its information to the client is a concern 1340 per https://mailarchive.ietf.org/arch/msg/secdir/ 1341 KJhx4aq_U5uk3k6zpYP-CEHbpVM 1342 o Moved the Security and Privacy Considerations sections to before 1343 the IANA Considerations. 1345 -14 1347 o Added text in Section 4.1 about the "act" claim stating that only 1348 the top-level claims and the current actor are to be considered in 1349 applying access control decisions. 1351 -13 1353 o Updated the claim name and value syntax for scope to be consistent 1354 with the treatment of scope in RFC 7662 OAuth 2.0 Token 1355 Introspection. 1356 o Updated the client identifier claim name to be consistent with the 1357 treatment of client id in RFC 7662 OAuth 2.0 Token Introspection. 1359 -12 1361 o Updated to use the boilerplate from RFC 8174. 1363 -11 1365 o Added new WG chair and AD to the Acknowledgements. 1366 o Applied clarifications suggested during AD review by EKR. 1368 -10 1370 o Defined token type URIs for base64url-encoded SAML 1.1 and SAML 1371 2.0 assertions. 1372 o Applied editorial fixes. 1374 -09 1376 o Changed "security tokens obtained could be used in a number of 1377 contexts" to "security tokens obtained may be used in a number of 1378 contexts" per a WGLC suggestion. 1379 o Clarified that the validity of the subject or actor token have no 1380 impact on the validity of the issued token after the exchange has 1381 occurred per a WGLC comment. 1383 o Changed use of invalid_target error code to a SHOULD per a WGLC 1384 comment. 1385 o Clarified text about non-identity claims within the "act" claim 1386 being meaningless per a WGLC comment. 1387 o Added brief Privacy Considerations section per WGLC comments. 1389 -08 1391 o Use the bibxml reference for OpenID.Core rather than defining it 1392 inline. 1393 o Added editor role for Campbell. 1394 o Minor clarification of the text for actor_token. 1396 -07 1398 o Fixed typo (desecration -> discretion). 1399 o Added an explanation of the relationship between scope, audience 1400 and resource in the request and added an "invalid_target" error 1401 code enabling the AS to tell the client that the requested 1402 audiences/resources were too broad. 1404 -06 1406 o Drop "An STS for the REST of Us" from the title. 1407 o Drop "heavyweight" and "lightweight" from the abstract and 1408 introduction. 1409 o Clarifications on the language around xxxxxx_token_type. 1410 o Remove the want_composite parameter. 1411 o Add a short mention of proof-of-possession style tokens to the 1412 introduction and remove the respective open issue. 1414 -05 1416 o Defined the JWT claim "cid" to express the OAuth 2.0 client 1417 identifier of the client that requested the token. 1418 o Defined and requested registration for "act" and "may_act" as 1419 Token introspection response parameters (in addition to being JWT 1420 claims). 1421 o Loosen up the language about refresh_token in the response to 1422 OPTIONAL from NOT RECOMMENDED based on feedback form real world 1423 deployment experience. 1424 o Add clarifying text about the distinction between JWT and access 1425 token URIs. 1426 o Close out (remove) some of the Open Issues bullets that have been 1427 resolved. 1429 -04 1430 o Clarified that the "resource" and "audience" request parameters 1431 can be used at the same time (via http://www.ietf.org/mail- 1432 archive/web/oauth/current/msg15335.html). 1433 o Clarified subject/actor token validity after token exchange and 1434 explained a bit more about the recommendation to not issue refresh 1435 tokens (via http://www.ietf.org/mail-archive/web/oauth/current/ 1436 msg15318.html). 1437 o Updated the examples appendix to use an issuer value that doesn't 1438 imply that the client issued and signed the tokens and used 1439 "Bearer" and "urn:ietf:params:oauth:token-type:access_token" in 1440 one of the responses (via http://www.ietf.org/mail- 1441 archive/web/oauth/current/msg15335.html). 1442 o Defined and registered urn:ietf:params:oauth:token-type:id_token, 1443 since some use cases perform token exchanges for ID Tokens and no 1444 URI to indicate that a token is an ID Token had previously been 1445 defined. 1447 -03 1449 o Updated the document editors (adding Campbell, Bradley, and 1450 Mortimore). 1451 o Added to the title. 1452 o Added to the abstract and introduction. 1453 o Updated the format of the request to use application/x-www-form- 1454 urlencoded request parameters and the response to use the existing 1455 token endpoint JSON parameters defined in OAuth 2.0. 1456 o Changed the grant type identifier to urn:ietf:params:oauth:grant- 1457 type:token-exchange. 1458 o Added RFC 6755 registration requests for 1459 urn:ietf:params:oauth:token-type:refresh_token, 1460 urn:ietf:params:oauth:token-type:access_token, and 1461 urn:ietf:params:oauth:grant-type:token-exchange. 1462 o Added RFC 6749 registration requests for request/response 1463 parameters. 1464 o Removed the Implementation Considerations and the requirement to 1465 support JWTs. 1466 o Clarified many aspects of the text. 1467 o Changed "on_behalf_of" to "subject_token", 1468 "on_behalf_of_token_type" to "subject_token_type", "act_as" to 1469 "actor_token", and "act_as_token_type" to "actor_token_type". 1470 o Added an "audience" request parameter used to indicate the logical 1471 names of the target services at which the client intends to use 1472 the requested security token. 1473 o Added a "want_composite" request parameter used to indicate the 1474 desire for a composite token rather than trying to infer it from 1475 the presence/absence of token(s) in the request. 1477 o Added a "resource" request parameter used to indicate the URLs of 1478 resources at which the client intends to use the requested 1479 security token. 1480 o Specified that multiple "audience" and "resource" request 1481 parameter values may be used. 1482 o Defined the JWT claim "act" (actor) to express the current actor 1483 or delegation principal. 1484 o Defined the JWT claim "may_act" to express that one party is 1485 authorized to act on behalf of another party. 1486 o Defined the JWT claim "scp" (scopes) to express OAuth 2.0 scope- 1487 token values. 1488 o Added the "N_A" (not applicable) OAuth Access Token Type 1489 definition for use in contexts in which the token exchange syntax 1490 requires a "token_type" value, but in which the token being issued 1491 is not an access token. 1492 o Added examples. 1494 -02 1496 o Enabled use of Security Token types other than JWTs for "act_as" 1497 and "on_behalf_of" request values. 1498 o Referenced the JWT and OAuth Assertions RFCs. 1500 -01 1502 o Updated references. 1504 -00 1506 o Created initial working group draft from draft-jones-oauth-token- 1507 exchange-01. 1509 Authors' Addresses 1511 Michael B. Jones 1512 Microsoft 1514 Email: mbj@microsoft.com 1515 URI: http://self-issued.info/ 1517 Anthony Nadalin 1518 Microsoft 1520 Email: tonynad@microsoft.com 1521 Brian Campbell (editor) 1522 Ping Identity 1524 Email: brian.d.campbell@gmail.com 1526 John Bradley 1527 Ping Identity 1529 Email: ve7jtb@ve7jtb.com 1531 Chuck Mortimore 1532 Salesforce 1534 Email: cmortimore@salesforce.com