idnits 2.17.1 draft-ietf-oauth-token-exchange-19.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 (July 20, 2019) is 1734 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) == Outdated reference: A later version (-08) exists of draft-ietf-oauth-resource-indicators-02 == Outdated reference: A later version (-25) exists of draft-ietf-oauth-security-topics-13 Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 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: January 21, 2020 B. Campbell, Ed. 6 Ping Identity 7 J. Bradley 8 Yubico 9 C. Mortimore 10 Salesforce 11 July 20, 2019 13 OAuth 2.0 Token Exchange 14 draft-ietf-oauth-token-exchange-19 16 Abstract 18 This specification defines a protocol for an HTTP- and JSON- based 19 Security Token Service (STS) by defining how to request and obtain 20 security tokens from OAuth 2.0 authorization servers, including 21 security tokens employing impersonation and delegation. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at https://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on January 21, 2020. 40 Copyright Notice 42 Copyright (c) 2019 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (https://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 58 1.1. Delegation vs. Impersonation Semantics . . . . . . . . . 4 59 1.2. Requirements Notation and Conventions . . . . . . . . . . 6 60 1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 61 2. Token Exchange Request and Response . . . . . . . . . . . . . 6 62 2.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 6 63 2.1.1. Relationship Between Resource, Audience and Scope . . 9 64 2.2. Response . . . . . . . . . . . . . . . . . . . . . . . . 9 65 2.2.1. Successful Response . . . . . . . . . . . . . . . . . 9 66 2.2.2. Error Response . . . . . . . . . . . . . . . . . . . 11 67 2.3. Example Token Exchange . . . . . . . . . . . . . . . . . 11 68 3. Token Type Identifiers . . . . . . . . . . . . . . . . . . . 13 69 4. JSON Web Token Claims and Introspection Response Parameters . 15 70 4.1. "act" (Actor) Claim . . . . . . . . . . . . . . . . . . . 15 71 4.2. "scope" (Scopes) Claim . . . . . . . . . . . . . . . . . 17 72 4.3. "client_id" (Client Identifier) Claim . . . . . . . . . . 18 73 4.4. "may_act" (Authorized Actor) Claim . . . . . . . . . . . 18 74 5. Security Considerations . . . . . . . . . . . . . . . . . . . 19 75 6. Privacy Considerations . . . . . . . . . . . . . . . . . . . 20 76 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 77 7.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 20 78 7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 20 79 7.2. OAuth Parameters Registration . . . . . . . . . . . . . . 21 80 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 21 81 7.3. OAuth Access Token Type Registration . . . . . . . . . . 22 82 7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 22 83 7.4. JSON Web Token Claims Registration . . . . . . . . . . . 22 84 7.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 22 85 7.5. OAuth Token Introspection Response Registration . . . . . 23 86 7.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 23 87 7.6. OAuth Extensions Error Registration . . . . . . . . . . . 23 88 7.6.1. Registry Contents . . . . . . . . . . . . . . . . . . 23 89 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 24 90 8.1. Normative References . . . . . . . . . . . . . . . . . . 24 91 8.2. Informative References . . . . . . . . . . . . . . . . . 24 92 Appendix A. Additional Token Exchange Examples . . . . . . . . . 26 93 A.1. Impersonation Token Exchange Example . . . . . . . . . . 26 94 A.1.1. Token Exchange Request . . . . . . . . . . . . . . . 26 95 A.1.2. Subject Token Claims . . . . . . . . . . . . . . . . 26 96 A.1.3. Token Exchange Response . . . . . . . . . . . . . . . 27 97 A.1.4. Issued Token Claims . . . . . . . . . . . . . . . . . 27 98 A.2. Delegation Token Exchange Example . . . . . . . . . . . . 28 99 A.2.1. Token Exchange Request . . . . . . . . . . . . . . . 28 100 A.2.2. Subject Token Claims . . . . . . . . . . . . . . . . 29 101 A.2.3. Actor Token Claims . . . . . . . . . . . . . . . . . 29 102 A.2.4. Token Exchange Response . . . . . . . . . . . . . . . 29 103 A.2.5. Issued Token Claims . . . . . . . . . . . . . . . . . 30 104 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 31 105 Appendix C. Document History . . . . . . . . . . . . . . . . . . 31 106 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 35 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 120 security tokens provided to it and issuing new security tokens in 121 response, which enables clients to obtain appropriate access 122 credentials for resources in heterogeneous environments or across 123 security domains. Web Service clients have used WS-Trust [WS-Trust] 124 as the protocol to interact with an STS for token exchange. While 125 WS-Trust uses XML and SOAP, the trend in modern Web development has 126 been towards RESTful patterns and JSON. The OAuth 2.0 Authorization 127 Framework [RFC6749] and OAuth 2.0 Bearer Tokens [RFC6750] have 128 emerged as popular standards for authorizing third-party 129 applications' access to HTTP and RESTful resources. The conventional 130 OAuth 2.0 interaction involves the exchange of some representation of 131 resource owner authorization for an access token, which has proven to 132 be an extremely useful pattern in practice. However, its input and 133 output are somewhat too constrained as is to fully accommodate a 134 security token exchange framework. 136 This specification defines a protocol extending OAuth 2.0 that 137 enables clients to request and obtain security tokens from 138 authorization servers acting in the role of an STS. Similar to OAuth 139 2.0, this specification focuses on client developer simplicity and 140 requires only an HTTP client and JSON parser, which are nearly 141 universally available in modern development environments. The STS 142 protocol defined in this specification is not itself RESTful (an STS 143 doesn't lend itself particularly well to a REST approach) but does 144 utilize communication patterns and data formats that should be 145 familiar to developers accustomed to working with RESTful systems. 147 A new grant type for a token exchange request and the associated 148 specific parameters for such a request to the token endpoint are 149 defined by this specification. A token exchange response is a normal 150 OAuth 2.0 response from the token endpoint with a few additional 151 parameters defined herein to provide information to the client. 153 The entity that makes the request to exchange tokens is considered 154 the client in the context of the token exchange interaction. 155 However, that does not restrict usage of this profile to traditional 156 OAuth clients. An OAuth resource server, for example, might assume 157 the role of the client during token exchange in order to trade an 158 access token that it received in a protected resource request for a 159 new token that is appropriate to include in a call to a backend 160 service. The new token might be an access token that is more 161 narrowly scoped for the downstream service or it could be an entirely 162 different kind of token. 164 The scope of this specification is limited to the definition of a 165 basic request-and-response protocol for an STS-style token exchange 166 utilizing OAuth 2.0. Although a few new JWT claims are defined that 167 enable delegation semantics to be expressed, the specific syntax, 168 semantics and security characteristics of the tokens themselves (both 169 those presented to the authorization server and those obtained by the 170 client) are explicitly out of scope and no requirements are placed on 171 the trust model in which an implementation might be deployed. 172 Additional profiles may provide more detailed requirements around the 173 specific nature of the parties and trust involved, such as whether 174 signing and/or encryption of tokens is needed or if proof-of- 175 possession style tokens will be required or issued; however, such 176 details will often be policy decisions made with respect to the 177 specific needs of individual deployments and will be configured or 178 implemented accordingly. 180 The security tokens obtained may be used in a number of contexts, the 181 specifics of which are also beyond the scope of this specification. 183 1.1. Delegation vs. Impersonation Semantics 185 One common use case for an STS (as alluded to in the previous 186 section) is to allow a resource server A to make calls to a backend 187 service C on behalf of the requesting user B. Depending on the local 188 site policy and authorization infrastructure, it may be desirable for 189 A to use its own credentials to access C along with an annotation of 190 some form that A is acting on behalf of B ("delegation"), or for A to 191 be granted a limited access credential to C but that continues to 192 identify B as the authorized entity ("impersonation"). Delegation 193 and impersonation can be useful concepts in other scenarios involving 194 multiple participants as well. 196 When principal A impersonates principal B, A is given all the rights 197 that B has within some defined rights context and is 198 indistinguishable from B in that context. Thus, when principal A 199 impersonates principal B, then insofar as any entity receiving such a 200 token is concerned, they are actually dealing with B. It is true 201 that some members of the identity system might have awareness that 202 impersonation is going on, but it is not a requirement. For all 203 intents and purposes, when A is impersonating B, A is B within the 204 context of the rights authorized by the token. A's ability to 205 impersonate B could be limited in scope or time, or even with a one- 206 time-use restriction, whether via the contents of the token or an 207 out-of-band mechanism. 209 Delegation semantics are different than impersonation semantics, 210 though the two are closely related. With delegation semantics, 211 principal A still has its own identity separate from B and it is 212 explicitly understood that while B may have delegated some of its 213 rights to A, any actions taken are being taken by A representing B. 214 In a sense, A is an agent for B. 216 Delegation and impersonation are not inclusive of all situations. 217 When a principal is acting directly on its own behalf, for example, 218 neither delegation nor impersonation are in play. They are, however, 219 the more common semantics operating for token exchange and, as such, 220 are given more direct treatment in this specification. 222 Delegation semantics are typically expressed in a token by including 223 information about both the primary subject of the token as well as 224 the actor to whom that subject has delegated some of its rights. 225 Such a token is sometimes referred to as a composite token because it 226 is composed of information about multiple subjects. Typically, in 227 the request, the "subject_token" represents the identity of the party 228 on behalf of whom the token is being requested while the 229 "actor_token" represents the identity of the party to whom the access 230 rights of the issued token are being delegated. A composite token 231 issued by the authorization server will contain information about 232 both parties. When and if a composite token is issued is at the 233 discretion of the authorization server and applicable policy and 234 configuration. 236 The specifics of representing a composite token and even whether or 237 not such a token will be issued depend on the details of the 238 implementation and the kind of token. The representations of 239 composite tokens that are not JWTs are beyond the scope of this 240 specification. The "actor_token" request parameter, however, does 241 provide a means for providing information about the desired actor and 242 the JWT "act" claim can provide a representation of a chain of 243 delegation. 245 1.2. Requirements Notation and Conventions 247 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 248 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 249 "OPTIONAL" in this document are to be interpreted as described in BCP 250 14 [RFC2119] [RFC8174] when, and only when, they appear in all 251 capitals, as shown here. 253 1.3. Terminology 255 This specification uses the terms "access token type", "authorization 256 server", "client", "client identifier", "resource server", "token 257 endpoint", "token request", and "token response" defined by OAuth 2.0 258 [RFC6749], and the terms "Base64url Encoding", "Claim", and "JWT 259 Claims Set" defined by JSON Web Token (JWT) [JWT]. 261 2. Token Exchange Request and Response 263 2.1. Request 265 A client requests a security token by making a token request to the 266 authorization server's token endpoint using the extension grant type 267 mechanism defined in Section 4.5 of [RFC6749]. 269 Client authentication to the authorization server is done using the 270 normal mechanisms provided by OAuth 2.0. Section 2.3.1 of [RFC6749] 271 defines password-based authentication of the client, however, client 272 authentication is extensible and other mechanisms are possible. For 273 example, [RFC7523] defines client authentication using bearer JSON 274 Web Tokens (JWTs) [JWT]. The supported methods of client 275 authentication and whether or not to allow unauthenticated or 276 unidentified clients are deployment decisions that are at the 277 discretion of the authorization server. Note that omitting client 278 authentication allows for a compromised token to be leveraged via an 279 STS into other tokens by anyone possessing the compromised token. 280 Thus client authentication allows for additional authorization checks 281 by the STS as to which entities are permitted to impersonate or 282 receive delegations from other entities. 284 The client makes a token exchange request to the token endpoint with 285 an extension grant type using the HTTP "POST" method. The following 286 parameters are included in the HTTP request entity-body using the 287 "application/x-www-form-urlencoded" format with a character encoding 288 of UTF-8 as described in Appendix B of RFC6749 [RFC6749]. 290 grant_type 291 REQUIRED. The value "urn:ietf:params:oauth:grant-type:token- 292 exchange" indicates that a token exchange is being performed. 294 resource 295 OPTIONAL. A URI that indicates the target service or resource 296 where the client intends to use the requested security token. 297 This enables the authorization server to apply policy as 298 appropriate for the target, such as determining the type and 299 content of the token to be issued or if and how the token is to be 300 encrypted. In many cases, a client will not have knowledge of the 301 logical organization of the systems with which it interacts and 302 will only know a URI of the service where it intends to use the 303 token. The "resource" parameter allows the client to indicate to 304 the authorization server where it intends to use the issued token 305 by providing the location, typically as an https URL, in the token 306 exchange request in the same form that will be used to access that 307 resource. The authorization server will typically have the 308 capability to map from a resource URI value to an appropriate 309 policy. The value of the "resource" parameter MUST be an absolute 310 URI, as specified by Section 4.3 of [RFC3986], which MAY include a 311 query component and MUST NOT include a fragment component. 312 Multiple "resource" parameters may be used to indicate that the 313 issued token is intended to be used at the multiple resources 314 listed. See [I-D.ietf-oauth-resource-indicators] for additional 315 background and uses of the "resource" parameter. 317 audience 318 OPTIONAL. The logical name of the target service where the client 319 intends to use the requested security token. This serves a 320 purpose similar to the "resource" parameter, but with the client 321 providing a logical name for the target service. Interpretation 322 of the name requires that the value be something that both the 323 client and the authorization server understand. An OAuth client 324 identifier, a SAML entity identifier [OASIS.saml-core-2.0-os], an 325 OpenID Connect Issuer Identifier [OpenID.Core], are examples of 326 things that might be used as "audience" parameter values. 327 However, "audience" values used with a given authorization server 328 must be unique within that server, to ensure that they are 329 properly interpreted as the intended type of value. Multiple 330 "audience" parameters may be used to indicate that the issued 331 token is intended to be used at the multiple audiences listed. 332 The "audience" and "resource" parameters may be used together to 333 indicate multiple target services with a mix of logical names and 334 resource URIs. 336 scope 337 OPTIONAL. A list of space-delimited, case-sensitive strings, as 338 defined in Section 3.3 of [RFC6749], that allow the client to 339 specify the desired scope of the requested security token in the 340 context of the service or resource where the token will be used. 341 The values and associated semantics of scope are service specific 342 and expected to be described in the relevant service 343 documentation. 345 requested_token_type 346 OPTIONAL. An identifier, as described in Section 3, for the type 347 of the requested security token. If the requested type is 348 unspecified, the issued token type is at the discretion of the 349 authorization server and may be dictated by knowledge of the 350 requirements of the service or resource indicated by the 351 "resource" or "audience" parameter. 353 subject_token 354 REQUIRED. A security token that represents the identity of the 355 party on behalf of whom the request is being made. Typically, the 356 subject of this token will be the subject of the security token 357 issued in response to the request. 359 subject_token_type 360 REQUIRED. An identifier, as described in Section 3, that 361 indicates the type of the security token in the "subject_token" 362 parameter. 364 actor_token 365 OPTIONAL. A security token that represents the identity of the 366 acting party. Typically, this will be the party that is 367 authorized to use the requested security token and act on behalf 368 of the subject. 370 actor_token_type 371 An identifier, as described in Section 3, that indicates the type 372 of the security token in the "actor_token" parameter. This is 373 REQUIRED when the "actor_token" parameter is present in the 374 request but MUST NOT be included otherwise. 376 In processing the request, the authorization server MUST perform the 377 appropriate validation procedures for the indicated token type and, 378 if the actor token is present, also perform the appropriate 379 validation procedures for its indicated token type. The validity 380 criteria and details of any particular token are beyond the scope of 381 this document and are specific to the respective type of token and 382 its content. 384 In the absence of one-time-use or other semantics specific to the 385 token type, the act of performing a token exchange has no impact on 386 the validity of the subject token or actor token. Furthermore, the 387 exchange is a one-time event and does not create a tight linkage 388 between the input and output tokens, so that (for example) while the 389 expiration time of the output token may be influenced by that of the 390 input token, renewal or extension of the input token is not expected 391 to be reflected in the output token's properties. It may still be 392 appropriate or desirable to propagate token revocation events. 393 However, doing so is not a general property of the STS protocol and 394 would be specific to a particular implementation, token type or 395 deployment. 397 2.1.1. Relationship Between Resource, Audience and Scope 399 When requesting a token, the client can indicate the desired target 400 service(s) where it intends to use that token by way of the 401 "audience" and "resource" parameters, as well as indicating the 402 desired scope of the requested token using the "scope" parameter. 403 The semantics of such a request are that the client is asking for a 404 token with the requested scope that is usable at all the requested 405 target services. Effectively, the requested access rights of the 406 token are the cartesian product of all the scopes at all the target 407 services. 409 An authorization server may be unwilling or unable to fulfill any 410 token request but the likelihood of an unfulfillable request is 411 significantly higher when very broad access rights are being 412 solicited. As such, in the absence of specific knowledge about the 413 relationship of systems in a deployment, clients should exercise 414 discretion in the breadth of the access requested, particularly the 415 number of target services. An authorization server can use the 416 "invalid_target" error code, defined in Section 2.2.2, to inform a 417 client that it requested access to too many target services 418 simultaneously. 420 2.2. Response 422 The authorization server responds to a token exchange request with a 423 normal OAuth 2.0 response from the token endpoint, as specified in 424 Section 5 of [RFC6749]. Additional details and explanation are 425 provided in the following subsections. 427 2.2.1. Successful Response 429 If the request is valid and meets all policy and other criteria of 430 the authorization server, a successful token response is constructed 431 by adding the following parameters to the entity-body of the HTTP 432 response using the "application/json" media type, as specified by 433 [RFC8259], and an HTTP 200 status code. The parameters are 434 serialized into a JavaScript Object Notation (JSON) structure by 435 adding each parameter at the top level. Parameter names and string 436 values are included as JSON strings. Numerical values are included 437 as JSON numbers. The order of parameters does not matter and can 438 vary. 440 access_token 441 REQUIRED. The security token issued by the authorization server 442 in response to the token exchange request. The "access_token" 443 parameter from Section 5.1 of [RFC6749] is used here to carry the 444 requested token, which allows this token exchange protocol to use 445 the existing OAuth 2.0 request and response constructs defined for 446 the token endpoint. The identifier "access_token" is used for 447 historical reasons and the issued token need not be an OAuth 448 access token. 450 issued_token_type 451 REQUIRED. An identifier, as described in Section 3, for the 452 representation of the issued security token. 454 token_type 455 REQUIRED. A case-insensitive value specifying the method of using 456 the access token issued, as specified in Section 7.1 of [RFC6749]. 457 It provides the client with information about how to utilize the 458 access token to access protected resources. For example, a value 459 of "Bearer", as specified in [RFC6750], indicates that the issued 460 security token is a bearer token and the client can simply present 461 it as is without any additional proof of eligibility beyond the 462 contents of the token itself. Note that the meaning of this 463 parameter is different from the meaning of the "issued_token_type" 464 parameter, which declares the representation of the issued 465 security token; the term "token type" is more typically used with 466 the aforementioned meaning as the structural or syntactical 467 representation of the security token, as it is in all 468 "*_token_type" parameters in this specification. If the issued 469 token is not an access token or usable as an access token, then 470 the "token_type" value "N_A" is used to indicate that an OAuth 2.0 471 "token_type" identifier is not applicable in that context. 473 expires_in 474 RECOMMENDED. The validity lifetime, in seconds, of the token 475 issued by the authorization server. Oftentimes the client will 476 not have the inclination or capability to inspect the content of 477 the token and this parameter provides a consistent and token-type- 478 agnostic indication of how long the token can be expected to be 479 valid. For example, the value 1800 denotes that the token will 480 expire in thirty minutes from the time the response was generated. 482 scope 483 OPTIONAL, if the scope of the issued security token is identical 484 to the scope requested by the client; otherwise, REQUIRED. 486 refresh_token 487 OPTIONAL. A refresh token will typically not be issued when the 488 exchange is of one temporary credential (the subject_token) for a 489 different temporary credential (the issued token) for use in some 490 other context. A refresh token can be issued in cases where the 491 client of the token exchange needs the ability to access a 492 resource even when the original credential is no longer valid 493 (e.g., user-not-present or offline scenarios where there is no 494 longer any user entertaining an active session with the client). 495 Profiles or deployments of this specification should clearly 496 document the conditions under which a client should expect a 497 refresh token in response to "urn:ietf:params:oauth:grant- 498 type:token-exchange" grant type requests. 500 2.2.2. Error Response 502 If the request itself is not valid or if either the "subject_token" 503 or "actor_token" are invalid for any reason, or are unacceptable 504 based on policy, the authorization server MUST construct an error 505 response, as specified in Section 5.2 of [RFC6749]. The value of the 506 "error" parameter MUST be the "invalid_request" error code. 508 If the authorization server is unwilling or unable to issue a token 509 for any target service indicated by the "resource" or "audience" 510 parameters, the "invalid_target" error code SHOULD be used in the 511 error response. 513 The authorization server MAY include additional information regarding 514 the reasons for the error using the "error_description" as discussed 515 in Section 5.2 of [RFC6749]. 517 Other error codes may also be used, as appropriate. 519 2.3. Example Token Exchange 521 The following example demonstrates a hypothetical token exchange in 522 which an OAuth resource server assumes the role of the client during 523 the exchange. It trades an access token, which it received in a 524 protected resource request, for a new token that it will use to call 525 to a backend service (extra line breaks and indentation in the 526 examples are for display purposes only). 528 Figure 1 shows the resource server receiving a protected resource 529 request containing an OAuth access token in the Authorization header, 530 as specified in Section 2.1 of [RFC6750]. 532 GET /resource HTTP/1.1 533 Host: frontend.example.com 534 Authorization: Bearer accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC 536 Figure 1: Protected Resource Request 538 In Figure 2, the resource server assumes the role of client for the 539 token exchange and the access token from the request in Figure 1 is 540 sent to the authorization server using a request as specified in 541 Section 2.1. The value of the "subject_token" parameter carries the 542 access token and the value of the "subject_token_type" parameter 543 indicates that it is an OAuth 2.0 access token. The resource server, 544 acting in the role of the client, uses its identifier and secret to 545 authenticate to the authorization server using the HTTP Basic 546 authentication scheme. The "resource" parameter indicates the 547 location of the backend service, https://backend.example.com/api, 548 where the issued token will be used. 550 POST /as/token.oauth2 HTTP/1.1 551 Host: as.example.com 552 Authorization: Basic cnMwODpsb25nLXNlY3VyZS1yYW5kb20tc2VjcmV0 553 Content-Type: application/x-www-form-urlencoded 555 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 556 &resource=https%3A%2F%2Fbackend.example.com%2Fapi 557 &subject_token=accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC 558 &subject_token_type= 559 urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token 561 Figure 2: Token Exchange Request 563 The authorization server validates the client credentials and the 564 "subject_token" presented in the token exchange request. From the 565 "resource" parameter, the authorization server is able to determine 566 the appropriate policy to apply to the request and issues a token 567 suitable for use at https://backend.example.com. The "access_token" 568 parameter of the response shown in Figure 3 contains the new token, 569 which is itself a bearer OAuth access token that is valid for one 570 minute. The token happens to be a JWT; however, its structure and 571 format are opaque to the client so the "issued_token_type" indicates 572 only that it is an access token. 574 HTTP/1.1 200 OK 575 Content-Type: application/json 576 Cache-Control: no-cache, no-store 578 { 579 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQiOiJo 580 dHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2FzLmV 581 4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1MzMsIn 582 N1YiI6ImJkY0BleGFtcGxlLmNvbSIsInNjb3BlIjoiYXBpIn0.40y3ZgQedw6rx 583 f59WlwHDD9jryFOr0_Wh3CGozQBihNBhnXEQgU85AI9x3KmsPottVMLPIWvmDCM 584 y5-kdXjwhw", 585 "issued_token_type": 586 "urn:ietf:params:oauth:token-type:access_token", 587 "token_type":"Bearer", 588 "expires_in":60 589 } 591 Figure 3: Token Exchange Response 593 The resource server can then use the newly acquired access token in 594 making a request to the backend server as illustrated in Figure 4. 596 GET /api HTTP/1.1 597 Host: backend.example.com 598 Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQ 599 iOiJodHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2 600 FzLmV4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1M 601 zMsInN1YiI6ImJkY0BleGFtcGxlLmNvbSIsInNjb3BlIjoiYXBpIn0.40y3ZgQe 602 dw6rxf59WlwHDD9jryFOr0_Wh3CGozQBihNBhnXEQgU85AI9x3KmsPottVMLPIW 603 vmDCMy5-kdXjwhw 605 Figure 4: Backend Protected Resource Request 607 Additional examples can be found in Appendix A. 609 3. Token Type Identifiers 611 Several parameters in this specification utilize an identifier as the 612 value to describe the token in question. Specifically, they are the 613 "requested_token_type", "subject_token_type", "actor_token_type" 614 parameters of the request and the "issued_token_type" member of the 615 response. Token type identifiers are URIs. Token Exchange can work 616 with both tokens issued by other parties and tokens from the given 617 authorization server. For the former the token type identifier 618 indicates the syntax (e.g., JWT or SAML 2.0) so the authorization 619 server can parse it; for the latter it indicates what the given 620 authorization server issued it for (e.g., access_token or 621 refresh_token). 623 The following token type identifiers are defined by this 624 specification. Other URIs MAY be used to indicate other token types. 626 urn:ietf:params:oauth:token-type:access_token 627 Indicates that the token is an OAuth 2.0 access token issued by 628 the given authorization server. 630 urn:ietf:params:oauth:token-type:refresh_token 631 Indicates that the token is an OAuth 2.0 refresh token issued by 632 the given authorization server. 634 urn:ietf:params:oauth:token-type:id_token 635 Indicates that the token is an ID Token, as defined in Section 2 636 of [OpenID.Core]. 638 urn:ietf:params:oauth:token-type:saml1 639 Indicates that the token is a base64url-encoded SAML 1.1 640 [OASIS.saml-core-1.1] assertion. 642 urn:ietf:params:oauth:token-type:saml2 643 Indicates that the token is a base64url-encoded SAML 2.0 644 [OASIS.saml-core-2.0-os] assertion. 646 The value "urn:ietf:params:oauth:token-type:jwt", which is defined in 647 Section 9 of [JWT], indicates that the token is a JWT. 649 The distinction between an access token and a JWT is subtle. An 650 access token represents a delegated authorization decision, whereas 651 JWT is a token format. An access token can be formatted as a JWT but 652 doesn't necessarily have to be. And a JWT might well be an access 653 token but not all JWTs are access tokens. The intent of this 654 specification is that "urn:ietf:params:oauth:token-type:access_token" 655 be an indicator that the token is a typical OAuth access token issued 656 by the authorization server in question, opaque to the client, and 657 usable the same manner as any other access token obtained from that 658 authorization server. (It could well be a JWT, but the client isn't 659 and needn't be aware of that fact.) Whereas, 660 "urn:ietf:params:oauth:token-type:jwt" is to indicate specifically 661 that a JWT is being requested or sent (perhaps in a cross-domain use- 662 case where the JWT is used as an authorization grant to obtain an 663 access token from a different authorization server as is facilitated 664 by [RFC7523]). 666 Note that for tokens which are binary in nature, the URI used for 667 conveying them needs to be associated with the semantics of a base64 668 or other encoding suitable for usage with HTTP and OAuth. 670 4. JSON Web Token Claims and Introspection Response Parameters 672 It is useful to have defined mechanisms to express delegation within 673 a token as well as to express authorization to delegate or 674 impersonate. Although the token exchange protocol described herein 675 can be used with any type of token, this section defines claims to 676 express such semantics specifically for JWTs and in an OAuth 2.0 677 Token Introspection [RFC7662] response. Similar definitions for 678 other types of tokens are possible but beyond the scope of this 679 specification. 681 Note that the claims not established herein but used in examples and 682 descriptions, such as "iss", "sub", "exp", etc., are defined by 683 [JWT]. 685 4.1. "act" (Actor) Claim 687 The "act" (actor) claim provides a means within a JWT to express that 688 delegation has occurred and identify the acting party to whom 689 authority has been delegated. The "act" claim value is a JSON object 690 and members in the JSON object are claims that identify the actor. 691 The claims that make up the "act" claim identify and possibly provide 692 additional information about the actor. For example, the combination 693 of the two claims "iss" and "sub" might be necessary to uniquely 694 identify an actor. 696 However, claims within the "act" claim pertain only to the identity 697 of the actor and are not relevant to the validity of the containing 698 JWT in the same manner as the top-level claims. Consequently, non- 699 identity claims (e.g., "exp", "nbf", and "aud") are not meaningful 700 when used within an "act" claim, and therefore are not used. 702 Figure 5 illustrates the "act" (actor) claim within a JWT Claims Set. 703 The claims of the token itself are about user@example.com while the 704 "act" claim indicates that admin@example.com is the current actor. 706 { 707 "aud":"https://consumer.example.com", 708 "iss":"https://issuer.example.com", 709 "exp":1443904177, 710 "nbf":1443904077, 711 "sub":"user@example.com", 712 "act": 713 { 714 "sub":"admin@example.com" 715 } 716 } 718 Figure 5: Actor Claim 720 A chain of delegation can be expressed by nesting one "act" claim 721 within another. The outermost "act" claim represents the current 722 actor while nested "act" claims represent prior actors. The least 723 recent actor is the most deeply nested. The nested "act" claims 724 serve as a history trail that connects the initial request and 725 subject through the various delegation steps undertaken before 726 reaching the current actor. In this sense, the current actor is 727 considered to include the entire authorization/delegation history, 728 leading naturally to the nested structure described here. 730 For the purpose of applying access control policy, the consumer of a 731 token MUST only consider the token's top-level claims and the party 732 identified as the current actor by the "act" claim. Prior actors 733 identified by any nested "act" claims are informational only and are 734 not to be considered in access control decisions. 736 The following example in Figure 6 illustrates nested "act" (actor) 737 claims within a JWT Claims Set. The claims of the token itself are 738 about user@example.com while the "act" claim indicates that the 739 system https://service16.example.com is the current actor and 740 https://service77.example.com was a prior actor. Such a token might 741 come about as the result of service16 receiving a token in a call 742 from service77 and exchanging it for a token suitable to call 743 service26 while the authorization server notes the situation in the 744 newly issued token. 746 { 747 "aud":"https://service26.example.com", 748 "iss":"https://issuer.example.com", 749 "exp":1443904100, 750 "nbf":1443904000, 751 "sub":"user@example.com", 752 "act": 753 { 754 "sub":"https://service16.example.com", 755 "act": 756 { 757 "sub":"https://service77.example.com" 758 } 759 } 760 } 762 Figure 6: Nested Actor Claim 764 When included as a top-level member of an OAuth token introspection 765 response, "act" has the same semantics and format as the claim of the 766 same name. 768 4.2. "scope" (Scopes) Claim 770 The value of the "scope" claim is a JSON string containing a space- 771 separated list of scopes associated with the token, in the format 772 described in Section 3.3 of [RFC6749]. 774 Figure 7 illustrates the "scope" claim within a JWT Claims Set. 776 { 777 "aud":"https://consumer.example.com", 778 "iss":"https://issuer.example.com", 779 "exp":1443904177, 780 "nbf":1443904077, 781 "sub":"dgaf4mvfs75Fci_FL3heQA", 782 "scope":"email profile phone address" 783 } 785 Figure 7: Scopes Claim 787 OAuth 2.0 Token Introspection [RFC7662] already defines the "scope" 788 parameter to convey the scopes associated with the token. 790 4.3. "client_id" (Client Identifier) Claim 792 The "client_id" claim carries the client identifier of the OAuth 2.0 793 [RFC6749] client that requested the token. 795 The following example in Figure 8 illustrates the "client_id" claim 796 within a JWT Claims Set indicating an OAuth 2.0 client with 797 "s6BhdRkqt3" as its identifier. 799 { 800 "aud":"https://consumer.example.com", 801 "iss":"https://issuer.example.com", 802 "exp":1443904177, 803 "sub":"user@example.com", 804 "client_id":"s6BhdRkqt3" 805 } 807 Figure 8: Client Identifier Claim 809 OAuth 2.0 Token Introspection [RFC7662] already defines the 810 "client_id" parameter as the client identifier for the OAuth 2.0 811 client that requested the token. 813 4.4. "may_act" (Authorized Actor) Claim 815 The "may_act" claim makes a statement that one party is authorized to 816 become the actor and act on behalf of another party. The claim might 817 be used, for example, when a "subject_token" is presented to the 818 token endpoint in a token exchange request and "may_act" claim in the 819 subject token can be used by the authorization server to determine 820 whether the client (or party identified in the "actor_token") is 821 authorized to engage in the requested delegation or impersonation. 823 The claim value is a JSON object and members in the JSON object are 824 claims that identify the party that is asserted as being eligible to 825 act for the party identified by the JWT containing the claim. The 826 claims that make up the "may_act" claim identify and possibly provide 827 additional information about the authorized actor. For example, the 828 combination of the two claims "iss" and "sub" are sometimes necessary 829 to uniquely identify an authorized actor, while the "email" claim 830 might be used to provide additional useful information about that 831 party. 833 However, claims within the "may_act" claim pertain only to the 834 identity of that party and are not relevant to the validity of the 835 containing JWT in the same manner as top-level claims. Consequently, 836 claims such as "exp", "nbf", and "aud" are not meaningful when used 837 within a "may_act" claim, and therefore are not used. 839 Figure 9 illustrates the "may_act" claim within a JWT Claims Set. 840 The claims of the token itself are about user@example.com while the 841 "may_act" claim indicates that admin@example.com is authorized to act 842 on behalf of user@example.com. 844 { 845 "aud":"https://consumer.example.com", 846 "iss":"https://issuer.example.com", 847 "exp":1443904177, 848 "nbf":1443904077, 849 "sub":"user@example.com", 850 "may_act": 851 { 852 "sub":"admin@example.com" 853 } 854 } 856 Figure 9: Authorized Actor Claim 858 When included as a top-level member of an OAuth token introspection 859 response, "may_act" has the same semantics and format as the claim of 860 the same name. 862 5. Security Considerations 864 Much of the guidance from Section 10 of [RFC6749], the Security 865 Considerations in The OAuth 2.0 Authorization Framework, is also 866 applicable here. Furthermore, [RFC6819] provides additional security 867 considerations for OAuth and [I-D.ietf-oauth-security-topics] has 868 updated security guidance based on deployment experience and new 869 threats that have emerged since OAuth 2.0 was originally published. 871 All of the normal security issues that are discussed in [JWT], 872 especially in relationship to comparing URIs and dealing with 873 unrecognized values, also apply here. 875 In addition, both delegation and impersonation introduce unique 876 security issues. Any time one principal is delegated the rights of 877 another principal, the potential for abuse is a concern. The use of 878 the "scope" claim (in addition to other typical constraints such as a 879 limited token lifetime) is suggested to mitigate potential for such 880 abuse, as it restricts the contexts in which the delegated rights can 881 be exercised. 883 6. Privacy Considerations 885 Tokens employed in the context of the functionality described herein 886 may contain privacy-sensitive information and, to prevent disclosure 887 of such information to unintended parties, MUST only be transmitted 888 over encrypted channels, such as Transport Layer Security (TLS). In 889 cases where it is desirable to prevent disclosure of certain 890 information to the client, the token MUST be encrypted to its 891 intended recipient. Deployments SHOULD determine the minimally 892 necessary amount of data and only include such information in issued 893 tokens. In some cases, data minimization may include representing 894 only an anonymous or pseudonymous user. 896 7. IANA Considerations 898 7.1. OAuth URI Registration 900 This specification registers the following values in the IANA "OAuth 901 URI" registry [IANA.OAuth.Parameters] established by [RFC6755]. 903 7.1.1. Registry Contents 905 o URN: urn:ietf:params:oauth:grant-type:token-exchange 906 o Common Name: Token exchange grant type for OAuth 2.0 907 o Change controller: IESG 908 o Specification Document: Section 2.1 of [[ this specification ]] 910 o URN: urn:ietf:params:oauth:token-type:access_token 911 o Common Name: Token type URI for an OAuth 2.0 access token 912 o Change controller: IESG 913 o Specification Document: Section 3 of [[this specification]] 915 o URN: urn:ietf:params:oauth:token-type:refresh_token 916 o Common Name: Token type URI for an OAuth 2.0 refresh token 917 o Change controller: IESG 918 o Specification Document: Section 3 of [[this specification]] 919 o URN: urn:ietf:params:oauth:token-type:id_token 920 o Common Name: Token type URI for an ID Token 921 o Change controller: IESG 922 o Specification Document: Section 3 of [[this specification]] 924 o URN: urn:ietf:params:oauth:token-type:saml1 925 o Common Name: Token type URI for a base64url-encoded SAML 1.1 926 assertion 927 o Change Controller: IESG 928 o Specification Document: Section 3 of [[this specification]] 930 o URN: urn:ietf:params:oauth:token-type:saml2 931 o Common Name: Token type URI for a base64url-encoded SAML 2.0 932 assertion 933 o Change Controller: IESG 934 o Specification Document: Section 3 of [[this specification]] 936 7.2. OAuth Parameters Registration 938 This specification registers the following values in the IANA "OAuth 939 Parameters" registry [IANA.OAuth.Parameters] established by 940 [RFC6749]. 942 7.2.1. Registry Contents 944 o Parameter name: resource 945 o Parameter usage location: token request 946 o Change controller: IESG 947 o Specification document(s): Section 2.1 of [[ this specification ]] 949 o Parameter name: audience 950 o Parameter usage location: token request 951 o Change controller: IESG 952 o Specification document(s): Section 2.1 of [[ this specification ]] 954 o Parameter name: requested_token_type 955 o Parameter usage location: token request 956 o Change controller: IESG 957 o Specification document(s): Section 2.1 of [[ this specification ]] 959 o Parameter name: subject_token 960 o Parameter usage location: token request 961 o Change controller: IESG 962 o Specification document(s): Section 2.1 of [[ this specification ]] 964 o Parameter name: subject_token_type 965 o Parameter usage location: token request 966 o Change controller: IESG 967 o Specification document(s): Section 2.1 of [[ this specification ]] 969 o Parameter name: actor_token 970 o Parameter usage location: token request 971 o Change controller: IESG 972 o Specification document(s): Section 2.1 of [[ this specification ]] 974 o Parameter name: actor_token_type 975 o Parameter usage location: token request 976 o Change controller: IESG 977 o Specification document(s): Section 2.1 of [[ this specification ]] 979 o Parameter name: issued_token_type 980 o Parameter usage location: token response 981 o Change controller: IESG 982 o Specification document(s): Section 2.2.1 of [[ this specification 983 ]] 985 7.3. OAuth Access Token Type Registration 987 This specification registers the following access token type in the 988 IANA "OAuth Access Token Types" registry [IANA.OAuth.Parameters] 989 established by [RFC6749]. 991 7.3.1. Registry Contents 993 o Type name: N_A 994 o Additional Token Endpoint Response Parameters: (none) 995 o HTTP Authentication Scheme(s): (none) 996 o Change controller: IESG 997 o Specification document(s): Section 2.2.1 of [[ this specification 998 ]] 1000 7.4. JSON Web Token Claims Registration 1002 This specification registers the following Claims in the IANA "JSON 1003 Web Token Claims" registry [IANA.JWT.Claims] established by [JWT]. 1005 7.4.1. Registry Contents 1007 o Claim Name: "act" 1008 o Claim Description: Actor 1009 o Change Controller: IESG 1010 o Specification Document(s): Section 4.1 of [[ this specification ]] 1012 o Claim Name: "scope" 1013 o Claim Description: Scope Values 1014 o Change Controller: IESG 1015 o Specification Document(s): Section 4.2 of [[ this specification ]] 1017 o Claim Name: "client_id" 1018 o Claim Description: Client Identifier 1019 o Change Controller: IESG 1020 o Specification Document(s): Section 4.3 of [[ this specification ]] 1022 o Claim Name: "may_act" 1023 o Claim Description: Authorized Actor - the party that is authorized 1024 to become the actor 1025 o Change Controller: IESG 1026 o Specification Document(s): Section 4.4 of [[ this specification ]] 1028 7.5. OAuth Token Introspection Response Registration 1030 This specification registers the following values in the IANA "OAuth 1031 Token Introspection Response" registry [IANA.OAuth.Parameters] 1032 established by [RFC7662]. 1034 7.5.1. Registry Contents 1036 o Claim Name: "act" 1037 o Claim Description: Actor 1038 o Change Controller: IESG 1039 o Specification Document(s): Section 4.1 of [[ this specification ]] 1041 o Claim Name: "may_act" 1042 o Claim Description: Authorized Actor - the party that is authorized 1043 to become the actor 1044 o Change Controller: IESG 1045 o Specification Document(s): Section 4.4 of [[ this specification ]] 1047 7.6. OAuth Extensions Error Registration 1049 This specification registers the following values in the IANA "OAuth 1050 Extensions Error" registry [IANA.OAuth.Parameters] established by 1051 [RFC6749]. 1053 7.6.1. Registry Contents 1055 o Error Name: "invalid_target" 1056 o Error Usage Location: token error response 1057 o Related Protocol Extension: OAuth 2.0 Token Exchange 1058 o Change Controller: IETF 1059 o Specification Document(s): Section 2.2.2 of [[ this specification 1060 ]] 1062 8. References 1064 8.1. Normative References 1066 [IANA.JWT.Claims] 1067 IANA, "JSON Web Token Claims", 1068 . 1070 [IANA.OAuth.Parameters] 1071 IANA, "OAuth Parameters", 1072 . 1074 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1075 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1076 . 1078 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1079 Requirement Levels", BCP 14, RFC 2119, 1080 DOI 10.17487/RFC2119, March 1997, 1081 . 1083 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1084 Resource Identifier (URI): Generic Syntax", STD 66, 1085 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1086 . 1088 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1089 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1090 . 1092 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 1093 RFC 7662, DOI 10.17487/RFC7662, October 2015, 1094 . 1096 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1097 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1098 May 2017, . 1100 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1101 Interchange Format", STD 90, RFC 8259, 1102 DOI 10.17487/RFC8259, December 2017, 1103 . 1105 8.2. Informative References 1107 [I-D.ietf-oauth-resource-indicators] 1108 Campbell, B., Bradley, J., and H. Tschofenig, "Resource 1109 Indicators for OAuth 2.0", draft-ietf-oauth-resource- 1110 indicators-02 (work in progress), January 2019. 1112 [I-D.ietf-oauth-security-topics] 1113 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 1114 "OAuth 2.0 Security Best Current Practice", draft-ietf- 1115 oauth-security-topics-13 (work in progress), July 2019. 1117 [OASIS.saml-core-1.1] 1118 Maler, E., Mishra, P., and R. Philpott, "Assertions and 1119 Protocol for the OASIS Security Assertion Markup Language 1120 (SAML) V1.1", OASIS Standard oasis-sstc-saml-core-1.1, 1121 September 2003. 1123 [OASIS.saml-core-2.0-os] 1124 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 1125 "Assertions and Protocol for the OASIS Security Assertion 1126 Markup Language (SAML) V2.0", OASIS Standard saml-core- 1127 2.0-os, March 2005. 1129 [OpenID.Core] 1130 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 1131 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 1132 . 1134 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1135 Framework: Bearer Token Usage", RFC 6750, 1136 DOI 10.17487/RFC6750, October 2012, 1137 . 1139 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 1140 for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, 1141 . 1143 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 1144 Threat Model and Security Considerations", RFC 6819, 1145 DOI 10.17487/RFC6819, January 2013, 1146 . 1148 [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 1149 "Assertion Framework for OAuth 2.0 Client Authentication 1150 and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, 1151 May 2015, . 1153 [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 1154 (JWT) Profile for OAuth 2.0 Client Authentication and 1155 Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 1156 2015, . 1158 [WS-Trust] 1159 Nadalin, A., Goodner, M., Gudgin, M., Barbir, A., and H. 1160 Granqvist, "WS-Trust 1.4", February 2012, 1161 . 1164 Appendix A. Additional Token Exchange Examples 1166 Two example token exchanges are provided in the following sections 1167 illustrating impersonation and delegation, respectively (with extra 1168 line breaks and indentation for display purposes only). 1170 A.1. Impersonation Token Exchange Example 1172 A.1.1. Token Exchange Request 1174 In the following token exchange request, a client is requesting a 1175 token with impersonation semantics (with only a "subject_token" and 1176 no "actor_token", delegation is impossible). The client tells the 1177 authorization server that it needs a token for use at the target 1178 service with the logical name "urn:example:cooperation-context". 1180 POST /as/token.oauth2 HTTP/1.1 1181 Host: as.example.com 1182 Content-Type: application/x-www-form-urlencoded 1184 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 1185 &audience=urn%3Aexample%3Acooperation-context 1186 &subject_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwc 1187 zovL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXI 1188 uZXhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTA2MDAsIm5iZiI6MTQ0MTkwOTAwMCwic 1189 3ViIjoiYmRjQGV4YW1wbGUubmV0Iiwic2NvcGUiOiJvcmRlcnMgcHJvZmlsZSBoaXN 1190 0b3J5In0.PRBg-jXn4cJuj1gmYXFiGkZzRuzbXZ_sDxdE98ddW44ufsbWLKd3JJ1VZ 1191 hF64pbTtfjy4VXFVBDaQpKjn5JzAw 1192 &subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1194 Figure 10: Token Exchange Request 1196 A.1.2. Subject Token Claims 1198 The "subject_token" in the prior request is a JWT and the decoded JWT 1199 Claims Set is shown here. The JWT is intended for consumption by the 1200 authorization server within a specific time window. The subject of 1201 the JWT ("bdc@example.net") is the party on behalf of whom the new 1202 token is being requested. 1204 { 1205 "aud":"https://as.example.com", 1206 "iss":"https://original-issuer.example.net", 1207 "exp":1441910600, 1208 "nbf":1441909000, 1209 "sub":"bdc@example.net", 1210 "scope":"orders profile history" 1211 } 1213 Figure 11: Subject Token Claims 1215 A.1.3. Token Exchange Response 1217 The "access_token" parameter of the token exchange response shown 1218 below contains the new token that the client requested. The other 1219 parameters of the response indicate that the token is a bearer access 1220 token that expires in an hour. 1222 HTTP/1.1 200 OK 1223 Content-Type: application/json 1224 Cache-Control: no-cache, no-store 1226 { 1227 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm4 1228 6ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5l 1229 eGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic3ViIjoiYmRjQGV4YW1wbGUub 1230 mV0Iiwic2NvcGUiOiJvcmRlcnMgcHJvZmlsZSBoaXN0b3J5In0.rMdWpSGNACTvnF 1231 uOL74sYZ6MVuld2Z2WkGLmQeR9ztj6w2OXraQlkJmGjyiCq24kcB7AI2VqVxl3wSW 1232 nVKh85A", 1233 "issued_token_type": 1234 "urn:ietf:params:oauth:token-type:access_token", 1235 "token_type":"Bearer", 1236 "expires_in":3600 1237 } 1239 Figure 12: Token Exchange Response 1241 A.1.4. Issued Token Claims 1243 The decoded JWT Claims Set of the issued token is shown below. The 1244 new JWT is issued by the authorization server and intended for 1245 consumption by a system entity known by the logical name 1246 "urn:example:cooperation-context" any time before its expiration. 1247 The subject ("sub") of the JWT is the same as the subject the token 1248 used to make the request, which effectively enables the client to 1249 impersonate that subject at the system entity known by the logical 1250 name of "urn:example:cooperation-context" by using the token. 1252 { 1253 "aud":"urn:example:cooperation-context", 1254 "iss":"https://as.example.com", 1255 "exp":1441913610, 1256 "sub":"bdc@example.net", 1257 "scope":"orders profile history" 1258 } 1260 Figure 13: Issued Token Claims 1262 A.2. Delegation Token Exchange Example 1264 A.2.1. Token Exchange Request 1266 In the following token exchange request, a client is requesting a 1267 token and providing both a "subject_token" and an "actor_token". The 1268 client tells the authorization server that it needs a token for use 1269 at the target service with the logical name "urn:example:cooperation- 1270 context". Policy at the authorization server dictates that the 1271 issued token be a composite. 1273 POST /as/token.oauth2 HTTP/1.1 1274 Host: as.example.com 1275 Content-Type: application/x-www-form-urlencoded 1277 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 1278 &audience=urn%3Aexample%3Acooperation-context 1279 &subject_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwc 1280 zovL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXI 1281 uZXhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTAwNjAsInNjb3BlIjoic3RhdHVzIGZlZ 1282 WQiLCJzdWIiOiJ1c2VyQGV4YW1wbGUubmV0IiwibWF5X2FjdCI6eyJzdWIiOiJhZG1 1283 pbkBleGFtcGxlLm5ldCJ9fQ.4rPRSWihQbpMIgAmAoqaJojAxj-p2X8_fAtAGTXrvM 1284 xU-eEZHnXqY0_AOZgLdxw5DyLzua8H_I10MCcckF-Q_g 1285 &subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1286 &actor_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwczo 1287 vL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXIuZ 1288 XhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTAwNjAsInN1YiI6ImFkbWluQGV4YW1wbGU 1289 ubmV0In0.7YQ-3zPfhUvzje5oqw8COCvN5uP6NsKik9CVV6cAOf4QKgM-tKfiOwcgZ 1290 oUuDL2tEs6tqPlcBlMjiSzEjm3yBg 1291 &actor_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1293 Figure 14: Token Exchange Request 1295 A.2.2. Subject Token Claims 1297 The "subject_token" in the prior request is a JWT and the decoded JWT 1298 Claims Set is shown here. The JWT is intended for consumption by the 1299 authorization server before a specific expiration time. The subject 1300 of the JWT ("user@example.net") is the party on behalf of whom the 1301 new token is being requested. 1303 { 1304 "aud":"https://as.example.com", 1305 "iss":"https://original-issuer.example.net", 1306 "exp":1441910060, 1307 "scope":"status feed", 1308 "sub":"user@example.net", 1309 "may_act": 1310 { 1311 "sub":"admin@example.net" 1312 } 1313 } 1315 Figure 15: Subject Token Claims 1317 A.2.3. Actor Token Claims 1319 The "actor_token" in the prior request is a JWT and the decoded JWT 1320 Claims Set is shown here. This JWT is also intended for consumption 1321 by the authorization server before a specific expiration time. The 1322 subject of the JWT ("admin@example.net") is the actor that will wield 1323 the security token being requested. 1325 { 1326 "aud":"https://as.example.com", 1327 "iss":"https://original-issuer.example.net", 1328 "exp":1441910060, 1329 "sub":"admin@example.net" 1330 } 1332 Figure 16: Actor Token Claims 1334 A.2.4. Token Exchange Response 1336 The "access_token" parameter of the token exchange response shown 1337 below contains the new token that the client requested. The other 1338 parameters of the response indicate that the token is a JWT that 1339 expires in an hour and that the access token type is not applicable 1340 since the issued token is not an access token. 1342 HTTP/1.1 200 OK 1343 Content-Type: application/json 1344 Cache-Control: no-cache, no-store 1346 { 1347 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm4 1348 6ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5l 1349 eGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic2NvcGUiOiJzdGF0dXMgZmVlZ 1350 CIsInN1YiI6InVzZXJAZXhhbXBsZS5uZXQiLCJhY3QiOnsic3ViIjoiYWRtaW5AZX 1351 hhbXBsZS5uZXQifX0.3paKl9UySKYB5ng6_cUtQ2qlO8Rc_y7Mea7IwEXTcYbNdwG 1352 9-G1EKCFe5fW3H0hwX-MSZ49Wpcb1SiAZaOQBtw", 1353 "issued_token_type":"urn:ietf:params:oauth:token-type:jwt", 1354 "token_type":"N_A", 1355 "expires_in":3600 1356 } 1358 Figure 17: Token Exchange Response 1360 A.2.5. Issued Token Claims 1362 The decoded JWT Claims Set of the issued token is shown below. The 1363 new JWT is issued by the authorization server and intended for 1364 consumption by a system entity known by the logical name 1365 "urn:example:cooperation-context" any time before its expiration. 1366 The subject ("sub") of the JWT is the same as the subject of the 1367 "subject_token" used to make the request. The actor ("act") of the 1368 JWT is the same as the subject of the "actor_token" used to make the 1369 request. This indicates delegation and identifies 1370 "admin@example.net" as the current actor to whom authority has been 1371 delegated to act on behalf of "user@example.net". 1373 { 1374 "aud":"urn:example:cooperation-context", 1375 "iss":"https://as.example.com", 1376 "exp":1441913610, 1377 "scope":"status feed", 1378 "sub":"user@example.net", 1379 "act": 1380 { 1381 "sub":"admin@example.net" 1382 } 1383 } 1385 Figure 18: Issued Token Claims 1387 Appendix B. Acknowledgements 1389 This specification was developed within the OAuth Working Group, 1390 which includes dozens of active and dedicated participants. It was 1391 produced under the chairmanship of Hannes Tschofenig, Derek Atkins, 1392 and Rifaat Shekh-Yusef with Kathleen Moriarty, Stephen Farrell, Eric 1393 Rescorla, Roman Danyliw, and Benjamin Kaduk serving as Security Area 1394 Directors. The following individuals contributed ideas, feedback, 1395 and wording to this specification: 1397 Caleb Baker, Vittorio Bertocci, Mike Brown, Thomas Broyer, Roman 1398 Danyliw, William Denniss, Vladimir Dzhuvinov, Eric Fazendin, Phil 1399 Hunt, Benjamin Kaduk, Jason Keglovitz, Torsten Lodderstedt, Barry 1400 Leiba, Adam Lewis, James Manger, Nov Matake, Matt Miller, Hilarie 1401 Orman, Matthew Perry, Eric Rescorla, Justin Richer, Adam Roach, 1402 Rifaat Shekh-Yusef, Scott Tomilson, and Hannes Tschofenig. 1404 Appendix C. Document History 1406 [[ to be removed by the RFC Editor before publication as an RFC ]] 1408 -19 1410 o Fix-up changes introduced in -18. 1411 o Fix invalid JSON in the Nested Actor Claim example. 1412 o Reference figure numbers in text when introducing the examples in 1413 Section 2 and 4. 1414 o Editorial updates from additional IESG evaluation comments. 1415 o Add an informational reference to ietf-oauth-resource-indicators 1416 o Update ietf-oauth-security-topics ref to 13 1418 -18 1420 o Editorial updates based on a few more IESG evaluation comments. 1422 -17 1424 o Editorial improvements and example fixes resulting from IESG 1425 evaluation comments. 1426 o Added a pointer to RFC6749's Appendix B. on the "Use of 1427 application/x-www-form-urlencoded Media Type" as a way of 1428 providing a normative citation (by reference) for the media type. 1429 o Strengthened some of the wording in the privacy considerations to 1430 bring it inline with RFC 7519 Sec. 12 and RFC 6749 Sec. 10.8. 1432 -16 1434 o Fixed typo and added an AD to Acknowledgements. 1436 -15 1438 o Updated the nested actor claim example to (hopefully) be more 1439 straightforward. 1440 o Reworked Privacy Considerations to say to use TLS in transit, 1441 minimize the amount of information in the token, and encrypt the 1442 token if disclosure of its information to the client is a concern 1443 per https://mailarchive.ietf.org/arch/msg/secdir/ 1444 KJhx4aq_U5uk3k6zpYP-CEHbpVM 1445 o Moved the Security and Privacy Considerations sections to before 1446 the IANA Considerations. 1448 -14 1450 o Added text in Section 4.1 about the "act" claim stating that only 1451 the top-level claims and the current actor are to be considered in 1452 applying access control decisions. 1454 -13 1456 o Updated the claim name and value syntax for scope to be consistent 1457 with the treatment of scope in RFC 7662 OAuth 2.0 Token 1458 Introspection. 1459 o Updated the client identifier claim name to be consistent with the 1460 treatment of client id in RFC 7662 OAuth 2.0 Token Introspection. 1462 -12 1464 o Updated to use the boilerplate from RFC 8174. 1466 -11 1468 o Added new WG chair and AD to the Acknowledgements. 1469 o Applied clarifications suggested during AD review by EKR. 1471 -10 1473 o Defined token type URIs for base64url-encoded SAML 1.1 and SAML 1474 2.0 assertions. 1475 o Applied editorial fixes. 1477 -09 1479 o Changed "security tokens obtained could be used in a number of 1480 contexts" to "security tokens obtained may be used in a number of 1481 contexts" per a WGLC suggestion. 1483 o Clarified that the validity of the subject or actor token have no 1484 impact on the validity of the issued token after the exchange has 1485 occurred per a WGLC comment. 1486 o Changed use of invalid_target error code to a SHOULD per a WGLC 1487 comment. 1488 o Clarified text about non-identity claims within the "act" claim 1489 being meaningless per a WGLC comment. 1490 o Added brief Privacy Considerations section per WGLC comments. 1492 -08 1494 o Use the bibxml reference for OpenID.Core rather than defining it 1495 inline. 1496 o Added editor role for Campbell. 1497 o Minor clarification of the text for actor_token. 1499 -07 1501 o Fixed typo (desecration -> discretion). 1502 o Added an explanation of the relationship between scope, audience 1503 and resource in the request and added an "invalid_target" error 1504 code enabling the AS to tell the client that the requested 1505 audiences/resources were too broad. 1507 -06 1509 o Drop "An STS for the REST of Us" from the title. 1510 o Drop "heavyweight" and "lightweight" from the abstract and 1511 introduction. 1512 o Clarifications on the language around xxxxxx_token_type. 1513 o Remove the want_composite parameter. 1514 o Add a short mention of proof-of-possession style tokens to the 1515 introduction and remove the respective open issue. 1517 -05 1519 o Defined the JWT claim "cid" to express the OAuth 2.0 client 1520 identifier of the client that requested the token. 1521 o Defined and requested registration for "act" and "may_act" as 1522 Token introspection response parameters (in addition to being JWT 1523 claims). 1524 o Loosen up the language about refresh_token in the response to 1525 OPTIONAL from NOT RECOMMENDED based on feedback form real world 1526 deployment experience. 1527 o Add clarifying text about the distinction between JWT and access 1528 token URIs. 1529 o Close out (remove) some of the Open Issues bullets that have been 1530 resolved. 1532 -04 1534 o Clarified that the "resource" and "audience" request parameters 1535 can be used at the same time (via http://www.ietf.org/mail- 1536 archive/web/oauth/current/msg15335.html). 1537 o Clarified subject/actor token validity after token exchange and 1538 explained a bit more about the recommendation to not issue refresh 1539 tokens (via http://www.ietf.org/mail-archive/web/oauth/current/ 1540 msg15318.html). 1541 o Updated the examples appendix to use an issuer value that doesn't 1542 imply that the client issued and signed the tokens and used 1543 "Bearer" and "urn:ietf:params:oauth:token-type:access_token" in 1544 one of the responses (via http://www.ietf.org/mail- 1545 archive/web/oauth/current/msg15335.html). 1546 o Defined and registered urn:ietf:params:oauth:token-type:id_token, 1547 since some use cases perform token exchanges for ID Tokens and no 1548 URI to indicate that a token is an ID Token had previously been 1549 defined. 1551 -03 1553 o Updated the document editors (adding Campbell, Bradley, and 1554 Mortimore). 1555 o Added to the title. 1556 o Added to the abstract and introduction. 1557 o Updated the format of the request to use application/x-www-form- 1558 urlencoded request parameters and the response to use the existing 1559 token endpoint JSON parameters defined in OAuth 2.0. 1560 o Changed the grant type identifier to urn:ietf:params:oauth:grant- 1561 type:token-exchange. 1562 o Added RFC 6755 registration requests for 1563 urn:ietf:params:oauth:token-type:refresh_token, 1564 urn:ietf:params:oauth:token-type:access_token, and 1565 urn:ietf:params:oauth:grant-type:token-exchange. 1566 o Added RFC 6749 registration requests for request/response 1567 parameters. 1568 o Removed the Implementation Considerations and the requirement to 1569 support JWTs. 1570 o Clarified many aspects of the text. 1571 o Changed "on_behalf_of" to "subject_token", 1572 "on_behalf_of_token_type" to "subject_token_type", "act_as" to 1573 "actor_token", and "act_as_token_type" to "actor_token_type". 1574 o Added an "audience" request parameter used to indicate the logical 1575 names of the target services at which the client intends to use 1576 the requested security token. 1577 o Added a "want_composite" request parameter used to indicate the 1578 desire for a composite token rather than trying to infer it from 1579 the presence/absence of token(s) in the request. 1581 o Added a "resource" request parameter used to indicate the URLs of 1582 resources at which the client intends to use the requested 1583 security token. 1584 o Specified that multiple "audience" and "resource" request 1585 parameter values may be used. 1586 o Defined the JWT claim "act" (actor) to express the current actor 1587 or delegation principal. 1588 o Defined the JWT claim "may_act" to express that one party is 1589 authorized to act on behalf of another party. 1590 o Defined the JWT claim "scp" (scopes) to express OAuth 2.0 scope- 1591 token values. 1592 o Added the "N_A" (not applicable) OAuth Access Token Type 1593 definition for use in contexts in which the token exchange syntax 1594 requires a "token_type" value, but in which the token being issued 1595 is not an access token. 1596 o Added examples. 1598 -02 1600 o Enabled use of Security Token types other than JWTs for "act_as" 1601 and "on_behalf_of" request values. 1602 o Referenced the JWT and OAuth Assertions RFCs. 1604 -01 1606 o Updated references. 1608 -00 1610 o Created initial working group draft from draft-jones-oauth-token- 1611 exchange-01. 1613 Authors' Addresses 1615 Michael B. Jones 1616 Microsoft 1618 Email: mbj@microsoft.com 1619 URI: http://self-issued.info/ 1621 Anthony Nadalin 1622 Microsoft 1624 Email: tonynad@microsoft.com 1625 Brian Campbell (editor) 1626 Ping Identity 1628 Email: brian.d.campbell@gmail.com 1630 John Bradley 1631 Yubico 1633 Email: ve7jtb@ve7jtb.com 1635 Chuck Mortimore 1636 Salesforce 1638 Email: cmortimore@salesforce.com