idnits 2.17.1 draft-ietf-oauth-token-exchange-08.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 (June 2, 2017) is 2513 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: December 4, 2017 B. Campbell, Ed. 6 J. Bradley 7 Ping Identity 8 C. Mortimore 9 Salesforce 10 June 2, 2017 12 OAuth 2.0 Token Exchange 13 draft-ietf-oauth-token-exchange-08 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 December 4, 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 . . . . . . . . . . . . . . . . . . . . . . . 31 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 acting party. Typically this will be the party that is authorized 332 to use the requested security token and act on behalf of the 333 subject. 335 actor_token_type 336 An identifier, as described in Section 3, that indicates the type 337 of the security token in the "actor_token" parameter. This is 338 REQUIRED when the "actor_token" parameter is present in the 339 request but MUST NOT be included otherwise. 341 In the absence of one-time-use or other semantics specific to the 342 token type, the act of performing a token exchange has no impact on 343 the validity of the subject token or actor token. 345 2.1.1. Relationship Between Resource, Audience and Scope 347 When requesting a token, the client can indicate the desired target 348 service(s) where it intends to use that token by way of the 349 "audience" and "resource" parameters, as well as indicating the 350 desired scope of the requested token using the "scope" parameter. 351 The semantics of such a request are that the client is asking for a 352 token with the requested scope that is usable at all the requested 353 target services. Effectively, the requested access rights of the 354 token are the cartesian product of all the scopes at all the target 355 services. 357 An authorization server may be unwilling or unable to fulfill any 358 token request but the likelihood of an unfulfillable request is 359 significantly higher when very broad access rights are being 360 solicited. As such, in the absence of specific knowledge about the 361 relationship of systems in a deployment, clients should exercise 362 discretion in the breadth of the access requested, particularly the 363 number of target services. An authorization server can use the 364 "invalid_target" error code, defined in Section 2.2.2, to inform a 365 client that it requested access to too many target services 366 simultaneously. 368 2.2. Response 370 The authorization server responds to a token exchange request with a 371 normal OAuth 2.0 response from the token endpoint, as specified in 372 Section 5 of [RFC6749]. Additional details and explanation are 373 provided in the following subsections. 375 2.2.1. Successful Response 377 If the request is valid and meets all policy and other criteria of 378 the authorization server, a successful token response is constructed 379 by adding the following parameters to the entity-body of the HTTP 380 response using the "application/json" media type, as specified by 381 [RFC7159], and an HTTP 200 status code. The parameters are 382 serialized into a JavaScript Object Notation (JSON) structure by 383 adding each parameter at the top level. Parameter names and string 384 values are included as JSON strings. Numerical values are included 385 as JSON numbers. The order of parameters does not matter and can 386 vary. 388 access_token 389 REQUIRED. The security token issued by the authorization server 390 in response to the token exchange request. The "access_token" 391 parameter from Section 5.1 of [RFC6749] is used here to carry the 392 requested token, which allows this token exchange protocol to use 393 the existing OAuth 2.0 request and response constructs defined for 394 the token endpoint. The identifier "access_token" is used for 395 historical reasons and the issued token need not be an OAuth 396 access token. 398 issued_token_type 399 REQUIRED. An identifier, as described in Section 3, for the 400 representation of the issued security token. 402 token_type 403 REQUIRED. A case-insensitive value specifying the method of using 404 of the access token issued, as specified in Section 7.1 of 405 [RFC6749]. It provides the client with information about how to 406 utilize the access token to access protected resources. For 407 example, a value of "Bearer", as specified in [RFC6750], indicates 408 that the security token is a bearer token and the client can 409 simply present it as is without any additional proof of 410 eligibility beyond the contents of the token itself. Note that 411 the meaning of this parameter is different from the meaning of the 412 "issued_token_type" parameter, which declares the representation 413 of the issued security token; the term "token type" is typically 414 used with this meaning, as it is in all "*_token_type" parameters 415 in this specification. If the issued token is not an access token 416 or usable as an access token, then the "token_type" value "N_A" is 417 used to indicate that an OAuth 2.0 "token_type" identifier is not 418 applicable in that context. 420 expires_in 421 RECOMMENDED. The validity lifetime, in seconds, of the token 422 issued by the authorization server. Oftentimes the client will 423 not have the inclination or capability to inspect the content of 424 the token and this parameter provides a consistent and token type 425 agnostic indication of how long the token can be expected to be 426 valid. For example, the value 1800 denotes that the token will 427 expire in thirty minutes from the time the response was generated. 429 scope 430 OPTIONAL, if the scope of the issued security token is identical 431 to the scope requested by the client; otherwise, REQUIRED. 433 refresh_token 434 OPTIONAL. A refresh token will typically not be issued when the 435 the exchange is of one temporary credential (the subject_token) 436 for a different temporary credential (the issued token) for use in 437 some other context. A refresh token can be issued in cases where 438 the client of the token exchange needs the ability to access a 439 resource even when the original credential is no longer valid 440 (e.g. user-not-present or offline scenarios where there is no 441 longer any user entertaining an active session with the client). 442 Profiles or deployments of this specification should clearly 443 document the conditions under which a client should expect a 444 refresh token in response to "urn:ietf:params:oauth:grant- 445 type:token-exchange" grant type requests. 447 2.2.2. Error Response 449 If either the "subject_token" or "actor_token" are invalid for any 450 reason, or are unacceptable based on policy, the authorization server 451 MUST construct an error response, as specified in Section 5.2 of 452 [RFC6749]. The value of the "error" parameter MUST be the 453 "invalid_request" error code. 455 If the authorization server is unwilling or unable to issue a token 456 for all the target services indicated by the "resource" or "audience" 457 parameters, the "invalid_target" error code MAY be used in the error 458 response. 460 The authorization server MAY include additional information regarding 461 the reasons for the error using the "error_description" and/or 462 "error_uri" parameters. 464 Other error codes may also be used, as appropriate. 466 2.3. Example Token Exchange 468 The following example demonstrates a hypothetical token exchange in 469 which an OAuth resource server assumes the role of the client during 470 token exchange in order to trade an access token that it received in 471 a protected resource request for a token that it will use to call to 472 a backend service (extra line breaks and indentation in the examples 473 are for display purposes only). 475 The resource server receives the following request containing an 476 OAuth access token in the Authorization request header, as specified 477 in Section 2.1 of [RFC6750]. 479 GET /resource HTTP/1.1 480 Host: frontend.example.com 481 Authorization: Bearer accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC 483 Figure 1: Protected Resource Request 485 The resource server assumes the role of the client for the token 486 exchange and the access token from the request above is sent to the 487 authorization server using a request as specified in Section 2.1. 488 The value of the "subject_token" parameter carries the access token 489 and the value of the "subject_token_type" parameter indicates that it 490 is an OAuth 2.0 access token. The resource server, acting in the 491 roll of the client, uses its identifier and secret to authenticate to 492 the authorization server using the HTTP Basic authentication scheme. 493 The "resource" parameter indicates the location of the backend 494 service, https://backend.example.com/api, where the issued token will 495 be used. 497 POST /as/token.oauth2 HTTP/1.1 498 Host: as.example.com 499 Authorization: Basic cnMwODpsb25nLXNlY3VyZS1yYW5kb20tc2VjcmV0 500 Content-Type: application/x-www-form-urlencoded 502 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 503 &resource=https%3A%2F%2Fbackend.example.com%2Fapi%20 504 &subject_token=accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC 505 &subject_token_type= 506 urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token 508 Figure 2: Token Exchange Request 510 The authorization server validates the client credentials and the 511 "subject_token" presented in the token exchange request. From the 512 "resource" parameter, the authorization server is able to determine 513 the appropriate policy to apply to the request and issues a token 514 suitable for use at https://backend.example.com. The "access_token" 515 parameter of the response contains the new token, which is itself a 516 bearer OAuth access token that is valid for one minute. The token 517 happens to be a JWT; however, its structure and format are opaque to 518 the client so the "issued_token_type" indicates only that it is an 519 access token. 521 HTTP/1.1 200 OK 522 Content-Type: application/json 523 Cache-Control: no-cache, no-store 525 { 526 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQiOiJo 527 dHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2FzLmV 528 4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1MzMsIn 529 N1YiI6ImJjQGV4YW1wbGUuY29tIiwic2NwIjpbImFwaSJdfQ.MXgnpvPMo0nhce 530 PwnQbunD2gw_pDyCFA-Saobl6gyLAdyPbaALFuAOyFc4XTWaPEnHV_LGmXklSTp 531 z0yC7hlSQ", 532 "issued_token_type": 533 "urn:ietf:params:oauth:token-type:access_token", 534 "token_type":"Bearer", 535 "expires_in":60 536 } 538 Figure 3: Token Exchange Response 540 The resource server can then use the newly acquired access token in 541 making a request to the backend server. 543 GET /api HTTP/1.1 544 Host: backend.example.com 545 Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQ 546 iOiJodHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2 547 FzLmV4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1M 548 zMsInN1YiI6ImJjQGV4YW1wbGUuY29tIiwic2NwIjpbImFwaSJdfQ.MXgnpvPMo 549 0nhcePwnQbunD2gw_pDyCFA-Saobl6gyLAdyPbaALFuAOyFc4XTWaPEnHV_LGmX 550 klSTpz0yC7hlSQ 552 Figure 4: Backend Protected Resource Request 554 Additional examples can be found in Appendix A. 556 3. Token Type Identifiers 558 Several parameters in this specification utilize an identifier as the 559 value to describe the token in question. Specifically, they are the 560 "requested_token_type", "subject_token_type", "actor_token_type" 561 parameters of the request and the "issued_token_type" member of the 562 response. Token type identifiers are URIs. Token Exchange can work 563 with both tokens issued by other parties and tokens from the given 564 authorization server. For the former the token type identifier 565 indicates the syntax (e.g. JWT or SAML) so the AS can parse it; for 566 the latter it indicates what the AS issued it for (e.g. access_token 567 or refresh_token). 569 This specification defines the token type identifiers 570 "urn:ietf:params:oauth:token-type:access_token" and 571 "urn:ietf:params:oauth:token-type:refresh_token" to indicate that the 572 token is an OAuth 2.0 access token or refresh token, respectively. 573 The value "urn:ietf:params:oauth:token-type:jwt" defined in Section 9 574 of [JWT] indicates that the token is a JWT. This specification also 575 defines the token type identifier "urn:ietf:params:oauth:token- 576 type:id_token" to indicate that the token is an ID Token, as defined 577 in Section 2 of [OpenID.Core]. Other URIs to indicate other token 578 types MAY be used. 580 The distinction between an access token and a JWT is subtle. An 581 access token represents a delegated authorization decision, whereas 582 JWT is a token format. An access token can be formatted as a JWT but 583 doesn't necessarily have to be. And a JWT might well be an access 584 token but not all JWTs are access tokens. The intent of this 585 specification is that "urn:ietf:params:oauth:token-type:access_token" 586 be an indicator that the token is a typical OAuth access token issued 587 by the authorization server in question, opaque to the client, and 588 usable the same manner as any other access token obtained from that 589 authorization server (it could well be a JWT but the client isn't and 590 needn't be aware of that fact). Whereas 591 "urn:ietf:params:oauth:token-type:jwt" is to indicate specifically 592 that a JWT is being requested or sent (perhaps in a cross-domain use- 593 case where the JWT is used as an authorization grant to obtain an 594 access token from a different authorization server as is facilitated 595 by [RFC7523]). 597 4. JSON Web Token Claims and Introspection Response Parameters 599 It is useful to have defined mechanisms to express delegation within 600 a token as well as to express authorization to delegate or 601 impersonate. Although the token exchange protocol described herein 602 can be used with any type of token, this section defines claims to 603 express such semantics specifically for JWTs and in an OAuth 2.0 604 Token Introspection [RFC7662] response. Similar definitions for 605 other types of tokens are possible but beyond the scope of this 606 specification. 608 4.1. "act" (Actor) Claim 610 The "act" (actor) claim provides a means within a JWT to express that 611 delegation has occurred and identify the acting party to whom 612 authority has been delegated. The "act" claim value is a JSON object 613 and members in the JSON object are claims that identify the actor. 614 The claims that make up the "act" claim identify and possibly provide 615 additional information about the actor. For example, the combination 616 of the two claims "iss" and "sub" might be necessary to uniquely 617 identify an actor. 619 However, claims within the "act" claim pertain only to the identity 620 of the actor and are not relevant to the validity of the containing 621 JWT in the same manner as the top-level claims. Consequently, claims 622 such as "exp", "nbf", and "aud" are not meaningful when used within 623 an "act" claim, and therefore should not be used. 625 The following example illustrates the "act" (actor) claim within a 626 JWT Claims Set. The claims of the token itself are about 627 user@example.com while the "act" claim indicates that 628 admin@example.com is the current actor. 630 { 631 "aud":"https://consumer.example.com", 632 "iss":"https://issuer.example.com", 633 "exp":1443904177, 634 "nbf":1443904077, 635 "sub":"user@example.com", 636 "act": 637 { 638 "sub":"admin@example.com" 639 } 640 } 642 Figure 5: Actor Claim 644 A chain of delegation can be expressed by nesting one "act" claim 645 within another. The outermost "act" claim represents the current 646 actor while nested "act" claims represent prior actors. The least 647 recent actor is the most deeply nested. 649 The following example illustrates nested "act" (actor) claims within 650 a JWT Claims Set. The claims of the token itself are about 651 user@example.com while the "act" claim indicates that the system 652 consumer.example.com-web-application is the current actor and 653 admin@example.com was a prior actor. Such a token might come about 654 as the result of the web application receiving a token like the one 655 in the previous example and exchanging it for a new token that lists 656 it as the current actor and that can be used at 657 https://backend.example.com. 659 { 660 "aud":"https://backend.example.com", 661 "iss":"https://issuer.example.com", 662 "exp":1443904100, 663 "nbf":1443904000, 664 "sub":"user@example.com", 665 "act": 666 { 667 "sub":"consumer.example.com-web-application", 668 "iss":"https://issuer.example.net", 669 "act": 670 { 671 "sub":"admin@example.com" 672 } 673 } 674 } 676 Figure 6: Nested Actor Claim 678 When included as a top-level member of an OAuth token introspection 679 response, "act" has the same semantics and format as the the claim of 680 the same name. 682 4.2. "scp" (Scopes) Claim 684 The "scp" claim is an array of strings, each of which represents an 685 OAuth scope granted for the issued security token. Each array entry 686 of the claim value is a scope-token, as defined in Section 3.3 of 687 OAuth 2.0 [RFC6749]. 689 The following example illustrates the "scp" claim within a JWT Claims 690 Set with four scope-tokens. 692 { 693 "aud":"https://consumer.example.com", 694 "iss":"https://issuer.example.com", 695 "exp":1443904177, 696 "nbf":1443904077, 697 "sub":"dgaf4mvfs75Fci_FL3heQA", 698 "scp":["email","address","profile","phone"] 699 } 701 Figure 7: Scopes Claim 703 OAuth 2.0 Token Introspection [RFC7662] defines the "scope" parameter 704 to convey the scopes associated with the token. 706 4.3. "cid" (Client Identifier) Claim 708 The "cid" claim carries the client identifier of the OAuth 2.0 709 [RFC6749] client that requested the token. 711 The following example illustrates the "cid" claim within a JWT Claims 712 Set indicating an OAuth 2.0 client with "s6BhdRkqt3" as its 713 identifier. 715 { 716 "aud":"https://consumer.example.com", 717 "iss":"https://issuer.example.com", 718 "exp":1443904177, 719 "sub":"user@example.com", 720 "cid":"s6BhdRkqt3" 721 } 723 Figure 8: Client Identifier Claim 725 OAuth 2.0 Token Introspection [RFC7662] defines the "client_id" 726 parameter as the client identifier for the OAuth 2.0 client that 727 requested the token. 729 4.4. "may_act" (May Act For) Claim 731 The "may_act" claim makes a statement that one party is authorized to 732 become the actor and act on behalf of another party. The claim value 733 is a JSON object and members in the JSON object are claims that 734 identify the party that is asserted as being eligible to act for the 735 party identified by the JWT containing the claim. The claims that 736 make up the "may_act" claim identify and possibly provide additional 737 information about the authorized actor. For example, the combination 738 of the two claims "iss" and "sub" are sometimes necessary to uniquely 739 identify an authorized actor, while the "email" claim might be used 740 to provide additional useful information about that party. 742 However, claims within the "may_act" claim pertain only to the 743 identity of that party and are not relevant to the validity of the 744 containing JWT in the same manner as top level claims. Consequently, 745 claims such as "exp", "nbf", and "aud" are not meaningful when used 746 within a "may_act" claim, and therefore should not be used. 748 The following example illustrates the "may_act" claim within a JWT 749 Claims Set. The claims of the token itself are about 750 user@example.com while the "may_act" claim indicates that 751 admin@example.com is authorized to act on behalf of user@example.com. 753 { 754 "aud":"https://consumer.example.com", 755 "iss":"https://issuer.example.com", 756 "exp":1443904177, 757 "nbf":1443904077, 758 "sub":"user@example.com", 759 "may_act": 760 { 761 "sub":"admin@example.com" 762 } 763 } 765 Figure 9: May Act For Claim 767 When included as a top-level member of an OAuth token introspection 768 response, "may_act" has the same semantics and format as the the 769 claim of the same name. 771 5. IANA Considerations 773 5.1. OAuth URI Registration 775 This specification registers the following values in the IANA "OAuth 776 URI" registry [IANA.OAuth.Parameters] established by [RFC6755]. 778 5.1.1. Registry Contents 780 o URN: urn:ietf:params:oauth:grant-type:token-exchange 781 o Common Name: Token exchange grant type for OAuth 2.0 782 o Change controller: IESG 783 o Specification Document: Section 2.1 of [[ this specification ]] 784 o URN: urn:ietf:params:oauth:token-type:access_token 785 o Common Name: Token type URI for an OAuth 2.0 access token 786 o Change controller: IESG 787 o Specification Document: Section 3 of [[this specification]] 789 o URN: urn:ietf:params:oauth:token-type:refresh_token 790 o Common Name: Token Type URI for an OAuth 2.0 refresh token 791 o Change controller: IESG 792 o Specification Document: Section 3 of [[this specification]] 794 o URN: urn:ietf:params:oauth:token-type:id_token 795 o Common Name: Token Type URI for an ID Token 796 o Change controller: IESG 797 o Specification Document: Section 3 of [[this specification]] 799 5.2. OAuth Parameters Registration 801 This specification registers the following values in the IANA "OAuth 802 Parameters" registry [IANA.OAuth.Parameters] established by 803 [RFC6749]. 805 5.2.1. Registry Contents 807 o Parameter name: resource 808 o Parameter usage location: token request 809 o Change controller: IESG 810 o Specification document(s): Section 2.1 of [[ this specification ]] 812 o Parameter name: audience 813 o Parameter usage location: token request 814 o Change controller: IESG 815 o Specification document(s): Section 2.1 of [[ this specification ]] 817 o Parameter name: requested_token_type 818 o Parameter usage location: token request 819 o Change controller: IESG 820 o Specification document(s): Section 2.1 of [[ this specification ]] 822 o Parameter name: subject_token 823 o Parameter usage location: token request 824 o Change controller: IESG 825 o Specification document(s): Section 2.1 of [[ this specification ]] 827 o Parameter name: subject_token_type 828 o Parameter usage location: token request 829 o Change controller: IESG 830 o Specification document(s): Section 2.1 of [[ this specification ]] 831 o Parameter name: actor_token 832 o Parameter usage location: token request 833 o Change controller: IESG 834 o Specification document(s): Section 2.1 of [[ this specification ]] 836 o Parameter name: actor_token_type 837 o Parameter usage location: token request 838 o Change controller: IESG 839 o Specification document(s): Section 2.1 of [[ this specification ]] 841 o Parameter name: issued_token_type 842 o Parameter usage location: token response 843 o Change controller: IESG 844 o Specification document(s): Section 2.2.1 of [[ this specification 845 ]] 847 5.3. OAuth Access Token Type Registration 849 This specification registers the following access token type in the 850 IANA "OAuth Access Token Types" registry [IANA.OAuth.Parameters] 851 established by [RFC6749]. 853 5.3.1. Registry Contents 855 o Type name: N_A 856 o Additional Token Endpoint Response Parameters: (none) 857 o HTTP Authentication Scheme(s): (none) 858 o Change controller: IESG 859 o Specification document(s): Section 2.2.1 of [[ this specification 860 ]] 862 5.4. JSON Web Token Claims Registration 864 This specification registers the following Claims in the IANA "JSON 865 Web Token Claims" registry [IANA.JWT.Claims] established by [JWT]. 867 5.4.1. Registry Contents 869 o Claim Name: "act" 870 o Claim Description: Actor 871 o Change Controller: IESG 872 o Specification Document(s): Section 4.1 of [[ this specification ]] 874 o Claim Name: "scp" 875 o Claim Description: Scope Values 876 o Change Controller: IESG 877 o Specification Document(s): Section 4.2 of [[ this specification ]] 878 o Claim Name: "cid" 879 o Claim Description: Client Identifier 880 o Change Controller: IESG 881 o Specification Document(s): Section 4.3 of [[ this specification ]] 883 o Claim Name: "may_act" 884 o Claim Description: May Act For 885 o Change Controller: IESG 886 o Specification Document(s): Section 4.4 of [[ this specification ]] 888 5.5. OAuth Token Introspection Response Registration 890 This specification registers the following values in the IANA "OAuth 891 Token Introspection Response" registry [IANA.OAuth.Parameters] 892 established by [RFC7662]. 894 5.5.1. Registry Contents 896 o Claim Name: "act" 897 o Claim Description: Actor 898 o Change Controller: IESG 899 o Specification Document(s): Section 4.1 of [[ this specification ]] 901 o Claim Name: "may_act" 902 o Claim Description: May Act For 903 o Change Controller: IESG 904 o Specification Document(s): Section 4.4 of [[ this specification ]] 906 5.6. OAuth Extensions Error Registration 908 This specification registers the following values in the IANA "OAuth 909 Extensions Error" registry [IANA.OAuth.Parameters] established by 910 [RFC6749]. 912 5.6.1. Registry Contents 914 o Error Name: "invalid_target" 915 o Error Usage Location: token error response 916 o Related Protocol Extension: OAuth 2.0 Token Exchange 917 o Change Controller: IETF 918 o Specification Document(s): Section 2.2.2 of [[ this specification 919 ]] 921 6. Security Considerations 923 All of the normal security issues that are discussed in [JWT], 924 especially in relationship to comparing URIs and dealing with 925 unrecognized values, also apply here. 927 In addition, both delegation and impersonation introduce unique 928 security issues. Any time one principal is delegated the rights of 929 another principal, the potential for abuse is a concern. The use of 930 the "scp" claim is suggested to mitigate potential for such abuse, as 931 it restricts the contexts in which the delegated rights can be 932 exercised. 934 7. References 936 7.1. Normative References 938 [IANA.JWT.Claims] 939 IANA, "JSON Web Token Claims", 940 . 942 [IANA.OAuth.Parameters] 943 IANA, "OAuth Parameters", 944 . 946 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 947 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 948 . 950 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 951 Requirement Levels", BCP 14, RFC 2119, 952 DOI 10.17487/RFC2119, March 1997, 953 . 955 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 956 Resource Identifier (URI): Generic Syntax", STD 66, 957 RFC 3986, DOI 10.17487/RFC3986, January 2005, 958 . 960 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 961 RFC 6749, DOI 10.17487/RFC6749, October 2012, 962 . 964 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 965 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 966 2014, . 968 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 969 RFC 7662, DOI 10.17487/RFC7662, October 2015, 970 . 972 7.2. Informative References 974 [OASIS.saml-core-2.0-os] 975 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 976 "Assertions and Protocol for the OASIS Security Assertion 977 Markup Language (SAML) V2.0", OASIS Standard saml-core- 978 2.0-os, March 2005. 980 [OpenID.Core] 981 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 982 C. Mortimore, "OpenID Connect Core 1.0", August 2015, 983 . 985 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 986 Framework: Bearer Token Usage", RFC 6750, 987 DOI 10.17487/RFC6750, October 2012, 988 . 990 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 991 for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, 992 . 994 [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 995 "Assertion Framework for OAuth 2.0 Client Authentication 996 and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, 997 May 2015, . 999 [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 1000 (JWT) Profile for OAuth 2.0 Client Authentication and 1001 Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 1002 2015, . 1004 [WS-Trust] 1005 Nadalin, A., Goodner, M., Gudgin, M., Barbir, A., and H. 1006 Granqvist, "WS-Trust 1.4", February 2012, 1007 . 1010 Appendix A. Additional Token Exchange Examples 1012 Two example token exchanges are provided in the following sections 1013 illustrating impersonation and delegation, respectively (with extra 1014 line breaks and indentation for display purposes only). 1016 A.1. Impersonation Token Exchange Example 1018 A.1.1. Token Exchange Request 1020 In the following token exchange request, a client is requesting a 1021 token with impersonation semantics. The client tells the 1022 authorization server that it needs a token for use at the target 1023 service with the logical name "urn:example:cooperation-context". 1025 POST /as/token.oauth2 HTTP/1.1 1026 Host: as.example.com 1027 Content-Type: application/x-www-form-urlencoded 1029 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 1030 &audience=urn%3Aexample%3Acooperation-context 1031 &subject_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwc 1032 zovL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXI 1033 uZXhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTA2MDAsIm5iZiI6MTQ0MTkwOTAwMCwic 1034 3ViIjoiYmNAZXhhbXBsZS5uZXQiLCJzY3AiOlsib3JkZXJzIiwicHJvZmlsZSIsImh 1035 pc3RvcnkiXX0.JDe7fZ267iIRXwbFmOugyCt5dmGoy6EeuzNQ3MqDek5cCUlyPhQC6 1036 cz9laKjK1bnjMQbLJqWix6ZdBI0isjsTA 1037 &subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1039 Figure 10: Token Exchange Request 1041 A.1.2. Subject Token Claims 1043 The "subject_token" in the prior request is a JWT and the decoded JWT 1044 Claims Set is shown here. The JWT is intended for consumption by the 1045 authorization server within a specific time window. The subject of 1046 the JWT ("bc@example.net") is the party on behalf of whom the new 1047 token is being requested. 1049 { 1050 "aud":"https://as.example.com", 1051 "iss":"https://original-issuer.example.net", 1052 "exp":1441910600, 1053 "nbf":1441909000, 1054 "sub":"bc@example.net", 1055 "scp":["orders","profile","history"] 1056 } 1058 Figure 11: Subject Token Claims 1060 A.1.3. Token Exchange Response 1062 The "access_token" parameter of the token exchange response shown 1063 below contains the new token that the client requested. The other 1064 parameters of the response indicate that the token is a bearer access 1065 token that expires in an hour. 1067 HTTP/1.1 200 OK 1068 Content-Type: application/json 1069 Cache-Control: no-cache, no-store 1071 { 1072 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm4 1073 6ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5l 1074 eGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic3ViIjoiYmNAZXhhbXBsZS5uZ 1075 XQiLCJzY3AiOlsib3JkZXJzIiwiaGlzdG9yeSIsInByb2ZpbGUiXX0.YQHuLmI1YD 1076 TugbfEvgGY2gaGBmMyj9BepZSECCBE9j9ogqZv2qx6VQQPrbT1k7vBYGLNMOkkpmm 1077 JkxZDS0YV7g", 1078 "issued_token_type": 1079 "urn:ietf:params:oauth:token-type:access_token", 1080 "token_type":"Bearer", 1081 "expires_in":3600 1082 } 1084 Figure 12: Token Exchange Response 1086 A.1.4. Issued Token Claims 1088 The decoded JWT Claims Set of the issued token is shown below. The 1089 new JWT is issued by the authorization server and intended for 1090 consumption by a system entity known by the logical name 1091 "urn:example:cooperation-context" any time before its expiration. 1092 The subject ("sub") of the JWT is the same as the subject the token 1093 used to make the request, which effectively enables the client to 1094 impersonate that subject at the system entity known by the logical 1095 name of "urn:example:cooperation-context" by using the token. 1097 { 1098 "aud":"urn:example:cooperation-context", 1099 "iss":"https://as.example.com", 1100 "exp":1441913610, 1101 "sub":"bc@example.net", 1102 "scp":["orders","history","profile"] 1103 } 1105 Figure 13: Issued Token Claims 1107 A.2. Delegation Token Exchange Example 1109 A.2.1. Token Exchange Request 1111 In the following token exchange request, a client is requesting a 1112 token and providing both a "subject_token" and an "actor_token". The 1113 client tells the authorization server that it needs a token for use 1114 at the target service with the logical name "urn:example:cooperation- 1115 context". Policy at the authorization server dictates that the 1116 issued token be a composite. 1118 POST /as/token.oauth2 HTTP/1.1 1119 Host: as.example.com 1120 Content-Type: application/x-www-form-urlencoded 1122 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 1123 &audience=urn%3Aexample%3Acooperation-context 1124 &subject_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwc 1125 zovL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXI 1126 uZXhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTAwNjAsInNjcCI6WyJzdGF0dXMiLCJmZ 1127 WVkIl0sInN1YiI6InVzZXJAZXhhbXBsZS5uZXQiLCJtYXlfYWN0Ijp7InN1YiI6ImF 1128 kbWluQGV4YW1wbGUubmV0In19.ut0Ll7wm920VzRvuLGLFoPJLeO5DDElxsax1L_xK 1129 Um2eooiNSfuif-OGa2382hPyFYnddKIa0wmDhQksW018Rw 1130 &subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1131 &actor_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwczo 1132 vL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXIuZ 1133 XhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTAwNjAsInN1YiI6ImFkbWluQGV4YW1wbGU 1134 ubmV0In0.7YQ-3zPfhUvzje5oqw8COCvN5uP6NsKik9CVV6cAOf4QKgM-tKfiOwcgZ 1135 oUuDL2tEs6tqPlcBlMjiSzEjm3yBg 1136 &actor_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1138 Figure 14: Token Exchange Request 1140 A.2.2. Subject Token Claims 1142 The "subject_token" in the prior request is a JWT and the decoded JWT 1143 Claims Set is shown here. The JWT is intended for consumption by the 1144 authorization server before a specific expiration time. The subject 1145 of the JWT ("user@example.net") is the party on behalf of whom the 1146 new token is being requested. 1148 { 1149 "aud":"https://as.example.com", 1150 "iss":"https://original-issuer.example.net", 1151 "exp":1441910060, 1152 "scp":["status","feed"], 1153 "sub":"user@example.net", 1154 "may_act": 1155 { 1156 "sub":"admin@example.net" 1157 } 1158 } 1160 Figure 15: Subject Token Claims 1162 A.2.3. Actor Token Claims 1164 The "actor_token" in the prior request is a JWT and the decoded JWT 1165 Claims Set is shown here. This JWT is also intended for consumption 1166 by the authorization server before a specific expiration time. The 1167 subject of the JWT ("admin@example.net") is the actor that will wield 1168 the security token being requested. 1170 { 1171 "aud":"https://as.example.com", 1172 "iss":"https://original-issuer.example.net", 1173 "exp":1441910060, 1174 "sub":"admin@example.net" 1175 } 1177 Figure 16: Actor Token Claims 1179 A.2.4. Token Exchange Response 1181 The "access_token" parameter of the token exchange response shown 1182 below contains the new token that the client requested. The other 1183 parameters of the response indicate that the token is a JWT that 1184 expires in an hour and that the access token type is not applicable 1185 since the issued token is not an access token. 1187 HTTP/1.1 200 OK 1188 Content-Type: application/json 1189 Cache-Control: no-cache, no-store 1191 { 1192 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm4 1193 6ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5l 1194 eGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic2NwIjpbInN0YXR1cyIsImZlZ 1195 WQiXSwic3ViIjoidXNlckBleGFtcGxlLm5ldCIsImFjdCI6eyJzdWIiOiJhZG1pbk 1196 BleGFtcGxlLm5ldCJ9fQ._qjM7Ij_HcrC78omT4jiZTFJOuzsAj1wPo31ymQS-Suq 1197 r64S1jCp6pfQR-in_OOAosAGamEg4jyPsht6kMAiYA", 1198 "issued_token_type":"urn:ietf:params:oauth:token-type:jwt", 1199 "token_type":"N_A", 1200 "expires_in":3600 1201 } 1203 Figure 17: Token Exchange Response 1205 A.2.5. Issued Token Claims 1207 The decoded JWT Claims Set of the issued token is shown below. The 1208 new JWT is issued by the authorization server and intended for 1209 consumption by a system entity known by the logical name 1210 "urn:example:cooperation-context" any time before its expiration. 1211 The subject ("sub") of the JWT is the same as the subject of the 1212 "subject_token" used to make the request. The actor ("act") of the 1213 JWT is the same as the subject of the "actor_token" used to make the 1214 request. This indicates delegation and identifies 1215 "admin@example.net" as the current actor to whom authority has been 1216 delegated to act on behalf of "user@example.net". 1218 { 1219 "aud":"urn:example:cooperation-context", 1220 "iss":"https://as.example.com", 1221 "exp":1441913610, 1222 "scp":["status","feed"], 1223 "sub":"user@example.net", 1224 "act": 1225 { 1226 "sub":"admin@example.net" 1227 } 1228 } 1230 Figure 18: Issued Token Claims 1232 Appendix B. Acknowledgements 1234 This specification was developed within the OAuth Working Group, 1235 which includes dozens of active and dedicated participants. It was 1236 produced under the chairmanship of Hannes Tschofenig and Derek Atkins 1237 with Kathleen Moriarty and Stephen Farrell serving as Security Area 1238 Directors. The following individuals contributed ideas, feedback, 1239 and wording to this specification: 1241 Caleb Baker, Vittorio Bertocci, Thomas Broyer, William Denniss, 1242 Vladimir Dzhuvinov, Phil Hunt, Benjamin Kaduk, Jason Keglovitz, 1243 Torsten Lodderstedt, Adam Lewis, James Manger, Nov Matake, Matt 1244 Miller, Matthew Perry, Justin Richer, Rifaat Shekh-Yusef, Scott 1245 Tomilson, and Hannes Tschofenig. 1247 Appendix C. Document History 1249 [[ to be removed by the RFC Editor before publication as an RFC ]] 1251 -08 1253 o Use the bibxml reference for OpenID.Core rather than defining it 1254 inline. 1255 o Added editor role for Campbell. 1256 o Minor clarification of the text for actor_token. 1258 -07 1260 o Fixed typo (desecration -> discretion). 1261 o Added an explanation of the relationship between scope, audience 1262 and resource in the request and added an "invalid_target" error 1263 code enabling the AS to tell the client that the requested 1264 audiences/resources were too broad. 1266 -06 1268 o Drop "An STS for the REST of Us" from the title. 1269 o Drop "heavyweight" and "lightweight" from the abstract and 1270 introduction. 1271 o Clarifications on the language around xxxxxx_token_type. 1272 o Remove the want_composite parameter. 1273 o Add a short mention of proof-of-possession style tokens to the 1274 introduction and remove the respective open issue. 1276 -05 1278 o Defined the JWT claim "cid" to express the OAuth 2.0 client 1279 identifier of the client that requested the token. 1281 o Defined and requested registration for "act" and "may_act" as 1282 Token introspection response parameters (in addition to being JWT 1283 claims). 1284 o Loosen up the language about refresh_token in the response to 1285 OPTIONAL from NOT RECOMMENDED based on feedback form real world 1286 deployment experience. 1287 o Add clarifying text about the distinction between JWT and access 1288 token URIs. 1289 o Close out (remove) some of the Open Issues bullets that have been 1290 resolved. 1292 -04 1294 o Clarified that the "resource" and "audience" request parameters 1295 can be used at the same time (via http://www.ietf.org/mail- 1296 archive/web/oauth/current/msg15335.html). 1297 o Clarified subject/actor token validity after token exchange and 1298 explained a bit more about the recommendation to not issue refresh 1299 tokens (via http://www.ietf.org/mail-archive/web/oauth/current/ 1300 msg15318.html). 1301 o Updated the examples appendix to use an issuer value that doesn't 1302 imply that the client issued and signed the tokens and used 1303 "Bearer" and "urn:ietf:params:oauth:token-type:access_token" in 1304 one of the responses (via http://www.ietf.org/mail- 1305 archive/web/oauth/current/msg15335.html). 1306 o Defined and registered urn:ietf:params:oauth:token-type:id_token, 1307 since some use cases perform token exchanges for ID Tokens and no 1308 URI to indicate that a token is an ID Token had previously been 1309 defined. 1311 -03 1313 o Updated the document editors (adding Campbell, Bradley, and 1314 Mortimore). 1315 o Added to the title. 1316 o Added to the abstract and introduction. 1317 o Updated the format of the request to use application/x-www-form- 1318 urlencoded request parameters and the response to use the existing 1319 token endpoint JSON parameters defined in OAuth 2.0. 1320 o Changed the grant type identifier to urn:ietf:params:oauth:grant- 1321 type:token-exchange. 1322 o Added RFC 6755 registration requests for 1323 urn:ietf:params:oauth:token-type:refresh_token, 1324 urn:ietf:params:oauth:token-type:access_token, and 1325 urn:ietf:params:oauth:grant-type:token-exchange. 1326 o Added RFC 6749 registration requests for request/response 1327 parameters. 1329 o Removed the Implementation Considerations and the requirement to 1330 support JWTs. 1331 o Clarified many aspects of the text. 1332 o Changed "on_behalf_of" to "subject_token", 1333 "on_behalf_of_token_type" to "subject_token_type", "act_as" to 1334 "actor_token", and "act_as_token_type" to "actor_token_type". 1335 o Added an "audience" request parameter used to indicate the logical 1336 names of the target services at which the client intends to use 1337 the requested security token. 1338 o Added a "want_composite" request parameter used to indicate the 1339 desire for a composite token rather than trying to infer it from 1340 the presence/absence of token(s) in the request. 1341 o Added a "resource" request parameter used to indicate the URLs of 1342 resources at which the client intends to use the requested 1343 security token. 1344 o Specified that multiple "audience" and "resource" request 1345 parameter values may be used. 1346 o Defined the JWT claim "act" (actor) to express the current actor 1347 or delegation principal. 1348 o Defined the JWT claim "may_act" to express that one party is 1349 authorized to act on behalf of another party. 1350 o Defined the JWT claim "scp" (scopes) to express OAuth 2.0 scope- 1351 token values. 1352 o Added the "N_A" (not applicable) OAuth Access Token Type 1353 definition for use in contexts in which the token exchange syntax 1354 requires a "token_type" value, but in which the token being issued 1355 is not an access token. 1356 o Added examples. 1358 -02 1360 o Enabled use of Security Token types other than JWTs for "act_as" 1361 and "on_behalf_of" request values. 1362 o Referenced the JWT and OAuth Assertions RFCs. 1364 -01 1366 o Updated references. 1368 -00 1370 o Created initial working group draft from draft-jones-oauth-token- 1371 exchange-01. 1373 Authors' Addresses 1375 Michael B. Jones 1376 Microsoft 1378 Email: mbj@microsoft.com 1379 URI: http://self-issued.info/ 1381 Anthony Nadalin 1382 Microsoft 1384 Email: tonynad@microsoft.com 1386 Brian Campbell (editor) 1387 Ping Identity 1389 Email: brian.d.campbell@gmail.com 1391 John Bradley 1392 Ping Identity 1394 Email: ve7jtb@ve7jtb.com 1396 Chuck Mortimore 1397 Salesforce 1399 Email: cmortimore@salesforce.com