idnits 2.17.1 draft-ietf-oauth-access-token-jwt-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == 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 (April 27, 2020) is 1460 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 622, but no explicit reference was found in the text == Unused Reference: 'RFC7644' is defined on line 679, 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 April 27, 2020 5 Expires: October 29, 2020 7 JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens 8 draft-ietf-oauth-access-token-jwt-07 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 29, 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 . . . . . . . . . . . . . . . . . 15 74 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 15 75 Appendix B. Document History . . . . . . . . . . . . . . . . . . 16 76 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 19 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). JWT access tokens MUST NOT use "none" as the signing 157 algorithm. See Section 4 for more details. 159 This specification registers the "application/at+jwt" media type, 160 which can be used to indicate that the content is an access token. 161 JWT access tokens MUST include this media type in the "typ" header 162 parameter to explicitly declare that the JWT represents an access 163 token complying with this profile. Per the definition of "typ" in 164 Section 4.1.9 of [RFC7515], it is RECOMMENDED that the "application/" 165 prefix be omitted. Therefore, the "typ" value used SHOULD be 166 "at+jwt". See the security considerations section for details on the 167 importance of preventing OpenID Connect ID Tokens from being accepted 168 as access tokens by resource servers implementing this profile. 170 2.2. Data Structure 172 The following claims are used in the JWT access token data structure. 174 iss REQUIRED - as defined in section 4.1.1 of [RFC7519]. 176 exp REQUIRED - as defined in section 4.1.4 of [RFC7519]. 178 aud REQUIRED - as defined in section 4.1.3 of [RFC7519]. See 179 Section 3 for indications on how an authorization server should 180 determine the value of ""aud" depending on the request. 182 sub REQUIRED - as defined in section 4.1.2 of [RFC7519]. In case of 183 access tokens obtained through grants where a resource owner is 184 involved, such as the authorization code grant, the value of "sub" 185 SHOULD correspond to the subject identifier of the resource owner. 186 In case of access tokens obtained through grants where no resource 187 owner is involved, such as the client credentials grant, the value 188 of "sub" SHOULD correspond to an identifier the authorization 189 server uses to indicate the client application. Please see 190 Section 5 for more details on this scenario. Also, please see 191 Section 6 for a discussion about how different choices in 192 assigning "sub" values can impact privacy. 194 client_id REQUIRED - as defined in section 4.3 of [RFC8693]. 196 iat REQUIRED - as defined in section 4.1.6 of [RFC7519]. This claim 197 identifies the time at which the JWT access token was issued. 199 jti REQUIRED - as defined in section 4.1.7 of [RFC7519]. 201 2.2.1. Authentication Information Claims 203 The claims listed in this section MAY be issued in the context of 204 authorization grants involving the resource owner, and reflect in the 205 access token the types and strength of authentication that the 206 authentication server enforced prior to returning the authorization 207 response to the client. Their values are fixed, and remain the same 208 across all access tokens that derive from a given authorization 209 response, whether the access token was obtained directly in the 210 response (e.g., via the implicit flow) or after one or more token 211 exchanges (e.g., obtaining a fresh access token using a refresh 212 token, or exchanging one access token for another via [RFC8693]). 214 auth_time OPTIONAL - as defined in section 2 of [OpenID.Core]. 216 acr, amr OPTIONAL - as defined in section 2 of [OpenID.Core]. 218 2.2.2. Identity Claims 220 In the context of authorization grants involving the resource owner, 221 commercial authorization servers will often include resource owner 222 attributes directly in access tokens, so that resource servers can 223 consume them directly for authorization or other purposes without any 224 further round trips to introspection ( [RFC7662]) or userinfo ( 225 [OpenID.Core]) endpoints. This is particularly common in scenarios 226 where the client and the resource server belong to the same entity 227 and are part of the same solution, as is the case for first party 228 clients invoking their own backend API. 230 This profile does not introduce any mechanism for a client to 231 directly request the presence of specific claims in JWT access 232 tokens, as the authorization server can determine what additional 233 claims are required by a particular resource server by taking in 234 consideration the client_id of the client, the "scope" and the 235 "resource" parameters included in the request. 237 Any additional attributes whose semantics are well described by the 238 attribute's description found in section 5.1 of [OpenID.Core] SHOULD 239 be codified in JWT access tokens via the corresponding claim names in 240 that section of the OpenID Connect specification. The same holds for 241 attributes defined in [RFC7662] and other identity related 242 specifications registering claims in the JSON Web Token (JWT) IANA 243 registry introduced in [RFC7519]. 245 Authorization servers MAY return arbitrary attributes not defined in 246 any existing specification, as long as the corresponding claim names 247 are collision resistant or the access tokens are meant to be used 248 only within a private subsystem. Please refer to sections 4.2 and 249 4.3 of [RFC7519] for details. 251 Authorization servers including resource owner attributes in JWT 252 access tokens should exercise care and verify that all privacy 253 requirements are met, as discussed in Section 6. 255 2.2.3. Authorization Claims 257 If an authorization request includes a scope parameter, the 258 corresponding issued JWT access token SHOULD include a "scope" claim 259 as defined in section 4.2 of [RFC8693]. 261 All the individual scope strings in the "scope" claim MUST have 262 meaning for the resources indicated in the "aud" claim. Please see 263 Section 5 for more considerations about the relationship between 264 scope strings and resources indicated by the "aud" claim. 266 2.2.3.1. Claims for Authorization Outside of Delegation Scenarios 268 Many authorization servers embed in the access tokens they issue 269 authorization attributes that go beyond the delegated scenarios 270 described by [RFC7519]. Typical examples include resource owner 271 memberships in roles and groups that are relevant to the resource 272 being accessed, entitlements assigned to the resource owner for the 273 targeted resource that the authorization server knows about, and so 274 on. 276 An authorization server wanting to include such attributes in a JWT 277 access token SHOULD use as claim types the attributes described by 278 the SCIM Core specification ([RFC7643]), section 4.1.2 and in 279 particular roles, groups and entitlements. This profile does not 280 provide a specific vocabulary for those entities. Section 7 of this 281 document does provide entries for registering the roles, groups and 282 entitlements attributes from [RFC7643] as claim types to be used in 283 this profile. 285 3. Requesting a JWT Access Token 287 An authorization server can issue a JWT access token in response to 288 any authorization grant defined by [RFC6749] and subsequent 289 extensions meant to result in an access token. 291 If the request includes a "resource" parameter (as defined in 292 [RFC8707]), the resulting JWT access token "aud" claim SHOULD have 293 the same value as the "resource" parameter in the request. 295 Example request below: 297 GET /as/authorization.oauth2?response_type=code 298 &client_id=s6BhdRkqt3& 299 state=laeb 300 &scope=openid%20profile%20reademail 301 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 302 &resource=https%3A%2F%2Frs.example.com%2F HTTP/1.1 303 Host: authorization-server.example.com 305 Figure 1: Authorization Request with Resource and Scope Parameters 307 Once redeemed, the code obtained from the request above will result 308 in a JWT access token in the form shown below: 310 {"typ":"at+JWT","alg":"RS256","kid":"RjEwOwOA"} 311 { 312 "iss": "https://authorization-server.example.com/", 313 "sub": " 5ba552d67", 314 "aud": "https://rs.example.com/", 315 "exp": 1544645174, 316 "client_id": "s6BhdRkqt3_", 317 "scope": "openid profile reademail" 318 } 320 Figure 2: A JWT Access Token 322 The authorization server MUST NOT issue a JWT access token if the 323 authorization granted by the token would be ambiguous. See Section 5 324 for more details about common cases that might lead to ambiguity and 325 strategies an authorization server can enact to prevent them. 327 If the request does not include a "resource" parameter, the 328 authorization server MUST use in the "aud" claim a default resource 329 indicator. If a "scope" parameter is present in the request, the 330 authorization server SHOULD use it to infer the value of the default 331 resource indicator to be used in the "aud" claim. The mechanism 332 through which scopes are associated to default resource indicator 333 values is outside the scope of this specification. If the values in 334 the "scope" parameter refer to different default resource indicator 335 values, the authorization server SHOULD reject the request with 336 "invalid_scope" as described in section 4.1.2.1 of [RFC6749]. 338 4. Validating JWT Access Tokens 340 For the purpose of facilitating validation data retrieval, it is 341 RECOMMENDED that authorization servers sign JWT access tokens with an 342 asymmetric algorithm. 344 Authorization servers SHOULD implement OAuth 2.0 Authorization Server 345 Metadata [RFC8414] to advertise to resource servers its signing keys 346 via "jwks_uri" and what "iss" claim value to expect via the issuer 347 metadata value. Alternatively, authorization servers implementing 348 OpenID Connect MAY use the OpenID Connect discovery document for the 349 same purpose. If an authorization server supports both OAuth 2.0 350 Authorization Server Metadata and OpenID Connect discovery, the 351 values provided MUST be consistent across the two publication 352 methods. 354 An authorization server MAY elect to use different keys to sign 355 OpenID Connect ID Tokens and JWT access tokens. This specification 356 does not provide a mechanism for identifying a specific key as the 357 one used to sign JWT access tokens. An authorization server can sign 358 JWT access tokens with any of the keys advertised via AS metadata or 359 OpenID Connect discovery. Please see section Section 5 for further 360 guidance on security implications. 362 When invoked as described in OAuth 2.0 Bearer Token Usage [RFC6750], 363 resource servers receiving a JWT access token MUST validate it in the 364 following manner. 366 o The resource server MUST verify that the typ header value is 367 "at+jwt" or "application/at+jwt" and reject tokens carrying any 368 other value. 370 o If the JWT access token is encrypted, decrypt it using the keys 371 and algorithms that the resource server specified during 372 registration. If encryption was negotiated with the authorization 373 server at registration time and the incoming JWT access token is 374 not encrypted, the resource server SHOULD reject it. 376 o The Issuer Identifier for the authorization server (which is 377 typically obtained during discovery) MUST exactly match the value 378 of the "iss" claim. 380 o The resource server MUST validate that the "aud" claim contains a 381 resource indicator value corresponding to an identifier the 382 resource server expects for itself. The JWT access token MUST be 383 rejected if "aud" does not contain a resource indicator of the 384 current resource server as a valid audience. 386 o The resource server MUST validate the signature of all incoming 387 JWT access tokens according to [RFC7515] using the algorithm 388 specified in the JWT alg Header Parameter. The resource server 389 MUST reject any JWT in which the value of "alg" is "none". The 390 resource server MUST use the keys provided by the authorization 391 server. 393 o The current time MUST be before the time represented by the "exp" 394 claim. 396 The resource server MUST handle errors as described in section 3.1 of 397 [RFC6750]. In particular, in case of any failure in the validation 398 checks listed above the authorization server response MUST include 399 the error code "invalid_token". 401 If the JWT access token includes authorization claims as described in 402 the authorization claims section, the resource server SHOULD use them 403 in combination with any other contextual information available to 404 determine whether the current call should be authorized or rejected. 405 Details about how a resource server performs those checks is beyond 406 the scope of this profile specification. 408 5. Security Considerations 410 The JWT access token data layout described here is very similar to 411 the one of the id_token as defined by [OpenID.Core]. The explicit 412 typing required in this profile, in line with the recommendations in 413 [RFC8725] helps the resource server to distinguish between JWT access 414 tokens and OpenID Connect ID Tokens. 416 Authorization servers should prevent scenarios where clients can 417 affect the value of the "sub" claim in ways that could confuse 418 resource servers. For example: if the authorization server elects to 419 use the client_id as the "sub" value for access tokens issued client 420 credentials grant, the authorization server should prevent clients to 421 register an arbitrary client_id value, as this would allow malicious 422 clients to select the sub of a high privilege resource owner and 423 confuse any authorization logic on the resource server relying on the 424 "sub" value. For more details please refer to section 4.13 of 425 [OAuth2.Security.BestPractices]. 427 To preventing cross-JWT confusion, authorization servers MUST use a 428 distinct identifier as "aud" claim value to uniquely identify access 429 tokens issued by the same issuer for distinct resources. For more 430 details on cross-JWT confusion please refer to 2.8 of [RFC8725]. 432 Authorization servers should use particular care when handling 433 requests that might lead to ambiguous authorization grants. For 434 example: if a request includes multiple resource indicators, the 435 authorization server should ensure that each scope string included in 436 the resulting JWT access token, if any, can be unambiguously 437 correlated to a specific resource among the ones listed in the "aud" 438 claim. The details on how to recognize and mitigate this and other 439 ambiguous situations is highly scenario-dependent, hence out of scope 440 for this profile. 442 Authorization servers should not rely on the use of different keys 443 for signing OpenID Connect ID Tokens and JWT tokens as a method to 444 safeguard against the consequences of leaking specific keys. Given 445 that resource servers have no way of knowing what key should be used 446 to validate JWT access tokens in particular, they have to accept 447 signatures performed with any of the keys published in AS metadata or 448 OpenID Connect discovery: consequently, an attacker just needs to 449 compromise any key among the ones published to be able to generate 450 and sign JWTs that will be accepted as valid by the resource server. 452 6. Privacy Considerations 454 As JWT access tokens carry information by value, it now becomes 455 possible for requestors and receivers to directly peek inside the 456 token claims collection. The client MUST NOT inspect the content of 457 the access token: the authorization server and the resource server 458 might decide to change token format at any time (for example by 459 switching from this profile to opaque tokens) hence any logic in the 460 client relying on the ability to read the access token content would 461 break without recourse. Nonetheless, authorization servers should 462 not assume that clients will comply with the above. Whenever client 463 access to the access token content presents privacy issues for a 464 given scenario, the authorization server should take explicit steps 465 to prevent it as described below. 467 In scenarios in which JWT access tokens are accessible to the end 468 user, it should be evaluated whether the information can be accessed 469 without privacy violations (for example, if an end user would simply 470 access his or her own personal information) or if steps must be taken 471 to enforce confidentiality. Possible measures include: encrypting 472 the access token, encrypting the sensitive claims, omitting the 473 sensitive claims or not using this profile, falling back on opaque 474 access tokens. 476 In every scenario, the content of the JWT access token will 477 eventually be accessible to the resource server. It's important to 478 evaluate whether the resource server gained the proper entitlement to 479 have access to any content received in form of claims, for example 480 through user consent in some form, policies and agreements with the 481 organization running the authorization servers, and so on. 483 This profile mandates the presence of the "sub" claim in every JWT 484 access token, making it possible for resource servers to rely on that 485 information for performing tasks such as correlating incoming 486 requests with data stored locally for the authenticated principal. 487 Although the ability to correlate requests might be required by 488 design in many scenarios, there are scenarios where the authorization 489 server might want to prevent correlation to preserve the desired 490 level of privacy. Authorization servers should choose how to assign 491 "sub" values according to the level of privacy required by each 492 situation. For instance: if a solution requires preventing tracking 493 principal activities across multiple resource servers, the 494 authorization server should ensure that JWT access tokens meant for 495 different resource servers have distinct "sub" values tht cannot be 496 correlated in the event of resource servers collusion. Similarly: if 497 a solution requires preventing a resource server from correlating the 498 principal's activity within the resource itself, the authorization 499 server should assign different "sub" values for every JWT access 500 token issued. In turn, the client should obtain a new JWT access 501 token for every call to the resource server, to ensure that the 502 resource server receives different "sub" and "jti" values at every 503 call, thus preventing correlation between distinct requests. 505 7. IANA Considerations 507 7.1. Media Type Registration 509 7.1.1. Registry Content 511 This section registers the "application/at+jwt" media type [RFC2046] 512 in the "Media Types" registry [IANA.MediaTypes] in the manner 513 described in [RFC6838], which can be used to indicate that the 514 content is an access token encoded in JWT format. 516 o Type name: application 518 o Subtype name: at+jwt 520 o Required parameters: N/A 522 o Optional parameters: N/A 524 o Encoding considerations: binary; JWT values are encoded as a 525 series of base64url-encoded values (with trailing '=' characters 526 removed), some of which may be the empty string, separated by 527 period ('.') characters. 529 o Security considerations: See the Security Considerations 530 Section of [[TODO: update once there's a RFC number for the JWT AT 531 profile]] 533 o Interoperability considerations: N/A 535 o Published specification: [[TODO: update once there's a RFC number 536 for the JWT AT profile]] 538 o Applications that use this media type: Applications that access 539 resource servers using OAuth 2.0 access tokens encoded in JWT 540 format 542 o Fragment identifier considerations: N/A 544 o Additional information: Magic number(s): N/A File extension(s): N/ 545 A Macintosh file type code(s): N/A 547 o Person and email address to contact for further information: 548 Vittorio Bertocci, vittorio@auth0.com 550 o Intended usage: COMMON 552 o Restrictions on usage: none 554 o Author: Vittorio Bertocci, vittorio@auth0.com 556 o Change controller: IESG 558 o Provisional registration? No 560 7.2. Claims Registration 562 Section Section 2.2.3.1 of this specification refers to the 563 attributes "roles", "groups", "entitlements" defined in [RFC7643] to 564 express authorization information in JWT access tokens. This section 565 registers those attributes as claims in the JSON Web Token (JWT) IANA 566 registry introduced in [RFC7519]. 568 7.2.1. Registry Contents 570 o Claim Name: "roles" 572 o Claim Description: Roles 574 o Change Controller: IESG 575 o Specification Document(s): section 4.1.2 of [RFC7643] and section 576 2.2.2.1 of [[this specification]] 578 o Claim Name: "groups" 580 o Claim Description: Groups 582 o Change Controller: IESG 584 o Specification Document(s): section 4.1.2 of [RFC7643] and section 585 2.2.2.1 of [[this specification]] 587 o Claim Name: "entitlements" 589 o Claim Description: Entitlements 591 o Change Controller: IESG 593 o Specification Document(s): section 4.1.2 of [RFC7643] and section 594 2.2.2.1 of [[this specification]] 596 8. References 598 8.1. Normative References 600 [IANA.OAuth.Parameters] 601 IANA, "OAuth Parameters", 602 . 604 [OAuth2.Security.BestPractices] 605 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 606 "OAuth 2.0 Security Best Current Practice", July 2019. 608 [OpenID.Core] 609 Sakimura, N., Bradley, J., Jones, M., Medeiros, B., and C. 610 Mortimore, "OpenID Connect Core 1.0", November 2014. 612 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 613 Extensions (MIME) Part Two: Media Types", RFC 2046, 614 DOI 10.17487/RFC2046, November 1996, 615 . 617 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 618 Requirement Levels", BCP 14, RFC 2119, 619 DOI 10.17487/RFC2119, March 1997, 620 . 622 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 623 Resource Identifier (URI): Generic Syntax", STD 66, 624 RFC 3986, DOI 10.17487/RFC3986, January 2005, 625 . 627 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 628 RFC 6749, DOI 10.17487/RFC6749, October 2012, 629 . 631 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 632 Specifications and Registration Procedures", BCP 13, 633 RFC 6838, DOI 10.17487/RFC6838, January 2013, 634 . 636 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 637 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 638 2015, . 640 [RFC7643] Hunt, P., Ed., Grizzle, K., Wahlstroem, E., and C. 641 Mortimore, "System for Cross-domain Identity Management: 642 Core Schema", RFC 7643, DOI 10.17487/RFC7643, September 643 2015, . 645 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 646 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 647 May 2017, . 649 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 650 Authorization Server Metadata", RFC 8414, 651 DOI 10.17487/RFC8414, June 2018, 652 . 654 [RFC8693] Jones, M., Nadalin, A., Campbell, B., Ed., Bradley, J., 655 and C. Mortimore, "OAuth 2.0 Token Exchange", RFC 8693, 656 DOI 10.17487/RFC8693, January 2020, 657 . 659 [RFC8707] Campbell, B., Bradley, J., and H. Tschofenig, "Resource 660 Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, 661 February 2020, . 663 [RFC8725] Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best 664 Current Practices", BCP 225, RFC 8725, 665 DOI 10.17487/RFC8725, February 2020, 666 . 668 8.2. Informative References 670 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 671 Framework: Bearer Token Usage", RFC 6750, 672 DOI 10.17487/RFC6750, October 2012, 673 . 675 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 676 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 677 . 679 [RFC7644] Hunt, P., Ed., Grizzle, K., Ansari, M., Wahlstroem, E., 680 and C. Mortimore, "System for Cross-domain Identity 681 Management: Protocol", RFC 7644, DOI 10.17487/RFC7644, 682 September 2015, . 684 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 685 RFC 7662, DOI 10.17487/RFC7662, October 2015, 686 . 688 Appendix A. Acknowledgements 690 The initial set of requirements informing this specification was 691 extracted by numerous examples of access tokens issued in JWT format 692 by production systems. Thanks to Dominick Baier (IdentityServer), 693 Brian Campbell (Ping Identity), Daniel Dobalian (Microsoft), Karl 694 Guinness (Okta) for providing sample tokens issued by their products 695 and services. Brian Campbell and Filip Skokan provided early 696 feedback that shaped the direction of the specification. This 697 profile was discussed at lenght during the OAuth Security Workshop 698 2019, with several individuals contributing ideas and feedback. The 699 author would like to acknowledge the contributions of: 701 John Bradley, Brian Campbell, Vladimir Dzhuvinov, Torsten 702 Lodderstedt, Nat Sakimura, Hannes Tschofenig and everyone who 703 actively participated in the unconference discussions. 705 The following individuals contributed useful feedback and insights on 706 the drafts, both on the IETF OAuth 2.0 WG DL and during the IIW28 707 conference: 709 Dale Olds, George Fletcher, David Waite, Michael Engan, Mike Jones, 710 Hans Zandbelt, Vladimir Dzhuvinov, Martin Schanzenbach , Aaron 711 Parecki, Annabelle Richard Backman, Dick Hardt, Denis Pinkas, 712 Benjamin Kaduk, Dominick Baier, Mike Jones and everyone who actively 713 participated in the IIW28 unconference discussions and the IETF OAuth 714 2.0 WG DL discussions. 716 Appendix B. Document History 718 [[ to be removed by the RFC Editor before publication as an RFC ]] 720 draft-ietf-oauth-access-token-jwt-07 722 o In Section 2.1, added language that forbids use of none as alg 723 value, and references Section 4 where the same prohibition was 724 already expressed from the RS perspective. 725 o In the sub definition in Section 2.2, added a sentence that 726 clarifies what goes in the sub in the case of grants where a 727 resource owner is involved. 728 o Updated acknowledgements. 729 o Updated Section 2.2.1 to clarify that acr, amr and auth_type can 730 occur if the AT has been obtained by grants where the resource 731 owner is involved. 732 o Updated Section 2.2.2 to clarify that identity claims can occur if 733 the AT has been obtained by grants where the resource owner is 734 involved. 735 o In Section 2.2.3.1 eliminated the claim that SCIM doesn't provide 736 a vocabulary for the attributes listed there. 737 o In Section 5 added reference to 8725. 738 o In Section 4 added application/jwt+at as accepted typ value. 739 o Various typos and formatting issues fixed. 741 draft-ietf-oauth-access-token-jwt-06 743 o In Section 2.2 and Section 6 added a discussion about how 744 different sub values affect the privacy properties of a solution. 745 o In Section 2.2.3 and Section 3 eliminated language prohibiting JWT 746 AT requests featuring multiple resources, substituting it with the 747 prohibition for the AS to emit JWT ATs expressing ambiguous 748 authorization grants. In Section 5, added language warning 749 against scope confusion and mentioned the existence of other 750 ambiguous authorization grant. 751 o In Section 2.2 promoted claims iat and jti from RECOMMENDED to 752 REQUIRED. 753 o In Section 2.1 eliminated temporary note on the lack of 754 authenticated encryption methods specifications. 755 o Updated acknowledgements. 757 draft-ietf-oauth-access-token-jwt-05 759 o Varios typos, grammar issues and improper abbreviations fixed. 760 o Reworded the definition of at+jwt in Section 2.1. 761 o In Section 2.2, clarified that iat refers to the issuance time of 762 the JWT itself. 764 o In Section 2.2.2, added a reference to public/private claims 765 definitions (sections 4.2, 4.3) of [RFC7519]. 766 o In Section 3, removed the paragrah stating that every JWT AT MUST 767 have an aud, as it is already defined in Section 2.2. 768 o Reworded description of the JWT AT adoption landscape in 769 Section 1. 770 o Simplified the individual descriptions of the claims list in 771 Section 2.2.1. 772 o Updated Section 4 and Section 5 to clarify that the AS can use any 773 of the published keys to sign JWT access tokens, and that the AS 774 should not rely on use of different signing keys per token type as 775 a security mechanism. 776 o In Section 2.2 promoted claims iat and jti from OPTIONAL to 777 RECOMMENDED 778 o In Section 4, switched the validation steps list type from numbers 779 to bullets. 780 o In Section 4, eliminated the auth_time instructions from the 781 validation steps list. 782 o In Section 2.2.2, added a reference to the JWT claims registry as 783 source of claims for JWT ATs 784 o In Section 4, clarified that failures in JWT AT validation checks 785 will result in invalid_token. 787 draft-ietf-oauth-access-token-jwt-04 789 o Eliminated reference to resource aliases list from the aud claim 790 description in Section 2. 791 o Eliminated references to resource aliases list from the aud 792 validation guidance in Section 4. 793 o Introduced a new subsection Section 2.2.1, moved the definitions 794 of auth_time, acr and amr there and incorporated the language 795 proposed by Annabelle and Brian on the WG mailing list. 796 o In section Section 3 softened (from MUST to SHOULD) the 797 requirement that ties the resource identifier in the request to 798 the value in the aud claim of the issued access token. 799 o Updated acknowledgements. 800 o In the section Section 3, the example request now has 801 response_type=code. 802 o Updated text in the Privacy Consideration section to clarify what 803 protection steps the text refers to. 804 o Updated the typ header discussion in Section 2.1 to clarify that 805 it helps preventing resources from accepting OpenID Connect ID 806 Tokens as JWT access tokens. 807 o Updated refrences to token exchange, resource indicators and JWT 808 best practices to reflect their RFC status (8693,8707,8725). 810 draft-ietf-oauth-access-token-jwt-03 811 o Varios typos fixed. 812 o In the security considerations section, relaxed the claim that the 813 typ header value "at+jwt" will prevent RS from misinterpreting JWT 814 ATs as idtokens. 815 o In the "Requesting JWT Access Tokens" section, added 816 "invalid_target" as a possible error returned for the multiple 817 resources request case. 818 o In the Validating JWT Access Tokens" section, disallowed JWTs with 819 "alg":"none" 820 o in the IANA registration entries for the SCIM claim types, 821 complemented the reference to the SCIM spec with a reference to 822 this spec so that the eventual registration entries have better 823 context. 824 o Updated acknowledgements. 825 o In the section Section 3, the example request now has 826 response_type=code. 827 o Updated text in the Privacy Consideration section to clarify what 828 protection steps the text refers to. 830 draft-ietf-oauth-access-token-jwt-02 832 o In 2.2.1, opened the sources of identity attributes to any 833 identity related specification. 834 o In 2.2.2, relaxed from MUST to SHOULD the requirement that 835 requests including a scope always result in access tkens 836 containing a corresponding scope claim. 837 o In the security considerations setting, added a requirement for 838 the authorization server to assing unique identifiers for 839 different resources- to prevent cross JWT confusion. 840 o Added IANA registration for the authorization attributes borrowed 841 from SCIM CORE 843 draft-ietf-oauth-access-token-jwt-01 845 o Added note on authenticated encryption. 846 o Added a mention to the 1st party clients scenarios in the identity 847 claims section. 848 o Changed the definition reference for the iss, exp, aud, sub, iat 849 claims from OpenID.Core to RFC7519. 850 o Added a mention of the client_id==sub case in the security 851 considerations section, added a reference to draft-ietf-oauth- 852 security-topics-13. Added a reference to the security 853 considerations from the sub claim definition section. 854 o Specified invalid_request as the error code the authorization 855 server should return in case of multiple resources in the access 856 token request. 858 o Specified invalid_scope as the error code the authorization server 859 should return in case it isn;t possible to determine to which 860 resource the requested scopes refers to. 861 o In the identity claims section, added a reference to introspection 862 as possible source of claim types and added language explicitly 863 stating that the AS can add arbitrary attributes as long as they 864 are collision resistant or private. 865 o Updated language for the auth_time claim to include the case in 866 which the AS reauthenticates the user mid-session (e.g. during 867 step up auth). 868 o Removed note about adding a mechanism for extablishing whether the 869 token was obtained on behalf or the resource owner or of the 870 client itself (client credentials grant). 871 o Removed note about adding a mechanism for indicating whether the 872 authorization server sent the resource owner to authenticate with 873 a federated identity provider, and the identity of that federated 874 provider. 875 o Removed the note in the security consideration sections about 876 discussing the purpose of aud, iss, exp validation (redundant). 877 o In the authorization claims section, stated intent to register 878 roles, groups and entitlements as claim types in IANA 879 o Clarified in the privacy considerations that clients should not 880 inspect access tokens. 881 o Expanded the privacy considerations with more explicit guidance 882 about privacy preserving approaches. 883 o Added IANA registry content for the at+JWT MIME type. 884 o Updated acknowledgements. 886 draft-ietf-oauth-access-token-jwt-00 888 o Initial draft to define a JWTt profile for OAuth 2.0 access 889 tokens. 891 Author's Address 893 Vittorio Bertocci 894 Auth0 896 Email: vittorio@auth0.com