idnits 2.17.1 draft-ietf-oauth-token-exchange-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 8, 2016) is 2839 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group M. Jones 3 Internet-Draft A. Nadalin 4 Intended status: Standards Track Microsoft 5 Expires: January 9, 2017 B. Campbell 6 J. Bradley 7 Ping Identity 8 C. Mortimore 9 Salesforce 10 July 8, 2016 12 OAuth 2.0 Token Exchange: An STS for the REST of Us 13 draft-ietf-oauth-token-exchange-05 15 Abstract 17 This specification defines a protocol for a lightweight HTTP- and 18 JSON- based Security Token Service (STS) by defining how to request 19 and obtain security tokens from OAuth 2.0 authorization servers, 20 including security tokens employing impersonation and delegation. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on January 9, 2017. 39 Copyright Notice 41 Copyright (c) 2016 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.2. Response . . . . . . . . . . . . . . . . . . . . . . . . 8 63 2.2.1. Successful Response . . . . . . . . . . . . . . . . . 8 64 2.2.2. Error Response . . . . . . . . . . . . . . . . . . . 10 65 2.3. Example Token Exchange . . . . . . . . . . . . . . . . . 10 66 3. Token Type Identifiers . . . . . . . . . . . . . . . . . . . 12 67 4. JSON Web Token Claims and Introspection Response Parameters . 13 68 4.1. "act" (Actor) Claim . . . . . . . . . . . . . . . . . . . 13 69 4.2. "scp" (Scopes) Claim . . . . . . . . . . . . . . . . . . 15 70 4.3. "cid" (Client Identifier) Claim . . . . . . . . . . . . . 16 71 4.4. "may_act" (May Act For) Claim . . . . . . . . . . . . . . 16 72 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 73 5.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 17 74 5.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 17 75 5.2. OAuth Parameters Registration . . . . . . . . . . . . . . 18 76 5.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 18 77 5.3. OAuth Access Token Type Registration . . . . . . . . . . 19 78 5.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 19 79 5.4. JSON Web Token Claims Registration . . . . . . . . . . . 19 80 5.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 19 81 5.5. OAuth Token Introspection Response Registration . . . . . 20 82 5.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 20 83 6. Security Considerations . . . . . . . . . . . . . . . . . . . 20 84 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 85 7.1. Normative References . . . . . . . . . . . . . . . . . . 21 86 7.2. Informative References . . . . . . . . . . . . . . . . . 21 87 Appendix A. Additional Token Exchange Examples . . . . . . . . . 22 88 A.1. Impersonation Token Exchange Example . . . . . . . . . . 22 89 A.1.1. Token Exchange Request . . . . . . . . . . . . . . . 22 90 A.1.2. Subject Token Claims . . . . . . . . . . . . . . . . 23 91 A.1.3. Token Exchange Response . . . . . . . . . . . . . . . 23 92 A.1.4. Issued Token Claims . . . . . . . . . . . . . . . . . 24 93 A.2. Delegation Token Exchange Example . . . . . . . . . . . . 24 94 A.2.1. Token Exchange Request . . . . . . . . . . . . . . . 24 95 A.2.2. Subject Token Claims . . . . . . . . . . . . . . . . 25 96 A.2.3. Actor Token Claims . . . . . . . . . . . . . . . . . 26 97 A.2.4. Token Exchange Response . . . . . . . . . . . . . . . 26 98 A.2.5. Issued Token Claims . . . . . . . . . . . . . . . . . 26 99 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 27 100 Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . 27 101 Appendix D. Document History . . . . . . . . . . . . . . . . . . 28 102 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30 104 1. Introduction 106 A security token is a set of information that facilitates the sharing 107 of identity and security information in heterogeneous environments or 108 across security domains. Examples of security tokens include JSON 109 Web Tokens (JWTs) [JWT] and SAML Assertions [OASIS.saml-core-2.0-os]. 110 Security tokens are typically signed to achieve integrity and 111 sometimes also encrypted to achieve confidentiality. Security tokens 112 are also sometimes described as Assertions, such as in [RFC7521]. 114 A Security Token Service (STS) is a service capable of validating and 115 issuing security tokens, which enables clients to obtain appropriate 116 access credentials for resources in heterogeneous environments or 117 across security domains. Web Service clients have used WS-Trust 118 [WS-Trust] as the protocol to interact with an STS for token 119 exchange, however WS-Trust is a fairly heavyweight protocol, which 120 uses XML, SOAP, etc. Whereas, the trend in modern Web development 121 has been towards lightweight services utilizing RESTful patterns and 122 JSON. The OAuth 2.0 Authorization Framework [RFC6749] and OAuth 2.0 123 Bearer Tokens [RFC6750] have emerged as popular standards for 124 authorizing and securing access to HTTP and RESTful resources but do 125 not provide everything necessary to facilitate token exchange 126 interactions. 128 This specification defines a lightweight protocol extending OAuth 2.0 129 that 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 required; however, such details will 167 often be policy decisions made with respect to the specific needs of 168 individual deployments and will be configured or implemented 169 accordingly. 171 The security tokens obtained could be used in a number of contexts, 172 the specifics of which are also beyond the scope of this 173 specification. 175 1.1. Delegation vs. Impersonation Semantics 177 When principal A impersonates principal B, A is given all the rights 178 that B has within some defined rights context and is 179 indistinguishable from B in that context. Thus, when principal A 180 impersonates principal B, then in so far as any entity receiving such 181 a token is concerned, they are actually dealing with B. It is true 182 that some members of the identity system might have awareness that 183 impersonation is going on, but it is not a requirement. For all 184 intents and purposes, when A is impersonating B, A is B. 186 Delegation semantics are different than impersonation semantics, 187 though the two are closely related. With delegation semantics, 188 principal A still has its own identity separate from B and it is 189 explicitly understood that while B may have delegated some of its 190 rights to A, any actions taken are being taken by A representing B. 191 In a sense, A is an agent for B. 193 Delegation and impersonation are not inclusive of all situations. 194 When a principal is acting directly on its own behalf, for example, 195 neither delegation nor impersonation are in play. They are, however, 196 the more common semantics operating for token exchange and, as such, 197 are given more direct treatment in this specification. 199 Delegation semantics are typically expressed in a token by including 200 information about both the primary subject of the token as well as 201 the actor to whom that subject has delegated some of its rights. 202 Such a token is sometimes referred to as a composite token because it 203 is composed of information about multiple subjects. A client can 204 indicate the desire for a composite token by including a 205 "want_composite" parameter in the request with the value "true". 206 Typically, in the request, the "subject_token" represents the 207 identity of the party on behalf of whom the token is being requested 208 while the "actor_token" represents the identity of the party to whom 209 the access rights of the issued token are being delegated. A 210 composite token issued by the authorization server will contain 211 information about both parties. 213 The specifics of representing a composite token and even whether or 214 not such a token will be issued depend on the details of the 215 implementation and the kind of token. The representations of 216 composite tokens that are not JWTs are beyond the scope of this 217 specification. The Section 4.1 request parameter, however, does 218 provide a means for providing information about the desired actor 219 though the representation of a chain of delegation using the JWT 220 "act" claim. 222 1.2. Requirements Notation and Conventions 224 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 225 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 226 "OPTIONAL" in this document are to be interpreted as described in RFC 227 2119 [RFC2119]. 229 1.3. Terminology 231 This specification uses the terms "access token type", "authorization 232 server", "client", "client identifier", "resource server", "token 233 endpoint", "token request", and "token response" defined by OAuth 2.0 234 [RFC6749], and the terms "Claim" and "JWT Claims Set" defined by JSON 235 Web Token (JWT) [JWT]. 237 2. Token Exchange Request and Response 239 2.1. Request 241 A client requests a security token by making a token request to the 242 authorization server's token endpoint using the extension grant type 243 mechanism defined in Section 4.5 of OAuth 2.0 [RFC6749]. 245 Client authentication to the authorization server is done using the 246 normal mechanisms provided by OAuth 2.0. Section 2.3.1 of The OAuth 247 2.0 Authorization Framework [RFC6749] defines password-based 248 authentication of the client, however, client authentication is 249 extensible and other mechanisms are possible. For example, [RFC7523] 250 defines client authentication using JSON Web Tokens (JWTs) [JWT]. 251 The supported methods of client authentication and whether or not to 252 allow unauthenticated or unidentified clients are deployment 253 decisions that are at the discretion of the authorization server. 255 The client makes a token exchange request to the token endpoint with 256 an extension grant type by including the following parameters using 257 the "application/x-www-form-urlencoded" format with a character 258 encoding of UTF-8 in the HTTP request entity-body: 260 grant_type 261 REQUIRED. The value "urn:ietf:params:oauth:grant-type:token- 262 exchange" indicates that a token exchange is being performed. 264 resource 265 OPTIONAL. Indicates the physical location of the target service 266 or resource where the client intends to use the requested security 267 token. This enables the authorization server to apply policy as 268 appropriate for the target, such as determining the type and 269 content of the token to be issued or if and how the token is to be 270 encrypted. In many cases, a client will not have knowledge of the 271 logical organization of the systems with which it interacts and 272 will only know the location of the service where it intends to use 273 the token. The "resource" parameter allows the client to indicate 274 to the authorization server where it intends to use the issued 275 token by providing the location, typically as an https URL, in the 276 token exchange request in the same form that will be used to 277 access that resource. The authorization server will typically 278 have the capability to map from a resource URI value to an 279 appropriate policy. The value of the "resource" parameter MUST be 280 an absolute URI, as specified by Section 4.3 of [RFC3986], which 281 MAY include a query component and MUST NOT include a fragment 282 component. Multiple "resource" parameters may be used to indicate 283 that the issued token is intended to be used at the multiple 284 resources listed. 286 audience 287 OPTIONAL. The logical name of the target service where the client 288 intends to use the requested security token. This serves a 289 purpose similar to the "resource" parameter, but with the client 290 providing a logical name rather than a physical location. 291 Interpretation of the name requires that the value be something 292 that both the client and the authorization server understand. An 293 OAuth client identifier, a SAML entity identifier 294 [OASIS.saml-core-2.0-os], an OpenID Connect Issuer Identifier 295 [OpenID.Core], or a URI are examples of things that might be used 296 as "audience" parameter values. Multiple "audience" parameters 297 may be used to indicate that the issued token is intended to be 298 used at the multiple audiences listed. The "audience" and 299 "resource" parameters may be used together to indicate multiple 300 target services with a mix of logical names and physical 301 locations. 303 scope 304 OPTIONAL. A list of space-delimited, case-sensitive strings that 305 allow the client to specify the desired scope of the requested 306 security token in the context of the service or resource where the 307 token will be used. 309 requested_token_type 310 OPTIONAL. An identifier, as described in Section 3, for the type 311 of the requested security token. For example, a JWT can be 312 requested with the identifier "urn:ietf:params:oauth:token- 313 type:jwt". If the requested type is unspecified, the issued token 314 type is at the discretion of the authorization server and may be 315 dictated by knowledge of the requirements of the service or 316 resource indicated by the "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. For example, a value of "urn:ietf:params:oauth:token- 328 type:jwt", would indicate that the token is a JWT and a value of 329 "urn:ietf:params:oauth:token-type:access_token" would indicate 330 that the token is an OAuth access token. 332 actor_token 333 OPTIONAL. A security token that represents the identity of the 334 party that is authorized to use the requested security token and 335 act on behalf of the subject. 337 actor_token_type 338 An identifier, as described in Section 3, that indicates the type 339 of the security token in the "actor_token" parameter. This is 340 REQUIRED when the "actor_token" parameter is present in the 341 request but MUST NOT be included otherwise. 343 want_composite 344 OPTIONAL. When the value of this parameter is "true", it 345 indicates the client's desire for a composite security token to be 346 issued, which contains claims about both the main subject of the 347 token as well as about the party who is authorized to act on 348 behalf of that subject. Note that this parameter only provides a 349 means for the client to indicate its preference. The 350 authorization server is not required to honor the stated 351 preference and the nature of the tokens it issues are ultimately 352 at its discretion. 354 In the absence of one-time-use or other semantics specific to the 355 token type, the act of performing a token exchange has no impact on 356 the validity of the subject token or actor token. 358 2.2. Response 360 The authorization server responds to a token exchange request with a 361 normal OAuth 2.0 response from the token endpoint, as specified in 362 Section 5 of [RFC6749]. Additional details and explanation are 363 provided in the following subsections. 365 2.2.1. Successful Response 367 If the request is valid and meets all policy and other criteria of 368 the authorization server, a successful token response is constructed 369 by adding the following parameters to the entity-body of the HTTP 370 response using the "application/json" media type, as specified by 371 [RFC7159], and an HTTP 200 status code. The parameters are 372 serialized into a JavaScript Object Notation (JSON) structure by 373 adding each parameter at the top level. Parameter names and string 374 values are included as JSON strings. Numerical values are included 375 as JSON numbers. The order of parameters does not matter and can 376 vary. 378 access_token 379 REQUIRED. The security token issued by the authorization server 380 in response to the token exchange request. The "access_token" 381 parameter from Section 5.1 of [RFC6749] is used here to carry the 382 requested token, which allows this token exchange protocol to use 383 the existing OAuth 2.0 request and response constructs defined for 384 the token endpoint. The identifier "access_token" is used for 385 historical reasons and the issued token need not be an OAuth 386 access token. 388 issued_token_type 389 REQUIRED. An identifier, as described in Section 3, for the 390 representation of the issued security token. For example, a value 391 of "urn:ietf:params:oauth:token-type:access_token" indicates that 392 the issued token is an access token and a value of 393 "urn:ietf:params:oauth:token-type:jwt" indicates that it is a JWT. 395 token_type 396 REQUIRED. A case-insensitive value specifying the method of using 397 of the access token issued, as specified in Section 7.1 of 398 [RFC6749]. It provides the client with information about how to 399 utilize the access token to access protected resources. For 400 example, a value of "Bearer", as specified in [RFC6750], indicates 401 that the security token is a bearer token and the client can 402 simply present it as is without any additional proof of 403 eligibility beyond the contents of the token itself. Note that 404 the meaning of this parameter is different from the meaning of the 405 "issued_token_type" parameter, which declares the representation 406 of the issued security token; the term "token type" is typically 407 used with this meaning, as it is in all "*_token_type" parameters 408 in this specification. If the issued token is not an access token 409 or usable as an access token, then the "token_type" value "N_A" is 410 used to indicate that an OAuth 2.0 "token_type" identifier is not 411 applicable in that context. 413 expires_in 414 RECOMMENDED. The validity lifetime, in seconds, of the token 415 issued by the authorization server. Oftentimes the client will 416 not have the inclination or capability to inspect the content of 417 the token and this parameter provides a consistent and token type 418 agnostic indication of how long the token can be expected to be 419 valid. For example, the value 1800 denotes that the token will 420 expire in thirty minutes from the time the response was generated. 422 scope 423 OPTIONAL, if the scope of the issued security token is identical 424 to the scope requested by the client; otherwise, REQUIRED. 426 refresh_token 427 OPTIONAL. A refresh token will typically not be issued when the 428 the exchange is of one temporary credential (the subject_token) 429 for a different temporary credential (the issued token) for use in 430 some other context. A refresh token can be issued in cases where 431 the client of the token exchange needs the ability to access a 432 resource even when the original credential is no longer valid 433 (e.g. user-not-present or offline scenarios where there is no 434 longer any user entertaining an active session with the client). 435 Profiles or deployments of this specification should clearly 436 document the conditions under which a client should expect a 437 refresh token in response to "urn:ietf:params:oauth:grant- 438 type:token-exchange" grant type requests. 440 2.2.2. Error Response 442 If either the "subject_token" or "actor_token" are invalid for any 443 reason, or are unacceptable based on policy, the authorization server 444 MUST construct an error response, as specified in Section 5.2 of 445 [RFC6749]. The value of the "error" parameter MUST be the 446 "invalid_request" error code. The authorization server MAY include 447 additional information regarding the reasons for the error using the 448 "error_description" and/or "error_uri" parameters. Other error codes 449 may also be used, as appropriate. 451 2.3. Example Token Exchange 453 The following example demonstrates a hypothetical token exchange in 454 which an OAuth resource server assumes the role of the client during 455 token exchange in order to trade an access token that it received in 456 a request for a token that it will use to call to a backend service 457 (extra line breaks and indentation in the examples are for display 458 purposes only). 460 The resource server receives the following request containing an 461 OAuth access token in the Authorization request header, as specified 462 in Section 2.1 of [RFC6750]. 464 GET /resource HTTP/1.1 465 Host: frontend.example.com 466 Authorization: Bearer accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC 468 Figure 1: Protected Resource Request 470 The resource server assumes the role of the client for the token 471 exchange and the access token from the request above is sent to the 472 authorization server using a request as specified in Section 2.1. 473 The value of the "subject_token" parameter carries the access token 474 and the value of the "subject_token_type" parameter indicates that it 475 is an OAuth 2.0 access token. The resource server, acting as the 476 client, uses its identifier and secret to authenticate to the 477 authorization server using the HTTP Basic authentication scheme. The 478 "resource" parameter indicates the location of the backend service, 479 https://backend.example.com/api, where the issued token will be used. 481 POST /as/token.oauth2 HTTP/1.1 482 Host: as.example.com 483 Authorization: Basic cnMwODpsb25nLXNlY3VyZS1yYW5kb20tc2VjcmV0 484 Content-Type: application/x-www-form-urlencoded 486 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 487 &resource=https%3A%2F%2Fbackend.example.com%2Fapi%20 488 &subject_token=accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC 489 &subject_token_type= 490 urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token 492 Figure 2: Token Exchange Request 494 The authorization server validates the client credentials and the 495 "subject_token" presented in the token exchange request. From the 496 "resource" parameter, the authorization server is able to determine 497 the appropriate policy to apply to the request and issues a token 498 suitable for use at https://backend.example.com. The "access_token" 499 parameter of the response contains the new token, which is itself a 500 bearer OAuth access token that is valid for one minute. The token 501 happens to be a JWT; however, its structure and format are opaque to 502 the client so the "issued_token_type" indicates only that it is an 503 access token. 505 HTTP/1.1 200 OK 506 Content-Type: application/json 507 Cache-Control: no-cache, no-store 509 { 510 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQiOiJo 511 dHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2FzLmV 512 4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1MzMsIn 513 N1YiI6ImJjQGV4YW1wbGUuY29tIiwic2NwIjpbImFwaSJdfQ.MXgnpvPMo0nhce 514 PwnQbunD2gw_pDyCFA-Saobl6gyLAdyPbaALFuAOyFc4XTWaPEnHV_LGmXklSTp 515 z0yC7hlSQ", 516 "issued_token_type": 517 "urn:ietf:params:oauth:token-type:access_token", 518 "token_type":"Bearer", 519 "expires_in":60 520 } 522 Figure 3: Token Exchange Response 524 The resource server can then use the newly acquired access token in 525 making a request to the backend server. 527 GET /api HTTP/1.1 528 Host: backend.example.com 529 Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQ 530 iOiJodHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2 531 FzLmV4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1M 532 zMsInN1YiI6ImJjQGV4YW1wbGUuY29tIiwic2NwIjpbImFwaSJdfQ.MXgnpvPMo 533 0nhcePwnQbunD2gw_pDyCFA-Saobl6gyLAdyPbaALFuAOyFc4XTWaPEnHV_LGmX 534 klSTpz0yC7hlSQ 536 Figure 4: Backend Protected Resource Request 538 Additional examples can be found in Appendix A. 540 3. Token Type Identifiers 542 Several parameters in this specification utilize an identifier as the 543 value to describe the type of token in question. Specifically, they 544 are the "requested_token_type", "subject_token_type", 545 "actor_token_type" parameters of the request and the 546 "issued_token_type" member of the response. Token type identifiers 547 are URIs. 549 This specification defines the token type identifiers 550 "urn:ietf:params:oauth:token-type:access_token" and 551 "urn:ietf:params:oauth:token-type:refresh_token" to indicate that the 552 token is an OAuth 2.0 access token or refresh token, respectively. 553 The value "urn:ietf:params:oauth:token-type:jwt" defined in Section 9 554 of [JWT] indicates that the token is a JWT. This specification also 555 defines the token type identifier "urn:ietf:params:oauth:token- 556 type:id_token" to indicate that the token is an ID Token, as defined 557 in Section 2 of [OpenID.Core]. Other URIs to indicate other token 558 types MAY be used. 560 The distinction between an access token and a JWT is subtle. An 561 access token represents a delegated authorization decision, whereas 562 JWT is a token format. An access token can be formatted as a JWT but 563 doesn't necessarily have to be. And a JWT might well be an access 564 token but not all JWTs are access tokens. The intent of this 565 specification is that "urn:ietf:params:oauth:token-type:access_token" 566 be an indicator that the token is a typical OAuth access token issued 567 by the authorization server in question, opaque to the client, and 568 usable the same manner as any other access token obtained from that 569 authorization server (it could well be a JWT but the client isn't and 570 needn't be aware of that fact). Whereas 571 "urn:ietf:params:oauth:token-type:jwt" is to indicate specifically 572 that a JWT is being requested or sent (perhaps in a cross-domain use- 573 case where the JWT is used as an authorization grant to obtain an 574 access token from a different authorization server as is facilitated 575 by [RFC7523]). 577 4. JSON Web Token Claims and Introspection Response Parameters 579 It is useful to have defined mechanisms to express delegation within 580 a token as well as to express authorization to delegate or 581 impersonate. Although the token exchange protocol described herein 582 can be used with any type of token, this section defines claims to 583 express such semantics specifically for JWTs and in an OAuth 2.0 584 Token Introspection [RFC7662] response. Similar definitions for 585 other types of tokens are possible but beyond the scope of this 586 specification. 588 4.1. "act" (Actor) Claim 590 The "act" (actor) claim provides a means within a JWT to express that 591 delegation has occurred and identify the acting party to whom 592 authority has been delegated. The "act" claim value is a JSON object 593 and members in the JSON object are claims that identify the actor. 594 The claims that make up the "act" claim identify and possibly provide 595 additional information about the actor. For example, the combination 596 of the two claims "iss" and "sub" might be necessary to uniquely 597 identify an actor. 599 However, claims within the "act" claim pertain only to the identity 600 of the actor and are not relevant to the validity of the containing 601 JWT in the same manner as the top-level claims. Consequently, claims 602 such as "exp", "nbf", and "aud" are not meaningful when used within 603 an "act" claim, and therefore should not be used. 605 The following example illustrates the "act" (actor) claim within a 606 JWT Claims Set. The claims of the token itself are about 607 user@example.com while the "act" claim indicates that 608 admin@example.com is the current actor. 610 { 611 "aud":"https://consumer.example.com", 612 "iss":"https://issuer.example.com", 613 "exp":1443904177, 614 "nbf":1443904077, 615 "sub":"user@example.com", 616 "act": 617 { 618 "sub":"admin@example.com" 619 } 620 } 622 Figure 5: Actor Claim 624 A chain of delegation can be expressed by nesting one "act" claim 625 within another. The outermost "act" claim represents the current 626 actor while nested "act" claims represent prior actors. The least 627 recent actor is the most deeply nested. 629 The following example illustrates nested "act" (actor) claims within 630 a JWT Claims Set. The claims of the token itself are about 631 user@example.com while the "act" claim indicates that the system 632 consumer.example.com-web-application is the current actor and 633 admin@example.com was a prior actor. Such a token might come about 634 as the result of the web application receiving a token like the one 635 in the previous example and exchanging it for a new token that lists 636 it as the current actor and that can be used at 637 https://backend.example.com. 639 { 640 "aud":"https://backend.example.com", 641 "iss":"https://issuer.example.com", 642 "exp":1443904100, 643 "nbf":1443904000, 644 "sub":"user@example.com", 645 "act": 646 { 647 "sub":"consumer.example.com-web-application", 648 "iss":"https://issuer.example.net", 649 "act": 650 { 651 "sub":"admin@example.com" 652 } 653 } 654 } 656 Figure 6: Nested Actor Claim 658 When included as a top-level member of an OAuth token introspection 659 response, "act" has the same semantics and format as the the claim of 660 the same name. 662 4.2. "scp" (Scopes) Claim 664 The "scp" claim is an array of strings, each of which represents an 665 OAuth scope granted for the issued security token. Each array entry 666 of the claim value is a scope-token, as defined in Section 3.3 of 667 OAuth 2.0 [RFC6749]. 669 The following example illustrates the "scp" claim within a JWT Claims 670 Set with four scope-tokens. 672 { 673 "aud":"https://consumer.example.com", 674 "iss":"https://issuer.example.com", 675 "exp":1443904177, 676 "nbf":1443904077, 677 "sub":"dgaf4mvfs75Fci_FL3heQA", 678 "scp":["email","address","profile","phone"] 679 } 681 Figure 7: Scopes Claim 683 OAuth 2.0 Token Introspection [RFC7662] defines the "scope" parameter 684 to convey the scopes associated with the token. 686 4.3. "cid" (Client Identifier) Claim 688 The "cid" claim carries the client identifier of the OAuth 2.0 689 [RFC6749] client that requested the token. 691 The following example illustrates the "cid" claim within a JWT Claims 692 Set indicating an OAuth 2.0 client with "s6BhdRkqt3" as its 693 identifier. 695 { 696 "aud":"https://consumer.example.com", 697 "iss":"https://issuer.example.com", 698 "exp":1443904177, 699 "sub":"user@example.com", 700 "cid":"s6BhdRkqt3" 701 } 703 Figure 8: Client Identifier Claim 705 OAuth 2.0 Token Introspection [RFC7662] defines the "client_id" 706 parameter as the client identifier for the OAuth 2.0 client that 707 requested the token. 709 4.4. "may_act" (May Act For) Claim 711 The "may_act" claim makes a statement that one party is authorized to 712 become the actor and act on behalf of another party. The claim value 713 is a JSON object and members in the JSON object are claims that 714 identify the party that is asserted as being eligible to act for the 715 party identified by the JWT containing the claim. The claims that 716 make up the "may_act" claim identify and possibly provide additional 717 information about the authorized actor. For example, the combination 718 of the two claims "iss" and "sub" are sometimes necessary to uniquely 719 identify an authorized actor, while the "email" claim might be used 720 to provide additional useful information about that party. 722 However, claims within the "may_act" claim pertain only to the 723 identity of that party and are not relevant to the validity of the 724 containing JWT in the same manner as top level claims. Consequently, 725 claims such as "exp", "nbf", and "aud" are not meaningful when used 726 within a "may_act" claim, and therefore should not be used. 728 The following example illustrates the "may_act" claim within a JWT 729 Claims Set. The claims of the token itself are about 730 user@example.com while the "may_act" claim indicates that 731 admin@example.com is authorized to act on behalf of user@example.com. 733 { 734 "aud":"https://consumer.example.com", 735 "iss":"https://issuer.example.com", 736 "exp":1443904177, 737 "nbf":1443904077, 738 "sub":"user@example.com", 739 "may_act": 740 { 741 "sub":"admin@example.com" 742 } 743 } 745 Figure 9: May Act For Claim 747 When included as a top-level member of an OAuth token introspection 748 response, "may_act" has the same semantics and format as the the 749 claim of the same name. 751 5. IANA Considerations 753 5.1. OAuth URI Registration 755 This specification registers the following values in the IANA "OAuth 756 URI" registry [IANA.OAuth.Parameters] established by [RFC6755]. 758 5.1.1. Registry Contents 760 o URN: urn:ietf:params:oauth:grant-type:token-exchange 761 o Common Name: Token exchange grant type for OAuth 2.0 762 o Change controller: IESG 763 o Specification Document: Section 2.1 of [[ this specification ]] 764 o URN: urn:ietf:params:oauth:token-type:access_token 765 o Common Name: Token type URI for an OAuth 2.0 access token 766 o Change controller: IESG 767 o Specification Document: Section 3 of [[this specification]] 769 o URN: urn:ietf:params:oauth:token-type:refresh_token 770 o Common Name: Token Type URI for an OAuth 2.0 refresh token 771 o Change controller: IESG 772 o Specification Document: Section 3 of [[this specification]] 774 o URN: urn:ietf:params:oauth:token-type:id_token 775 o Common Name: Token Type URI for an ID Token 776 o Change controller: IESG 777 o Specification Document: Section 3 of [[this specification]] 779 5.2. OAuth Parameters Registration 781 This specification registers the following values in the IANA "OAuth 782 Parameters" registry [IANA.OAuth.Parameters] established by 783 [RFC6749]. 785 5.2.1. Registry Contents 787 o Parameter name: resource 788 o Parameter usage location: token request 789 o Change controller: IESG 790 o Specification document(s): Section 2.1 of [[ this specification ]] 792 o Parameter name: audience 793 o Parameter usage location: token request 794 o Change controller: IESG 795 o Specification document(s): Section 2.1 of [[ this specification ]] 797 o Parameter name: requested_token_type 798 o Parameter usage location: token request 799 o Change controller: IESG 800 o Specification document(s): Section 2.1 of [[ this specification ]] 802 o Parameter name: subject_token 803 o Parameter usage location: token request 804 o Change controller: IESG 805 o Specification document(s): Section 2.1 of [[ this specification ]] 807 o Parameter name: subject_token_type 808 o Parameter usage location: token request 809 o Change controller: IESG 810 o Specification document(s): Section 2.1 of [[ this specification ]] 811 o Parameter name: actor_token 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: actor_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: want_composite 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: issued_token_type 827 o Parameter usage location: token response 828 o Change controller: IESG 829 o Specification document(s): Section 2.2.1 of [[ this specification 830 ]] 832 5.3. OAuth Access Token Type Registration 834 This specification registers the following access token type in the 835 IANA "OAuth Access Token Types" registry [IANA.OAuth.Parameters] 836 established by [RFC6749]. 838 5.3.1. Registry Contents 840 o Type name: N_A 841 o Additional Token Endpoint Response Parameters: (none) 842 o HTTP Authentication Scheme(s): (none) 843 o Change controller: IESG 844 o Specification document(s): Section 2.2.1 of [[ this specification 845 ]] 847 5.4. JSON Web Token Claims Registration 849 This specification registers the following Claims in the IANA "JSON 850 Web Token Claims" registry [IANA.JWT.Claims] established by [JWT]. 852 5.4.1. Registry Contents 854 o Claim Name: "act" 855 o Claim Description: Actor 856 o Change Controller: IESG 857 o Specification Document(s): Section 4.1 of [[ this specification ]] 858 o Claim Name: "scp" 859 o Claim Description: Scope Values 860 o Change Controller: IESG 861 o Specification Document(s): Section 4.2 of [[ this specification ]] 863 o Claim Name: "cid" 864 o Claim Description: Client Identifier 865 o Change Controller: IESG 866 o Specification Document(s): Section 4.3 of [[ this specification ]] 868 o Claim Name: "may_act" 869 o Claim Description: May Act For 870 o Change Controller: IESG 871 o Specification Document(s): Section 4.4 of [[ this specification ]] 873 5.5. OAuth Token Introspection Response Registration 875 This specification registers the following values in the IANA "OAuth 876 Token Introspection Response" registry [IANA.OAuth.Parameters] 877 established by [RFC7662]. 879 5.5.1. Registry Contents 881 o Claim Name: "act" 882 o Claim Description: Actor 883 o Change Controller: IESG 884 o Specification Document(s): Section 4.1 of [[ this specification ]] 886 o Claim Name: "may_act" 887 o Claim Description: May Act For 888 o Change Controller: IESG 889 o Specification Document(s): Section 4.4 of [[ this specification ]] 891 6. Security Considerations 893 All of the normal security issues that are discussed in [JWT], 894 especially in relationship to comparing URIs and dealing with 895 unrecognized values, also apply here. 897 In addition, both delegation and impersonation introduce unique 898 security issues. Any time one principal is delegated the rights of 899 another principal, the potential for abuse is a concern. The use of 900 the "scp" claim is suggested to mitigate potential for such abuse, as 901 it restricts the contexts in which the delegated rights can be 902 exercised. 904 7. References 906 7.1. Normative References 908 [IANA.JWT.Claims] 909 IANA, "JSON Web Token Claims", 910 . 912 [IANA.OAuth.Parameters] 913 IANA, "OAuth Parameters", 914 . 916 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 917 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 918 . 920 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 921 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 922 RFC2119, March 1997, 923 . 925 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 926 Resource Identifier (URI): Generic Syntax", STD 66, RFC 927 3986, DOI 10.17487/RFC3986, January 2005, 928 . 930 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 931 RFC 6749, DOI 10.17487/RFC6749, October 2012, 932 . 934 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 935 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 936 2014, . 938 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", RFC 939 7662, DOI 10.17487/RFC7662, October 2015, 940 . 942 7.2. Informative References 944 [OASIS.saml-core-2.0-os] 945 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 946 "Assertions and Protocol for the OASIS Security Assertion 947 Markup Language (SAML) V2.0", OASIS Standard saml-core- 948 2.0-os, March 2005. 950 [OpenID.Core] 951 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 952 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 953 . 955 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 956 Framework: Bearer Token Usage", RFC 6750, DOI 10.17487/ 957 RFC6750, October 2012, 958 . 960 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 961 for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, 962 . 964 [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 965 "Assertion Framework for OAuth 2.0 Client Authentication 966 and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, 967 May 2015, . 969 [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 970 (JWT) Profile for OAuth 2.0 Client Authentication and 971 Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 972 2015, . 974 [WS-Trust] 975 Nadalin, A., Goodner, M., Gudgin, M., Barbir, A., and H. 976 Granqvist, "WS-Trust 1.4", February 2012, 977 . 980 Appendix A. Additional Token Exchange Examples 982 Two example token exchanges are provided in the following sections 983 illustrating impersonation and delegation, respectively (with extra 984 line breaks and indentation for display purposes only). 986 A.1. Impersonation Token Exchange Example 988 A.1.1. Token Exchange Request 990 In the following token exchange request, an anonymous client is 991 requesting a token with impersonation semantics. The client tells 992 the authorization server that it needs a token for use at the target 993 service with the logical name "urn:example:cooperation-context". 995 POST /as/token.oauth2 HTTP/1.1 996 Host: as.example.com 997 Content-Type: application/x-www-form-urlencoded 999 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 1000 &audience=urn%3Aexample%3Acooperation-context 1001 &subject_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwc 1002 zovL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXI 1003 uZXhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTA2MDAsIm5iZiI6MTQ0MTkwOTAwMCwic 1004 3ViIjoiYmNAZXhhbXBsZS5uZXQiLCJzY3AiOlsib3JkZXJzIiwicHJvZmlsZSIsImh 1005 pc3RvcnkiXX0.JDe7fZ267iIRXwbFmOugyCt5dmGoy6EeuzNQ3MqDek5cCUlyPhQC6 1006 cz9laKjK1bnjMQbLJqWix6ZdBI0isjsTA 1007 &subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1009 Figure 10: Token Exchange Request 1011 A.1.2. Subject Token Claims 1013 The "subject_token" in the prior request is a JWT and the decoded JWT 1014 Claims Set is shown here. The JWT is intended for consumption by the 1015 authorization server within a specific time window. The subject of 1016 the JWT ("bc@example.net") is the party on behalf of whom the new 1017 token is being requested. 1019 { 1020 "aud":"https://as.example.com", 1021 "iss":"https://original-issuer.example.net", 1022 "exp":1441910600, 1023 "nbf":1441909000, 1024 "sub":"bc@example.net", 1025 "scp":["orders","profile","history"] 1026 } 1028 Figure 11: Subject Token Claims 1030 A.1.3. Token Exchange Response 1032 The "access_token" parameter of the token exchange response shown 1033 below contains the new token that the client requested. The other 1034 parameters of the response indicate that the token is a bearer access 1035 token that expires in an hour. 1037 HTTP/1.1 200 OK 1038 Content-Type: application/json 1039 Cache-Control: no-cache, no-store 1041 { 1042 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm4 1043 6ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5l 1044 eGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic3ViIjoiYmNAZXhhbXBsZS5uZ 1045 XQiLCJzY3AiOlsib3JkZXJzIiwiaGlzdG9yeSIsInByb2ZpbGUiXX0.YQHuLmI1YD 1046 TugbfEvgGY2gaGBmMyj9BepZSECCBE9j9ogqZv2qx6VQQPrbT1k7vBYGLNMOkkpmm 1047 JkxZDS0YV7g", 1048 "issued_token_type": 1049 "urn:ietf:params:oauth:token-type:access_token", 1050 "token_type":"Bearer", 1051 "expires_in":3600 1052 } 1054 Figure 12: Token Exchange Response 1056 A.1.4. Issued Token Claims 1058 The decoded JWT Claims Set of the issued token is shown below. The 1059 new JWT is issued by the authorization server and intended for 1060 consumption by a system entity known by the logical name 1061 "urn:example:cooperation-context" any time before its expiration. 1062 The subject ("sub") of the JWT is the same as the subject the token 1063 used to make the request, which effectively enables the client to 1064 impersonate that subject at the system entity known by the logical 1065 name of "urn:example:cooperation-context" by using the token. 1067 { 1068 "aud":"urn:example:cooperation-context", 1069 "iss":"https://as.example.com", 1070 "exp":1441913610, 1071 "sub":"bc@example.net", 1072 "scp":["orders","history","profile"] 1073 } 1075 Figure 13: Issued Token Claims 1077 A.2. Delegation Token Exchange Example 1079 A.2.1. Token Exchange Request 1081 In the following token exchange request, an anonymous client is 1082 requesting a token with delegation semantics, which is indicated by 1083 the inclusion of the "want_composite" parameter. The client tells 1084 the authorization server that it needs a token for use at the target 1085 service with the logical name "urn:example:cooperation-context". 1087 POST /as/token.oauth2 HTTP/1.1 1088 Host: as.example.com 1089 Content-Type: application/x-www-form-urlencoded 1091 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange 1092 &audience=urn%3Aexample%3Acooperation-context 1093 &want_composite=true 1094 &subject_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwc 1095 zovL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXI 1096 uZXhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTAwNjAsInNjcCI6WyJzdGF0dXMiLCJmZ 1097 WVkIl0sInN1YiI6InVzZXJAZXhhbXBsZS5uZXQiLCJtYXlfYWN0Ijp7InN1YiI6ImF 1098 kbWluQGV4YW1wbGUubmV0In19.ut0Ll7wm920VzRvuLGLFoPJLeO5DDElxsax1L_xK 1099 Um2eooiNSfuif-OGa2382hPyFYnddKIa0wmDhQksW018Rw 1100 &subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1101 &actor_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwczo 1102 vL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXIuZ 1103 XhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTAwNjAsInN1YiI6ImFkbWluQGV4YW1wbGU 1104 ubmV0In0.7YQ-3zPfhUvzje5oqw8COCvN5uP6NsKik9CVV6cAOf4QKgM-tKfiOwcgZ 1105 oUuDL2tEs6tqPlcBlMjiSzEjm3yBg 1106 &actor_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt 1108 Figure 14: Token Exchange Request 1110 A.2.2. Subject Token Claims 1112 The "subject_token" in the prior request is a JWT and the decoded JWT 1113 Claims Set is shown here. The JWT is intended for consumption by the 1114 authorization server before a specific expiration time. The subject 1115 of the JWT ("user@example.net") is the party on behalf of whom the 1116 new token is being requested. 1118 { 1119 "aud":"https://as.example.com", 1120 "iss":"https://original-issuer.example.net", 1121 "exp":1441910060, 1122 "scp":["status","feed"], 1123 "sub":"user@example.net", 1124 "may_act": 1125 { 1126 "sub":"admin@example.net" 1127 } 1128 } 1130 Figure 15: Subject Token Claims 1132 A.2.3. Actor Token Claims 1134 The "actor_token" in the prior request is a JWT and the decoded JWT 1135 Claims Set is shown here. This JWT is also intended for consumption 1136 by the authorization server before a specific expiration time. The 1137 subject of the JWT ("admin@example.net") is the actor that will wield 1138 the security token being requested. 1140 { 1141 "aud":"https://as.example.com", 1142 "iss":"https://original-issuer.example.net", 1143 "exp":1441910060, 1144 "sub":"admin@example.net" 1145 } 1147 Figure 16: Actor Token Claims 1149 A.2.4. Token Exchange Response 1151 The "access_token" parameter of the token exchange response shown 1152 below contains the new token that the client requested. The other 1153 parameters of the response indicate that the token is a JWT that 1154 expires in an hour and that the access token type is not applicable 1155 since the issued token is not an access token. 1157 HTTP/1.1 200 OK 1158 Content-Type: application/json 1159 Cache-Control: no-cache, no-store 1161 { 1162 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm4 1163 6ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5l 1164 eGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic2NwIjpbInN0YXR1cyIsImZlZ 1165 WQiXSwic3ViIjoidXNlckBleGFtcGxlLm5ldCIsImFjdCI6eyJzdWIiOiJhZG1pbk 1166 BleGFtcGxlLm5ldCJ9fQ._qjM7Ij_HcrC78omT4jiZTFJOuzsAj1wPo31ymQS-Suq 1167 r64S1jCp6pfQR-in_OOAosAGamEg4jyPsht6kMAiYA", 1168 "issued_token_type":"urn:ietf:params:oauth:token-type:jwt", 1169 "token_type":"N_A", 1170 "expires_in":3600 1171 } 1173 Figure 17: Token Exchange Response 1175 A.2.5. Issued Token Claims 1177 The decoded JWT Claims Set of the issued token is shown below. The 1178 new JWT is issued by the authorization server and intended for 1179 consumption by a system entity known by the logical name 1180 "urn:example:cooperation-context" any time before its expiration. 1181 The subject ("sub") of the JWT is the same as the subject of the 1182 "subject_token" used to make the request. The actor ("act") of the 1183 JWT is the same as the subject of the "actor_token" used to make the 1184 request. This indicates delegation and identifies 1185 "admin@example.net" as the current actor to whom authority has been 1186 delegated to act on behalf of "user@example.net". 1188 { 1189 "aud":"urn:example:cooperation-context", 1190 "iss":"https://as.example.com", 1191 "exp":1441913610, 1192 "scp":["status","feed"], 1193 "sub":"user@example.net", 1194 "act": 1195 { 1196 "sub":"admin@example.net" 1197 } 1198 } 1200 Figure 18: Issued Token Claims 1202 Appendix B. Acknowledgements 1204 This specification was developed within the OAuth Working Group, 1205 which includes dozens of active and dedicated participants. It was 1206 produced under the chairmanship of Hannes Tschofenig and Derek Atkins 1207 with Kathleen Moriarty and Stephen Farrell serving as Security Area 1208 Directors. The following individuals contributed ideas, feedback, 1209 and wording to this specification: 1211 Caleb Baker, Vittorio Bertocci, Thomas Broyer, William Denniss, 1212 Vladimir Dzhuvinov, Phil Hunt, Jason Keglovitz, Adam Lewis, Nov 1213 Matake, Matt Miller, Matthew Perry, Justin Richer, Rifaat Shekh- 1214 Yusef, Scott Tomilson, and Hannes Tschofenig. 1216 Appendix C. Open Issues 1218 The following decisions need to be made and updates to this spec 1219 performed: 1221 o Understand and define exactly how the presentation of PoP/non- 1222 bearer tokens works. Of course, the specifications defining these 1223 kinds of tokens need to do so first before there is much we can do 1224 in this specification in this regard. 1226 Appendix D. Document History 1228 [[ to be removed by the RFC Editor before publication as an RFC ]] 1230 -05 1232 o Defined the JWT claim "cid" to express the OAuth 2.0 client 1233 identifier of the client that requested the token. 1234 o Defined and requested registration for "act" and "may_act" as 1235 Token introspection response parameters (in addition to being JWT 1236 claims). 1237 o Loosen up the language about refresh_token in the response to 1238 OPTIONAL from NOT RECOMMENDED based on feedback form real world 1239 deployment experience. 1240 o Add clarifying text about the distinction between JWT and access 1241 token URIs. 1242 o Close out (remove) some of the Open Issues bullets that have been 1243 resolved. 1245 -04 1247 o Clarified that the "resource" and "audience" request parameters 1248 can be used at the same time (via http://www.ietf.org/mail- 1249 archive/web/oauth/current/msg15335.html). 1250 o Clarified subject/actor token validity after token exchange and 1251 explained a bit more about the recommendation to not issue refresh 1252 tokens (via http://www.ietf.org/mail-archive/web/oauth/current/ 1253 msg15318.html). 1254 o Updated the examples appendix to use an issuer value that doesn't 1255 imply that the client issued and signed the tokens and used 1256 "Bearer" and "urn:ietf:params:oauth:token-type:access_token" in 1257 one of the responses (via http://www.ietf.org/mail- 1258 archive/web/oauth/current/msg15335.html). 1259 o Defined and registered urn:ietf:params:oauth:token-type:id_token, 1260 since some use cases perform token exchanges for ID Tokens and no 1261 URI to indicate that a token is an ID Token had previously been 1262 defined. 1264 -03 1266 o Updated the document editors (adding Campbell, Bradley, and 1267 Mortimore). 1268 o Added to the title. 1269 o Added to the abstract and introduction. 1270 o Updated the format of the request to use application/x-www-form- 1271 urlencoded request parameters and the response to use the existing 1272 token endpoint JSON parameters defined in OAuth 2.0. 1274 o Changed the grant type identifier to urn:ietf:params:oauth:grant- 1275 type:token-exchange. 1276 o Added RFC 6755 registration requests for 1277 urn:ietf:params:oauth:token-type:refresh_token, 1278 urn:ietf:params:oauth:token-type:access_token, and 1279 urn:ietf:params:oauth:grant-type:token-exchange. 1280 o Added RFC 6749 registration requests for request/response 1281 parameters. 1282 o Removed the Implementation Considerations and the requirement to 1283 support JWTs. 1284 o Clarified many aspects of the text. 1285 o Changed "on_behalf_of" to "subject_token", 1286 "on_behalf_of_token_type" to "subject_token_type", "act_as" to 1287 "actor_token", and "act_as_token_type" to "actor_token_type". 1288 o Added an "audience" request parameter used to indicate the logical 1289 names of the target services at which the client intends to use 1290 the requested security token. 1291 o Added a "want_composite" request parameter used to indicate the 1292 desire for a composite token rather than trying to infer it from 1293 the presence/absence of token(s) in the request. 1294 o Added a "resource" request parameter used to indicate the URLs of 1295 resources at which the client intends to use the requested 1296 security token. 1297 o Specified that multiple "audience" and "resource" request 1298 parameter values may be used. 1299 o Defined the JWT claim "act" (actor) to express the current actor 1300 or delegation principal. 1301 o Defined the JWT claim "may_act" to express that one party is 1302 authorized to act on behalf of another party. 1303 o Defined the JWT claim "scp" (scopes) to express OAuth 2.0 scope- 1304 token values. 1305 o Added the "N_A" (not applicable) OAuth Access Token Type 1306 definition for use in contexts in which the token exchange syntax 1307 requires a "token_type" value, but in which the token being issued 1308 is not an access token. 1309 o Added examples. 1311 -02 1313 o Enabled use of Security Token types other than JWTs for "act_as" 1314 and "on_behalf_of" request values. 1315 o Referenced the JWT and OAuth Assertions RFCs. 1317 -01 1319 o Updated references. 1321 -00 1322 o Created initial working group draft from draft-jones-oauth-token- 1323 exchange-01. 1325 Authors' Addresses 1327 Michael B. Jones 1328 Microsoft 1330 Email: mbj@microsoft.com 1331 URI: http://self-issued.info/ 1333 Anthony Nadalin 1334 Microsoft 1336 Email: tonynad@microsoft.com 1338 Brian Campbell 1339 Ping Identity 1341 Email: brian.d.campbell@gmail.com 1343 John Bradley 1344 Ping Identity 1346 Email: ve7jtb@ve7jtb.com 1348 Chuck Mortimore 1349 Salesforce 1351 Email: cmortimore@salesforce.com