idnits 2.17.1 draft-ietf-oauth-access-token-jwt-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 : ---------------------------------------------------------------------------- == 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 31, 2020) is 1487 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 599, but no explicit reference was found in the text == Unused Reference: 'RFC7644' is defined on line 656, 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 31, 2020 5 Expires: October 2, 2020 7 JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens 8 draft-ietf-oauth-access-token-jwt-05 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 October 2, 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 . . . . . . . . . . . . . . . . . . . . . 11 67 7.1. Media Type Registration . . . . . . . . . . . . . . . . . 11 68 7.1.1. Registry Content . . . . . . . . . . . . . . . . . . 11 69 7.2. Claims Registration . . . . . . . . . . . . . . . . . . . 12 70 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 12 71 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 72 8.1. Normative References . . . . . . . . . . . . . . . . . . 13 73 8.2. Informative References . . . . . . . . . . . . . . . . . 14 74 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 14 75 Appendix B. Document History . . . . . . . . . . . . . . . . . . 15 76 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 18 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 83 scenarios, in-market use has shown that many commercial OAuth 2.0 84 implementations elected to issue access tokens using a format that 85 can be parsed and validated by resource servers directly, without 86 further authorization server involvement. The approach is 87 particularly common in topologies where the authorization server and 88 resource server are not co-located, are not run by the same entity, 89 or are otherwise separated by some boundary. At the time of writing, 90 many commercial implementations leverage the JSON Web Tokens(JWT) 91 [RFC7519] format. 93 Many vendor specific JWT access tokens share the same functional 94 layout, using JWT claims to convey the information needed to support 95 a common set of use cases: token validation, transporting 96 authorization information in forms of scopes and entitlements, 97 carrying identity information about the subject, and so on. The 98 differences are mostly confined to the claim names and syntax used to 99 represent the same entities, suggesting that interoperability could 100 be easily achieved by standardizing on a common set of claims and 101 validation rules. 103 The assumption that access tokens are associated to specific 104 information doesn't appear only in commercial implementations. 105 Various specifications in the OAuth 2.0 family (such as resource 106 indicators [RFC8707], OAuth 2.0 bearer token usage [RFC6750] and 107 others) postulate the presence in access tokens of scoping 108 mechanisms, such as an audience. The family of specifications 109 associated to introspection also indirectly suggest a fundamental set 110 of information access tokens are expected to carry or at least be 111 associated with. 113 This specification aims to provide a standardized and interoperable 114 profile as an alternative to the proprietary JWT access token layouts 115 going forward. Besides defining a common set of mandatory and 116 optional claims, the profile provides clear indications on how 117 authorization request parameters determine the content of the issued 118 JWT access token, how an authorization server can publish metadata 119 relevant to the JWT access tokens it issues, and how a resource 120 server should validate incoming JWT access tokens. 122 Finally, this specification provides security and privacy 123 considerations meant to prevent common mistakes and anti patterns 124 that are likely to occur in naive use of the JWT format to represent 125 access tokens. 127 1.1. Requirements Notation and Conventions 129 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 130 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 131 "OPTIONAL" in this document are to be interpreted as described in BCP 132 14 [RFC2119] [RFC8174] when, and only when, they appear in all 133 capitals, as shown here. 135 1.2. Terminology 137 JWT access token An OAuth 2.0 access token encoded in JWT format and 138 complying with the requirements described in this specification. 140 This specification uses the terms "access token", "refresh token", 141 "authorization server", "resource server", "authorization endpoint", 142 "authorization request", "authorization response", "token endpoint", 143 "grant type", "access token request", "access token response", and 144 "client" defined by The OAuth 2.0 Authorization Framework [RFC6749]. 146 2. JWT Access Token Header and Data Structure 148 JWT access tokens are regular JWTs complying with the requirements 149 described in this section. 151 2.1. Header 153 Although JWT access tokens can use any signing algorithm, use of 154 asymmetric algorithms is RECOMMENDED as it simplifies the process of 155 acquiring validation information for resource servers (see 156 Section 4). 158 NOTE: there were discussions about adding a reference to 159 authenticated encryption methods as well, but there's no internet 160 draft specifying interoperable public key methods at this time 162 This specification registers the "application/at+jwt" media type, 163 which can be used to indicate that the content is an access token. 164 JWT access tokens MUST include this media type in the "typ" header 165 parameter to explicitly declare that the JWT represents an access 166 token complying with this profile. Per the definition of "typ" in 167 Section 4.1.9 of [RFC7515], it is RECOMMENDED that the "application/" 168 prefix be omitted. Therefore,the "typ" value used SHOULD be 169 "at+jwt". See the security considerations section for details on the 170 importance of preventing OpenID Connect ID Tokens from being accepted 171 as access tokens by resource servers implementing this profile. 173 2.2. Data Structure 175 The following claims are used in the JWT access token data structure. 177 iss REQUIRED - as defined in section 4.1.1 of [RFC7519]. 179 exp REQUIRED - as defined in section 4.1.4 of [RFC7519]. 181 aud REQUIRED - as defined in section 4.1.3 of [RFC7519]. See 182 Section 3 for indications on how an authorization server should 183 determine the value of aud depending on the request. 185 sub REQUIRED - as defined in section 4.1.2 of [RFC7519]. In case of 186 access tokens obtained through grants where no resource owner is 187 involved, such as the client credentials grant, the value of sub 188 SHOULD correspond to an identifier the authorization server uses 189 to indicate the client application. Please see Section 5 for more 190 details on this scenario. 192 client_id REQUIRED - as defined in section 4.3 of [RFC8693]. 194 iat RECOMMENDED - as defined in section 4.1.6 of [RFC7519]. This 195 claim identifies the time at which the JWT access token was 196 issued. 198 jti RECOMMENDED - as defined in section 4.1.7 of [RFC7519]. 200 2.2.1. Authentication Information Claims 202 The claims listed in this section reflect in the access token the 203 types and strength of authentication that the authentication server 204 enforced prior to returning the authorization response to the client. 205 Their values are fixed, and remain the same across all access tokens 206 that derive from a given authorization response, whether the access 207 token was obtained directly in the response (e.g., via the implicit 208 flow) or after one or more token exchanges (e.g., obtaining a fresh 209 access token using a refresh token, or exchanging one access token 210 for another via [RFC8693]). 212 auth_time OPTIONAL - as defined in section 2 of [OpenID.Core]. 214 acr, amr OPTIONAL - as defined in section 2 of [OpenID.Core]. 216 2.2.2. Identity Claims 218 Commercial authorization servers will often include resource owner 219 attributes directly in access tokens, so that resource servers can 220 consume them directly for authorization or other purposes without any 221 further round trips to introspection ( [RFC7662]) or userinfo ( 222 [OpenID.Core]) endpoints. This is particularly common in scenarios 223 where the client and the resource server belong to the same entity 224 and are part of the same solution, as is the case for first party 225 clients invoking their own backend API. 227 This profile does not introduce any mechanism for a client to 228 directly request the presence of specific claims in JWT access 229 tokens, as the authorization server can determine what additional 230 claims are required by a particular resource server by taking in 231 consideration the client_id of the client, the scope and the resource 232 parameters included in the request. 234 Any additional attributes whose semantics are well described by the 235 attribute's description found in section 5.1 of [OpenID.Core] SHOULD 236 be codified in JWT access tokens via the corresponding claim names in 237 that section of the OpenID Connect specification. The same holds for 238 attributes defined in [RFC7662] and other identity related 239 specifications registering claims in the JSON Web Token (JWT) IANA 240 registry introduced in [RFC7519]. 242 Authorization servers MAY return arbitrary attributes not defined in 243 any existing specification, as long as the corresponding claim names 244 are collision resistant or the access tokens are meant to be used 245 only within a private subsystem. Please refer to sections 4.2 and 246 4.3 of [RFC7519] for details. 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 scope strings in the scope claim MUST have meaning 259 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. Section 7 of this document does provide entries for 277 registering the roles, groups and entitlements attributes from 278 [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 If the request includes a resource parameter (as defined in 287 [RFC8707]), the resulting JWT access token aud claim SHOULD have the 288 same value as the resource parameter in the request. 290 Example request below: 292 GET /as/authorization.oauth2?response_type=code 293 &client_id=s6BhdRkqt3&state=laeb 294 &scope=openid%20profile%20reademail 295 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 296 &resource=https%3A%2F%2Frs.example.com%2F HTTP/1.1 297 Host: authorization-server.example.com 299 Figure 1: Authorization Request with Resource and Scope Parameters 301 Once redeemed, the code obtained from the request above will result 302 in a JWT access token in the form shown below: 304 {"typ":"at+JWT","alg":"RS256","kid":"RjEwOwOA"} 305 { 306 "iss": "https://authorization-server.example.com/", 307 "sub": " 5ba552d67", 308 "aud": "https://rs.example.com/", 309 "exp": 1544645174, 310 "client_id": "s6BhdRkqt3_", 311 "scope": "openid profile reademail" 312 } 314 Figure 2: A JWT Access Token 316 If it receives a request for an access token containing more than one 317 resource parameter, an authorization server issuing JWT access tokens 318 MUST reject the request and fail with "invalid_request" as described 319 in section 4.1.2.1 of [RFC6749] or with "invalid_target" as defined 320 in section 2 of [RFC8707]. See Section 2.2 and Section 5 for more 321 details on how this measure ensures there's no confusion on to what 322 resource the access token granted scopes apply. 324 If the request does not include a resource parameter, the 325 authorization server MUST use in the aud claim a default resource 326 indicator. If a scope parameter is present in the request, the 327 authorization server SHOULD use it to infer the value of the default 328 resource indicator to be used in the aud claim. The mechanism 329 through which scopes are associated to default resource indicator 330 values is outside the scope of this specification. If the values in 331 the scope parameter refer to different default resource indicator 332 values, the authorization server SHOULD reject the request with 333 invalid_scope as described in section 4.1.2.1 of [RFC6749]. 335 4. Validating JWT Access Tokens 337 For the purpose of facilitating validation data retrieval, it is 338 RECOMMENDED that authorization servers sign JWT access tokens with an 339 asymmetric algorithm. 341 Authorization servers SHOULD implement OAuth 2.0 Authorization Server 342 Metadata [RFC8414] to advertise to resource servers its signing keys 343 via jwks_uri and what iss claim value to expect via the issuer 344 metadata value. Alternatively, authorization servers implementing 345 OpenID Connect MAY use the OpenID Connect discovery document for the 346 same purpose. If an authorization server supports both AS metadata 347 and OpenID Connect discovery, the values provided MUST be consistent 348 across the two publication methods. 350 An authorization server MAY elect to use different keys to sign 351 OpenID Connect ID Tokens and JWT access tokens. This specification 352 does not provide a mechanism for identifying a specific key as the 353 one used to sign JWT access tokens. An authorization server can sign 354 JWT access tokens with any of the keys advertised via AS metadata or 355 OpenID Connect discovery. Please see section Section 5 for further 356 guidance on security implications. 358 When invoked as described in OAuth 2.0 Bearer Token Usage [RFC6750], 359 resource servers receiving a JWT access token MUST validate it in the 360 following manner. 362 o The resource server MUST verify that the typ header value is 363 at+jwt and reject tokens carrying any other value. 365 o If the JWT access token is encrypted, decrypt it using the keys 366 and algorithms that the resource server specified during 367 registration. If encryption was negotiated with the authorization 368 server at registration time and the incoming JWT access token is 369 not encrypted, the resource server SHOULD reject it. 371 o The Issuer Identifier for the authorization server (which is 372 typically obtained during discovery) MUST exactly match the value 373 of the iss claim. 375 o The resource server MUST validate that the aud claim contains the 376 resource indicator value corresponding to the identifier the 377 resource server expects for itself. The JWT access token MUST be 378 rejected if aud does not contain the resource indicator of the 379 current resource server as a valid audience. 381 o The resource server MUST validate the signature of all incoming 382 JWT access tokens according to [RFC7515] using the algorithm 383 specified in the JWT alg Header Parameter. The resource server 384 MUST reject any JWT in which the value of "alg" is "none". The 385 resource server MUST use the keys provided by the authorization 386 server. 388 o The current time MUST be before the time represented by the exp 389 claim. 391 The resource server MUST handle errors as described in section 3.1 of 392 [RFC6750]. In particular, in case of any failure in the validation 393 checks listed above the authorization server response MUST include 394 the error code "invalid_token". 396 If the JWT access token includes authorization claims as described in 397 the authorization claims section, the resource server SHOULD use them 398 in combination with any other contextual information available to 399 determine whether the current call should be authorized or rejected. 400 Details about how a resource server performs those checks is beyond 401 the scope of this profile specification. 403 5. Security Considerations 405 The JWT access token data layout described here is very similar to 406 the one of the id_token as defined by [OpenID.Core]. The explicit 407 typing required in this profile, in line with the recommendations in 408 [RFC8725] helps the resource server to distinguish between JWT access 409 tokens and OpenID Connect ID Tokens. 411 Authorization servers should prevent scenarios where clients can 412 affect the value of the sub claim in ways that could confuse resource 413 servers. For example: if the authorization server elects to use the 414 client_id as the sub value for access tokens issued client 415 credentials grant, the authorization server should prevent clients to 416 register an arbitrary client_id value, as this would allow malicious 417 clients to select the sub of a high privilege resource owner and 418 confuse any authorization logic on the resource server relying on the 419 sub value. For more details please refer to section 4.13 of 420 [OAuth2.Security.BestPractices]. 422 To preventing cross-JWT confusion, authorization servers MUST use a 423 distinct identifier as "aud" claim value to uniquely identify access 424 tokens issued by the same issuer for distinct resources. 426 This profile explicitly forbids the use of multi value aud claim when 427 the individual values refer to different resources, as that would 428 introduce confusion about what scopes apply to which resource- 429 possibly opening up avenues for elevation of delegated privileges 430 attacks. Alternative techniques to prevent scope confusion include 431 "scope stuffing", imposing to every individual scope string to 432 include a reference to the resource they are meant to be applied to, 433 but its application is problematic (scope opacity violations, size 434 inflation, more error conditions become possible when the combination 435 of requested scopes and resource indicators is invalid) and the 436 observed frequency of the scenario doesn't warrant complicating the 437 more common cases. 439 Authorization servers should not rely on the use of different keys 440 for signing OpenID Connect ID Tokens and JWT tokens as a method to 441 safeguard against the consequences of leaking specific keys. Given 442 that resource servers have no way of knowing what key should be used 443 to validate JWT access tokens in particular, they have to accept 444 signatures performed with any of the keys published in AS metadata or 445 OpennID Connect discovery: consequently, an attacker just needs to 446 compromise any key among the ones published to be able to generate 447 and sign JWT tokens that will be accepted as valid by the resource 448 server. 450 6. Privacy Considerations 452 As JWT access tokens carry information by value, it now becomes 453 possible for requestors and receivers to directly peek inside the 454 token claims collection. The client MUST NOT inspect the content of 455 the access token: the authorization server and the resource server 456 might decide to change token format at any time (for example by 457 switching from this profile to opaque tokens) hence any logic in the 458 client relying on the ability to read the access token content would 459 break without recourse. Nonetheless, authorization servers should 460 not assume that clients will comply with the above. Whenever client 461 access to the access token content presents privacy issues for a 462 given scenario, the authorization server should take explicit steps 463 to prevent it as described below. 465 In scenarios in which JWT access tokens are accessible to the end 466 user, it should be evaluated whether the information can be accessed 467 without privacy violations (for example, if an end user would simply 468 access his or her own personal information) or if steps must be taken 469 to enforce confidentiality. Possible measures include: encrypting 470 the access token, encrypting the sensitive claims, omitting the 471 sensitive claims or not using this profile, falling back on opaque 472 access tokens. 474 In every scenario, the content of the JWT access token will 475 eventually be accessible to the resource server. It's important to 476 evaluate whether the resource server gained the proper entitlement to 477 have access to any content received in form of claims, for example 478 through user consent in some form, policies and agreements with the 479 organization running the authorization servers, and so on. 481 7. IANA Considerations 483 7.1. Media Type Registration 485 7.1.1. Registry Content 487 This section registers the "application/at+jwt" media type [RFC2046] 488 in the "Media Types" registry [IANA.MediaTypes] in the manner 489 described in [RFC6838], which can be used to indicate that the 490 content is an access token encoded in JWT format. 492 o Type name: application 494 o Subtype name: at+jwt 496 o Required parameters: N/A 498 o Optional parameters: N/A 500 o Encoding considerations: binary; JWT values are encoded as a 501 series of base64url-encoded values (with trailing '=' characters 502 removed), some of which may be the empty string, separated by 503 period ('.') characters. 505 o Security considerations: See the Security Considerations 506 Section of [[TODO: update once there's a RFC number for the JWT AT 507 profile]] 509 o Interoperability considerations: N/A 511 o Published specification: [[TODO: update once there's a RFC number 512 for the JWT AT profile]] 514 o Applications that use this media type: Applications that access 515 resource servers using OAuth 2.0 access tokens encoded in JTW 516 format 518 o Fragment identifier considerations: N/ 520 o Additional information: Magic number(s): N/A File extension(s): N/ 521 A Macintosh file type code(s): N/A 523 o Person and email address to contact for further information: 524 Vittorio Bertocci, vittorio@auth0.com 526 o Intended usage: COMMON 528 o Restrictions on usage: none 530 o Author: Vittorio Bertocci, vittorio@auth0.com 532 o Change controller: IESG 534 o Provisional registration? No 536 7.2. Claims Registration 538 Section Section 2.2.3.1 of this specification refers to the 539 attributes "roles","groups", "entitlements" defined in [RFC7643] to 540 express authorization information in JWT access tokens. This section 541 registers those attributes as claims in the JSON Web Token (JWT) IANA 542 registry introduced in [RFC7519]. 544 7.2.1. Registry Contents 546 o Claim Name: "roles" 548 o Claim Description: Roles 550 o Change Controller: IESG 552 o Specification Document(s): section 4.1.2 of [RFC7643] and section 553 2.2.2.1 of [[this specification]] 555 o Claim Name: "groups" 557 o Claim Description: Groups 559 o Change Controller: IESG 561 o Specification Document(s): section 4.1.2 of [RFC7643] and section 562 2.2.2.1 of [[this specification]] 564 o Claim Name: "entitlements" 566 o Claim Description: Entitlements 568 o Change Controller: IESG 570 o Specification Document(s): section 4.1.2 of [RFC7643] and section 571 2.2.2.1 of [[this specification]] 573 8. References 575 8.1. Normative References 577 [IANA.OAuth.Parameters] 578 IANA, "OAuth Parameters", 579 . 581 [OAuth2.Security.BestPractices] 582 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 583 "OAuth 2.0 Security Best Current Practice", July 2019. 585 [OpenID.Core] 586 Sakimura, N., Bradley, J., Jones, M., Medeiros, B., and C. 587 Mortimore, "OpenID Connect Core 1.0", November 2014. 589 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 590 Extensions (MIME) Part Two: Media Types", RFC 2046, 591 DOI 10.17487/RFC2046, November 1996, 592 . 594 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 595 Requirement Levels", BCP 14, RFC 2119, 596 DOI 10.17487/RFC2119, March 1997, 597 . 599 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 600 Resource Identifier (URI): Generic Syntax", STD 66, 601 RFC 3986, DOI 10.17487/RFC3986, January 2005, 602 . 604 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 605 RFC 6749, DOI 10.17487/RFC6749, October 2012, 606 . 608 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 609 Specifications and Registration Procedures", BCP 13, 610 RFC 6838, DOI 10.17487/RFC6838, January 2013, 611 . 613 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 614 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 615 2015, . 617 [RFC7643] Hunt, P., Ed., Grizzle, K., Wahlstroem, E., and C. 618 Mortimore, "System for Cross-domain Identity Management: 619 Core Schema", RFC 7643, DOI 10.17487/RFC7643, September 620 2015, . 622 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 623 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 624 May 2017, . 626 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 627 Authorization Server Metadata", RFC 8414, 628 DOI 10.17487/RFC8414, June 2018, 629 . 631 [RFC8693] Jones, M., Nadalin, A., Campbell, B., Ed., Bradley, J., 632 and C. Mortimore, "OAuth 2.0 Token Exchange", RFC 8693, 633 DOI 10.17487/RFC8693, January 2020, 634 . 636 [RFC8707] Campbell, B., Bradley, J., and H. Tschofenig, "Resource 637 Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, 638 February 2020, . 640 [RFC8725] Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best 641 Current Practices", BCP 225, RFC 8725, 642 DOI 10.17487/RFC8725, February 2020, 643 . 645 8.2. Informative References 647 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 648 Framework: Bearer Token Usage", RFC 6750, 649 DOI 10.17487/RFC6750, October 2012, 650 . 652 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 653 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 654 . 656 [RFC7644] Hunt, P., Ed., Grizzle, K., Ansari, M., Wahlstroem, E., 657 and C. Mortimore, "System for Cross-domain Identity 658 Management: Protocol", RFC 7644, DOI 10.17487/RFC7644, 659 September 2015, . 661 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 662 RFC 7662, DOI 10.17487/RFC7662, October 2015, 663 . 665 Appendix A. Acknowledgements 667 The initial set of requirements informing this specification was 668 extracted by numerous examples of access tokens issued in JWT format 669 by production systems. Thanks to Dominick Bauer (IdentityServer), 670 Brian Campbell (Ping Identity), Daniel Dobalian (Microsoft), Karl 671 Guinness (Okta) for providing sample tokens issued by their products 672 and services. Brian Campbell and Filip Skokan provided early 673 feedback that shaped the direction of the specification. This 674 profile was discussed at lenght during the OAuth Security Workshop 675 2019, with several individuals contributing ideas and feedback. The 676 author would like to acknowledge the contributions of: 678 John Bradley, Brian Campbell, Vladimir Dzhuvinov, Torsten 679 Lodderstedt, Nat Sakimura, Hannes Tschofenig and everyone who 680 actively participated in the unconference discussions. 682 The following individuals contributed useful feedback and insights on 683 the initial draft, both on the IETF OAuth 2.0 WG DL and during the 684 IIW28 conference: 686 Dale Olds, George Fletcher, David Waite, Michael Engan, Mike Jones, 687 Hans Zandbelt, Vladimir Dzhuvinov, Martin Schanzenbach , Aaron 688 Parecki, Annabelle Richard Backman and everyone who actively 689 participated in the IIW28 unconference discussions and the IETF OAuth 690 2.0 WG DL discussions. 692 Appendix B. Document History 694 [[ to be removed by the RFC Editor before publication as an RFC ]] 696 draft-ietf-oauth-access-token-jwt-05 698 o Varios typos, grammar issues and improper abbreviations fixed. 699 o Reworded the definition of at+jwt in Section 2.1. 700 o In Section 2.2, clarified that iat refers to the issuance time of 701 the JWT itself. 702 o In Section 2.2.2, added a reference to public/private claims 703 definitions (sections 4.2, 4.3) of [RFC7519]. 704 o In Section 3, removed the paragrah stating that every JWT AT MUST 705 have an aud, as it is already defined in Section 2.2. 706 o Reworded description of the JWT AT adoption landscape in 707 Section 1. 708 o Simplified the individual descriptions of the claims list in 709 Section 2.2.1. 710 o Updated Section 4 and Section 5 to clarify that the AS can use any 711 of the published keys to sign JWT access tokens, and that the AS 712 should not rely on use of different signing keys per token type as 713 a security mechanism. 714 o In Section 2.2 promoted claims iat and jti from OPTIONAL to 715 RECOMMENDED 716 o In Section 4, switched the validation steps list type from numbers 717 to bullets. 719 o In Section 4, eliminated the auth_time instructions from the 720 validation steps list. 721 o In Section 2.2.2, added a reference to the JWT claims registry as 722 source of claims for JWT ATs 723 o In Section 4, clarified that failures in JWT AT validation checks 724 will result in invalid_token. 726 draft-ietf-oauth-access-token-jwt-04 728 o Eliminated reference to resource aliases list from the aud claim 729 description in Section 2. 730 o Eliminated references to resource aliases list from the aud 731 validation guidance in Section 4. 732 o Introduced a new subsection Section 2.2.1, moved the definitions 733 of auth_time, acr and amr there and incorporated the language 734 proposed by Annabelle and Brian on the WG mailing list. 735 o In section Section 3 softened (from MUST to SHOULD) the 736 requirement that ties the resource identifier in the request to 737 the value in the aud claim of the issued access token. 738 o Updated acknowledgements. 739 o In the section Section 3, the example request now has 740 response_type=code. 741 o Updated text in the Privacy Consideration section to clarify what 742 protection steps the text refers to. 743 o Updated the typ header discussion in Section 2.1 to clarify that 744 it helps preventing resources from accepting OpenID Connect ID 745 Tokens as JWT access tokens. 746 o Updated refrences to token exchange, resource indicators and JWT 747 best practices to reflect their RFC status (8693,8707,8725). 749 draft-ietf-oauth-access-token-jwt-03 751 o Varios typos fixed. 752 o In the security considerations section, relaxed the claim that the 753 typ header value "at+jwt" will prevent RS from misinterpreting JWT 754 ATs as idtokens. 755 o In the "Requesting JWT Access Tokens" section, added 756 "invalid_target" as a possible error returned for the multiple 757 resources request case. 758 o In the Validating JWT Access Tokens" section, disallowed JWTs with 759 "alg":"none" 760 o in the IANA registration entries for the SCIM claim types, 761 complemented the reference to the SCIM spec with a reference to 762 this spec so that the eventual registration entries have better 763 context. 764 o Updated acknowledgements. 765 o In the section Section 3, the example request now has 766 response_type=code. 768 o Updated text in the Privacy Consideration section to clarify what 769 protection steps the text refers to. 771 draft-ietf-oauth-access-token-jwt-02 773 o In 2.2.1, opened the sources of identity attributes to any 774 identity related specification. 775 o In 2.2.2, relaxed from MUST to SHOULD the requirement that 776 requests including a scope always result in access tkens 777 containing a corresponding scope claim. 778 o In the security considerations setting, added a requirement for 779 the authorization server to assing unique identifiers for 780 different resources- to prevent cross JWT confusion. 781 o Added IANA registration for the authorization attributes borrowed 782 from SCIM CORE 784 draft-ietf-oauth-access-token-jwt-01 786 o Added note on authenticated encryption. 787 o Added a mention to the 1st party clients scenarios in the identity 788 claims section. 789 o Changed the definition reference for the iss, exp, aud, sub, iat 790 claims from OpenID.Core to RFC7519. 791 o Added a mention of the client_id==sub case in the security 792 considerations section, added a reference to draft-ietf-oauth- 793 security-topics-13. Added a reference to the security 794 considerations from the sub claim definition section. 795 o Specified invalid_request as the error code the authorization 796 server should return in case of multiple resources in the access 797 token request. 798 o Specified invalid_scope as the error code the authorization server 799 should return in case it isn;t possible to determine to which 800 resource the requested scopes refers to. 801 o In the identity claims section, added a reference to introspection 802 as possible source of claim types and added language explicitly 803 stating that the AS can add arbitrary attributes as long as they 804 are collision resistant or private. 805 o Updated language for the auth_time claim to include the case in 806 which the AS reauthenticates the user mid-session (e.g. during 807 step up auth). 808 o Removed note about adding a mechanism for extablishing whether the 809 token was obtained on behalf or the resource owner or of the 810 client itself (client credentials grant). 811 o Removed note about adding a mechanism for indicating whether the 812 authorization server sent the resource owner to authenticate with 813 a federated identity provider, and the identity of that federated 814 provider. 816 o Removed the note in the security consideration sections about 817 discussing the purpose of aud, iss, exp validation (redundant). 818 o In the authorization claims section, stated intent to register 819 roles, groups and entitlements as claim types in IANA 820 o Clarified in the privacy considerations that clients should not 821 inspect access tokens. 822 o Expanded the privacy considerations with more explicit guidance 823 about privacy preserving approaches. 824 o Added IANA registry content for the at+JWT MIME type. 825 o Updated acknowledgements. 827 draft-ietf-oauth-access-token-jwt-00 829 o Initial draft to define a JWTt profile for OAuth 2.0 access 830 tokens. 832 Author's Address 834 Vittorio Bertocci 835 Auth0 837 Email: vittorio@auth0.com