idnits 2.17.1 draft-ietf-oauth-access-token-jwt-04.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 : ---------------------------------------------------------------------------- == There are 3 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 6, 2020) is 1509 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) == Unused Reference: 'RFC3986' is defined on line 583, but no explicit reference was found in the text == Unused Reference: 'RFC7644' is defined on line 640, but no explicit reference was found in the text Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group V. Bertocci 3 Internet-Draft Auth0 4 Intended status: Standards Track March 6, 2020 5 Expires: September 7, 2020 7 JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens 8 draft-ietf-oauth-access-token-jwt-04 10 Abstract 12 This specification defines a profile for issuing OAuth 2.0 access 13 tokens in JSON web token (JWT) format. Authorization servers and 14 resource servers from different vendors can leverage this profile to 15 issue and consume access tokens in interoperable manner. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at https://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on September 7, 2020. 34 Copyright Notice 36 Copyright (c) 2020 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (https://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 1.1. Requirements Notation and Conventions . . . . . . . . . . 3 53 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 54 2. JWT Access Token Header and Data Structure . . . . . . . . . 4 55 2.1. Header . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 2.2. Data Structure . . . . . . . . . . . . . . . . . . . . . 4 57 2.2.1. Authentication Information Claims . . . . . . . . . . 5 58 2.2.2. Identity Claims . . . . . . . . . . . . . . . . . . . 5 59 2.2.3. Authorization Claims . . . . . . . . . . . . . . . . 6 60 2.2.3.1. Claims for Authorization Outside of Delegation 61 Scenarios . . . . . . . . . . . . . . . . . . . . 6 62 3. Requesting a JWT Access Token . . . . . . . . . . . . . . . . 6 63 4. Validating JWT Access Tokens . . . . . . . . . . . . . . . . 8 64 5. Security Considerations . . . . . . . . . . . . . . . . . . . 9 65 6. Privacy Considerations . . . . . . . . . . . . . . . . . . . 10 66 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 67 7.1. Media Type Registration . . . . . . . . . . . . . . . . . 10 68 7.1.1. Registry Content . . . . . . . . . . . . . . . . . . 11 69 7.2. Claims Registration . . . . . . . . . . . . . . . . . . . 12 70 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 12 71 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 72 8.1. Normative References . . . . . . . . . . . . . . . . . . 12 73 8.2. Informative References . . . . . . . . . . . . . . . . . 14 74 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 14 75 Appendix B. Document History . . . . . . . . . . . . . . . . . . 15 76 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 17 78 1. Introduction 80 The original OAuth 2.0 Authorization Framework [RFC6749] 81 specification does not mandate any specific format for access tokens. 82 While that remains perfectly appropriate for many important scenario, 83 in-market use has shown that many commercial OAuth2 implementations 84 elected to issue access tokens using a format that can be parsed and 85 validated by resource servers directly, without further authorization 86 server involvement. The approach is particularly common in 87 topologies where the authorization server and resource server are not 88 co-located, are not ran by the same entity, or are otherwise 89 separated by some boundary. All of the known commercial 90 implementations known at this time leverage the JSON Web Tokens(JWT) 91 [RFC7519] format. 93 Most vendor specific JWT access tokens share the same functional 94 layout, including information in forms of claims meant to support the 95 same scenarios: token validation, transporting authorization 96 information in forms of scopes and entitlements, carrying identity 97 information about the subject, and so on. The differences are mostly 98 confined to the claim names and syntax used to represent the same 99 entities, suggesting that interoperability could be easily achieved 100 by standardizing on a common set of claims and validation rules. 102 The assumption that access tokens are associated to specific 103 information doesn't appear only in commercial implementations. 104 Various specifications in the OAuth2 family (such as resource 105 indicators [RFC8707], OAuth 2.0 bearer token usage [RFC6750] and 106 others) postulate the presence in access tokens of scoping 107 mechanisms, such as an audience. The family of specifications 108 associated to introspection also indirectly suggest a fundamental set 109 of information access tokens are expected to carry or at least be 110 associated with. 112 This specification aims to provide a standardized and interoperable 113 profile as an alternative to the proprietary JWT access tokens 114 layouts going forward. Besides defining a common set of mandatory 115 and optional claims, the profile provides clear indications on how 116 authorization requests parameters determine the content of the issued 117 JWT access token, how an authorization server can publish metadata 118 relevant to the JWT access tokens it issues, and how a resource 119 server should validate incoming JWT access tokens. 121 Finally, this specification provides security and privacy 122 considerations meant to prevent common mistakes and anti patterns 123 that are likely to occur in naive use of the JWT format to represent 124 access tokens. 126 1.1. Requirements Notation and Conventions 128 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 129 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 130 "OPTIONAL" in this document are to be interpreted as described in BCP 131 14 [RFC2119] [RFC8174] when, and only when, they appear in all 132 capitals, as shown here. 134 1.2. Terminology 136 JWT access token An OAuth 2.0 access token encoded in JWT format and 137 complying with the requirements described in this specification. 139 This specification uses the terms "access token", "refresh token", 140 "authorization server", "resource server", "authorization endpoint", 141 "authorization request", "authorization response", "token endpoint", 142 "grant type", "access token request", "access token response", and 143 "client" defined by The OAuth 2.0 Authorization Framework [RFC6749]. 145 2. JWT Access Token Header and Data Structure 147 JWT access tokens are regular JWT tokens complying with the 148 requirements described in this section. 150 2.1. Header 152 Although JWT access tokens can use any signing algorithm, use of 153 asymmetric algorithms is RECOMMENDED as it simplifies the process of 154 acquiring validation information for resource servers (see 155 Section 4). 157 NOTE: there were discussions about adding a reference to 158 authenticated encryption methods as well, but there's no internet 159 draft specifying interoperable public key methods at this time 161 The typ header parameter for a JWT access token MUST be at+jwt. See 162 the security considerations section for details on the importance of 163 preventing id_tokens from being accepted as access tokens by resource 164 servers implementing this profile. 166 2.2. Data Structure 168 The following claims are used in the JWT access token data structure. 170 iss REQUIRED - as defined in section 4.1.1 of [RFC7519]. 172 exp REQUIRED - as defined in section 4.1.4 of [RFC7519]. 174 aud REQUIRED - as defined in section 4.1.3 of [RFC7519]. See 175 Section 3 for indications on how an authorization server should 176 determine the value of aud depending on the request. 178 sub REQUIRED - as defined in section 4.1.2 of [RFC7519]. In case of 179 access tokens obtained through grants where no resource owner is 180 involved, such as the client credentials grant, the value of sub 181 SHOULD correspond to an identifier the authorization server uses 182 to indicate the client application. Please see Section 5 for more 183 details on this scenario. 185 client_id REQUIRED - as defined in section 4.3 of [RFC8693]. 187 iat OPTIONAL - as defined in section 4.1.6 of [RFC7519]. 189 jti OPTIONAL - as defined in section 4.1.7 of [RFC7519]. 191 2.2.1. Authentication Information Claims 193 The claims listed in this section reflect in the access token the the 194 types and strength of authentication that the authentication server 195 enforced prior to returning the authorization response to the client. 196 Their values are fixed, and remain the same across all access tokens 197 that derive from a given authorization response, whether the access 198 token was obtained directly in the response (e.g., via the implicit 199 flow) or after one or more token exchanges (e.g., obtaining a fresh 200 access token using a refresh token, or exchanging one access token 201 for another via [RFC8693]). 203 auth_time OPTIONAL - as defined in section 2 of [OpenID.Core]. This 204 claim represents the time at which the end user last authenticated 205 during the session that was used to obtain the token. This means 206 that all the JWT access tokens obtained with a given refresh token 207 will all have the same value of auth_time, corresponding to the 208 instant in which the user authenticated to obtain the refresh 209 token. 211 acr, amr OPTIONAL - as defined in section 2 of [OpenID.Core]. The 212 same considerations presented for auth_time apply to acr and amr: 213 those values reflect the authentication context and method used 214 when the end user originally authenticated, and will remain 215 unchanged for the JWT access tokens issued within the context of 216 that session. 218 2.2.2. Identity Claims 220 Commercial authorization servers will often include resource owner 221 attributes directly in access tokens, so that resource servers can 222 consume them directly for authorization or other purposes without any 223 further roudtrips to introspection ( [RFC7662]) or userinfo ( 224 [OpenID.Core]) endpoints. This is particularly common in scenarios 225 where the client and the resource server belong to the same entity 226 and are part of the same solution, as it is the case for first party 227 clients invoking their own backend API. 229 This profile does not introduce any mechanism for a client to 230 directly request the presence of specific claims in JWT access 231 tokens, as the authorization server can determine what additional 232 claims are required by a particular resource server by taking in 233 consideration the client_id of the client, the scope and the resource 234 parameters included in the request. 236 Any additional attributes whose semantic is well described by the 237 attributes description found in section 5.1 of [OpenID.Core] SHOULD 238 be codified in JWT access tokens via the corresponding claim names in 239 that section of the OpenID Connect specification. The same holds for 240 attributes defined in [RFC7662] and other identity related 241 specifications. 243 Authorization server MAY return arbitrary attributes not defined in 244 any existing specification, as long as the corresponding claim names 245 are collision resistant or the access tokens are meant to be used 246 only within a private subsystem. 248 Authorization servers including resource owner attributes in JWT 249 access tokens should exercise care and verify that all privacy 250 requirements are met, as discussed in Section 6. 252 2.2.3. Authorization Claims 254 If an authorization request includes a scope parameter, the 255 corresponding issued JWT access token SHOULD include a scope claim as 256 defined in section 4.2 of [RFC8693]. 258 All the individual scopes strings in the scope claim MUST have 259 meaning for the resource indicated in the aud claim. 261 2.2.3.1. Claims for Authorization Outside of Delegation Scenarios 263 Many authorization servers embed in the access tokens they issue 264 authorization attributes that go beyond the delegated scenarios 265 described by [RFC7519]. Typical examples include resource owner 266 memberships in roles and groups that are relevant to the resource 267 being accessed, entitlements assigned to the resource owner for the 268 targeted resource that the authorization server knows about, and so 269 on. 271 An authorization server wanting to include such attributes in a JWT 272 access token SHOULD use as claim types the attributes described by 273 section 4.1.2 of SCIM Core ( [RFC7643]) and in particular roles, 274 groups and entitlements. As in their original definition in 275 [RFC7643] , this profile does not provide a specific vocabulary for 276 those entities. The Section 7 section of this document does provide 277 entries for registering the roles, groups and entitlements attributes 278 from [RFC7643] as claim types to be used in this profile. 280 3. Requesting a JWT Access Token 282 An authorization server can issue a JWT access token in response to 283 any authorization grant defined by [RFC6749] and subsequent 284 extensions meant to result in an access token. 286 Every JWT access token MUST include an aud claim (see Section 2.2). 288 If the request includes a resource parameter (as defined in 289 [RFC8707]), the resulting JWT access token aud claim SHOULD have the 290 same value as the resource parameter in the request. 292 Example request below: 294 GET /as/authorization.oauth2?response_type=code 295 &client_id=s6BhdRkqt3&state=laeb 296 &scope=openid%20profile%20reademail 297 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 298 &resource=https%3A%2F%2Frs.example.com%2F HTTP/1.1 299 Host: authorization-server.example.com 301 Figure 1: Authorization Request with Resource and Scope Parameters 303 Once redeemed, the code obtained from the request above will result 304 in a JWT access token in the form shown below: 306 {"typ":"at+JWT","alg":"RS256","kid":"RjEwOwOA"} 307 { 308 "iss": "https://authorization-server.example.com/", 309 "sub": " 5ba552d67", 310 "aud": "https://rs.example.com/", 311 "exp": 1544645174, 312 "client_id": "s6BhdRkqt3_", 313 "scope": "openid profile reademail" 314 } 316 Figure 2: A JWT Access Token 318 If it receives a request for an access token containing more than one 319 resource parameter, an authorization server issuing JWT access tokens 320 MUST reject the request and fail with "invalid_request" as described 321 in section 4.1.2.1 of [RFC6749] or with "invalid_target" as defined 322 in section 2 of [RFC8707]. See Section 2.2 and Section 5 for more 323 details on how this measure ensures there's no confusion on to what 324 resource the access token granted scopes apply. 326 If the request does not include a resource parameter, the 327 authorization server MUST use in the aud claim a default resource 328 indicator. If a scope parameter is present in the request, the 329 authorization server SHOULD use it to infer the value of the default 330 resource indicator to be used in the aud claim. The mechanism 331 through which scopes are associated to default resource indicator 332 values is outside the scope of this specification. If the values in 333 the scope parameter refer to different default resource indicator 334 values, the authorization server SHOULD reject the request with 335 invalid_scope as described in section 4.1.2.1 of [RFC6749]. 337 4. Validating JWT Access Tokens 339 For the purpose of facilitating validation data retrieval, it is 340 RECOMMENDED that authorization servers sign JWT access tokens with an 341 asymmetric algorithm. 343 Authorization servers SHOULD implement OAuth 2.0 Authorization Server 344 Metadata [RFC8414] to advertise to resource servers its signing keys 345 via jwks_uri and what iss claim value to expect via the issuer 346 metadata value. Alternatively, authorization servers implementing 347 OpenID Connect MAY use the OpenID Connect discovery document for the 348 same purpose. If an authorization server supports both AS metadata 349 and Openid discovery, the values provided MUST be consistent across 350 the two publication methods. 352 An authorization server MAY elect to use different keys to sign 353 id_tokens and JWT access tokens. 355 When invoked as described in OAuth 2.0 Bearer Token Usage [RFC6750], 356 resource servers receiving a JWT access token MUST validate it in the 357 following manner. 359 1. The resource server MUST verify that the typ header value is 360 at+jwt and reject tokens carrying any other value. 362 2. If the JWT access token is encrypted, decrypt it using the keys 363 and algorithms that the resource server specified during 364 registration. If encryption was negotiated with the 365 authorization server at registration time and the incoming JWT 366 access token is not encrypted, the resource server SHOULD reject 367 it. 369 3. The Issuer Identifier for the authorization server (which is 370 typically obtained during discovery) MUST exactly match the value 371 of the iss claim. 373 4. The resource server MUST validate that the aud claim contains the 374 resource indicator value corresponding to the identifier the 375 resource server expects for itself. The JWT access token MUST be 376 rejected if aud does not contain the resource indicator of the 377 current resource server as a valid audience. 379 5. The resource server MUST validate the signature of all incoming 380 JWT access tokens according to [RFC7515] using the algorithm 381 specified in the JWT alg Header Parameter. The resource server 382 MUST reject any JWT in which the value of "alg" is "none". The 383 resource server MUST use the keys provided by the authorization 384 server. 386 6. The current time MUST be before the time represented by the exp 387 claim. 389 7. If the auth_time claim is present, the resource server SHOULD 390 check the auth_time value and request re-authentication if it 391 determines too much time has elapsed since the last resource 392 owner authentication. 394 If the JWT access token includes authorization claims as described in 395 the authorization claims section, the resource server SHOULD use them 396 in combination with any other contextual information available to 397 determine whether the current call should be authorized or rejected. 398 Details about how a resource server performs those checks is beyond 399 the scope of this profile specification. 401 5. Security Considerations 403 The JWT access token data layout described here is very similar to 404 the one of the id_token as defined by [OpenID.Core]. The explicit 405 typing required in this profile, in line with the recommendations in 406 [RFC8725] helps the resource server to distinguish between JWT access 407 tokens and id_tokens. 409 Authorization servers should prevent scenarios where clients can 410 affect the value of the sub claim in ways that could confuse resource 411 servers. For example: if the authorization server elects to use the 412 client_id as the sub value for access tokens issued client 413 credentials grant, the authorization server should prevent clients to 414 register an arbitrary client_id value, as this would allow malicious 415 clients to select the sub of a high privilege resource owner and 416 confuse any authorization logic on the resource server relying on the 417 sub value. For more details please refer to section 4.13 of 418 [OAuth2.Security.BestPractices]. 420 To preventing cross-JWT confusion, authorization servers MUST use a 421 distinct identifier as "aud" claim value to uniquely identify access 422 tokens issued by the same issuer for distinct resources. 424 This profile explicitly forbids the use of multi value aud claim when 425 the individual values refer to different resources, as that would 426 introduce confusion about what scopes apply to which resource- 427 possibly opening up avenues for elevation of delegated privileges 428 attacks. Alternative techniques to prevent scope confusion include 429 "scope stuffing", imposing to every individual scope string to 430 include a reference to the resource they are meant to be applied to, 431 but its application is problematic (scope opacity violations, size 432 inflation, more error conditions become possible when the combination 433 of requested scopes and resource indicators is invalid) and the 434 observed frequency of the scenario doesn't warrant complicating the 435 more common cases. 437 6. Privacy Considerations 439 As JWT access tokens carry information by value, it now becomes 440 possible for requestors and receivers to directly peek inside the 441 token claims collection. The client MUST NOT inspect the content of 442 the access token: the authorization server and the resource server 443 might decide to change token format at any time (for example by 444 switching from this profile to opaque tokens) hence any logic in the 445 client relying on the ability to read the access token content would 446 break without recourse. Nonetheless, authorization servers should 447 not assume that clients will comply with the above. Whenever client 448 access to the access token content presents privacy issues for a 449 given scenario, the authorization server should take explicit steps 450 to prevent it as described below. 452 In scenarios in which JWT access tokens are accessible to the end 453 user, it should be evaluated whether the information can be accessed 454 without privacy violations (for example, if an end user would simply 455 access his or her own personal information) or if steps must be taken 456 to enforce cofidentiality. Possible measures include: encrypting the 457 access token, encrypting the sensitive claims, omitting the sensitive 458 claims or not using this profile, falling back on opaque access 459 tokens. 461 In every scenario, the content of the JWT access token will 462 eventually be accessible to the resource server. It's important to 463 evaluate whether the resource server gained the proper entitlement to 464 have access to any content received in form of claims, for example 465 through user consent in some form, policies and agreements with the 466 organization running the authorization servers, and so on. 468 7. IANA Considerations 470 7.1. Media Type Registration 471 7.1.1. Registry Content 473 This section registers the "application/at+jwt" media type [RFC2046] 474 in the "Media Types" registry [IANA.MediaTypes] in the manner 475 described in [RFC6838], which can be used to indicate that the 476 content is an access token encoded in JWT format. 478 o Type name: application 480 o Subtype name: at+jwt 482 o Required parameters: N/A 484 o Optional parameters: N/A 486 o Encoding considerations: binary; JWT values are encoded as a 487 series of base64url-encoded values (with trailing '=' characters 488 removed), some of which may be the empty string, separated by 489 period ('.') characters. 491 o Security considerations: See the Security Considerations 492 Section of [[TODO: update once there's a RFC number for the JWT AT 493 profile]] 495 o Interoperability considerations: N/A 497 o Published specification: [[TODO: update once there's a RFC number 498 for the JWT AT profile]] 500 o Applications that use this media type: Applications that access 501 resource servers using OAuth2 access tokens encoded in JTW format 503 o Fragment identifier considerations: N/ 505 o Additional information: Magic number(s): N/A File extension(s): N/ 506 A Macintosh file type code(s): N/A 508 o Person and email address to contact for further information: 509 Vittorio Bertocci, vittorio@auth0.com 511 o Intended usage: COMMON 513 o Restrictions on usage: none 515 o Author: Vittorio Bertocci, vittorio@auth0.com 517 o Change controller: IESG 518 o Provisional registration? No 520 7.2. Claims Registration 522 Section Section 2.2.3.1 of this specification refers to the 523 attributes "roles","groups", "entitlements" defined in [RFC7643] to 524 express authorization information in JWT access tokens. This section 525 registers those attributes as claims in the JSON Web Token (JWT) IANA 526 registry introduced in [RFC7519]. 528 7.2.1. Registry Contents 530 o Claim Name: "roles" 532 o Claim Description: Roles 534 o Change Controller: IESG 536 o Specification Document(s): section 4.1.2 of [RFC7643] and section 537 2.2.2.1 of [[this specification]] 539 o Claim Name: "groups" 541 o Claim Description: Groups 543 o Change Controller: IESG 545 o Specification Document(s): section 4.1.2 of [RFC7643] and section 546 2.2.2.1 of [[this specification]] 548 o Claim Name: "entitlements" 550 o Claim Description: Entitlements 552 o Change Controller: IESG 554 o Specification Document(s): section 4.1.2 of [RFC7643] and section 555 2.2.2.1 of [[this specification]] 557 8. References 559 8.1. Normative References 561 [IANA.OAuth.Parameters] 562 IANA, "OAuth Parameters", 563 . 565 [OAuth2.Security.BestPractices] 566 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 567 "OAuth 2.0 Security Best Current Practice", July 2019. 569 [OpenID.Core] 570 Sakimura, N., Bradley, J., Jones, M., Medeiros, B., and C. 571 Mortimore, "OpenID Connect Core 1.0", November 2014. 573 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 574 Extensions (MIME) Part Two: Media Types", RFC 2046, 575 DOI 10.17487/RFC2046, November 1996, 576 . 578 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 579 Requirement Levels", BCP 14, RFC 2119, 580 DOI 10.17487/RFC2119, March 1997, 581 . 583 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 584 Resource Identifier (URI): Generic Syntax", STD 66, 585 RFC 3986, DOI 10.17487/RFC3986, January 2005, 586 . 588 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 589 RFC 6749, DOI 10.17487/RFC6749, October 2012, 590 . 592 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 593 Specifications and Registration Procedures", BCP 13, 594 RFC 6838, DOI 10.17487/RFC6838, January 2013, 595 . 597 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 598 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 599 2015, . 601 [RFC7643] Hunt, P., Ed., Grizzle, K., Wahlstroem, E., and C. 602 Mortimore, "System for Cross-domain Identity Management: 603 Core Schema", RFC 7643, DOI 10.17487/RFC7643, September 604 2015, . 606 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 607 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 608 May 2017, . 610 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 611 Authorization Server Metadata", RFC 8414, 612 DOI 10.17487/RFC8414, June 2018, 613 . 615 [RFC8693] Jones, M., Nadalin, A., Campbell, B., Ed., Bradley, J., 616 and C. Mortimore, "OAuth 2.0 Token Exchange", RFC 8693, 617 DOI 10.17487/RFC8693, January 2020, 618 . 620 [RFC8707] Campbell, B., Bradley, J., and H. Tschofenig, "Resource 621 Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, 622 February 2020, . 624 [RFC8725] Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best 625 Current Practices", BCP 225, RFC 8725, 626 DOI 10.17487/RFC8725, February 2020, 627 . 629 8.2. Informative References 631 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 632 Framework: Bearer Token Usage", RFC 6750, 633 DOI 10.17487/RFC6750, October 2012, 634 . 636 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 637 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 638 . 640 [RFC7644] Hunt, P., Ed., Grizzle, K., Ansari, M., Wahlstroem, E., 641 and C. Mortimore, "System for Cross-domain Identity 642 Management: Protocol", RFC 7644, DOI 10.17487/RFC7644, 643 September 2015, . 645 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 646 RFC 7662, DOI 10.17487/RFC7662, October 2015, 647 . 649 Appendix A. Acknowledgements 651 The initial set of requirements informing this specification was 652 extracted by numerous examples of access tokens issued in JWT format 653 by production systems. Thanks to Dominick Bauer (IdentityServer), 654 Brian Campbell (Ping Identity), Daniel Dobalian (Microsoft), Karl 655 Guinness (Okta) for providing sample tokens issued by their products 656 and services. Brian Campbell and Filip Skokan provided early 657 feedback that shaped the direction of the specification. This 658 profile was discussed at lenght during the OAuth Security Workshop 659 2019, with several individuals contributing ideas and feedback. The 660 author would like to acknowledge the contributions of: 662 John Bradley, Brian Campbell, Vladimir Dzhuvinov, Torsten 663 Lodderstedt, Nat Sakimura, Hannes Tschofenig and everyone who 664 actively participated in the unconference discussions. 666 The following individuals contributed useful feedback and insights on 667 the initial draft, both on the IETF OAuth2 WG DL and during the IIW28 668 conference: 670 Dale Olds, George Fletcher, David Waite, Michael Engan, Mike Jones, 671 Hans Zandbelt, Vladimir Dzhuvinov, Martin Schanzenbach , Aaron 672 Parecki, Annabelle Richard Backman and everyone who actively 673 participated in the IIW28 unconference discussions and the IETF 674 OAuth2 WG DL discussions. 676 Appendix B. Document History 678 [[ to be removed by the RFC Editor before publication as an RFC ]] 680 draft-ietf-oauth-access-token-jwt-04 682 o Eliminated reference to resource aliases list from the aud claim 683 description in Section 2. 684 o Eliminated references to resource aliases list from the aud 685 validation guidance in Section 4. 686 o Introduced a new subsection Section 2.2.1, moved the definitions 687 of auth_time, acr and amr there and incorporated the language 688 proposed by Annabelle and Brian on the WG mailing list. 689 o In section Section 3 softened (from MUST to SHOULD) the 690 requirement that ties the resource identifier in the request to 691 the value in the aud claim of the issued access token. 692 o Updated acknowledgements. 693 o In the section Section 3, the example request now has 694 response_type=code. 695 o Updated text in the Privacy Consideration section to clarify what 696 protection steps the text refers to. 697 o Updated the typ header discussion in Section 2.1 to clarify that 698 it helps preventing resources from accepting id_tokens as JWT 699 access tokens. 700 o Updated refrences to token exchange, resource indicators and JWT 701 best practices to reflect their RFC status (8793,8707,8725). 703 draft-ietf-oauth-access-token-jwt-03 705 o Varios typos fixed. 707 o In the security considerations section, relaxed the claim that the 708 typ header value "at+jwt" will prevent RS from misinterpreting JWT 709 ATs as idtokens. 710 o In the "Requesting JWT Access Tokens" section, added 711 "invalid_target" as a possible error returned for the multiple 712 resources request case. 713 o In the Validating JWT Access Tokens" section, disallowed JWTs with 714 "alg":"none" 715 o in the IANA registration entries for the SCIM claim types, 716 complemented the reference to the SCIM spec with a reference to 717 this spec so that the eventual registration entries have better 718 context. 719 o Updated acknowledgements. 720 o In the section Section 3, the example request now has 721 response_type=code. 722 o Updated text in the Privacy Consideration section to clarify what 723 protection steps the text refers to. 725 draft-ietf-oauth-access-token-jwt-02 727 o In 2.2.1, opened the sources of identity attributes to any 728 identity related specification. 729 o In 2.2.2, relaxed from MUST to SHOULD the requirement that 730 requests including a scope always result in access tkens 731 containing a corresponding scope claim. 732 o In the security considerations setting, added a requirement for 733 the authorization server to assing unique identifiers for 734 different resources- to prevent cross JWT confusion. 735 o Added IANA registration for the authorization attributes borrowed 736 from SCIM CORE 738 draft-ietf-oauth-access-token-jwt-01 740 o Added note on authenticated encryption. 741 o Added a mention to the 1st party clients scenarios in the identity 742 claims section. 743 o Changed the definition reference for the iss, exp, aud, sub, iat 744 claims from OpenID.Core to RFC7519. 745 o Added a mention of the client_id==sub case in the security 746 considerations section, added a reference to draft-ietf-oauth- 747 security-topics-13. Added a reference to the security 748 considerations from the sub claim definition section. 749 o Specified invalid_request as the error code the authorization 750 server should return in case of multiple resources in the access 751 token request. 752 o Specified invalid_scope as the error code the authorization server 753 should return in case it isn;t possible to determine to which 754 resource the requested scopes refers to. 756 o In the identity claims section, added a reference to introspection 757 as possible source of claim types and added language explicitly 758 stating that the AS can add arbitrary attributes as long as they 759 are collision resistant or private. 760 o Updated language for the auth_time claim to include the case in 761 which the AS reauthenticates the user mid-session (e.g. during 762 step up auth). 763 o Removed note about adding a mechanism for extablishing whether the 764 token was obtained on behalf or the resource owner or of the 765 client itself (client credentials grant). 766 o Removed note about adding a mechanism for indicating whether the 767 authorization server sent the resource owner to authenticate with 768 a federated identity provider, and the identity of that federated 769 provider. 770 o Removed the note in the security consideration sections about 771 discussing the purpose of aud, iss, exp validation (redundant). 772 o In the authorization claims section, stated intent to register 773 roles, groups and entitlements as claim types in IANA 774 o Clarified in the privacy considerations that clients should not 775 inspect access tokens. 776 o Expanded the privacy considerations with more explicit guidance 777 about privacy preserving approaches. 778 o Added IANA registry content for the at+JWT MIME type. 779 o Updated acknowledgements. 781 draft-ietf-oauth-access-token-jwt-00 783 o Initial draft to define a JWTt profile for OAuth 2.0 access 784 tokens. 786 Author's Address 788 Vittorio Bertocci 789 Auth0 791 Email: vittorio@auth0.com