idnits 2.17.1 draft-ietf-oauth-token-exchange-09.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 3, 2017) is 2486 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group M. Jones 3 Internet-Draft A. Nadalin 4 Intended status: Standards Track Microsoft 5 Expires: January 4, 2018 B. Campbell, Ed. 6 J. Bradley 7 Ping Identity 8 C. Mortimore 9 Salesforce 10 July 3, 2017 12 OAuth 2.0 Token Exchange 13 draft-ietf-oauth-token-exchange-09 15 Abstract 17 This specification defines a protocol for an HTTP- and JSON- based 18 Security Token Service (STS) by defining how to request and obtain 19 security tokens from OAuth 2.0 authorization servers, including 20 security tokens employing impersonation and delegation. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on January 4, 2018. 39 Copyright Notice 41 Copyright (c) 2017 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.1. Delegation vs. Impersonation Semantics . . . . . . . . . 4 58 1.2. Requirements Notation and Conventions . . . . . . . . . . 5 59 1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 60 2. Token Exchange Request and Response . . . . . . . . . . . . . 6 61 2.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 6 62 2.1.1. Relationship Between Resource, Audience and Scope . . 8 63 2.2. Response . . . . . . . . . . . . . . . . . . . . . . . . 8 64 2.2.1. Successful Response . . . . . . . . . . . . . . . . . 8 65 2.2.2. Error Response . . . . . . . . . . . . . . . . . . . 10 66 2.3. Example Token Exchange . . . . . . . . . . . . . . . . . 10 67 3. Token Type Identifiers . . . . . . . . . . . . . . . . . . . 12 68 4. JSON Web Token Claims and Introspection Response Parameters . 13 69 4.1. "act" (Actor) Claim . . . . . . . . . . . . . . . . . . . 13 70 4.2. "scp" (Scopes) Claim . . . . . . . . . . . . . . . . . . 15 71 4.3. "cid" (Client Identifier) Claim . . . . . . . . . . . . . 16 72 4.4. "may_act" (May Act For) Claim . . . . . . . . . . . . . . 16 73 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 74 5.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 17 75 5.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 17 76 5.2. OAuth Parameters Registration . . . . . . . . . . . . . . 18 77 5.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 18 78 5.3. OAuth Access Token Type Registration . . . . . . . . . . 19 79 5.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 19 80 5.4. JSON Web Token Claims Registration . . . . . . . . . . . 19 81 5.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 19 82 5.5. OAuth Token Introspection Response Registration . . . . . 20 83 5.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 20 84 5.6. OAuth Extensions Error Registration . . . . . . . . . . . 20 85 5.6.1. Registry Contents . . . . . . . . . . . . . . . . . . 20 86 6. Security Considerations . . . . . . . . . . . . . . . . . . . 20 87 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 21 88 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 89 8.1. Normative References . . . . . . . . . . . . . . . . . . 21 90 8.2. Informative References . . . . . . . . . . . . . . . . . 22 91 Appendix A. Additional Token Exchange Examples . . . . . . . . . 22 92 A.1. Impersonation Token Exchange Example . . . . . . . . . . 23 93 A.1.1. Token Exchange Request . . . . . . . . . . . . . . . 23 94 A.1.2. Subject Token Claims . . . . . . . . . . . . . . . . 23 95 A.1.3. Token Exchange Response . . . . . . . . . . . . . . . 24 96 A.1.4. Issued Token Claims . . . . . . . . . . . . . . . . . 24 98 A.2. Delegation Token Exchange Example . . . . . . . . . . . . 25 99 A.2.1. Token Exchange Request . . . . . . . . . . . . . . . 25 100 A.2.2. Subject Token Claims . . . . . . . . . . . . . . . . 25 101 A.2.3. Actor Token Claims . . . . . . . . . . . . . . . . . 26 102 A.2.4. Token Exchange Response . . . . . . . . . . . . . . . 26 103 A.2.5. Issued Token Claims . . . . . . . . . . . . . . . . . 27 104 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 28 105 Appendix C. Document History . . . . . . . . . . . . . . . . . . 28 106 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 31 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 Assertions [OASIS.saml-core-2.0-os]. 114 Security tokens are typically signed to achieve integrity and 115 sometimes also encrypted to achieve confidentiality. Security tokens 116 are also sometimes described as Assertions, such as in [RFC7521]. 118 A Security Token Service (STS) is a service capable of validating and 119 issuing security tokens, which enables clients to obtain appropriate 120 access credentials for resources in heterogeneous environments or 121 across security domains. Web Service clients have used WS-Trust 122 [WS-Trust] as the protocol to interact with an STS for token 123 exchange. While WS-Trust uses XML and SOAP, the trend in modern Web 124 development has been towards RESTful patterns and JSON. The OAuth 125 2.0 Authorization Framework [RFC6749] and OAuth 2.0 Bearer Tokens 126 [RFC6750] have emerged as popular standards for authorizing and 127 securing access to HTTP and RESTful resources but do not provide 128 everything necessary to facilitate token exchange interactions. 130 This specification defines a protocol extending OAuth 2.0 that 131 enables clients to request and obtain security tokens from 132 authorization servers acting in the role of an STS. Similar to OAuth 133 2.0, this specification focuses on client developer simplicity and 134 requires only an HTTP client and JSON parser, which are nearly 135 universally available in modern development environments. The STS 136 protocol defined in this specification is not itself RESTful (an STS 137 doesn't lend itself particularly well to a REST approach) but does 138 utilize communication patterns and data formats that should be 139 familiar to developers accustomed to working with RESTful systems. 141 A new grant type for a token exchange request and the associated 142 specific parameters for such a request to the token endpoint are 143 defined by this specification. A token exchange response is a normal 144 OAuth 2.0 response from the token endpoint with a few additional 145 parameters defined herein to provide information to the client. 147 The entity that makes the request to exchange tokens is considered 148 the client in the context of the token exchange interaction. 149 However, that does not restrict usage of this profile to traditional 150 OAuth clients. An OAuth resource server, for example, might assume 151 the role of the client during token exchange in order to trade an 152 access token, which it received in a protected resource request, for 153 a new token that is appropriate to include in a call to a backend 154 service. The new token might be an access token that is more 155 narrowly scoped for the downstream service or it could be an entirely 156 different kind of token. 158 The scope of this specification is limited to the definition of a 159 basic request and response protocol for an STS-style token exchange 160 utilizing OAuth 2.0. Although a few new JWT claims are defined that 161 enable delegation semantics to be expressed, the specific syntax, 162 semantics and security characteristics of the tokens themselves (both 163 those presented to the AS and those obtained by the client) are 164 explicitly out of scope and no requirements are placed on the trust 165 model in which an implementation might be deployed. Additional 166 profiles may provide more detailed requirements around the specific 167 nature of the parties and trust involved, such as whether signing 168 and/or encryption of tokens is needed or if proof-of-possession style 169 tokens will be required or issued; however, such details will often 170 be policy decisions made with respect to the specific needs of 171 individual deployments and will be configured or implemented 172 accordingly. 174 The security tokens obtained may be used in a number of contexts, the 175 specifics of which are also beyond the scope of this specification. 177 1.1. Delegation vs. Impersonation Semantics 179 When principal A impersonates principal B, A is given all the rights 180 that B has within some defined rights context and is 181 indistinguishable from B in that context. Thus, when principal A 182 impersonates principal B, then in so far as any entity receiving such 183 a token is concerned, they are actually dealing with B. It is true 184 that some members of the identity system might have awareness that 185 impersonation is going on, but it is not a requirement. For all 186 intents and purposes, when A is impersonating B, A is B. 188 Delegation semantics are different than impersonation semantics, 189 though the two are closely related. With delegation semantics, 190 principal A still has its own identity separate from B and it is 191 explicitly understood that while B may have delegated some of its 192 rights to A, any actions taken are being taken by A representing B. 193 In a sense, A is an agent for B. 195 Delegation and impersonation are not inclusive of all situations. 196 When a principal is acting directly on its own behalf, for example, 197 neither delegation nor impersonation are in play. They are, however, 198 the more common semantics operating for token exchange and, as such, 199 are given more direct treatment in this specification. 201 Delegation semantics are typically expressed in a token by including 202 information about both the primary subject of the token as well as 203 the actor to whom that subject has delegated some of its rights. 204 Such a token is sometimes referred to as a composite token because it 205 is composed of information about multiple subjects. Typically, in 206 the request, the "subject_token" represents the identity of the party 207 on behalf of whom the token is being requested while the 208 "actor_token" represents the identity of the party to whom the access 209 rights of the issued token are being delegated. A composite token 210 issued by the authorization server will contain information about 211 both parties. When and if a composite token is issued is at the 212 discretion of the authorization server and applicable policy and 213 configuration. 215 The specifics of representing a composite token and even whether or 216 not such a token will be issued depend on the details of the 217 implementation and the kind of token. The representations of 218 composite tokens that are not JWTs are beyond the scope of this 219 specification. The "actor_token" request parameter, however, does 220 provide a means for providing information about the desired actor and 221 the JWT "act" claim can provide a representation of a chain of 222 delegation. 224 1.2. Requirements Notation and Conventions 226 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 227 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 228 "OPTIONAL" in this document are to be interpreted as described in RFC 229 2119 [RFC2119]. 231 1.3. Terminology 233 This specification uses the terms "access token type", "authorization 234 server", "client", "client identifier", "resource server", "token 235 endpoint", "token request", and "token response" defined by OAuth 2.0 236 [RFC6749], and the terms "Claim" and "JWT Claims Set" defined by JSON 237 Web Token (JWT) [JWT]. 239 2. Token Exchange Request and Response 241 2.1. Request 243 A client requests a security token by making a token request to the 244 authorization server's token endpoint using the extension grant type 245 mechanism defined in Section 4.5 of OAuth 2.0 [RFC6749]. 247 Client authentication to the authorization server is done using the 248 normal mechanisms provided by OAuth 2.0. Section 2.3.1 of The OAuth 249 2.0 Authorization Framework [RFC6749] defines password-based 250 authentication of the client, however, client authentication is 251 extensible and other mechanisms are possible. For example, [RFC7523] 252 defines client authentication using JSON Web Tokens (JWTs) [JWT]. 253 The supported methods of client authentication and whether or not to 254 allow unauthenticated or unidentified clients are deployment 255 decisions that are at the discretion of the authorization server. 257 The client makes a token exchange request to the token endpoint with 258 an extension grant type by including the following parameters using 259 the "application/x-www-form-urlencoded" format with a character 260 encoding of UTF-8 in the HTTP request entity-body: 262 grant_type 263 REQUIRED. The value "urn:ietf:params:oauth:grant-type:token- 264 exchange" indicates that a token exchange is being performed. 266 resource 267 OPTIONAL. Indicates the physical location of the target service 268 or resource where the client intends to use the requested security 269 token. This enables the authorization server to apply policy as 270 appropriate for the target, such as determining the type and 271 content of the token to be issued or if and how the token is to be 272 encrypted. In many cases, a client will not have knowledge of the 273 logical organization of the systems with which it interacts and 274 will only know the location of the service where it intends to use 275 the token. The "resource" parameter allows the client to indicate 276 to the authorization server where it intends to use the issued 277 token by providing the location, typically as an https URL, in the 278 token exchange request in the same form that will be used to 279 access that resource. The authorization server will typically 280 have the capability to map from a resource URI value to an 281 appropriate policy. The value of the "resource" parameter MUST be 282 an absolute URI, as specified by Section 4.3 of [RFC3986], which 283 MAY include a query component and MUST NOT include a fragment 284 component. Multiple "resource" parameters may be used to indicate 285 that the issued token is intended to be used at the multiple 286 resources listed. 288 audience 289 OPTIONAL. The logical name of the target service where the client 290 intends to use the requested security token. This serves a 291 purpose similar to the "resource" parameter, but with the client 292 providing a logical name rather than a physical location. 293 Interpretation of the name requires that the value be something 294 that both the client and the authorization server understand. An 295 OAuth client identifier, a SAML entity identifier 296 [OASIS.saml-core-2.0-os], an OpenID Connect Issuer Identifier 297 [OpenID.Core], or a URI are examples of things that might be used 298 as "audience" parameter values. Multiple "audience" parameters 299 may be used to indicate that the issued token is intended to be 300 used at the multiple audiences listed. The "audience" and 301 "resource" parameters may be used together to indicate multiple 302 target services with a mix of logical names and physical 303 locations. 305 scope 306 OPTIONAL. A list of space-delimited, case-sensitive strings that 307 allow the client to specify the desired scope of the requested 308 security token in the context of the service or resource where the 309 token will be used. 311 requested_token_type 312 OPTIONAL. An identifier, as described in Section 3, for the type 313 of the requested security token. If the requested type is 314 unspecified, the issued token type is at the discretion of the 315 authorization server and may be dictated by knowledge of the 316 requirements of the service or resource indicated by the 317 "resource" or "audience" parameter. 319 subject_token 320 REQUIRED. A security token that represents the identity of the 321 party on behalf of whom the request is being made. Typically, the 322 subject of this token will be the subject of the security token 323 issued in response to this request. 325 subject_token_type 326 REQUIRED. An identifier, as described in Section 3, that 327 indicates the type of the security token in the "subject_token" 328 parameter. 330 actor_token 331 OPTIONAL. A security token that represents the identity of the 332 acting party. Typically this will be the party that is authorized 333 to use the requested security token and act on behalf of the 334 subject. 336 actor_token_type 337 An identifier, as described in Section 3, that indicates the type 338 of the security token in the "actor_token" parameter. This is 339 REQUIRED when the "actor_token" parameter is present in the 340 request but MUST NOT be included otherwise. 342 In the absence of one-time-use or other semantics specific to the 343 token type, the act of performing a token exchange has no impact on 344 the validity of the subject token or actor token. Furthermore, the 345 validity of the subject token or actor token have no impact on the 346 validity of the issued token after the exchange has occurred. 348 2.1.1. Relationship Between Resource, Audience and Scope 350 When requesting a token, the client can indicate the desired target 351 service(s) where it intends to use that token by way of the 352 "audience" and "resource" parameters, as well as indicating the 353 desired scope of the requested token using the "scope" parameter. 354 The semantics of such a request are that the client is asking for a 355 token with the requested scope that is usable at all the requested 356 target services. Effectively, the requested access rights of the 357 token are the cartesian product of all the scopes at all the target 358 services. 360 An authorization server may be unwilling or unable to fulfill any 361 token request but the likelihood of an unfulfillable request is 362 significantly higher when very broad access rights are being 363 solicited. As such, in the absence of specific knowledge about the 364 relationship of systems in a deployment, clients should exercise 365 discretion in the breadth of the access requested, particularly the 366 number of target services. An authorization server can use the 367 "invalid_target" error code, defined in Section 2.2.2, to inform a 368 client that it requested access to too many target services 369 simultaneously. 371 2.2. Response 373 The authorization server responds to a token exchange request with a 374 normal OAuth 2.0 response from the token endpoint, as specified in 375 Section 5 of [RFC6749]. Additional details and explanation are 376 provided in the following subsections. 378 2.2.1. Successful Response 380 If the request is valid and meets all policy and other criteria of 381 the authorization server, a successful token response is constructed 382 by adding the following parameters to the entity-body of the HTTP 383 response using the "application/json" media type, as specified by 385 [RFC7159], and an HTTP 200 status code. The parameters are 386 serialized into a JavaScript Object Notation (JSON) structure by 387 adding each parameter at the top level. Parameter names and string 388 values are included as JSON strings. Numerical values are included 389 as JSON numbers. The order of parameters does not matter and can 390 vary. 392 access_token 393 REQUIRED. The security token issued by the authorization server 394 in response to the token exchange request. The "access_token" 395 parameter from Section 5.1 of [RFC6749] is used here to carry the 396 requested token, which allows this token exchange protocol to use 397 the existing OAuth 2.0 request and response constructs defined for 398 the token endpoint. The identifier "access_token" is used for 399 historical reasons and the issued token need not be an OAuth 400 access token. 402 issued_token_type 403 REQUIRED. An identifier, as described in Section 3, for the 404 representation of the issued security token. 406 token_type 407 REQUIRED. A case-insensitive value specifying the method of using 408 of the access token issued, as specified in Section 7.1 of 409 [RFC6749]. It provides the client with information about how to 410 utilize the access token to access protected resources. For 411 example, a value of "Bearer", as specified in [RFC6750], indicates 412 that the security token is a bearer token and the client can 413 simply present it as is without any additional proof of 414 eligibility beyond the contents of the token itself. Note that 415 the meaning of this parameter is different from the meaning of the 416 "issued_token_type" parameter, which declares the representation 417 of the issued security token; the term "token type" is typically 418 used with this meaning, as it is in all "*_token_type" parameters 419 in this specification. If the issued token is not an access token 420 or usable as an access token, then the "token_type" value "N_A" is 421 used to indicate that an OAuth 2.0 "token_type" identifier is not 422 applicable in that context. 424 expires_in 425 RECOMMENDED. The validity lifetime, in seconds, of the token 426 issued by the authorization server. Oftentimes the client will 427 not have the inclination or capability to inspect the content of 428 the token and this parameter provides a consistent and token type 429 agnostic indication of how long the token can be expected to be 430 valid. For example, the value 1800 denotes that the token will 431 expire in thirty minutes from the time the response was generated. 433 scope 434 OPTIONAL, if the scope of the issued security token is identical 435 to the scope requested by the client; otherwise, REQUIRED. 437 refresh_token 438 OPTIONAL. A refresh token will typically not be issued when the 439 the exchange is of one temporary credential (the subject_token) 440 for a different temporary credential (the issued token) for use in 441 some other context. A refresh token can be issued in cases where 442 the client of the token exchange needs the ability to access a 443 resource even when the original credential is no longer valid 444 (e.g. user-not-present or offline scenarios where there is no 445 longer any user entertaining an active session with the client). 446 Profiles or deployments of this specification should clearly 447 document the conditions under which a client should expect a 448 refresh token in response to "urn:ietf:params:oauth:grant- 449 type:token-exchange" grant type requests. 451 2.2.2. Error Response 453 If either the "subject_token" or "actor_token" are invalid for any 454 reason, or are unacceptable based on policy, the authorization server 455 MUST construct an error response, as specified in Section 5.2 of 456 [RFC6749]. The value of the "error" parameter MUST be the 457 "invalid_request" error code. 459 If the authorization server is unwilling or unable to issue a token 460 for all the target services indicated by the "resource" or "audience" 461 parameters, the "invalid_target" error code SHOULD be used in the 462 error response. 464 The authorization server MAY include additional information regarding 465 the reasons for the error using the "error_description" and/or 466 "error_uri" parameters. 468 Other error codes may also be used, as appropriate. 470 2.3. Example Token Exchange 472 The following example demonstrates a hypothetical token exchange in 473 which an OAuth resource server assumes the role of the client during 474 token exchange in order to trade an access token that it received in 475 a protected resource request for a token that it will use to call to 476 a backend service (extra line breaks and indentation in the examples 477 are for display purposes only). 479 The resource server receives the following request containing an 480 OAuth access token in the Authorization request header, as specified 481 in Section 2.1 of [RFC6750]. 483 GET /resource HTTP/1.1 484 Host: frontend.example.com 485 Authorization: Bearer accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC 487 Figure 1: Protected Resource Request 489 The resource server assumes the role of the client for the token 490 exchange and the access token from the request above is sent to the 491 authorization server using a request as specified in Section 2.1. 492 The value of the "subject_token" parameter carries the access token 493 and the value of the "subject_token_type" parameter indicates that it 494 is an OAuth 2.0 access token. The resource server, acting in the 495 roll of the client, uses its identifier and secret to authenticate to 496 the authorization server using the HTTP Basic authentication scheme. 497 The "resource" parameter indicates the location of the backend 498 service, https://backend.example.com/api, where the issued token will 499 be used. 501 POST /as/token.oauth2 HTTP/1.1 502 Host: as.example.com 503 Authorization: Basic cnMwODpsb25nLXNlY3VyZS1yYW5kb20tc2VjcmV0 504 Content-Type: application/x-www-form-urlencoded 506 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 507 &resource=https%3A%2F%2Fbackend.example.com%2Fapi%20 508 &subject_token=accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC 509 &subject_token_type= 510 urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token 512 Figure 2: Token Exchange Request 514 The authorization server validates the client credentials and the 515 "subject_token" presented in the token exchange request. From the 516 "resource" parameter, the authorization server is able to determine 517 the appropriate policy to apply to the request and issues a token 518 suitable for use at https://backend.example.com. The "access_token" 519 parameter of the response contains the new token, which is itself a 520 bearer OAuth access token that is valid for one minute. The token 521 happens to be a JWT; however, its structure and format are opaque to 522 the client so the "issued_token_type" indicates only that it is an 523 access token. 525 HTTP/1.1 200 OK 526 Content-Type: application/json 527 Cache-Control: no-cache, no-store 529 { 530 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQiOiJo 531 dHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2FzLmV 532 4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1MzMsIn 533 N1YiI6ImJjQGV4YW1wbGUuY29tIiwic2NwIjpbImFwaSJdfQ.MXgnpvPMo0nhce 534 PwnQbunD2gw_pDyCFA-Saobl6gyLAdyPbaALFuAOyFc4XTWaPEnHV_LGmXklSTp 535 z0yC7hlSQ", 536 "issued_token_type": 537 "urn:ietf:params:oauth:token-type:access_token", 538 "token_type":"Bearer", 539 "expires_in":60 540 } 542 Figure 3: Token Exchange Response 544 The resource server can then use the newly acquired access token in 545 making a request to the backend server. 547 GET /api HTTP/1.1 548 Host: backend.example.com 549 Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQ 550 iOiJodHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2 551 FzLmV4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1M 552 zMsInN1YiI6ImJjQGV4YW1wbGUuY29tIiwic2NwIjpbImFwaSJdfQ.MXgnpvPMo 553 0nhcePwnQbunD2gw_pDyCFA-Saobl6gyLAdyPbaALFuAOyFc4XTWaPEnHV_LGmX 554 klSTpz0yC7hlSQ 556 Figure 4: Backend Protected Resource Request 558 Additional examples can be found in Appendix A. 560 3. Token Type Identifiers 562 Several parameters in this specification utilize an identifier as the 563 value to describe the token in question. Specifically, they are the 564 "requested_token_type", "subject_token_type", "actor_token_type" 565 parameters of the request and the "issued_token_type" member of the 566 response. Token type identifiers are URIs. Token Exchange can work 567 with both tokens issued by other parties and tokens from the given 568 authorization server. For the former the token type identifier 569 indicates the syntax (e.g. JWT or SAML) so the AS can parse it; for 570 the latter it indicates what the AS issued it for (e.g. access_token 571 or refresh_token). 573 This specification defines the token type identifiers 574 "urn:ietf:params:oauth:token-type:access_token" and 575 "urn:ietf:params:oauth:token-type:refresh_token" to indicate that the 576 token is an OAuth 2.0 access token or refresh token, respectively. 577 The value "urn:ietf:params:oauth:token-type:jwt" defined in Section 9 578 of [JWT] indicates that the token is a JWT. This specification also 579 defines the token type identifier "urn:ietf:params:oauth:token- 580 type:id_token" to indicate that the token is an ID Token, as defined 581 in Section 2 of [OpenID.Core]. Other URIs to indicate other token 582 types MAY be used. 584 The distinction between an access token and a JWT is subtle. An 585 access token represents a delegated authorization decision, whereas 586 JWT is a token format. An access token can be formatted as a JWT but 587 doesn't necessarily have to be. And a JWT might well be an access 588 token but not all JWTs are access tokens. The intent of this 589 specification is that "urn:ietf:params:oauth:token-type:access_token" 590 be an indicator that the token is a typical OAuth access token issued 591 by the authorization server in question, opaque to the client, and 592 usable the same manner as any other access token obtained from that 593 authorization server (it could well be a JWT but the client isn't and 594 needn't be aware of that fact). Whereas 595 "urn:ietf:params:oauth:token-type:jwt" is to indicate specifically 596 that a JWT is being requested or sent (perhaps in a cross-domain use- 597 case where the JWT is used as an authorization grant to obtain an 598 access token from a different authorization server as is facilitated 599 by [RFC7523]). 601 4. JSON Web Token Claims and Introspection Response Parameters 603 It is useful to have defined mechanisms to express delegation within 604 a token as well as to express authorization to delegate or 605 impersonate. Although the token exchange protocol described herein 606 can be used with any type of token, this section defines claims to 607 express such semantics specifically for JWTs and in an OAuth 2.0 608 Token Introspection [RFC7662] response. Similar definitions for 609 other types of tokens are possible but beyond the scope of this 610 specification. 612 4.1. "act" (Actor) Claim 614 The "act" (actor) claim provides a means within a JWT to express that 615 delegation has occurred and identify the acting party to whom 616 authority has been delegated. The "act" claim value is a JSON object 617 and members in the JSON object are claims that identify the actor. 618 The claims that make up the "act" claim identify and possibly provide 619 additional information about the actor. For example, the combination 620 of the two claims "iss" and "sub" might be necessary to uniquely 621 identify an actor. 623 However, claims within the "act" claim pertain only to the identity 624 of the actor and are not relevant to the validity of the containing 625 JWT in the same manner as the top-level claims. Consequently, non- 626 identity claims (e.g. "exp", "nbf", and "aud") are not meaningful 627 when used within an "act" claim, and therefore must not be used. 629 The following example illustrates the "act" (actor) claim within a 630 JWT Claims Set. The claims of the token itself are about 631 user@example.com while the "act" claim indicates that 632 admin@example.com is the current actor. 634 { 635 "aud":"https://consumer.example.com", 636 "iss":"https://issuer.example.com", 637 "exp":1443904177, 638 "nbf":1443904077, 639 "sub":"user@example.com", 640 "act": 641 { 642 "sub":"admin@example.com" 643 } 644 } 646 Figure 5: Actor Claim 648 A chain of delegation can be expressed by nesting one "act" claim 649 within another. The outermost "act" claim represents the current 650 actor while nested "act" claims represent prior actors. The least 651 recent actor is the most deeply nested. 653 The following example illustrates nested "act" (actor) claims within 654 a JWT Claims Set. The claims of the token itself are about 655 user@example.com while the "act" claim indicates that the system 656 consumer.example.com-web-application is the current actor and 657 admin@example.com was a prior actor. Such a token might come about 658 as the result of the web application receiving a token like the one 659 in the previous example and exchanging it for a new token that lists 660 it as the current actor and that can be used at 661 https://backend.example.com. 663 { 664 "aud":"https://backend.example.com", 665 "iss":"https://issuer.example.com", 666 "exp":1443904100, 667 "nbf":1443904000, 668 "sub":"user@example.com", 669 "act": 670 { 671 "sub":"consumer.example.com-web-application", 672 "iss":"https://issuer.example.net", 673 "act": 674 { 675 "sub":"admin@example.com" 676 } 677 } 678 } 680 Figure 6: Nested Actor Claim 682 When included as a top-level member of an OAuth token introspection 683 response, "act" has the same semantics and format as the the claim of 684 the same name. 686 4.2. "scp" (Scopes) Claim 688 The "scp" claim is an array of strings, each of which represents an 689 OAuth scope granted for the issued security token. Each array entry 690 of the claim value is a scope-token, as defined in Section 3.3 of 691 OAuth 2.0 [RFC6749]. 693 The following example illustrates the "scp" claim within a JWT Claims 694 Set with four scope-tokens. 696 { 697 "aud":"https://consumer.example.com", 698 "iss":"https://issuer.example.com", 699 "exp":1443904177, 700 "nbf":1443904077, 701 "sub":"dgaf4mvfs75Fci_FL3heQA", 702 "scp":["email","address","profile","phone"] 703 } 705 Figure 7: Scopes Claim 707 OAuth 2.0 Token Introspection [RFC7662] defines the "scope" parameter 708 to convey the scopes associated with the token. 710 4.3. "cid" (Client Identifier) Claim 712 The "cid" claim carries the client identifier of the OAuth 2.0 713 [RFC6749] client that requested the token. 715 The following example illustrates the "cid" claim within a JWT Claims 716 Set indicating an OAuth 2.0 client with "s6BhdRkqt3" as its 717 identifier. 719 { 720 "aud":"https://consumer.example.com", 721 "iss":"https://issuer.example.com", 722 "exp":1443904177, 723 "sub":"user@example.com", 724 "cid":"s6BhdRkqt3" 725 } 727 Figure 8: Client Identifier Claim 729 OAuth 2.0 Token Introspection [RFC7662] defines the "client_id" 730 parameter as the client identifier for the OAuth 2.0 client that 731 requested the token. 733 4.4. "may_act" (May Act For) Claim 735 The "may_act" claim makes a statement that one party is authorized to 736 become the actor and act on behalf of another party. The claim value 737 is a JSON object and members in the JSON object are claims that 738 identify the party that is asserted as being eligible to act for the 739 party identified by the JWT containing the claim. The claims that 740 make up the "may_act" claim identify and possibly provide additional 741 information about the authorized actor. For example, the combination 742 of the two claims "iss" and "sub" are sometimes necessary to uniquely 743 identify an authorized actor, while the "email" claim might be used 744 to provide additional useful information about that party. 746 However, claims within the "may_act" claim pertain only to the 747 identity of that party and are not relevant to the validity of the 748 containing JWT in the same manner as top level claims. Consequently, 749 claims such as "exp", "nbf", and "aud" are not meaningful when used 750 within a "may_act" claim, and therefore should not be used. 752 The following example illustrates the "may_act" claim within a JWT 753 Claims Set. The claims of the token itself are about 754 user@example.com while the "may_act" claim indicates that 755 admin@example.com is authorized to act on behalf of user@example.com. 757 { 758 "aud":"https://consumer.example.com", 759 "iss":"https://issuer.example.com", 760 "exp":1443904177, 761 "nbf":1443904077, 762 "sub":"user@example.com", 763 "may_act": 764 { 765 "sub":"admin@example.com" 766 } 767 } 769 Figure 9: May Act For Claim 771 When included as a top-level member of an OAuth token introspection 772 response, "may_act" has the same semantics and format as the the 773 claim of the same name. 775 5. IANA Considerations 777 5.1. OAuth URI Registration 779 This specification registers the following values in the IANA "OAuth 780 URI" registry [IANA.OAuth.Parameters] established by [RFC6755]. 782 5.1.1. Registry Contents 784 o URN: urn:ietf:params:oauth:grant-type:token-exchange 785 o Common Name: Token exchange grant type for OAuth 2.0 786 o Change controller: IESG 787 o Specification Document: Section 2.1 of [[ this specification ]] 788 o URN: urn:ietf:params:oauth:token-type:access_token 789 o Common Name: Token type URI for an OAuth 2.0 access token 790 o Change controller: IESG 791 o Specification Document: Section 3 of [[this specification]] 793 o URN: urn:ietf:params:oauth:token-type:refresh_token 794 o Common Name: Token Type URI for an OAuth 2.0 refresh token 795 o Change controller: IESG 796 o Specification Document: Section 3 of [[this specification]] 798 o URN: urn:ietf:params:oauth:token-type:id_token 799 o Common Name: Token Type URI for an ID Token 800 o Change controller: IESG 801 o Specification Document: Section 3 of [[this specification]] 803 5.2. OAuth Parameters Registration 805 This specification registers the following values in the IANA "OAuth 806 Parameters" registry [IANA.OAuth.Parameters] established by 807 [RFC6749]. 809 5.2.1. Registry Contents 811 o Parameter name: resource 812 o Parameter usage location: token request 813 o Change controller: IESG 814 o Specification document(s): Section 2.1 of [[ this specification ]] 816 o Parameter name: audience 817 o Parameter usage location: token request 818 o Change controller: IESG 819 o Specification document(s): Section 2.1 of [[ this specification ]] 821 o Parameter name: requested_token_type 822 o Parameter usage location: token request 823 o Change controller: IESG 824 o Specification document(s): Section 2.1 of [[ this specification ]] 826 o Parameter name: subject_token 827 o Parameter usage location: token request 828 o Change controller: IESG 829 o Specification document(s): Section 2.1 of [[ this specification ]] 831 o Parameter name: subject_token_type 832 o Parameter usage location: token request 833 o Change controller: IESG 834 o Specification document(s): Section 2.1 of [[ this specification ]] 835 o Parameter name: actor_token 836 o Parameter usage location: token request 837 o Change controller: IESG 838 o Specification document(s): Section 2.1 of [[ this specification ]] 840 o Parameter name: actor_token_type 841 o Parameter usage location: token request 842 o Change controller: IESG 843 o Specification document(s): Section 2.1 of [[ this specification ]] 845 o Parameter name: issued_token_type 846 o Parameter usage location: token response 847 o Change controller: IESG 848 o Specification document(s): Section 2.2.1 of [[ this specification 849 ]] 851 5.3. OAuth Access Token Type Registration 853 This specification registers the following access token type in the 854 IANA "OAuth Access Token Types" registry [IANA.OAuth.Parameters] 855 established by [RFC6749]. 857 5.3.1. Registry Contents 859 o Type name: N_A 860 o Additional Token Endpoint Response Parameters: (none) 861 o HTTP Authentication Scheme(s): (none) 862 o Change controller: IESG 863 o Specification document(s): Section 2.2.1 of [[ this specification 864 ]] 866 5.4. JSON Web Token Claims Registration 868 This specification registers the following Claims in the IANA "JSON 869 Web Token Claims" registry [IANA.JWT.Claims] established by [JWT]. 871 5.4.1. Registry Contents 873 o Claim Name: "act" 874 o Claim Description: Actor 875 o Change Controller: IESG 876 o Specification Document(s): Section 4.1 of [[ this specification ]] 878 o Claim Name: "scp" 879 o Claim Description: Scope Values 880 o Change Controller: IESG 881 o Specification Document(s): Section 4.2 of [[ this specification ]] 882 o Claim Name: "cid" 883 o Claim Description: Client Identifier 884 o Change Controller: IESG 885 o Specification Document(s): Section 4.3 of [[ this specification ]] 887 o Claim Name: "may_act" 888 o Claim Description: May Act For 889 o Change Controller: IESG 890 o Specification Document(s): Section 4.4 of [[ this specification ]] 892 5.5. OAuth Token Introspection Response Registration 894 This specification registers the following values in the IANA "OAuth 895 Token Introspection Response" registry [IANA.OAuth.Parameters] 896 established by [RFC7662]. 898 5.5.1. Registry Contents 900 o Claim Name: "act" 901 o Claim Description: Actor 902 o Change Controller: IESG 903 o Specification Document(s): Section 4.1 of [[ this specification ]] 905 o Claim Name: "may_act" 906 o Claim Description: May Act For 907 o Change Controller: IESG 908 o Specification Document(s): Section 4.4 of [[ this specification ]] 910 5.6. OAuth Extensions Error Registration 912 This specification registers the following values in the IANA "OAuth 913 Extensions Error" registry [IANA.OAuth.Parameters] established by 914 [RFC6749]. 916 5.6.1. Registry Contents 918 o Error Name: "invalid_target" 919 o Error Usage Location: token error response 920 o Related Protocol Extension: OAuth 2.0 Token Exchange 921 o Change Controller: IETF 922 o Specification Document(s): Section 2.2.2 of [[ this specification 923 ]] 925 6. Security Considerations 927 All of the normal security issues that are discussed in [JWT], 928 especially in relationship to comparing URIs and dealing with 929 unrecognized values, also apply here. 931 In addition, both delegation and impersonation introduce unique 932 security issues. Any time one principal is delegated the rights of 933 another principal, the potential for abuse is a concern. The use of 934 the "scp" claim is suggested to mitigate potential for such abuse, as 935 it restricts the contexts in which the delegated rights can be 936 exercised. 938 7. Privacy Considerations 940 Tokens typically carry personal information and their usage in Token 941 Exchange may reveal details of the target services being accessed. 942 As such, tokens should only be requested and sent according to the 943 privacy policies at the respective organizations. 945 8. References 947 8.1. Normative References 949 [IANA.JWT.Claims] 950 IANA, "JSON Web Token Claims", 951 . 953 [IANA.OAuth.Parameters] 954 IANA, "OAuth Parameters", 955 . 957 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 958 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 959 . 961 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 962 Requirement Levels", BCP 14, RFC 2119, 963 DOI 10.17487/RFC2119, March 1997, 964 . 966 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 967 Resource Identifier (URI): Generic Syntax", STD 66, 968 RFC 3986, DOI 10.17487/RFC3986, January 2005, 969 . 971 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 972 RFC 6749, DOI 10.17487/RFC6749, October 2012, 973 . 975 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 976 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 977 2014, . 979 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 980 RFC 7662, DOI 10.17487/RFC7662, October 2015, 981 . 983 8.2. Informative References 985 [OASIS.saml-core-2.0-os] 986 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 987 "Assertions and Protocol for the OASIS Security Assertion 988 Markup Language (SAML) V2.0", OASIS Standard saml-core- 989 2.0-os, March 2005. 991 [OpenID.Core] 992 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 993 C. Mortimore, "OpenID Connect Core 1.0", August 2015, 994 . 996 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 997 Framework: Bearer Token Usage", RFC 6750, 998 DOI 10.17487/RFC6750, October 2012, 999 . 1001 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 1002 for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, 1003 . 1005 [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 1006 "Assertion Framework for OAuth 2.0 Client Authentication 1007 and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, 1008 May 2015, . 1010 [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 1011 (JWT) Profile for OAuth 2.0 Client Authentication and 1012 Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 1013 2015, . 1015 [WS-Trust] 1016 Nadalin, A., Goodner, M., Gudgin, M., Barbir, A., and H. 1017 Granqvist, "WS-Trust 1.4", February 2012, 1018 . 1021 Appendix A. Additional Token Exchange Examples 1023 Two example token exchanges are provided in the following sections 1024 illustrating impersonation and delegation, respectively (with extra 1025 line breaks and indentation for display purposes only). 1027 A.1. Impersonation Token Exchange Example 1029 A.1.1. Token Exchange Request 1031 In the following token exchange request, a client is requesting a 1032 token with impersonation semantics. The client tells the 1033 authorization server that it needs a token for use at the target 1034 service with the logical name "urn:example:cooperation-context". 1036 POST /as/token.oauth2 HTTP/1.1 1037 Host: as.example.com 1038 Content-Type: application/x-www-form-urlencoded 1040 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 1041 &audience=urn%3Aexample%3Acooperation-context 1042 &subject_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwc 1043 zovL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXI 1044 uZXhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTA2MDAsIm5iZiI6MTQ0MTkwOTAwMCwic 1045 3ViIjoiYmNAZXhhbXBsZS5uZXQiLCJzY3AiOlsib3JkZXJzIiwicHJvZmlsZSIsImh 1046 pc3RvcnkiXX0.JDe7fZ267iIRXwbFmOugyCt5dmGoy6EeuzNQ3MqDek5cCUlyPhQC6 1047 cz9laKjK1bnjMQbLJqWix6ZdBI0isjsTA 1048 &subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1050 Figure 10: Token Exchange Request 1052 A.1.2. Subject Token Claims 1054 The "subject_token" in the prior request is a JWT and the decoded JWT 1055 Claims Set is shown here. The JWT is intended for consumption by the 1056 authorization server within a specific time window. The subject of 1057 the JWT ("bc@example.net") is the party on behalf of whom the new 1058 token is being requested. 1060 { 1061 "aud":"https://as.example.com", 1062 "iss":"https://original-issuer.example.net", 1063 "exp":1441910600, 1064 "nbf":1441909000, 1065 "sub":"bc@example.net", 1066 "scp":["orders","profile","history"] 1067 } 1069 Figure 11: Subject Token Claims 1071 A.1.3. Token Exchange Response 1073 The "access_token" parameter of the token exchange response shown 1074 below contains the new token that the client requested. The other 1075 parameters of the response indicate that the token is a bearer access 1076 token that expires in an hour. 1078 HTTP/1.1 200 OK 1079 Content-Type: application/json 1080 Cache-Control: no-cache, no-store 1082 { 1083 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm4 1084 6ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5l 1085 eGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic3ViIjoiYmNAZXhhbXBsZS5uZ 1086 XQiLCJzY3AiOlsib3JkZXJzIiwiaGlzdG9yeSIsInByb2ZpbGUiXX0.YQHuLmI1YD 1087 TugbfEvgGY2gaGBmMyj9BepZSECCBE9j9ogqZv2qx6VQQPrbT1k7vBYGLNMOkkpmm 1088 JkxZDS0YV7g", 1089 "issued_token_type": 1090 "urn:ietf:params:oauth:token-type:access_token", 1091 "token_type":"Bearer", 1092 "expires_in":3600 1093 } 1095 Figure 12: Token Exchange Response 1097 A.1.4. Issued Token Claims 1099 The decoded JWT Claims Set of the issued token is shown below. The 1100 new JWT is issued by the authorization server and intended for 1101 consumption by a system entity known by the logical name 1102 "urn:example:cooperation-context" any time before its expiration. 1103 The subject ("sub") of the JWT is the same as the subject the token 1104 used to make the request, which effectively enables the client to 1105 impersonate that subject at the system entity known by the logical 1106 name of "urn:example:cooperation-context" by using the token. 1108 { 1109 "aud":"urn:example:cooperation-context", 1110 "iss":"https://as.example.com", 1111 "exp":1441913610, 1112 "sub":"bc@example.net", 1113 "scp":["orders","history","profile"] 1114 } 1116 Figure 13: Issued Token Claims 1118 A.2. Delegation Token Exchange Example 1120 A.2.1. Token Exchange Request 1122 In the following token exchange request, a client is requesting a 1123 token and providing both a "subject_token" and an "actor_token". The 1124 client tells the authorization server that it needs a token for use 1125 at the target service with the logical name "urn:example:cooperation- 1126 context". Policy at the authorization server dictates that the 1127 issued token be a composite. 1129 POST /as/token.oauth2 HTTP/1.1 1130 Host: as.example.com 1131 Content-Type: application/x-www-form-urlencoded 1133 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 1134 &audience=urn%3Aexample%3Acooperation-context 1135 &subject_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwc 1136 zovL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXI 1137 uZXhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTAwNjAsInNjcCI6WyJzdGF0dXMiLCJmZ 1138 WVkIl0sInN1YiI6InVzZXJAZXhhbXBsZS5uZXQiLCJtYXlfYWN0Ijp7InN1YiI6ImF 1139 kbWluQGV4YW1wbGUubmV0In19.ut0Ll7wm920VzRvuLGLFoPJLeO5DDElxsax1L_xK 1140 Um2eooiNSfuif-OGa2382hPyFYnddKIa0wmDhQksW018Rw 1141 &subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1142 &actor_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwczo 1143 vL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXIuZ 1144 XhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTAwNjAsInN1YiI6ImFkbWluQGV4YW1wbGU 1145 ubmV0In0.7YQ-3zPfhUvzje5oqw8COCvN5uP6NsKik9CVV6cAOf4QKgM-tKfiOwcgZ 1146 oUuDL2tEs6tqPlcBlMjiSzEjm3yBg 1147 &actor_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1149 Figure 14: Token Exchange Request 1151 A.2.2. Subject Token Claims 1153 The "subject_token" in the prior request is a JWT and the decoded JWT 1154 Claims Set is shown here. The JWT is intended for consumption by the 1155 authorization server before a specific expiration time. The subject 1156 of the JWT ("user@example.net") is the party on behalf of whom the 1157 new token is being requested. 1159 { 1160 "aud":"https://as.example.com", 1161 "iss":"https://original-issuer.example.net", 1162 "exp":1441910060, 1163 "scp":["status","feed"], 1164 "sub":"user@example.net", 1165 "may_act": 1166 { 1167 "sub":"admin@example.net" 1168 } 1169 } 1171 Figure 15: Subject Token Claims 1173 A.2.3. Actor Token Claims 1175 The "actor_token" in the prior request is a JWT and the decoded JWT 1176 Claims Set is shown here. This JWT is also intended for consumption 1177 by the authorization server before a specific expiration time. The 1178 subject of the JWT ("admin@example.net") is the actor that will wield 1179 the security token being requested. 1181 { 1182 "aud":"https://as.example.com", 1183 "iss":"https://original-issuer.example.net", 1184 "exp":1441910060, 1185 "sub":"admin@example.net" 1186 } 1188 Figure 16: Actor Token Claims 1190 A.2.4. Token Exchange Response 1192 The "access_token" parameter of the token exchange response shown 1193 below contains the new token that the client requested. The other 1194 parameters of the response indicate that the token is a JWT that 1195 expires in an hour and that the access token type is not applicable 1196 since the issued token is not an access token. 1198 HTTP/1.1 200 OK 1199 Content-Type: application/json 1200 Cache-Control: no-cache, no-store 1202 { 1203 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm4 1204 6ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5l 1205 eGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic2NwIjpbInN0YXR1cyIsImZlZ 1206 WQiXSwic3ViIjoidXNlckBleGFtcGxlLm5ldCIsImFjdCI6eyJzdWIiOiJhZG1pbk 1207 BleGFtcGxlLm5ldCJ9fQ._qjM7Ij_HcrC78omT4jiZTFJOuzsAj1wPo31ymQS-Suq 1208 r64S1jCp6pfQR-in_OOAosAGamEg4jyPsht6kMAiYA", 1209 "issued_token_type":"urn:ietf:params:oauth:token-type:jwt", 1210 "token_type":"N_A", 1211 "expires_in":3600 1212 } 1214 Figure 17: Token Exchange Response 1216 A.2.5. Issued Token Claims 1218 The decoded JWT Claims Set of the issued token is shown below. The 1219 new JWT is issued by the authorization server and intended for 1220 consumption by a system entity known by the logical name 1221 "urn:example:cooperation-context" any time before its expiration. 1222 The subject ("sub") of the JWT is the same as the subject of the 1223 "subject_token" used to make the request. The actor ("act") of the 1224 JWT is the same as the subject of the "actor_token" used to make the 1225 request. This indicates delegation and identifies 1226 "admin@example.net" as the current actor to whom authority has been 1227 delegated to act on behalf of "user@example.net". 1229 { 1230 "aud":"urn:example:cooperation-context", 1231 "iss":"https://as.example.com", 1232 "exp":1441913610, 1233 "scp":["status","feed"], 1234 "sub":"user@example.net", 1235 "act": 1236 { 1237 "sub":"admin@example.net" 1238 } 1239 } 1241 Figure 18: Issued Token Claims 1243 Appendix B. Acknowledgements 1245 This specification was developed within the OAuth Working Group, 1246 which includes dozens of active and dedicated participants. It was 1247 produced under the chairmanship of Hannes Tschofenig and Derek Atkins 1248 with Kathleen Moriarty and Stephen Farrell serving as Security Area 1249 Directors. The following individuals contributed ideas, feedback, 1250 and wording to this specification: 1252 Caleb Baker, Vittorio Bertocci, Thomas Broyer, William Denniss, 1253 Vladimir Dzhuvinov, Phil Hunt, Benjamin Kaduk, Jason Keglovitz, 1254 Torsten Lodderstedt, Adam Lewis, James Manger, Nov Matake, Matt 1255 Miller, Matthew Perry, Justin Richer, Rifaat Shekh-Yusef, Scott 1256 Tomilson, and Hannes Tschofenig. 1258 Appendix C. Document History 1260 [[ to be removed by the RFC Editor before publication as an RFC ]] 1262 -09 1264 o Changed "security tokens obtained could be used in a number of 1265 contexts" to "security tokens obtained may be used in a number of 1266 contexts" per a WGLC suggestion. 1267 o Clarified that the validity of the subject or actor token have no 1268 impact on the validity of the issued token after the exchange has 1269 occurred per a WGLC comment. 1270 o Changed use of invalid_target error code to a SHOULD per a WGLC 1271 comment. 1272 o Clarified text about non-identity claims within the "act" claim 1273 being meaningless per a WGLC comment. 1274 o Added brief Privacy Considerations section per WGLC comments. 1276 -08 1278 o Use the bibxml reference for OpenID.Core rather than defining it 1279 inline. 1280 o Added editor role for Campbell. 1281 o Minor clarification of the text for actor_token. 1283 -07 1285 o Fixed typo (desecration -> discretion). 1286 o Added an explanation of the relationship between scope, audience 1287 and resource in the request and added an "invalid_target" error 1288 code enabling the AS to tell the client that the requested 1289 audiences/resources were too broad. 1291 -06 1293 o Drop "An STS for the REST of Us" from the title. 1294 o Drop "heavyweight" and "lightweight" from the abstract and 1295 introduction. 1296 o Clarifications on the language around xxxxxx_token_type. 1297 o Remove the want_composite parameter. 1298 o Add a short mention of proof-of-possession style tokens to the 1299 introduction and remove the respective open issue. 1301 -05 1303 o Defined the JWT claim "cid" to express the OAuth 2.0 client 1304 identifier of the client that requested the token. 1305 o Defined and requested registration for "act" and "may_act" as 1306 Token introspection response parameters (in addition to being JWT 1307 claims). 1308 o Loosen up the language about refresh_token in the response to 1309 OPTIONAL from NOT RECOMMENDED based on feedback form real world 1310 deployment experience. 1311 o Add clarifying text about the distinction between JWT and access 1312 token URIs. 1313 o Close out (remove) some of the Open Issues bullets that have been 1314 resolved. 1316 -04 1318 o Clarified that the "resource" and "audience" request parameters 1319 can be used at the same time (via http://www.ietf.org/mail- 1320 archive/web/oauth/current/msg15335.html). 1321 o Clarified subject/actor token validity after token exchange and 1322 explained a bit more about the recommendation to not issue refresh 1323 tokens (via http://www.ietf.org/mail-archive/web/oauth/current/ 1324 msg15318.html). 1325 o Updated the examples appendix to use an issuer value that doesn't 1326 imply that the client issued and signed the tokens and used 1327 "Bearer" and "urn:ietf:params:oauth:token-type:access_token" in 1328 one of the responses (via http://www.ietf.org/mail- 1329 archive/web/oauth/current/msg15335.html). 1330 o Defined and registered urn:ietf:params:oauth:token-type:id_token, 1331 since some use cases perform token exchanges for ID Tokens and no 1332 URI to indicate that a token is an ID Token had previously been 1333 defined. 1335 -03 1337 o Updated the document editors (adding Campbell, Bradley, and 1338 Mortimore). 1340 o Added to the title. 1341 o Added to the abstract and introduction. 1342 o Updated the format of the request to use application/x-www-form- 1343 urlencoded request parameters and the response to use the existing 1344 token endpoint JSON parameters defined in OAuth 2.0. 1345 o Changed the grant type identifier to urn:ietf:params:oauth:grant- 1346 type:token-exchange. 1347 o Added RFC 6755 registration requests for 1348 urn:ietf:params:oauth:token-type:refresh_token, 1349 urn:ietf:params:oauth:token-type:access_token, and 1350 urn:ietf:params:oauth:grant-type:token-exchange. 1351 o Added RFC 6749 registration requests for request/response 1352 parameters. 1353 o Removed the Implementation Considerations and the requirement to 1354 support JWTs. 1355 o Clarified many aspects of the text. 1356 o Changed "on_behalf_of" to "subject_token", 1357 "on_behalf_of_token_type" to "subject_token_type", "act_as" to 1358 "actor_token", and "act_as_token_type" to "actor_token_type". 1359 o Added an "audience" request parameter used to indicate the logical 1360 names of the target services at which the client intends to use 1361 the requested security token. 1362 o Added a "want_composite" request parameter used to indicate the 1363 desire for a composite token rather than trying to infer it from 1364 the presence/absence of token(s) in the request. 1365 o Added a "resource" request parameter used to indicate the URLs of 1366 resources at which the client intends to use the requested 1367 security token. 1368 o Specified that multiple "audience" and "resource" request 1369 parameter values may be used. 1370 o Defined the JWT claim "act" (actor) to express the current actor 1371 or delegation principal. 1372 o Defined the JWT claim "may_act" to express that one party is 1373 authorized to act on behalf of another party. 1374 o Defined the JWT claim "scp" (scopes) to express OAuth 2.0 scope- 1375 token values. 1376 o Added the "N_A" (not applicable) OAuth Access Token Type 1377 definition for use in contexts in which the token exchange syntax 1378 requires a "token_type" value, but in which the token being issued 1379 is not an access token. 1380 o Added examples. 1382 -02 1384 o Enabled use of Security Token types other than JWTs for "act_as" 1385 and "on_behalf_of" request values. 1386 o Referenced the JWT and OAuth Assertions RFCs. 1388 -01 1390 o Updated references. 1392 -00 1394 o Created initial working group draft from draft-jones-oauth-token- 1395 exchange-01. 1397 Authors' Addresses 1399 Michael B. Jones 1400 Microsoft 1402 Email: mbj@microsoft.com 1403 URI: http://self-issued.info/ 1405 Anthony Nadalin 1406 Microsoft 1408 Email: tonynad@microsoft.com 1410 Brian Campbell (editor) 1411 Ping Identity 1413 Email: brian.d.campbell@gmail.com 1415 John Bradley 1416 Ping Identity 1418 Email: ve7jtb@ve7jtb.com 1420 Chuck Mortimore 1421 Salesforce 1423 Email: cmortimore@salesforce.com