idnits 2.17.1 draft-ietf-oauth-token-exchange-18.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 6, 2019) is 1756 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 (-26) exists of draft-ietf-oauth-security-topics-12 Summary: 0 errors (**), 0 flaws (~~), 2 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 7, 2020 B. Campbell, Ed. 6 Ping Identity 7 J. Bradley 8 Yubico 9 C. Mortimore 10 Salesforce 11 July 6, 2019 13 OAuth 2.0 Token Exchange 14 draft-ietf-oauth-token-exchange-18 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 7, 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 . . . . . . . . . . . . . . . . 28 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, which it received in a protected resource request, for 159 a 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. 205 Delegation semantics are different than impersonation semantics, 206 though the two are closely related. With delegation semantics, 207 principal A still has its own identity separate from B and it is 208 explicitly understood that while B may have delegated some of its 209 rights to A, any actions taken are being taken by A representing B. 210 In a sense, A is an agent for B. 212 Delegation and impersonation are not inclusive of all situations. 213 When a principal is acting directly on its own behalf, for example, 214 neither delegation nor impersonation are in play. They are, however, 215 the more common semantics operating for token exchange and, as such, 216 are given more direct treatment in this specification. 218 Delegation semantics are typically expressed in a token by including 219 information about both the primary subject of the token as well as 220 the actor to whom that subject has delegated some of its rights. 221 Such a token is sometimes referred to as a composite token because it 222 is composed of information about multiple subjects. Typically, in 223 the request, the "subject_token" represents the identity of the party 224 on behalf of whom the token is being requested while the 225 "actor_token" represents the identity of the party to whom the access 226 rights of the issued token are being delegated. A composite token 227 issued by the authorization server will contain information about 228 both parties. When and if a composite token is issued is at the 229 discretion of the authorization server and applicable policy and 230 configuration. 232 The specifics of representing a composite token and even whether or 233 not such a token will be issued depend on the details of the 234 implementation and the kind of token. The representations of 235 composite tokens that are not JWTs are beyond the scope of this 236 specification. The "actor_token" request parameter, however, does 237 provide a means for providing information about the desired actor and 238 the JWT "act" claim can provide a representation of a chain of 239 delegation. 241 1.2. Requirements Notation and Conventions 243 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 244 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 245 "OPTIONAL" in this document are to be interpreted as described in BCP 246 14 [RFC2119] [RFC8174] when, and only when, they appear in all 247 capitals, as shown here. 249 1.3. Terminology 251 This specification uses the terms "access token type", "authorization 252 server", "client", "client identifier", "resource server", "token 253 endpoint", "token request", and "token response" defined by OAuth 2.0 254 [RFC6749], and the terms "Base64url Encoding", "Claim", and "JWT 255 Claims Set" defined by JSON Web Token (JWT) [JWT]. 257 2. Token Exchange Request and Response 259 2.1. Request 261 A client requests a security token by making a token request to the 262 authorization server's token endpoint using the extension grant type 263 mechanism defined in Section 4.5 of [RFC6749]. 265 Client authentication to the authorization server is done using the 266 normal mechanisms provided by OAuth 2.0. Section 2.3.1 of [RFC6749] 267 defines password-based authentication of the client, however, client 268 authentication is extensible and other mechanisms are possible. For 269 example, [RFC7523] defines client authentication using bearer JSON 270 Web Tokens (JWTs) [JWT]. The supported methods of client 271 authentication and whether or not to allow unauthenticated or 272 unidentified clients are deployment decisions that are at the 273 discretion of the authorization server. Note that omitting client 274 authentication allows for a compromised token to be leveraged via an 275 STS into other tokens by anyone possessing the compromised token. 276 Thus client authentication allows for additional authorization checks 277 by the STS as to which entities are permitted to impersonate or 278 receive delegations from other entities. 280 The client makes a token exchange request to the token endpoint with 281 an extension grant type using the HTTP "POST" method. The following 282 parameters are included in the HTTP request entity-body using the 283 "application/x-www-form-urlencoded" format with a character encoding 284 of UTF-8 as described in Appendix B of RFC6749 [RFC6749]. 286 grant_type 287 REQUIRED. The value "urn:ietf:params:oauth:grant-type:token- 288 exchange" indicates that a token exchange is being performed. 290 resource 291 OPTIONAL. A URI that indicates the target service or resource 292 where the client intends to use the requested security token. 293 This enables the authorization server to apply policy as 294 appropriate for the target, such as determining the type and 295 content of the token to be issued or if and how the token is to be 296 encrypted. In many cases, a client will not have knowledge of the 297 logical organization of the systems with which it interacts and 298 will only know a URI of the service where it intends to use the 299 token. The "resource" parameter allows the client to indicate to 300 the authorization server where it intends to use the issued token 301 by providing the location, typically as an https URL, in the token 302 exchange request in the same form that will be used to access that 303 resource. The authorization server will typically have the 304 capability to map from a resource URI value to an appropriate 305 policy. The value of the "resource" parameter MUST be an absolute 306 URI, as specified by Section 4.3 of [RFC3986], which MAY include a 307 query component and MUST NOT include a fragment component. 308 Multiple "resource" parameters may be used to indicate that the 309 issued token is intended to be used at the multiple resources 310 listed. 312 audience 313 OPTIONAL. The logical name of the target service where the client 314 intends to use the requested security token. This serves a 315 purpose similar to the "resource" parameter, but with the client 316 providing a logical name for the target service. Interpretation 317 of the name requires that the value be something that both the 318 client and the authorization server understand. An OAuth client 319 identifier, a SAML entity identifier [OASIS.saml-core-2.0-os], an 320 OpenID Connect Issuer Identifier [OpenID.Core], are examples of 321 things that might be used as "audience" parameter values. 322 However, "audience" values used with a given authorization server 323 must be unique within that server, to ensure that they are 324 properly interpreted as the intended type of value. Multiple 325 "audience" parameters may be used to indicate that the issued 326 token is intended to be used at the multiple audiences listed. 327 The "audience" and "resource" parameters may be used together to 328 indicate multiple target services with a mix of logical names and 329 resource URIs. 331 scope 332 OPTIONAL. A list of space-delimited, case-sensitive strings, as 333 defined in Section 3.3 of [RFC6749], that allow the client to 334 specify the desired scope of the requested security token in the 335 context of the service or resource where the token will be used. 336 The values and associated semantics of scope are service specific 337 and expected to be described in the relevant service 338 documentation. 340 requested_token_type 341 OPTIONAL. An identifier, as described in Section 3, for the type 342 of the requested security token. If the requested type is 343 unspecified, the issued token type is at the discretion of the 344 authorization server and may be dictated by knowledge of the 345 requirements of the service or resource indicated by the 346 "resource" or "audience" parameter. 348 subject_token 349 REQUIRED. A security token that represents the identity of the 350 party on behalf of whom the request is being made. Typically, the 351 subject of this token will be the subject of the security token 352 issued in response to the request. 354 subject_token_type 355 REQUIRED. An identifier, as described in Section 3, that 356 indicates the type of the security token in the "subject_token" 357 parameter. 359 actor_token 360 OPTIONAL. A security token that represents the identity of the 361 acting party. Typically, this will be the party that is 362 authorized to use the requested security token and act on behalf 363 of the subject. 365 actor_token_type 366 An identifier, as described in Section 3, that indicates the type 367 of the security token in the "actor_token" parameter. This is 368 REQUIRED when the "actor_token" parameter is present in the 369 request but MUST NOT be included otherwise. 371 In processing the request, the authorization server MUST perform the 372 appropriate validation procedures for the indicated token type and, 373 if the actor token is present, also perform the appropriate 374 validation procedures for its indicated token type. The validity 375 criteria and details of any particular token are beyond the scope of 376 this document and are specific to the respective type of token and 377 its content. 379 In the absence of one-time-use or other semantics specific to the 380 token type, the act of performing a token exchange has no impact on 381 the validity of the subject token or actor token. Furthermore, the 382 exchange is a one-time event and does not create a tight linkage 383 between the input and output tokens, so that (for example) while the 384 expiration time of the output token may be influenced by that of the 385 input token, renewal or extension of the input token is not expected 386 to be reflected in the output token's properties. It may still be 387 appropriate or desirable to propagate token revocation events, 388 however, doing so is not a general property of the STS protocol a 389 would be specific to a particular token type or deployment/ 390 implementation. 392 2.1.1. Relationship Between Resource, Audience and Scope 394 When requesting a token, the client can indicate the desired target 395 service(s) where it intends to use that token by way of the 396 "audience" and "resource" parameters, as well as indicating the 397 desired scope of the requested token using the "scope" parameter. 398 The semantics of such a request are that the client is asking for a 399 token with the requested scope that is usable at all the requested 400 target services. Effectively, the requested access rights of the 401 token are the cartesian product of all the scopes at all the target 402 services. 404 An authorization server may be unwilling or unable to fulfill any 405 token request but the likelihood of an unfulfillable request is 406 significantly higher when very broad access rights are being 407 solicited. As such, in the absence of specific knowledge about the 408 relationship of systems in a deployment, clients should exercise 409 discretion in the breadth of the access requested, particularly the 410 number of target services. An authorization server can use the 411 "invalid_target" error code, defined in Section 2.2.2, to inform a 412 client that it requested access to too many target services 413 simultaneously. 415 2.2. Response 417 The authorization server responds to a token exchange request with a 418 normal OAuth 2.0 response from the token endpoint, as specified in 419 Section 5 of [RFC6749]. Additional details and explanation are 420 provided in the following subsections. 422 2.2.1. Successful Response 424 If the request is valid and meets all policy and other criteria of 425 the authorization server, a successful token response is constructed 426 by adding the following parameters to the entity-body of the HTTP 427 response using the "application/json" media type, as specified by 428 [RFC8259], and an HTTP 200 status code. The parameters are 429 serialized into a JavaScript Object Notation (JSON) structure by 430 adding each parameter at the top level. Parameter names and string 431 values are included as JSON strings. Numerical values are included 432 as JSON numbers. The order of parameters does not matter and can 433 vary. 435 access_token 436 REQUIRED. The security token issued by the authorization server 437 in response to the token exchange request. The "access_token" 438 parameter from Section 5.1 of [RFC6749] is used here to carry the 439 requested token, which allows this token exchange protocol to use 440 the existing OAuth 2.0 request and response constructs defined for 441 the token endpoint. The identifier "access_token" is used for 442 historical reasons and the issued token need not be an OAuth 443 access token. 445 issued_token_type 446 REQUIRED. An identifier, as described in Section 3, for the 447 representation of the issued security token. 449 token_type 450 REQUIRED. A case-insensitive value specifying the method of using 451 the access token issued, as specified in Section 7.1 of [RFC6749]. 452 It provides the client with information about how to utilize the 453 access token to access protected resources. For example, a value 454 of "Bearer", as specified in [RFC6750], indicates that the issued 455 security token is a bearer token and the client can simply present 456 it as is without any additional proof of eligibility beyond the 457 contents of the token itself. Note that the meaning of this 458 parameter is different from the meaning of the "issued_token_type" 459 parameter, which declares the representation of the issued 460 security token; the term "token type" is more typically used with 461 the aforementioned meaning as the structural or syntactical 462 representation of the security token, as it is in all 463 "*_token_type" parameters in this specification. If the issued 464 token is not an access token or usable as an access token, then 465 the "token_type" value "N_A" is used to indicate that an OAuth 2.0 466 "token_type" identifier is not applicable in that context. 468 expires_in 469 RECOMMENDED. The validity lifetime, in seconds, of the token 470 issued by the authorization server. Oftentimes the client will 471 not have the inclination or capability to inspect the content of 472 the token and this parameter provides a consistent and token-type- 473 agnostic indication of how long the token can be expected to be 474 valid. For example, the value 1800 denotes that the token will 475 expire in thirty minutes from the time the response was generated. 477 scope 478 OPTIONAL, if the scope of the issued security token is identical 479 to the scope requested by the client; otherwise, REQUIRED. 481 refresh_token 482 OPTIONAL. A refresh token will typically not be issued when the 483 exchange is of one temporary credential (the subject_token) for a 484 different temporary credential (the issued token) for use in some 485 other context. A refresh token can be issued in cases where the 486 client of the token exchange needs the ability to access a 487 resource even when the original credential is no longer valid 488 (e.g., user-not-present or offline scenarios where there is no 489 longer any user entertaining an active session with the client). 490 Profiles or deployments of this specification should clearly 491 document the conditions under which a client should expect a 492 refresh token in response to "urn:ietf:params:oauth:grant- 493 type:token-exchange" grant type requests. 495 2.2.2. Error Response 497 If the request itself is not valid or if either the "subject_token" 498 or "actor_token" are invalid for any reason, or are unacceptable 499 based on policy, the authorization server MUST construct an error 500 response, as specified in Section 5.2 of [RFC6749]. The value of the 501 "error" parameter MUST be the "invalid_request" error code. 503 If the authorization server is unwilling or unable to issue a token 504 for all the target services indicated by the "resource" or "audience" 505 parameters, the "invalid_target" error code SHOULD be used in the 506 error response. 508 The authorization server MAY include additional information regarding 509 the reasons for the error using the "error_description" as discussed 510 in Section 5.2 of [RFC6749]. 512 Other error codes may also be used, as appropriate. 514 2.3. Example Token Exchange 516 The following example demonstrates a hypothetical token exchange in 517 which an OAuth resource server assumes the role of the client during 518 the exchange. It trades an access token, which it received in a 519 protected resource request, for a new token that it will use to call 520 to a backend service (extra line breaks and indentation in the 521 examples are for display purposes only). 523 The resource server receives the following request containing an 524 OAuth access token in the Authorization request header, as specified 525 in Section 2.1 of [RFC6750]. 527 GET /resource HTTP/1.1 528 Host: frontend.example.com 529 Authorization: Bearer accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC 531 Figure 1: Protected Resource Request 533 The resource server assumes the role of the client for the token 534 exchange and the access token from the request above is sent to the 535 authorization server using a request as specified in Section 2.1. 536 The value of the "subject_token" parameter carries the access token 537 and the value of the "subject_token_type" parameter indicates that it 538 is an OAuth 2.0 access token. The resource server, acting in the 539 role of the client, uses its identifier and secret to authenticate to 540 the authorization server using the HTTP Basic authentication scheme. 541 The "resource" parameter indicates the location of the backend 542 service, https://backend.example.com/api, where the issued token will 543 be used. 545 POST /as/token.oauth2 HTTP/1.1 546 Host: as.example.com 547 Authorization: Basic cnMwODpsb25nLXNlY3VyZS1yYW5kb20tc2VjcmV0 548 Content-Type: application/x-www-form-urlencoded 550 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 551 &resource=https%3A%2F%2Fbackend.example.com%2Fapi 552 &subject_token=accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC 553 &subject_token_type= 554 urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token 556 Figure 2: Token Exchange Request 558 The authorization server validates the client credentials and the 559 "subject_token" presented in the token exchange request. From the 560 "resource" parameter, the authorization server is able to determine 561 the appropriate policy to apply to the request and issues a token 562 suitable for use at https://backend.example.com. The "access_token" 563 parameter of the response contains the new token, which is itself a 564 bearer OAuth access token that is valid for one minute. The token 565 happens to be a JWT; however, its structure and format are opaque to 566 the client so the "issued_token_type" indicates only that it is an 567 access token. 569 HTTP/1.1 200 OK 570 Content-Type: application/json 571 Cache-Control: no-cache, no-store 573 { 574 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQiOiJo 575 dHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2FzLmV 576 4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1MzMsIn 577 N1YiI6ImJkY0BleGFtcGxlLmNvbSIsInNjb3BlIjoiYXBpIn0.40y3ZgQedw6rx 578 f59WlwHDD9jryFOr0_Wh3CGozQBihNBhnXEQgU85AI9x3KmsPottVMLPIWvmDCM 579 y5-kdXjwhw", 580 "issued_token_type": 581 "urn:ietf:params:oauth:token-type:access_token", 582 "token_type":"Bearer", 583 "expires_in":60 584 } 586 Figure 3: Token Exchange Response 588 The resource server can then use the newly acquired access token in 589 making a request to the backend server. 591 GET /api HTTP/1.1 592 Host: backend.example.com 593 Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQ 594 iOiJodHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2 595 FzLmV4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1M 596 zMsInN1YiI6ImJkY0BleGFtcGxlLmNvbSIsInNjb3BlIjoiYXBpIn0.40y3ZgQe 597 dw6rxf59WlwHDD9jryFOr0_Wh3CGozQBihNBhnXEQgU85AI9x3KmsPottVMLPIW 598 vmDCMy5-kdXjwhw 600 Figure 4: Backend Protected Resource Request 602 Additional examples can be found in Appendix A. 604 3. Token Type Identifiers 606 Several parameters in this specification utilize an identifier as the 607 value to describe the token in question. Specifically, they are the 608 "requested_token_type", "subject_token_type", "actor_token_type" 609 parameters of the request and the "issued_token_type" member of the 610 response. Token type identifiers are URIs. Token Exchange can work 611 with both tokens issued by other parties and tokens from the given 612 authorization server. For the former the token type identifier 613 indicates the syntax (e.g., JWT or SAML 2.0) so the authorization 614 server can parse it; for the latter it indicates what the given 615 authorization server issued it for (e.g., access_token or 616 refresh_token). 618 The following token type identifiers are defined by this 619 specification. Other URIs MAY be used to indicate other token types. 621 urn:ietf:params:oauth:token-type:access_token 622 Indicates that the token is an OAuth 2.0 access token issued by 623 the given authorization server. 625 urn:ietf:params:oauth:token-type:refresh_token 626 Indicates that the token is an OAuth 2.0 refresh token issued by 627 the given authorization server. 629 urn:ietf:params:oauth:token-type:id_token 630 Indicates that the token is an ID Token, as defined in Section 2 631 of [OpenID.Core]. 633 urn:ietf:params:oauth:token-type:saml1 634 Indicates that the token is a base64url-encoded SAML 1.1 635 [OASIS.saml-core-1.1] assertion. 637 urn:ietf:params:oauth:token-type:saml2 638 Indicates that the token is a base64url-encoded SAML 2.0 639 [OASIS.saml-core-2.0-os] assertion. 641 The value "urn:ietf:params:oauth:token-type:jwt", which is defined in 642 Section 9 of [JWT], indicates that the token is a JWT. 644 The distinction between an access token and a JWT is subtle. An 645 access token represents a delegated authorization decision, whereas 646 JWT is a token format. An access token can be formatted as a JWT but 647 doesn't necessarily have to be. And a JWT might well be an access 648 token but not all JWTs are access tokens. The intent of this 649 specification is that "urn:ietf:params:oauth:token-type:access_token" 650 be an indicator that the token is a typical OAuth access token issued 651 by the authorization server in question, opaque to the client, and 652 usable the same manner as any other access token obtained from that 653 authorization server. (It could well be a JWT, but the client isn't 654 and needn't be aware of that fact.) Whereas, 655 "urn:ietf:params:oauth:token-type:jwt" is to indicate specifically 656 that a JWT is being requested or sent (perhaps in a cross-domain use- 657 case where the JWT is used as an authorization grant to obtain an 658 access token from a different authorization server as is facilitated 659 by [RFC7523]). 661 Note that for tokens which are binary in nature, the URI used for 662 conveying them needs to be associated with the semantics of a base64 663 or other encoding suitable for usage with HTTP and OAuth. 665 4. JSON Web Token Claims and Introspection Response Parameters 667 It is useful to have defined mechanisms to express delegation within 668 a token as well as to express authorization to delegate or 669 impersonate. Although the token exchange protocol described herein 670 can be used with any type of token, this section defines claims to 671 express such semantics specifically for JWTs and in an OAuth 2.0 672 Token Introspection [RFC7662] response. Similar definitions for 673 other types of tokens are possible but beyond the scope of this 674 specification. 676 Note that the claims not established herein but used in examples and 677 descriptions, such as "iss", "sub", "exp", etc., are defined by 678 [JWT]. 680 4.1. "act" (Actor) Claim 682 The "act" (actor) claim provides a means within a JWT to express that 683 delegation has occurred and identify the acting party to whom 684 authority has been delegated. The "act" claim value is a JSON object 685 and members in the JSON object are claims that identify the actor. 686 The claims that make up the "act" claim identify and possibly provide 687 additional information about the actor. For example, the combination 688 of the two claims "iss" and "sub" might be necessary to uniquely 689 identify an actor. 691 However, claims within the "act" claim pertain only to the identity 692 of the actor and are not relevant to the validity of the containing 693 JWT in the same manner as the top-level claims. Consequently, non- 694 identity claims (e.g., "exp", "nbf", and "aud") are not meaningful 695 when used within an "act" claim, and therefore must not be used. 697 The following example illustrates the "act" (actor) claim within a 698 JWT Claims Set. The claims of the token itself are about 699 user@example.com while the "act" claim indicates that 700 admin@example.com is the current actor. 702 { 703 "aud":"https://consumer.example.com", 704 "iss":"https://issuer.example.com", 705 "exp":1443904177, 706 "nbf":1443904077, 707 "sub":"user@example.com", 708 "act": 709 { 710 "sub":"admin@example.com" 711 } 712 } 714 Figure 5: Actor Claim 716 A chain of delegation can be expressed by nesting one "act" claim 717 within another. The outermost "act" claim represents the current 718 actor while nested "act" claims represent prior actors. The least 719 recent actor is the most deeply nested. The nested "act" claims 720 serve as a history trail that connects the initial request and 721 subject through the various delegation steps undertaken before 722 reaching the current actor. In this sense, the current actor is 723 considered to include the entire authorization/delegation history, 724 leading naturally to the nested structure described here. 726 For the purpose of applying access control policy, the consumer of a 727 token MUST only consider the token's top-level claims and the party 728 identified as the current actor by the "act" claim. Prior actors 729 identified by any nested "act" claims are informational only and are 730 not to be considered in access control decisions. 732 The following example illustrates nested "act" (actor) claims within 733 a JWT Claims Set. The claims of the token itself are about 734 user@example.com while the "act" claim indicates that the system 735 https://service16.example.com is the current actor and 736 https://service77.example.com was a prior actor. Such a token might 737 come about as the result of service16 receiving a token in a call 738 from service77 and exchanging it for a token suitable to call 739 service26 while the authorization server notes the situation in the 740 newly issued token. 742 { 743 "aud":"https://service26.example.com", 744 "iss":"https://issuer.example.com", 745 "exp":1443904100, 746 "nbf":1443904000, 747 "sub":"user@example.com", 748 "act": 749 { 750 "sub":"https://service16.example.com", 751 "act": 752 { 753 "sub":"https://service77.example.com", 754 } 755 } 756 } 758 Figure 6: Nested Actor Claim 760 When included as a top-level member of an OAuth token introspection 761 response, "act" has the same semantics and format as the claim of the 762 same name. 764 4.2. "scope" (Scopes) Claim 766 The value of the "scope" claim is a JSON string containing a space- 767 separated list of scopes associated with the token, in the format 768 described in Section 3.3 of [RFC6749]. 770 The following example illustrates the "scope" claim within a JWT 771 Claims Set. 773 { 774 "aud":"https://consumer.example.com", 775 "iss":"https://issuer.example.com", 776 "exp":1443904177, 777 "nbf":1443904077, 778 "sub":"dgaf4mvfs75Fci_FL3heQA", 779 "scope":"email profile phone address" 780 } 782 Figure 7: Scopes Claim 784 OAuth 2.0 Token Introspection [RFC7662] already defines the "scope" 785 parameter to convey the scopes associated with the token. 787 4.3. "client_id" (Client Identifier) Claim 789 The "client_id" claim carries the client identifier of the OAuth 2.0 790 [RFC6749] client that requested the token. 792 The following example illustrates the "client_id" claim within a JWT 793 Claims Set indicating an OAuth 2.0 client with "s6BhdRkqt3" as its 794 identifier. 796 { 797 "aud":"https://consumer.example.com", 798 "iss":"https://issuer.example.com", 799 "exp":1443904177, 800 "sub":"user@example.com", 801 "client_id":"s6BhdRkqt3" 802 } 804 Figure 8: Client Identifier Claim 806 OAuth 2.0 Token Introspection [RFC7662] already defines the 807 "client_id" parameter as the client identifier for the OAuth 2.0 808 client that requested the token. 810 4.4. "may_act" (Authorized Actor) Claim 812 The "may_act" claim makes a statement that one party is authorized to 813 become the actor and act on behalf of another party. The claim might 814 be used, for example, when a "subject_token" is presented to the 815 token endpoint in a token exchange request and "may_act" claim in the 816 subject token can be used by the authorization server to determine 817 whether the client (or party identified in the "actor_token") is 818 authorized to engage in the requested delegation or impersonation. 819 The claim value is a JSON object and members in the JSON object are 820 claims that identify the party that is asserted as being eligible to 821 act for the party identified by the JWT containing the claim. The 822 claims that make up the "may_act" claim identify and possibly provide 823 additional information about the authorized actor. For example, the 824 combination of the two claims "iss" and "sub" are sometimes necessary 825 to uniquely identify an authorized actor, while the "email" claim 826 might be used to provide additional useful information about that 827 party. 829 However, claims within the "may_act" claim pertain only to the 830 identity of that party and are not relevant to the validity of the 831 containing JWT in the same manner as top-level claims. Consequently, 832 claims such as "exp", "nbf", and "aud" are not meaningful when used 833 within a "may_act" claim, and therefore should not be used. 835 The following example illustrates the "may_act" claim within a JWT 836 Claims Set. The claims of the token itself are about 837 user@example.com while the "may_act" claim indicates that 838 admin@example.com is authorized to act on behalf of user@example.com. 840 { 841 "aud":"https://consumer.example.com", 842 "iss":"https://issuer.example.com", 843 "exp":1443904177, 844 "nbf":1443904077, 845 "sub":"user@example.com", 846 "may_act": 847 { 848 "sub":"admin@example.com" 849 } 850 } 852 Figure 9: Authorized Actor Claim 854 When included as a top-level member of an OAuth token introspection 855 response, "may_act" has the same semantics and format as the claim of 856 the same name. 858 5. Security Considerations 860 Much of the guidance from Section 10 of [RFC6749], the Security 861 Considerations in The OAuth 2.0 Authorization Framework, is also 862 applicable here. Furthermore, [RFC6819] provides additional security 863 considerations for OAuth and [I-D.ietf-oauth-security-topics] has 864 updated security guidance based on deployment experience and new 865 threats that have emerged since OAuth 2.0 was originally published. 867 All of the normal security issues that are discussed in [JWT], 868 especially in relationship to comparing URIs and dealing with 869 unrecognized values, also apply here. 871 In addition, both delegation and impersonation introduce unique 872 security issues. Any time one principal is delegated the rights of 873 another principal, the potential for abuse is a concern. The use of 874 the "scope" claim is suggested to mitigate potential for such abuse, 875 as it restricts the contexts in which the delegated rights can be 876 exercised. 878 6. Privacy Considerations 880 Tokens employed in the context of the functionality described herein 881 may contain privacy-sensitive information and, to prevent disclosure 882 of such information to unintended parties, MUST only be transmitted 883 over encrypted channels, such as Transport Layer Security (TLS). In 884 cases where it is desirable to prevent disclosure of certain 885 information to the client, the token MUST be encrypted to its 886 intended recipient. Deployments SHOULD determine the minimally 887 necessary amount of data and only include such information in issued 888 tokens. In some cases, data minimization may include representing 889 only an anonymous or pseudonymous user. 891 7. IANA Considerations 893 7.1. OAuth URI Registration 895 This specification registers the following values in the IANA "OAuth 896 URI" registry [IANA.OAuth.Parameters] established by [RFC6755]. 898 7.1.1. Registry Contents 900 o URN: urn:ietf:params:oauth:grant-type:token-exchange 901 o Common Name: Token exchange grant type for OAuth 2.0 902 o Change controller: IESG 903 o Specification Document: Section 2.1 of [[ this specification ]] 905 o URN: urn:ietf:params:oauth:token-type:access_token 906 o Common Name: Token type URI for an OAuth 2.0 access token 907 o Change controller: IESG 908 o Specification Document: Section 3 of [[this specification]] 910 o URN: urn:ietf:params:oauth:token-type:refresh_token 911 o Common Name: Token type URI for an OAuth 2.0 refresh token 912 o Change controller: IESG 913 o Specification Document: Section 3 of [[this specification]] 914 o URN: urn:ietf:params:oauth:token-type:id_token 915 o Common Name: Token type URI for an ID Token 916 o Change controller: IESG 917 o Specification Document: Section 3 of [[this specification]] 919 o URN: urn:ietf:params:oauth:token-type:saml1 920 o Common Name: Token type URI for a base64url-encoded SAML 1.1 921 assertion 922 o Change Controller: IESG 923 o Specification Document: Section 3 of [[this specification]] 925 o URN: urn:ietf:params:oauth:token-type:saml2 926 o Common Name: Token type URI for a base64url-encoded SAML 2.0 927 assertion 928 o Change Controller: IESG 929 o Specification Document: Section 3 of [[this specification]] 931 7.2. OAuth Parameters Registration 933 This specification registers the following values in the IANA "OAuth 934 Parameters" registry [IANA.OAuth.Parameters] established by 935 [RFC6749]. 937 7.2.1. Registry Contents 939 o Parameter name: resource 940 o Parameter usage location: token request 941 o Change controller: IESG 942 o Specification document(s): Section 2.1 of [[ this specification ]] 944 o Parameter name: audience 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: requested_token_type 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: subject_token 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_type 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: actor_token 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_type 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: issued_token_type 975 o Parameter usage location: token response 976 o Change controller: IESG 977 o Specification document(s): Section 2.2.1 of [[ this specification 978 ]] 980 7.3. OAuth Access Token Type Registration 982 This specification registers the following access token type in the 983 IANA "OAuth Access Token Types" registry [IANA.OAuth.Parameters] 984 established by [RFC6749]. 986 7.3.1. Registry Contents 988 o Type name: N_A 989 o Additional Token Endpoint Response Parameters: (none) 990 o HTTP Authentication Scheme(s): (none) 991 o Change controller: IESG 992 o Specification document(s): Section 2.2.1 of [[ this specification 993 ]] 995 7.4. JSON Web Token Claims Registration 997 This specification registers the following Claims in the IANA "JSON 998 Web Token Claims" registry [IANA.JWT.Claims] established by [JWT]. 1000 7.4.1. Registry Contents 1002 o Claim Name: "act" 1003 o Claim Description: Actor 1004 o Change Controller: IESG 1005 o Specification Document(s): Section 4.1 of [[ this specification ]] 1007 o Claim Name: "scope" 1008 o Claim Description: Scope Values 1009 o Change Controller: IESG 1010 o Specification Document(s): Section 4.2 of [[ this specification ]] 1012 o Claim Name: "client_id" 1013 o Claim Description: Client Identifier 1014 o Change Controller: IESG 1015 o Specification Document(s): Section 4.3 of [[ this specification ]] 1017 o Claim Name: "may_act" 1018 o Claim Description: Authorized Actor - the party that is authorized 1019 to become the actor 1020 o Change Controller: IESG 1021 o Specification Document(s): Section 4.4 of [[ this specification ]] 1023 7.5. OAuth Token Introspection Response Registration 1025 This specification registers the following values in the IANA "OAuth 1026 Token Introspection Response" registry [IANA.OAuth.Parameters] 1027 established by [RFC7662]. 1029 7.5.1. Registry Contents 1031 o Claim Name: "act" 1032 o Claim Description: Actor 1033 o Change Controller: IESG 1034 o Specification Document(s): Section 4.1 of [[ this specification ]] 1036 o Claim Name: "may_act" 1037 o Claim Description: Authorized Actor - the party that is authorized 1038 to become the actor 1039 o Change Controller: IESG 1040 o Specification Document(s): Section 4.4 of [[ this specification ]] 1042 7.6. OAuth Extensions Error Registration 1044 This specification registers the following values in the IANA "OAuth 1045 Extensions Error" registry [IANA.OAuth.Parameters] established by 1046 [RFC6749]. 1048 7.6.1. Registry Contents 1050 o Error Name: "invalid_target" 1051 o Error Usage Location: token error response 1052 o Related Protocol Extension: OAuth 2.0 Token Exchange 1053 o Change Controller: IETF 1054 o Specification Document(s): Section 2.2.2 of [[ this specification 1055 ]] 1057 8. References 1059 8.1. Normative References 1061 [IANA.JWT.Claims] 1062 IANA, "JSON Web Token Claims", 1063 . 1065 [IANA.OAuth.Parameters] 1066 IANA, "OAuth Parameters", 1067 . 1069 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1070 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1071 . 1073 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1074 Requirement Levels", BCP 14, RFC 2119, 1075 DOI 10.17487/RFC2119, March 1997, 1076 . 1078 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1079 Resource Identifier (URI): Generic Syntax", STD 66, 1080 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1081 . 1083 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1084 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1085 . 1087 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 1088 RFC 7662, DOI 10.17487/RFC7662, October 2015, 1089 . 1091 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1092 Interchange Format", STD 90, RFC 8259, 1093 DOI 10.17487/RFC8259, December 2017, 1094 . 1096 8.2. Informative References 1098 [I-D.ietf-oauth-security-topics] 1099 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 1100 "OAuth 2.0 Security Best Current Practice", draft-ietf- 1101 oauth-security-topics-12 (work in progress), March 2019. 1103 [OASIS.saml-core-1.1] 1104 Maler, E., Mishra, P., and R. Philpott, "Assertions and 1105 Protocol for the OASIS Security Assertion Markup Language 1106 (SAML) V1.1", OASIS Standard oasis-sstc-saml-core-1.1, 1107 September 2003. 1109 [OASIS.saml-core-2.0-os] 1110 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 1111 "Assertions and Protocol for the OASIS Security Assertion 1112 Markup Language (SAML) V2.0", OASIS Standard saml-core- 1113 2.0-os, March 2005. 1115 [OpenID.Core] 1116 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 1117 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 1118 . 1120 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1121 Framework: Bearer Token Usage", RFC 6750, 1122 DOI 10.17487/RFC6750, October 2012, 1123 . 1125 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 1126 for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, 1127 . 1129 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 1130 Threat Model and Security Considerations", RFC 6819, 1131 DOI 10.17487/RFC6819, January 2013, 1132 . 1134 [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 1135 "Assertion Framework for OAuth 2.0 Client Authentication 1136 and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, 1137 May 2015, . 1139 [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 1140 (JWT) Profile for OAuth 2.0 Client Authentication and 1141 Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 1142 2015, . 1144 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1145 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1146 May 2017, . 1148 [WS-Trust] 1149 Nadalin, A., Goodner, M., Gudgin, M., Barbir, A., and H. 1150 Granqvist, "WS-Trust 1.4", February 2012, 1151 . 1154 Appendix A. Additional Token Exchange Examples 1156 Two example token exchanges are provided in the following sections 1157 illustrating impersonation and delegation, respectively (with extra 1158 line breaks and indentation for display purposes only). 1160 A.1. Impersonation Token Exchange Example 1162 A.1.1. Token Exchange Request 1164 In the following token exchange request, a client is requesting a 1165 token with impersonation semantics (with only a "subject_token" and 1166 no "actor_token", delegation is impossible). The client tells the 1167 authorization server that it needs a token for use at the target 1168 service with the logical name "urn:example:cooperation-context". 1170 POST /as/token.oauth2 HTTP/1.1 1171 Host: as.example.com 1172 Content-Type: application/x-www-form-urlencoded 1174 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 1175 &audience=urn%3Aexample%3Acooperation-context 1176 &subject_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwc 1177 zovL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXI 1178 uZXhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTA2MDAsIm5iZiI6MTQ0MTkwOTAwMCwic 1179 3ViIjoiYmRjQGV4YW1wbGUubmV0Iiwic2NvcGUiOiJvcmRlcnMgcHJvZmlsZSBoaXN 1180 0b3J5In0.PRBg-jXn4cJuj1gmYXFiGkZzRuzbXZ_sDxdE98ddW44ufsbWLKd3JJ1VZ 1181 hF64pbTtfjy4VXFVBDaQpKjn5JzAw 1182 &subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1184 Figure 10: Token Exchange Request 1186 A.1.2. Subject Token Claims 1188 The "subject_token" in the prior request is a JWT and the decoded JWT 1189 Claims Set is shown here. The JWT is intended for consumption by the 1190 authorization server within a specific time window. The subject of 1191 the JWT ("bdc@example.net") is the party on behalf of whom the new 1192 token is being requested. 1194 { 1195 "aud":"https://as.example.com", 1196 "iss":"https://original-issuer.example.net", 1197 "exp":1441910600, 1198 "nbf":1441909000, 1199 "sub":"bdc@example.net", 1200 "scope":"orders profile history" 1201 } 1203 Figure 11: Subject Token Claims 1205 A.1.3. Token Exchange Response 1207 The "access_token" parameter of the token exchange response shown 1208 below contains the new token that the client requested. The other 1209 parameters of the response indicate that the token is a bearer access 1210 token that expires in an hour. 1212 HTTP/1.1 200 OK 1213 Content-Type: application/json 1214 Cache-Control: no-cache, no-store 1216 { 1217 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm4 1218 6ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5l 1219 eGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic3ViIjoiYmRjQGV4YW1wbGUub 1220 mV0Iiwic2NvcGUiOiJvcmRlcnMgcHJvZmlsZSBoaXN0b3J5In0.rMdWpSGNACTvnF 1221 uOL74sYZ6MVuld2Z2WkGLmQeR9ztj6w2OXraQlkJmGjyiCq24kcB7AI2VqVxl3wSW 1222 nVKh85A", 1223 "issued_token_type": 1224 "urn:ietf:params:oauth:token-type:access_token", 1225 "token_type":"Bearer", 1226 "expires_in":3600 1227 } 1229 Figure 12: Token Exchange Response 1231 A.1.4. Issued Token Claims 1233 The decoded JWT Claims Set of the issued token is shown below. The 1234 new JWT is issued by the authorization server and intended for 1235 consumption by a system entity known by the logical name 1236 "urn:example:cooperation-context" any time before its expiration. 1237 The subject ("sub") of the JWT is the same as the subject the token 1238 used to make the request, which effectively enables the client to 1239 impersonate that subject at the system entity known by the logical 1240 name of "urn:example:cooperation-context" by using the token. 1242 { 1243 "aud":"urn:example:cooperation-context", 1244 "iss":"https://as.example.com", 1245 "exp":1441913610, 1246 "sub":"bdc@example.net", 1247 "scope":"orders profile history" 1248 } 1250 Figure 13: Issued Token Claims 1252 A.2. Delegation Token Exchange Example 1254 A.2.1. Token Exchange Request 1256 In the following token exchange request, a client is requesting a 1257 token and providing both a "subject_token" and an "actor_token". The 1258 client tells the authorization server that it needs a token for use 1259 at the target service with the logical name "urn:example:cooperation- 1260 context". Policy at the authorization server dictates that the 1261 issued token be a composite. 1263 POST /as/token.oauth2 HTTP/1.1 1264 Host: as.example.com 1265 Content-Type: application/x-www-form-urlencoded 1267 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 1268 &audience=urn%3Aexample%3Acooperation-context 1269 &subject_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwc 1270 zovL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXI 1271 uZXhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTAwNjAsInNjb3BlIjoic3RhdHVzIGZlZ 1272 WQiLCJzdWIiOiJ1c2VyQGV4YW1wbGUubmV0IiwibWF5X2FjdCI6eyJzdWIiOiJhZG1 1273 pbkBleGFtcGxlLm5ldCJ9fQ.4rPRSWihQbpMIgAmAoqaJojAxj-p2X8_fAtAGTXrvM 1274 xU-eEZHnXqY0_AOZgLdxw5DyLzua8H_I10MCcckF-Q_g 1275 &subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1276 &actor_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwczo 1277 vL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXIuZ 1278 XhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTAwNjAsInN1YiI6ImFkbWluQGV4YW1wbGU 1279 ubmV0In0.7YQ-3zPfhUvzje5oqw8COCvN5uP6NsKik9CVV6cAOf4QKgM-tKfiOwcgZ 1280 oUuDL2tEs6tqPlcBlMjiSzEjm3yBg 1281 &actor_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1283 Figure 14: Token Exchange Request 1285 A.2.2. Subject Token Claims 1287 The "subject_token" in the prior request is a JWT and the decoded JWT 1288 Claims Set is shown here. The JWT is intended for consumption by the 1289 authorization server before a specific expiration time. The subject 1290 of the JWT ("user@example.net") is the party on behalf of whom the 1291 new token is being requested. 1293 { 1294 "aud":"https://as.example.com", 1295 "iss":"https://original-issuer.example.net", 1296 "exp":1441910060, 1297 "scope":"status feed", 1298 "sub":"user@example.net", 1299 "may_act": 1300 { 1301 "sub":"admin@example.net" 1302 } 1303 } 1305 Figure 15: Subject Token Claims 1307 A.2.3. Actor Token Claims 1309 The "actor_token" in the prior request is a JWT and the decoded JWT 1310 Claims Set is shown here. This JWT is also intended for consumption 1311 by the authorization server before a specific expiration time. The 1312 subject of the JWT ("admin@example.net") is the actor that will wield 1313 the security token being requested. 1315 { 1316 "aud":"https://as.example.com", 1317 "iss":"https://original-issuer.example.net", 1318 "exp":1441910060, 1319 "sub":"admin@example.net" 1320 } 1322 Figure 16: Actor Token Claims 1324 A.2.4. Token Exchange Response 1326 The "access_token" parameter of the token exchange response shown 1327 below contains the new token that the client requested. The other 1328 parameters of the response indicate that the token is a JWT that 1329 expires in an hour and that the access token type is not applicable 1330 since the issued token is not an access token. 1332 HTTP/1.1 200 OK 1333 Content-Type: application/json 1334 Cache-Control: no-cache, no-store 1336 { 1337 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm4 1338 6ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5l 1339 eGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic2NvcGUiOiJzdGF0dXMgZmVlZ 1340 CIsInN1YiI6InVzZXJAZXhhbXBsZS5uZXQiLCJhY3QiOnsic3ViIjoiYWRtaW5AZX 1341 hhbXBsZS5uZXQifX0.3paKl9UySKYB5ng6_cUtQ2qlO8Rc_y7Mea7IwEXTcYbNdwG 1342 9-G1EKCFe5fW3H0hwX-MSZ49Wpcb1SiAZaOQBtw", 1343 "issued_token_type":"urn:ietf:params:oauth:token-type:jwt", 1344 "token_type":"N_A", 1345 "expires_in":3600 1346 } 1348 Figure 17: Token Exchange Response 1350 A.2.5. Issued Token Claims 1352 The decoded JWT Claims Set of the issued token is shown below. The 1353 new JWT is issued by the authorization server and intended for 1354 consumption by a system entity known by the logical name 1355 "urn:example:cooperation-context" any time before its expiration. 1356 The subject ("sub") of the JWT is the same as the subject of the 1357 "subject_token" used to make the request. The actor ("act") of the 1358 JWT is the same as the subject of the "actor_token" used to make the 1359 request. This indicates delegation and identifies 1360 "admin@example.net" as the current actor to whom authority has been 1361 delegated to act on behalf of "user@example.net". 1363 { 1364 "aud":"urn:example:cooperation-context", 1365 "iss":"https://as.example.com", 1366 "exp":1441913610, 1367 "scope":"status feed", 1368 "sub":"user@example.net", 1369 "act": 1370 { 1371 "sub":"admin@example.net" 1372 } 1373 } 1375 Figure 18: Issued Token Claims 1377 Appendix B. Acknowledgements 1379 This specification was developed within the OAuth Working Group, 1380 which includes dozens of active and dedicated participants. It was 1381 produced under the chairmanship of Hannes Tschofenig, Derek Atkins, 1382 and Rifaat Shekh-Yusef with Kathleen Moriarty, Stephen Farrell, Eric 1383 Rescorla, Roman Danyliw, and Benjamin Kaduk serving as Security Area 1384 Directors. The following individuals contributed ideas, feedback, 1385 and wording to this specification: 1387 Caleb Baker, Vittorio Bertocci, Mike Brown, Thomas Broyer, William 1388 Denniss, Vladimir Dzhuvinov, Phil Hunt, Benjamin Kaduk, Jason 1389 Keglovitz, Torsten Lodderstedt, Adam Lewis, James Manger, Nov Matake, 1390 Matt Miller, Hilarie Orman, Matthew Perry, Eric Rescorla, Justin 1391 Richer, Adam Roach, Rifaat Shekh-Yusef, Scott Tomilson, and Hannes 1392 Tschofenig. 1394 Appendix C. Document History 1396 [[ to be removed by the RFC Editor before publication as an RFC ]] 1398 -18 1400 o 1402 -17 1404 o Editorial improvements and example fixes resulting from IESG 1405 evaluation comments. 1406 o Added a pointer to RFC6749's Appendix B. on the "Use of 1407 application/x-www-form-urlencoded Media Type" as a way of 1408 providing a normative citation (by reference) for the media type. 1409 o Strengthened some of the wording in the privacy considerations to 1410 bring it inline with RFC 7519 Sec. 12 and RFC 6749 Sec. 10.8. 1412 -16 1414 o Fixed typo and added an AD to Acknowledgements. 1416 -15 1418 o Updated the nested actor claim example to (hopefully) be more 1419 straightforward. 1420 o Reworked Privacy Considerations to say to use TLS in transit, 1421 minimize the amount of information in the token, and encrypt the 1422 token if disclosure of its information to the client is a concern 1423 per https://mailarchive.ietf.org/arch/msg/secdir/ 1424 KJhx4aq_U5uk3k6zpYP-CEHbpVM 1426 o Moved the Security and Privacy Considerations sections to before 1427 the IANA Considerations. 1429 -14 1431 o Added text in Section 4.1 about the "act" claim stating that only 1432 the top-level claims and the current actor are to be considered in 1433 applying access control decisions. 1435 -13 1437 o Updated the claim name and value syntax for scope to be consistent 1438 with the treatment of scope in RFC 7662 OAuth 2.0 Token 1439 Introspection. 1440 o Updated the client identifier claim name to be consistent with the 1441 treatment of client id in RFC 7662 OAuth 2.0 Token Introspection. 1443 -12 1445 o Updated to use the boilerplate from RFC 8174. 1447 -11 1449 o Added new WG chair and AD to the Acknowledgements. 1450 o Applied clarifications suggested during AD review by EKR. 1452 -10 1454 o Defined token type URIs for base64url-encoded SAML 1.1 and SAML 1455 2.0 assertions. 1456 o Applied editorial fixes. 1458 -09 1460 o Changed "security tokens obtained could be used in a number of 1461 contexts" to "security tokens obtained may be used in a number of 1462 contexts" per a WGLC suggestion. 1463 o Clarified that the validity of the subject or actor token have no 1464 impact on the validity of the issued token after the exchange has 1465 occurred per a WGLC comment. 1466 o Changed use of invalid_target error code to a SHOULD per a WGLC 1467 comment. 1468 o Clarified text about non-identity claims within the "act" claim 1469 being meaningless per a WGLC comment. 1470 o Added brief Privacy Considerations section per WGLC comments. 1472 -08 1473 o Use the bibxml reference for OpenID.Core rather than defining it 1474 inline. 1475 o Added editor role for Campbell. 1476 o Minor clarification of the text for actor_token. 1478 -07 1480 o Fixed typo (desecration -> discretion). 1481 o Added an explanation of the relationship between scope, audience 1482 and resource in the request and added an "invalid_target" error 1483 code enabling the AS to tell the client that the requested 1484 audiences/resources were too broad. 1486 -06 1488 o Drop "An STS for the REST of Us" from the title. 1489 o Drop "heavyweight" and "lightweight" from the abstract and 1490 introduction. 1491 o Clarifications on the language around xxxxxx_token_type. 1492 o Remove the want_composite parameter. 1493 o Add a short mention of proof-of-possession style tokens to the 1494 introduction and remove the respective open issue. 1496 -05 1498 o Defined the JWT claim "cid" to express the OAuth 2.0 client 1499 identifier of the client that requested the token. 1500 o Defined and requested registration for "act" and "may_act" as 1501 Token introspection response parameters (in addition to being JWT 1502 claims). 1503 o Loosen up the language about refresh_token in the response to 1504 OPTIONAL from NOT RECOMMENDED based on feedback form real world 1505 deployment experience. 1506 o Add clarifying text about the distinction between JWT and access 1507 token URIs. 1508 o Close out (remove) some of the Open Issues bullets that have been 1509 resolved. 1511 -04 1513 o Clarified that the "resource" and "audience" request parameters 1514 can be used at the same time (via http://www.ietf.org/mail- 1515 archive/web/oauth/current/msg15335.html). 1516 o Clarified subject/actor token validity after token exchange and 1517 explained a bit more about the recommendation to not issue refresh 1518 tokens (via http://www.ietf.org/mail-archive/web/oauth/current/ 1519 msg15318.html). 1521 o Updated the examples appendix to use an issuer value that doesn't 1522 imply that the client issued and signed the tokens and used 1523 "Bearer" and "urn:ietf:params:oauth:token-type:access_token" in 1524 one of the responses (via http://www.ietf.org/mail- 1525 archive/web/oauth/current/msg15335.html). 1526 o Defined and registered urn:ietf:params:oauth:token-type:id_token, 1527 since some use cases perform token exchanges for ID Tokens and no 1528 URI to indicate that a token is an ID Token had previously been 1529 defined. 1531 -03 1533 o Updated the document editors (adding Campbell, Bradley, and 1534 Mortimore). 1535 o Added to the title. 1536 o Added to the abstract and introduction. 1537 o Updated the format of the request to use application/x-www-form- 1538 urlencoded request parameters and the response to use the existing 1539 token endpoint JSON parameters defined in OAuth 2.0. 1540 o Changed the grant type identifier to urn:ietf:params:oauth:grant- 1541 type:token-exchange. 1542 o Added RFC 6755 registration requests for 1543 urn:ietf:params:oauth:token-type:refresh_token, 1544 urn:ietf:params:oauth:token-type:access_token, and 1545 urn:ietf:params:oauth:grant-type:token-exchange. 1546 o Added RFC 6749 registration requests for request/response 1547 parameters. 1548 o Removed the Implementation Considerations and the requirement to 1549 support JWTs. 1550 o Clarified many aspects of the text. 1551 o Changed "on_behalf_of" to "subject_token", 1552 "on_behalf_of_token_type" to "subject_token_type", "act_as" to 1553 "actor_token", and "act_as_token_type" to "actor_token_type". 1554 o Added an "audience" request parameter used to indicate the logical 1555 names of the target services at which the client intends to use 1556 the requested security token. 1557 o Added a "want_composite" request parameter used to indicate the 1558 desire for a composite token rather than trying to infer it from 1559 the presence/absence of token(s) in the request. 1560 o Added a "resource" request parameter used to indicate the URLs of 1561 resources at which the client intends to use the requested 1562 security token. 1563 o Specified that multiple "audience" and "resource" request 1564 parameter values may be used. 1565 o Defined the JWT claim "act" (actor) to express the current actor 1566 or delegation principal. 1567 o Defined the JWT claim "may_act" to express that one party is 1568 authorized to act on behalf of another party. 1570 o Defined the JWT claim "scp" (scopes) to express OAuth 2.0 scope- 1571 token values. 1572 o Added the "N_A" (not applicable) OAuth Access Token Type 1573 definition for use in contexts in which the token exchange syntax 1574 requires a "token_type" value, but in which the token being issued 1575 is not an access token. 1576 o Added examples. 1578 -02 1580 o Enabled use of Security Token types other than JWTs for "act_as" 1581 and "on_behalf_of" request values. 1582 o Referenced the JWT and OAuth Assertions RFCs. 1584 -01 1586 o Updated references. 1588 -00 1590 o Created initial working group draft from draft-jones-oauth-token- 1591 exchange-01. 1593 Authors' Addresses 1595 Michael B. Jones 1596 Microsoft 1598 Email: mbj@microsoft.com 1599 URI: http://self-issued.info/ 1601 Anthony Nadalin 1602 Microsoft 1604 Email: tonynad@microsoft.com 1606 Brian Campbell (editor) 1607 Ping Identity 1609 Email: brian.d.campbell@gmail.com 1611 John Bradley 1612 Yubico 1614 Email: ve7jtb@ve7jtb.com 1615 Chuck Mortimore 1616 Salesforce 1618 Email: cmortimore@salesforce.com