idnits 2.17.1 draft-ietf-oauth-token-exchange-07.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 (January 11, 2017) is 2662 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: July 15, 2017 B. Campbell 6 J. Bradley 7 Ping Identity 8 C. Mortimore 9 Salesforce 10 January 11, 2017 12 OAuth 2.0 Token Exchange 13 draft-ietf-oauth-token-exchange-07 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 July 15, 2017. 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. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 88 7.1. Normative References . . . . . . . . . . . . . . . . . . 21 89 7.2. Informative References . . . . . . . . . . . . . . . . . 22 90 Appendix A. Additional Token Exchange Examples . . . . . . . . . 22 91 A.1. Impersonation Token Exchange Example . . . . . . . . . . 23 92 A.1.1. Token Exchange Request . . . . . . . . . . . . . . . 23 93 A.1.2. Subject Token Claims . . . . . . . . . . . . . . . . 23 94 A.1.3. Token Exchange Response . . . . . . . . . . . . . . . 24 95 A.1.4. Issued Token Claims . . . . . . . . . . . . . . . . . 24 96 A.2. Delegation Token Exchange Example . . . . . . . . . . . . 25 97 A.2.1. Token Exchange Request . . . . . . . . . . . . . . . 25 98 A.2.2. Subject Token Claims . . . . . . . . . . . . . . . . 25 99 A.2.3. Actor Token Claims . . . . . . . . . . . . . . . . . 26 100 A.2.4. Token Exchange Response . . . . . . . . . . . . . . . 26 101 A.2.5. Issued Token Claims . . . . . . . . . . . . . . . . . 27 102 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 28 103 Appendix C. Document History . . . . . . . . . . . . . . . . . . 28 104 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30 106 1. Introduction 108 A security token is a set of information that facilitates the sharing 109 of identity and security information in heterogeneous environments or 110 across security domains. Examples of security tokens include JSON 111 Web Tokens (JWTs) [JWT] and SAML Assertions [OASIS.saml-core-2.0-os]. 112 Security tokens are typically signed to achieve integrity and 113 sometimes also encrypted to achieve confidentiality. Security tokens 114 are also sometimes described as Assertions, such as in [RFC7521]. 116 A Security Token Service (STS) is a service capable of validating and 117 issuing security tokens, which enables clients to obtain appropriate 118 access credentials for resources in heterogeneous environments or 119 across security domains. Web Service clients have used WS-Trust 120 [WS-Trust] as the protocol to interact with an STS for token 121 exchange. While WS-Trust uses XML and SOAP, the trend in modern Web 122 development has been towards RESTful patterns and JSON. The OAuth 123 2.0 Authorization Framework [RFC6749] and OAuth 2.0 Bearer Tokens 124 [RFC6750] have emerged as popular standards for authorizing and 125 securing access to HTTP and RESTful resources but do not provide 126 everything necessary to facilitate token exchange interactions. 128 This specification defines a protocol extending OAuth 2.0 that 129 enables clients to request and obtain security tokens from 130 authorization servers acting in the role of an STS. Similar to OAuth 131 2.0, this specification focuses on client developer simplicity and 132 requires only an HTTP client and JSON parser, which are nearly 133 universally available in modern development environments. The STS 134 protocol defined in this specification is not itself RESTful (an STS 135 doesn't lend itself particularly well to a REST approach) but does 136 utilize communication patterns and data formats that should be 137 familiar to developers accustomed to working with RESTful systems. 139 A new grant type for a token exchange request and the associated 140 specific parameters for such a request to the token endpoint are 141 defined by this specification. A token exchange response is a normal 142 OAuth 2.0 response from the token endpoint with a few additional 143 parameters defined herein to provide information to the client. 145 The entity that makes the request to exchange tokens is considered 146 the client in the context of the token exchange interaction. 147 However, that does not restrict usage of this profile to traditional 148 OAuth clients. An OAuth resource server, for example, might assume 149 the role of the client during token exchange in order to trade an 150 access token, which it received in a protected resource request, for 151 a new token that is appropriate to include in a call to a backend 152 service. The new token might be an access token that is more 153 narrowly scoped for the downstream service or it could be an entirely 154 different kind of token. 156 The scope of this specification is limited to the definition of a 157 basic request and response protocol for an STS-style token exchange 158 utilizing OAuth 2.0. Although a few new JWT claims are defined that 159 enable delegation semantics to be expressed, the specific syntax, 160 semantics and security characteristics of the tokens themselves (both 161 those presented to the AS and those obtained by the client) are 162 explicitly out of scope and no requirements are placed on the trust 163 model in which an implementation might be deployed. Additional 164 profiles may provide more detailed requirements around the specific 165 nature of the parties and trust involved, such as whether signing 166 and/or encryption of tokens is needed or if proof-of-possession style 167 tokens will be required or issued; however, such details will often 168 be policy decisions made with respect to the specific needs of 169 individual deployments and will be configured or implemented 170 accordingly. 172 The security tokens obtained could be used in a number of contexts, 173 the specifics of which are also beyond the scope of this 174 specification. 176 1.1. Delegation vs. Impersonation Semantics 178 When principal A impersonates principal B, A is given all the rights 179 that B has within some defined rights context and is 180 indistinguishable from B in that context. Thus, when principal A 181 impersonates principal B, then in so far as any entity receiving such 182 a token is concerned, they are actually dealing with B. It is true 183 that some members of the identity system might have awareness that 184 impersonation is going on, but it is not a requirement. For all 185 intents and purposes, when A is impersonating B, A is B. 187 Delegation semantics are different than impersonation semantics, 188 though the two are closely related. With delegation semantics, 189 principal A still has its own identity separate from B and it is 190 explicitly understood that while B may have delegated some of its 191 rights to A, any actions taken are being taken by A representing B. 192 In a sense, A is an agent for B. 194 Delegation and impersonation are not inclusive of all situations. 195 When a principal is acting directly on its own behalf, for example, 196 neither delegation nor impersonation are in play. They are, however, 197 the more common semantics operating for token exchange and, as such, 198 are given more direct treatment in this specification. 200 Delegation semantics are typically expressed in a token by including 201 information about both the primary subject of the token as well as 202 the actor to whom that subject has delegated some of its rights. 203 Such a token is sometimes referred to as a composite token because it 204 is composed of information about multiple subjects. Typically, in 205 the request, the "subject_token" represents the identity of the party 206 on behalf of whom the token is being requested while the 207 "actor_token" represents the identity of the party to whom the access 208 rights of the issued token are being delegated. A composite token 209 issued by the authorization server will contain information about 210 both parties. When and if a composite token is issued is at the 211 discretion of the authorization server and applicable policy and 212 configuration. 214 The specifics of representing a composite token and even whether or 215 not such a token will be issued depend on the details of the 216 implementation and the kind of token. The representations of 217 composite tokens that are not JWTs are beyond the scope of this 218 specification. The "actor_token" request parameter, however, does 219 provide a means for providing information about the desired actor and 220 the JWT "act" claim can provide a representation of a chain of 221 delegation. 223 1.2. Requirements Notation and Conventions 225 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 226 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 227 "OPTIONAL" in this document are to be interpreted as described in RFC 228 2119 [RFC2119]. 230 1.3. Terminology 232 This specification uses the terms "access token type", "authorization 233 server", "client", "client identifier", "resource server", "token 234 endpoint", "token request", and "token response" defined by OAuth 2.0 235 [RFC6749], and the terms "Claim" and "JWT Claims Set" defined by JSON 236 Web Token (JWT) [JWT]. 238 2. Token Exchange Request and Response 240 2.1. Request 242 A client requests a security token by making a token request to the 243 authorization server's token endpoint using the extension grant type 244 mechanism defined in Section 4.5 of OAuth 2.0 [RFC6749]. 246 Client authentication to the authorization server is done using the 247 normal mechanisms provided by OAuth 2.0. Section 2.3.1 of The OAuth 248 2.0 Authorization Framework [RFC6749] defines password-based 249 authentication of the client, however, client authentication is 250 extensible and other mechanisms are possible. For example, [RFC7523] 251 defines client authentication using JSON Web Tokens (JWTs) [JWT]. 252 The supported methods of client authentication and whether or not to 253 allow unauthenticated or unidentified clients are deployment 254 decisions that are at the discretion of the authorization server. 256 The client makes a token exchange request to the token endpoint with 257 an extension grant type by including the following parameters using 258 the "application/x-www-form-urlencoded" format with a character 259 encoding of UTF-8 in the HTTP request entity-body: 261 grant_type 262 REQUIRED. The value "urn:ietf:params:oauth:grant-type:token- 263 exchange" indicates that a token exchange is being performed. 265 resource 266 OPTIONAL. Indicates the physical location of the target service 267 or resource where the client intends to use the requested security 268 token. This enables the authorization server to apply policy as 269 appropriate for the target, such as determining the type and 270 content of the token to be issued or if and how the token is to be 271 encrypted. In many cases, a client will not have knowledge of the 272 logical organization of the systems with which it interacts and 273 will only know the location of the service where it intends to use 274 the token. The "resource" parameter allows the client to indicate 275 to the authorization server where it intends to use the issued 276 token by providing the location, typically as an https URL, in the 277 token exchange request in the same form that will be used to 278 access that resource. The authorization server will typically 279 have the capability to map from a resource URI value to an 280 appropriate policy. The value of the "resource" parameter MUST be 281 an absolute URI, as specified by Section 4.3 of [RFC3986], which 282 MAY include a query component and MUST NOT include a fragment 283 component. Multiple "resource" parameters may be used to indicate 284 that the issued token is intended to be used at the multiple 285 resources listed. 287 audience 288 OPTIONAL. The logical name of the target service where the client 289 intends to use the requested security token. This serves a 290 purpose similar to the "resource" parameter, but with the client 291 providing a logical name rather than a physical location. 292 Interpretation of the name requires that the value be something 293 that both the client and the authorization server understand. An 294 OAuth client identifier, a SAML entity identifier 295 [OASIS.saml-core-2.0-os], an OpenID Connect Issuer Identifier 296 [OpenID.Core], or a URI are examples of things that might be used 297 as "audience" parameter values. Multiple "audience" parameters 298 may be used to indicate that the issued token is intended to be 299 used at the multiple audiences listed. The "audience" and 300 "resource" parameters may be used together to indicate multiple 301 target services with a mix of logical names and physical 302 locations. 304 scope 305 OPTIONAL. A list of space-delimited, case-sensitive strings that 306 allow the client to specify the desired scope of the requested 307 security token in the context of the service or resource where the 308 token will be used. 310 requested_token_type 311 OPTIONAL. An identifier, as described in Section 3, for the type 312 of the requested security token. If the requested type is 313 unspecified, the issued token type is at the discretion of the 314 authorization server and may be dictated by knowledge of the 315 requirements of the service or resource indicated by the 316 "resource" or "audience" parameter. 318 subject_token 319 REQUIRED. A security token that represents the identity of the 320 party on behalf of whom the request is being made. Typically, the 321 subject of this token will be the subject of the security token 322 issued in response to this request. 324 subject_token_type 325 REQUIRED. An identifier, as described in Section 3, that 326 indicates the type of the security token in the "subject_token" 327 parameter. 329 actor_token 330 OPTIONAL. A security token that represents the identity of the 331 party that is authorized to use the requested security token and 332 act on behalf of the subject. 334 actor_token_type 335 An identifier, as described in Section 3, that indicates the type 336 of the security token in the "actor_token" parameter. This is 337 REQUIRED when the "actor_token" parameter is present in the 338 request but MUST NOT be included otherwise. 340 In the absence of one-time-use or other semantics specific to the 341 token type, the act of performing a token exchange has no impact on 342 the validity of the subject token or actor token. 344 2.1.1. Relationship Between Resource, Audience and Scope 346 When requesting a token, the client can indicate the desired target 347 service(s) where it intends to use that token by way of the 348 "audience" and "resource" parameters, as well as indicating the 349 desired scope of the requested token using the "scope" parameter. 350 The semantics of such a request are that the client is asking for a 351 token with the requested scope that is usable at all the requested 352 target services. Effectively, the requested access rights of the 353 token are the cartesian product of all the scopes at all the target 354 services. 356 An authorization server may be unwilling or unable to fulfill any 357 token request but the likelihood of an unfulfillable request is 358 significantly higher when very broad access rights are being 359 solicited. As such, in the absence of specific knowledge about the 360 relationship of systems in a deployment, clients should exercise 361 discretion in the breadth of the access requested, particularly the 362 number of target services. An authorization server can use the 363 "invalid_target" error code, defined in Section 2.2.2, to inform a 364 client that it requested access to too many target services 365 simultaneously. 367 2.2. Response 369 The authorization server responds to a token exchange request with a 370 normal OAuth 2.0 response from the token endpoint, as specified in 371 Section 5 of [RFC6749]. Additional details and explanation are 372 provided in the following subsections. 374 2.2.1. Successful Response 376 If the request is valid and meets all policy and other criteria of 377 the authorization server, a successful token response is constructed 378 by adding the following parameters to the entity-body of the HTTP 379 response using the "application/json" media type, as specified by 380 [RFC7159], and an HTTP 200 status code. The parameters are 381 serialized into a JavaScript Object Notation (JSON) structure by 382 adding each parameter at the top level. Parameter names and string 383 values are included as JSON strings. Numerical values are included 384 as JSON numbers. The order of parameters does not matter and can 385 vary. 387 access_token 388 REQUIRED. The security token issued by the authorization server 389 in response to the token exchange request. The "access_token" 390 parameter from Section 5.1 of [RFC6749] is used here to carry the 391 requested token, which allows this token exchange protocol to use 392 the existing OAuth 2.0 request and response constructs defined for 393 the token endpoint. The identifier "access_token" is used for 394 historical reasons and the issued token need not be an OAuth 395 access token. 397 issued_token_type 398 REQUIRED. An identifier, as described in Section 3, for the 399 representation of the issued security token. 401 token_type 402 REQUIRED. A case-insensitive value specifying the method of using 403 of the access token issued, as specified in Section 7.1 of 404 [RFC6749]. It provides the client with information about how to 405 utilize the access token to access protected resources. For 406 example, a value of "Bearer", as specified in [RFC6750], indicates 407 that the security token is a bearer token and the client can 408 simply present it as is without any additional proof of 409 eligibility beyond the contents of the token itself. Note that 410 the meaning of this parameter is different from the meaning of the 411 "issued_token_type" parameter, which declares the representation 412 of the issued security token; the term "token type" is typically 413 used with this meaning, as it is in all "*_token_type" parameters 414 in this specification. If the issued token is not an access token 415 or usable as an access token, then the "token_type" value "N_A" is 416 used to indicate that an OAuth 2.0 "token_type" identifier is not 417 applicable in that context. 419 expires_in 420 RECOMMENDED. The validity lifetime, in seconds, of the token 421 issued by the authorization server. Oftentimes the client will 422 not have the inclination or capability to inspect the content of 423 the token and this parameter provides a consistent and token type 424 agnostic indication of how long the token can be expected to be 425 valid. For example, the value 1800 denotes that the token will 426 expire in thirty minutes from the time the response was generated. 428 scope 429 OPTIONAL, if the scope of the issued security token is identical 430 to the scope requested by the client; otherwise, REQUIRED. 432 refresh_token 433 OPTIONAL. A refresh token will typically not be issued when the 434 the exchange is of one temporary credential (the subject_token) 435 for a different temporary credential (the issued token) for use in 436 some other context. A refresh token can be issued in cases where 437 the client of the token exchange needs the ability to access a 438 resource even when the original credential is no longer valid 439 (e.g. user-not-present or offline scenarios where there is no 440 longer any user entertaining an active session with the client). 441 Profiles or deployments of this specification should clearly 442 document the conditions under which a client should expect a 443 refresh token in response to "urn:ietf:params:oauth:grant- 444 type:token-exchange" grant type requests. 446 2.2.2. Error Response 448 If either the "subject_token" or "actor_token" are invalid for any 449 reason, or are unacceptable based on policy, the authorization server 450 MUST construct an error response, as specified in Section 5.2 of 451 [RFC6749]. The value of the "error" parameter MUST be the 452 "invalid_request" error code. 454 If the authorization server is unwilling or unable to issue a token 455 for all the target services indicated by the "resource" or "audience" 456 parameters, the "invalid_target" error code MAY be used in the error 457 response. 459 The authorization server MAY include additional information regarding 460 the reasons for the error using the "error_description" and/or 461 "error_uri" parameters. 463 Other error codes may also be used, as appropriate. 465 2.3. Example Token Exchange 467 The following example demonstrates a hypothetical token exchange in 468 which an OAuth resource server assumes the role of the client during 469 token exchange in order to trade an access token that it received in 470 a protected resource request for a token that it will use to call to 471 a backend service (extra line breaks and indentation in the examples 472 are for display purposes only). 474 The resource server receives the following request containing an 475 OAuth access token in the Authorization request header, as specified 476 in Section 2.1 of [RFC6750]. 478 GET /resource HTTP/1.1 479 Host: frontend.example.com 480 Authorization: Bearer accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC 482 Figure 1: Protected Resource Request 484 The resource server assumes the role of the client for the token 485 exchange and the access token from the request above is sent to the 486 authorization server using a request as specified in Section 2.1. 487 The value of the "subject_token" parameter carries the access token 488 and the value of the "subject_token_type" parameter indicates that it 489 is an OAuth 2.0 access token. The resource server, acting in the 490 roll of the client, uses its identifier and secret to authenticate to 491 the authorization server using the HTTP Basic authentication scheme. 492 The "resource" parameter indicates the location of the backend 493 service, https://backend.example.com/api, where the issued token will 494 be used. 496 POST /as/token.oauth2 HTTP/1.1 497 Host: as.example.com 498 Authorization: Basic cnMwODpsb25nLXNlY3VyZS1yYW5kb20tc2VjcmV0 499 Content-Type: application/x-www-form-urlencoded 501 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 502 &resource=https%3A%2F%2Fbackend.example.com%2Fapi%20 503 &subject_token=accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC 504 &subject_token_type= 505 urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token 507 Figure 2: Token Exchange Request 509 The authorization server validates the client credentials and the 510 "subject_token" presented in the token exchange request. From the 511 "resource" parameter, the authorization server is able to determine 512 the appropriate policy to apply to the request and issues a token 513 suitable for use at https://backend.example.com. The "access_token" 514 parameter of the response contains the new token, which is itself a 515 bearer OAuth access token that is valid for one minute. The token 516 happens to be a JWT; however, its structure and format are opaque to 517 the client so the "issued_token_type" indicates only that it is an 518 access token. 520 HTTP/1.1 200 OK 521 Content-Type: application/json 522 Cache-Control: no-cache, no-store 524 { 525 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQiOiJo 526 dHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2FzLmV 527 4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1MzMsIn 528 N1YiI6ImJjQGV4YW1wbGUuY29tIiwic2NwIjpbImFwaSJdfQ.MXgnpvPMo0nhce 529 PwnQbunD2gw_pDyCFA-Saobl6gyLAdyPbaALFuAOyFc4XTWaPEnHV_LGmXklSTp 530 z0yC7hlSQ", 531 "issued_token_type": 532 "urn:ietf:params:oauth:token-type:access_token", 533 "token_type":"Bearer", 534 "expires_in":60 535 } 537 Figure 3: Token Exchange Response 539 The resource server can then use the newly acquired access token in 540 making a request to the backend server. 542 GET /api HTTP/1.1 543 Host: backend.example.com 544 Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQ 545 iOiJodHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2 546 FzLmV4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1M 547 zMsInN1YiI6ImJjQGV4YW1wbGUuY29tIiwic2NwIjpbImFwaSJdfQ.MXgnpvPMo 548 0nhcePwnQbunD2gw_pDyCFA-Saobl6gyLAdyPbaALFuAOyFc4XTWaPEnHV_LGmX 549 klSTpz0yC7hlSQ 551 Figure 4: Backend Protected Resource Request 553 Additional examples can be found in Appendix A. 555 3. Token Type Identifiers 557 Several parameters in this specification utilize an identifier as the 558 value to describe the token in question. Specifically, they are the 559 "requested_token_type", "subject_token_type", "actor_token_type" 560 parameters of the request and the "issued_token_type" member of the 561 response. Token type identifiers are URIs. Token Exchange can work 562 with both tokens issued by other parties and tokens from the given 563 authorization server. For the former the token type identifier 564 indicates the syntax (e.g. JWT or SAML) so the AS can parse it; for 565 the latter it indicates what the AS issued it for (e.g. access_token 566 or refresh_token). 568 This specification defines the token type identifiers 569 "urn:ietf:params:oauth:token-type:access_token" and 570 "urn:ietf:params:oauth:token-type:refresh_token" to indicate that the 571 token is an OAuth 2.0 access token or refresh token, respectively. 572 The value "urn:ietf:params:oauth:token-type:jwt" defined in Section 9 573 of [JWT] indicates that the token is a JWT. This specification also 574 defines the token type identifier "urn:ietf:params:oauth:token- 575 type:id_token" to indicate that the token is an ID Token, as defined 576 in Section 2 of [OpenID.Core]. Other URIs to indicate other token 577 types MAY be used. 579 The distinction between an access token and a JWT is subtle. An 580 access token represents a delegated authorization decision, whereas 581 JWT is a token format. An access token can be formatted as a JWT but 582 doesn't necessarily have to be. And a JWT might well be an access 583 token but not all JWTs are access tokens. The intent of this 584 specification is that "urn:ietf:params:oauth:token-type:access_token" 585 be an indicator that the token is a typical OAuth access token issued 586 by the authorization server in question, opaque to the client, and 587 usable the same manner as any other access token obtained from that 588 authorization server (it could well be a JWT but the client isn't and 589 needn't be aware of that fact). Whereas 590 "urn:ietf:params:oauth:token-type:jwt" is to indicate specifically 591 that a JWT is being requested or sent (perhaps in a cross-domain use- 592 case where the JWT is used as an authorization grant to obtain an 593 access token from a different authorization server as is facilitated 594 by [RFC7523]). 596 4. JSON Web Token Claims and Introspection Response Parameters 598 It is useful to have defined mechanisms to express delegation within 599 a token as well as to express authorization to delegate or 600 impersonate. Although the token exchange protocol described herein 601 can be used with any type of token, this section defines claims to 602 express such semantics specifically for JWTs and in an OAuth 2.0 603 Token Introspection [RFC7662] response. Similar definitions for 604 other types of tokens are possible but beyond the scope of this 605 specification. 607 4.1. "act" (Actor) Claim 609 The "act" (actor) claim provides a means within a JWT to express that 610 delegation has occurred and identify the acting party to whom 611 authority has been delegated. The "act" claim value is a JSON object 612 and members in the JSON object are claims that identify the actor. 613 The claims that make up the "act" claim identify and possibly provide 614 additional information about the actor. For example, the combination 615 of the two claims "iss" and "sub" might be necessary to uniquely 616 identify an actor. 618 However, claims within the "act" claim pertain only to the identity 619 of the actor and are not relevant to the validity of the containing 620 JWT in the same manner as the top-level claims. Consequently, claims 621 such as "exp", "nbf", and "aud" are not meaningful when used within 622 an "act" claim, and therefore should not be used. 624 The following example illustrates the "act" (actor) claim within a 625 JWT Claims Set. The claims of the token itself are about 626 user@example.com while the "act" claim indicates that 627 admin@example.com is the current actor. 629 { 630 "aud":"https://consumer.example.com", 631 "iss":"https://issuer.example.com", 632 "exp":1443904177, 633 "nbf":1443904077, 634 "sub":"user@example.com", 635 "act": 636 { 637 "sub":"admin@example.com" 638 } 639 } 641 Figure 5: Actor Claim 643 A chain of delegation can be expressed by nesting one "act" claim 644 within another. The outermost "act" claim represents the current 645 actor while nested "act" claims represent prior actors. The least 646 recent actor is the most deeply nested. 648 The following example illustrates nested "act" (actor) claims within 649 a JWT Claims Set. The claims of the token itself are about 650 user@example.com while the "act" claim indicates that the system 651 consumer.example.com-web-application is the current actor and 652 admin@example.com was a prior actor. Such a token might come about 653 as the result of the web application receiving a token like the one 654 in the previous example and exchanging it for a new token that lists 655 it as the current actor and that can be used at 656 https://backend.example.com. 658 { 659 "aud":"https://backend.example.com", 660 "iss":"https://issuer.example.com", 661 "exp":1443904100, 662 "nbf":1443904000, 663 "sub":"user@example.com", 664 "act": 665 { 666 "sub":"consumer.example.com-web-application", 667 "iss":"https://issuer.example.net", 668 "act": 669 { 670 "sub":"admin@example.com" 671 } 672 } 673 } 675 Figure 6: Nested Actor Claim 677 When included as a top-level member of an OAuth token introspection 678 response, "act" has the same semantics and format as the the claim of 679 the same name. 681 4.2. "scp" (Scopes) Claim 683 The "scp" claim is an array of strings, each of which represents an 684 OAuth scope granted for the issued security token. Each array entry 685 of the claim value is a scope-token, as defined in Section 3.3 of 686 OAuth 2.0 [RFC6749]. 688 The following example illustrates the "scp" claim within a JWT Claims 689 Set with four scope-tokens. 691 { 692 "aud":"https://consumer.example.com", 693 "iss":"https://issuer.example.com", 694 "exp":1443904177, 695 "nbf":1443904077, 696 "sub":"dgaf4mvfs75Fci_FL3heQA", 697 "scp":["email","address","profile","phone"] 698 } 700 Figure 7: Scopes Claim 702 OAuth 2.0 Token Introspection [RFC7662] defines the "scope" parameter 703 to convey the scopes associated with the token. 705 4.3. "cid" (Client Identifier) Claim 707 The "cid" claim carries the client identifier of the OAuth 2.0 708 [RFC6749] client that requested the token. 710 The following example illustrates the "cid" claim within a JWT Claims 711 Set indicating an OAuth 2.0 client with "s6BhdRkqt3" as its 712 identifier. 714 { 715 "aud":"https://consumer.example.com", 716 "iss":"https://issuer.example.com", 717 "exp":1443904177, 718 "sub":"user@example.com", 719 "cid":"s6BhdRkqt3" 720 } 722 Figure 8: Client Identifier Claim 724 OAuth 2.0 Token Introspection [RFC7662] defines the "client_id" 725 parameter as the client identifier for the OAuth 2.0 client that 726 requested the token. 728 4.4. "may_act" (May Act For) Claim 730 The "may_act" claim makes a statement that one party is authorized to 731 become the actor and act on behalf of another party. The claim value 732 is a JSON object and members in the JSON object are claims that 733 identify the party that is asserted as being eligible to act for the 734 party identified by the JWT containing the claim. The claims that 735 make up the "may_act" claim identify and possibly provide additional 736 information about the authorized actor. For example, the combination 737 of the two claims "iss" and "sub" are sometimes necessary to uniquely 738 identify an authorized actor, while the "email" claim might be used 739 to provide additional useful information about that party. 741 However, claims within the "may_act" claim pertain only to the 742 identity of that party and are not relevant to the validity of the 743 containing JWT in the same manner as top level claims. Consequently, 744 claims such as "exp", "nbf", and "aud" are not meaningful when used 745 within a "may_act" claim, and therefore should not be used. 747 The following example illustrates the "may_act" claim within a JWT 748 Claims Set. The claims of the token itself are about 749 user@example.com while the "may_act" claim indicates that 750 admin@example.com is authorized to act on behalf of user@example.com. 752 { 753 "aud":"https://consumer.example.com", 754 "iss":"https://issuer.example.com", 755 "exp":1443904177, 756 "nbf":1443904077, 757 "sub":"user@example.com", 758 "may_act": 759 { 760 "sub":"admin@example.com" 761 } 762 } 764 Figure 9: May Act For Claim 766 When included as a top-level member of an OAuth token introspection 767 response, "may_act" has the same semantics and format as the the 768 claim of the same name. 770 5. IANA Considerations 772 5.1. OAuth URI Registration 774 This specification registers the following values in the IANA "OAuth 775 URI" registry [IANA.OAuth.Parameters] established by [RFC6755]. 777 5.1.1. Registry Contents 779 o URN: urn:ietf:params:oauth:grant-type:token-exchange 780 o Common Name: Token exchange grant type for OAuth 2.0 781 o Change controller: IESG 782 o Specification Document: Section 2.1 of [[ this specification ]] 783 o URN: urn:ietf:params:oauth:token-type:access_token 784 o Common Name: Token type URI for an OAuth 2.0 access token 785 o Change controller: IESG 786 o Specification Document: Section 3 of [[this specification]] 788 o URN: urn:ietf:params:oauth:token-type:refresh_token 789 o Common Name: Token Type URI for an OAuth 2.0 refresh token 790 o Change controller: IESG 791 o Specification Document: Section 3 of [[this specification]] 793 o URN: urn:ietf:params:oauth:token-type:id_token 794 o Common Name: Token Type URI for an ID Token 795 o Change controller: IESG 796 o Specification Document: Section 3 of [[this specification]] 798 5.2. OAuth Parameters Registration 800 This specification registers the following values in the IANA "OAuth 801 Parameters" registry [IANA.OAuth.Parameters] established by 802 [RFC6749]. 804 5.2.1. Registry Contents 806 o Parameter name: resource 807 o Parameter usage location: token request 808 o Change controller: IESG 809 o Specification document(s): Section 2.1 of [[ this specification ]] 811 o Parameter name: audience 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: requested_token_type 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: subject_token 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_type 827 o Parameter usage location: token request 828 o Change controller: IESG 829 o Specification document(s): Section 2.1 of [[ this specification ]] 830 o Parameter name: actor_token 831 o Parameter usage location: token request 832 o Change controller: IESG 833 o Specification document(s): Section 2.1 of [[ this specification ]] 835 o Parameter name: actor_token_type 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: issued_token_type 841 o Parameter usage location: token response 842 o Change controller: IESG 843 o Specification document(s): Section 2.2.1 of [[ this specification 844 ]] 846 5.3. OAuth Access Token Type Registration 848 This specification registers the following access token type in the 849 IANA "OAuth Access Token Types" registry [IANA.OAuth.Parameters] 850 established by [RFC6749]. 852 5.3.1. Registry Contents 854 o Type name: N_A 855 o Additional Token Endpoint Response Parameters: (none) 856 o HTTP Authentication Scheme(s): (none) 857 o Change controller: IESG 858 o Specification document(s): Section 2.2.1 of [[ this specification 859 ]] 861 5.4. JSON Web Token Claims Registration 863 This specification registers the following Claims in the IANA "JSON 864 Web Token Claims" registry [IANA.JWT.Claims] established by [JWT]. 866 5.4.1. Registry Contents 868 o Claim Name: "act" 869 o Claim Description: Actor 870 o Change Controller: IESG 871 o Specification Document(s): Section 4.1 of [[ this specification ]] 873 o Claim Name: "scp" 874 o Claim Description: Scope Values 875 o Change Controller: IESG 876 o Specification Document(s): Section 4.2 of [[ this specification ]] 877 o Claim Name: "cid" 878 o Claim Description: Client Identifier 879 o Change Controller: IESG 880 o Specification Document(s): Section 4.3 of [[ this specification ]] 882 o Claim Name: "may_act" 883 o Claim Description: May Act For 884 o Change Controller: IESG 885 o Specification Document(s): Section 4.4 of [[ this specification ]] 887 5.5. OAuth Token Introspection Response Registration 889 This specification registers the following values in the IANA "OAuth 890 Token Introspection Response" registry [IANA.OAuth.Parameters] 891 established by [RFC7662]. 893 5.5.1. Registry Contents 895 o Claim Name: "act" 896 o Claim Description: Actor 897 o Change Controller: IESG 898 o Specification Document(s): Section 4.1 of [[ this specification ]] 900 o Claim Name: "may_act" 901 o Claim Description: May Act For 902 o Change Controller: IESG 903 o Specification Document(s): Section 4.4 of [[ this specification ]] 905 5.6. OAuth Extensions Error Registration 907 This specification registers the following values in the IANA "OAuth 908 Extensions Error" registry [IANA.OAuth.Parameters] established by 909 [RFC6749]. 911 5.6.1. Registry Contents 913 o Error Name: "invalid_target" 914 o Error Usage Location: token error response 915 o Related Protocol Extension: OAuth 2.0 Token Exchange 916 o Change Controller: IETF 917 o Specification Document(s): Section 2.2.2 of [[ this specification 918 ]] 920 6. Security Considerations 922 All of the normal security issues that are discussed in [JWT], 923 especially in relationship to comparing URIs and dealing with 924 unrecognized values, also apply here. 926 In addition, both delegation and impersonation introduce unique 927 security issues. Any time one principal is delegated the rights of 928 another principal, the potential for abuse is a concern. The use of 929 the "scp" claim is suggested to mitigate potential for such abuse, as 930 it restricts the contexts in which the delegated rights can be 931 exercised. 933 7. References 935 7.1. Normative References 937 [IANA.JWT.Claims] 938 IANA, "JSON Web Token Claims", 939 . 941 [IANA.OAuth.Parameters] 942 IANA, "OAuth Parameters", 943 . 945 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 946 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 947 . 949 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 950 Requirement Levels", BCP 14, RFC 2119, 951 DOI 10.17487/RFC2119, March 1997, 952 . 954 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 955 Resource Identifier (URI): Generic Syntax", STD 66, 956 RFC 3986, DOI 10.17487/RFC3986, January 2005, 957 . 959 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 960 RFC 6749, DOI 10.17487/RFC6749, October 2012, 961 . 963 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 964 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 965 2014, . 967 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 968 RFC 7662, DOI 10.17487/RFC7662, October 2015, 969 . 971 7.2. Informative References 973 [OASIS.saml-core-2.0-os] 974 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 975 "Assertions and Protocol for the OASIS Security Assertion 976 Markup Language (SAML) V2.0", OASIS Standard saml-core- 977 2.0-os, March 2005. 979 [OpenID.Core] 980 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 981 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 982 . 984 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 985 Framework: Bearer Token Usage", RFC 6750, 986 DOI 10.17487/RFC6750, October 2012, 987 . 989 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 990 for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, 991 . 993 [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 994 "Assertion Framework for OAuth 2.0 Client Authentication 995 and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, 996 May 2015, . 998 [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 999 (JWT) Profile for OAuth 2.0 Client Authentication and 1000 Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 1001 2015, . 1003 [WS-Trust] 1004 Nadalin, A., Goodner, M., Gudgin, M., Barbir, A., and H. 1005 Granqvist, "WS-Trust 1.4", February 2012, 1006 . 1009 Appendix A. Additional Token Exchange Examples 1011 Two example token exchanges are provided in the following sections 1012 illustrating impersonation and delegation, respectively (with extra 1013 line breaks and indentation for display purposes only). 1015 A.1. Impersonation Token Exchange Example 1017 A.1.1. Token Exchange Request 1019 In the following token exchange request, a client is requesting a 1020 token with impersonation semantics. The client tells the 1021 authorization server that it needs a token for use at the target 1022 service with the logical name "urn:example:cooperation-context". 1024 POST /as/token.oauth2 HTTP/1.1 1025 Host: as.example.com 1026 Content-Type: application/x-www-form-urlencoded 1028 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 1029 &audience=urn%3Aexample%3Acooperation-context 1030 &subject_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwc 1031 zovL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXI 1032 uZXhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTA2MDAsIm5iZiI6MTQ0MTkwOTAwMCwic 1033 3ViIjoiYmNAZXhhbXBsZS5uZXQiLCJzY3AiOlsib3JkZXJzIiwicHJvZmlsZSIsImh 1034 pc3RvcnkiXX0.JDe7fZ267iIRXwbFmOugyCt5dmGoy6EeuzNQ3MqDek5cCUlyPhQC6 1035 cz9laKjK1bnjMQbLJqWix6ZdBI0isjsTA 1036 &subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1038 Figure 10: Token Exchange Request 1040 A.1.2. Subject Token Claims 1042 The "subject_token" in the prior request is a JWT and the decoded JWT 1043 Claims Set is shown here. The JWT is intended for consumption by the 1044 authorization server within a specific time window. The subject of 1045 the JWT ("bc@example.net") is the party on behalf of whom the new 1046 token is being requested. 1048 { 1049 "aud":"https://as.example.com", 1050 "iss":"https://original-issuer.example.net", 1051 "exp":1441910600, 1052 "nbf":1441909000, 1053 "sub":"bc@example.net", 1054 "scp":["orders","profile","history"] 1055 } 1057 Figure 11: Subject Token Claims 1059 A.1.3. Token Exchange Response 1061 The "access_token" parameter of the token exchange response shown 1062 below contains the new token that the client requested. The other 1063 parameters of the response indicate that the token is a bearer access 1064 token that expires in an hour. 1066 HTTP/1.1 200 OK 1067 Content-Type: application/json 1068 Cache-Control: no-cache, no-store 1070 { 1071 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm4 1072 6ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5l 1073 eGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic3ViIjoiYmNAZXhhbXBsZS5uZ 1074 XQiLCJzY3AiOlsib3JkZXJzIiwiaGlzdG9yeSIsInByb2ZpbGUiXX0.YQHuLmI1YD 1075 TugbfEvgGY2gaGBmMyj9BepZSECCBE9j9ogqZv2qx6VQQPrbT1k7vBYGLNMOkkpmm 1076 JkxZDS0YV7g", 1077 "issued_token_type": 1078 "urn:ietf:params:oauth:token-type:access_token", 1079 "token_type":"Bearer", 1080 "expires_in":3600 1081 } 1083 Figure 12: Token Exchange Response 1085 A.1.4. Issued Token Claims 1087 The decoded JWT Claims Set of the issued token is shown below. The 1088 new JWT is issued by the authorization server and intended for 1089 consumption by a system entity known by the logical name 1090 "urn:example:cooperation-context" any time before its expiration. 1091 The subject ("sub") of the JWT is the same as the subject the token 1092 used to make the request, which effectively enables the client to 1093 impersonate that subject at the system entity known by the logical 1094 name of "urn:example:cooperation-context" by using the token. 1096 { 1097 "aud":"urn:example:cooperation-context", 1098 "iss":"https://as.example.com", 1099 "exp":1441913610, 1100 "sub":"bc@example.net", 1101 "scp":["orders","history","profile"] 1102 } 1104 Figure 13: Issued Token Claims 1106 A.2. Delegation Token Exchange Example 1108 A.2.1. Token Exchange Request 1110 In the following token exchange request, a client is requesting a 1111 token and providing both a "subject_token" and an "actor_token". The 1112 client tells the authorization server that it needs a token for use 1113 at the target service with the logical name "urn:example:cooperation- 1114 context". Policy at the authorization server dictates that the 1115 issued token be a composite. 1117 POST /as/token.oauth2 HTTP/1.1 1118 Host: as.example.com 1119 Content-Type: application/x-www-form-urlencoded 1121 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 1122 &audience=urn%3Aexample%3Acooperation-context 1123 &subject_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwc 1124 zovL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXI 1125 uZXhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTAwNjAsInNjcCI6WyJzdGF0dXMiLCJmZ 1126 WVkIl0sInN1YiI6InVzZXJAZXhhbXBsZS5uZXQiLCJtYXlfYWN0Ijp7InN1YiI6ImF 1127 kbWluQGV4YW1wbGUubmV0In19.ut0Ll7wm920VzRvuLGLFoPJLeO5DDElxsax1L_xK 1128 Um2eooiNSfuif-OGa2382hPyFYnddKIa0wmDhQksW018Rw 1129 &subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1130 &actor_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwczo 1131 vL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXIuZ 1132 XhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTAwNjAsInN1YiI6ImFkbWluQGV4YW1wbGU 1133 ubmV0In0.7YQ-3zPfhUvzje5oqw8COCvN5uP6NsKik9CVV6cAOf4QKgM-tKfiOwcgZ 1134 oUuDL2tEs6tqPlcBlMjiSzEjm3yBg 1135 &actor_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1137 Figure 14: Token Exchange Request 1139 A.2.2. Subject Token Claims 1141 The "subject_token" in the prior request is a JWT and the decoded JWT 1142 Claims Set is shown here. The JWT is intended for consumption by the 1143 authorization server before a specific expiration time. The subject 1144 of the JWT ("user@example.net") is the party on behalf of whom the 1145 new token is being requested. 1147 { 1148 "aud":"https://as.example.com", 1149 "iss":"https://original-issuer.example.net", 1150 "exp":1441910060, 1151 "scp":["status","feed"], 1152 "sub":"user@example.net", 1153 "may_act": 1154 { 1155 "sub":"admin@example.net" 1156 } 1157 } 1159 Figure 15: Subject Token Claims 1161 A.2.3. Actor Token Claims 1163 The "actor_token" in the prior request is a JWT and the decoded JWT 1164 Claims Set is shown here. This JWT is also intended for consumption 1165 by the authorization server before a specific expiration time. The 1166 subject of the JWT ("admin@example.net") is the actor that will wield 1167 the security token being requested. 1169 { 1170 "aud":"https://as.example.com", 1171 "iss":"https://original-issuer.example.net", 1172 "exp":1441910060, 1173 "sub":"admin@example.net" 1174 } 1176 Figure 16: Actor Token Claims 1178 A.2.4. Token Exchange Response 1180 The "access_token" parameter of the token exchange response shown 1181 below contains the new token that the client requested. The other 1182 parameters of the response indicate that the token is a JWT that 1183 expires in an hour and that the access token type is not applicable 1184 since the issued token is not an access token. 1186 HTTP/1.1 200 OK 1187 Content-Type: application/json 1188 Cache-Control: no-cache, no-store 1190 { 1191 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm4 1192 6ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5l 1193 eGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic2NwIjpbInN0YXR1cyIsImZlZ 1194 WQiXSwic3ViIjoidXNlckBleGFtcGxlLm5ldCIsImFjdCI6eyJzdWIiOiJhZG1pbk 1195 BleGFtcGxlLm5ldCJ9fQ._qjM7Ij_HcrC78omT4jiZTFJOuzsAj1wPo31ymQS-Suq 1196 r64S1jCp6pfQR-in_OOAosAGamEg4jyPsht6kMAiYA", 1197 "issued_token_type":"urn:ietf:params:oauth:token-type:jwt", 1198 "token_type":"N_A", 1199 "expires_in":3600 1200 } 1202 Figure 17: Token Exchange Response 1204 A.2.5. Issued Token Claims 1206 The decoded JWT Claims Set of the issued token is shown below. The 1207 new JWT is issued by the authorization server and intended for 1208 consumption by a system entity known by the logical name 1209 "urn:example:cooperation-context" any time before its expiration. 1210 The subject ("sub") of the JWT is the same as the subject of the 1211 "subject_token" used to make the request. The actor ("act") of the 1212 JWT is the same as the subject of the "actor_token" used to make the 1213 request. This indicates delegation and identifies 1214 "admin@example.net" as the current actor to whom authority has been 1215 delegated to act on behalf of "user@example.net". 1217 { 1218 "aud":"urn:example:cooperation-context", 1219 "iss":"https://as.example.com", 1220 "exp":1441913610, 1221 "scp":["status","feed"], 1222 "sub":"user@example.net", 1223 "act": 1224 { 1225 "sub":"admin@example.net" 1226 } 1227 } 1229 Figure 18: Issued Token Claims 1231 Appendix B. Acknowledgements 1233 This specification was developed within the OAuth Working Group, 1234 which includes dozens of active and dedicated participants. It was 1235 produced under the chairmanship of Hannes Tschofenig and Derek Atkins 1236 with Kathleen Moriarty and Stephen Farrell serving as Security Area 1237 Directors. The following individuals contributed ideas, feedback, 1238 and wording to this specification: 1240 Caleb Baker, Vittorio Bertocci, Thomas Broyer, William Denniss, 1241 Vladimir Dzhuvinov, Phil Hunt, Benjamin Kaduk, Jason Keglovitz, 1242 Torsten Lodderstedt, Adam Lewis, James Manger, Nov Matake, Matt 1243 Miller, Matthew Perry, Justin Richer, Rifaat Shekh-Yusef, Scott 1244 Tomilson, and Hannes Tschofenig. 1246 Appendix C. Document History 1248 [[ to be removed by the RFC Editor before publication as an RFC ]] 1250 -07 1252 o Fixed typo (desecration -> discretion). 1253 o Added an explanation of the relationship between scope, audience 1254 and resource in the request and added an "invalid_target" error 1255 code enabling the AS to tell the client that the requested 1256 audiences/resources were too broad. 1258 -06 1260 o Drop "An STS for the REST of Us" from the title. 1261 o Drop "heavyweight" and "lightweight" from the abstract and 1262 introduction. 1263 o Clarifications on the language around xxxxxx_token_type. 1264 o Remove the want_composite parameter. 1265 o Add a short mention of proof-of-possession style tokens to the 1266 introduction and remove the respective open issue. 1268 -05 1270 o Defined the JWT claim "cid" to express the OAuth 2.0 client 1271 identifier of the client that requested the token. 1272 o Defined and requested registration for "act" and "may_act" as 1273 Token introspection response parameters (in addition to being JWT 1274 claims). 1275 o Loosen up the language about refresh_token in the response to 1276 OPTIONAL from NOT RECOMMENDED based on feedback form real world 1277 deployment experience. 1279 o Add clarifying text about the distinction between JWT and access 1280 token URIs. 1281 o Close out (remove) some of the Open Issues bullets that have been 1282 resolved. 1284 -04 1286 o Clarified that the "resource" and "audience" request parameters 1287 can be used at the same time (via http://www.ietf.org/mail- 1288 archive/web/oauth/current/msg15335.html). 1289 o Clarified subject/actor token validity after token exchange and 1290 explained a bit more about the recommendation to not issue refresh 1291 tokens (via http://www.ietf.org/mail-archive/web/oauth/current/ 1292 msg15318.html). 1293 o Updated the examples appendix to use an issuer value that doesn't 1294 imply that the client issued and signed the tokens and used 1295 "Bearer" and "urn:ietf:params:oauth:token-type:access_token" in 1296 one of the responses (via http://www.ietf.org/mail- 1297 archive/web/oauth/current/msg15335.html). 1298 o Defined and registered urn:ietf:params:oauth:token-type:id_token, 1299 since some use cases perform token exchanges for ID Tokens and no 1300 URI to indicate that a token is an ID Token had previously been 1301 defined. 1303 -03 1305 o Updated the document editors (adding Campbell, Bradley, and 1306 Mortimore). 1307 o Added to the title. 1308 o Added to the abstract and introduction. 1309 o Updated the format of the request to use application/x-www-form- 1310 urlencoded request parameters and the response to use the existing 1311 token endpoint JSON parameters defined in OAuth 2.0. 1312 o Changed the grant type identifier to urn:ietf:params:oauth:grant- 1313 type:token-exchange. 1314 o Added RFC 6755 registration requests for 1315 urn:ietf:params:oauth:token-type:refresh_token, 1316 urn:ietf:params:oauth:token-type:access_token, and 1317 urn:ietf:params:oauth:grant-type:token-exchange. 1318 o Added RFC 6749 registration requests for request/response 1319 parameters. 1320 o Removed the Implementation Considerations and the requirement to 1321 support JWTs. 1322 o Clarified many aspects of the text. 1323 o Changed "on_behalf_of" to "subject_token", 1324 "on_behalf_of_token_type" to "subject_token_type", "act_as" to 1325 "actor_token", and "act_as_token_type" to "actor_token_type". 1327 o Added an "audience" request parameter used to indicate the logical 1328 names of the target services at which the client intends to use 1329 the requested security token. 1330 o Added a "want_composite" request parameter used to indicate the 1331 desire for a composite token rather than trying to infer it from 1332 the presence/absence of token(s) in the request. 1333 o Added a "resource" request parameter used to indicate the URLs of 1334 resources at which the client intends to use the requested 1335 security token. 1336 o Specified that multiple "audience" and "resource" request 1337 parameter values may be used. 1338 o Defined the JWT claim "act" (actor) to express the current actor 1339 or delegation principal. 1340 o Defined the JWT claim "may_act" to express that one party is 1341 authorized to act on behalf of another party. 1342 o Defined the JWT claim "scp" (scopes) to express OAuth 2.0 scope- 1343 token values. 1344 o Added the "N_A" (not applicable) OAuth Access Token Type 1345 definition for use in contexts in which the token exchange syntax 1346 requires a "token_type" value, but in which the token being issued 1347 is not an access token. 1348 o Added examples. 1350 -02 1352 o Enabled use of Security Token types other than JWTs for "act_as" 1353 and "on_behalf_of" request values. 1354 o Referenced the JWT and OAuth Assertions RFCs. 1356 -01 1358 o Updated references. 1360 -00 1362 o Created initial working group draft from draft-jones-oauth-token- 1363 exchange-01. 1365 Authors' Addresses 1367 Michael B. Jones 1368 Microsoft 1370 Email: mbj@microsoft.com 1371 URI: http://self-issued.info/ 1372 Anthony Nadalin 1373 Microsoft 1375 Email: tonynad@microsoft.com 1377 Brian Campbell 1378 Ping Identity 1380 Email: brian.d.campbell@gmail.com 1382 John Bradley 1383 Ping Identity 1385 Email: ve7jtb@ve7jtb.com 1387 Chuck Mortimore 1388 Salesforce 1390 Email: cmortimore@salesforce.com