idnits 2.17.1 draft-ietf-oauth-access-token-jwt-12.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 17, 2021) is 1134 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) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 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 17, 2021 5 Expires: September 18, 2021 7 JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens 8 draft-ietf-oauth-access-token-jwt-12 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 an 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 18, 2021. 34 Copyright Notice 36 Copyright (c) 2021 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 . . . . . . . . . . . . . . . . . . . . . . . 4 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 . . . . . . . . . . . . . . . . 7 63 4. Validating JWT Access Tokens . . . . . . . . . . . . . . . . 8 64 5. Security Considerations . . . . . . . . . . . . . . . . . . . 10 65 6. Privacy Considerations . . . . . . . . . . . . . . . . . . . 11 66 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 67 7.1. Media Type Registration . . . . . . . . . . . . . . . . . 12 68 7.1.1. Registry Content . . . . . . . . . . . . . . . . . . 12 69 7.2. Claims Registration . . . . . . . . . . . . . . . . . . . 13 70 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 13 71 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 72 8.1. Normative References . . . . . . . . . . . . . . . . . . 14 73 8.2. Informative References . . . . . . . . . . . . . . . . . 15 74 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 16 75 Appendix B. Document History . . . . . . . . . . . . . . . . . . 16 76 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 21 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 Please note: although both this document and [RFC7523] use JSON Web 128 Tokens in the context of the OAuth2 framework, the two specifications 129 differ in both intent and mechanics. Whereas [RFC7523] defines how a 130 JWT Bearer Token can be used to request an access token, this 131 documents describes how to encode access tokens in JWT format. 133 1.1. Requirements Notation and Conventions 135 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 136 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 137 "OPTIONAL" in this document are to be interpreted as described in BCP 138 14 [RFC2119] [RFC8174] when, and only when, they appear in all 139 capitals, as shown here. 141 1.2. Terminology 143 JWT access token: An OAuth 2.0 access token encoded in JWT format 144 and complying with the requirements described in this 145 specification. 147 This specification uses the terms "access token", "refresh token", 148 "authorization server", "resource server", "authorization endpoint", 149 "authorization request", "authorization response", "token endpoint", 150 "grant type", "access token request", "access token response", and 151 "client" defined by The OAuth 2.0 Authorization Framework [RFC6749]. 153 2. JWT Access Token Header and Data Structure 155 2.1. Header 157 Although JWT access tokens can use any signing algorithm, use of 158 asymmetric cryptography is RECOMMENDED as it simplifies the process 159 of acquiring validation information for resource servers (see 160 Section 4). JWT access tokens MUST NOT use "none" as the signing 161 algorithm. See Section 4 for more details. 163 Authorization servers and resource servers conforming to this 164 specification MUST include RS256 (as defined in [RFC7518]) among 165 their supported signature algorithms. 167 This specification registers the "application/at+jwt" media type, 168 which can be used to indicate that the content is a JWT access token. 169 JWT access tokens MUST include this media type in the "typ" header 170 parameter to explicitly declare that the JWT represents an access 171 token complying with this profile. Per the definition of "typ" in 172 Section 4.1.9 of [RFC7515], it is RECOMMENDED that the "application/" 173 prefix be omitted. Therefore, the "typ" value used SHOULD be 174 "at+jwt". See the security considerations section for details on the 175 importance of preventing OpenID Connect ID Tokens (as defined by 176 Section 2 of [OpenID.Core]) from being accepted as access tokens by 177 resource servers implementing this profile. 179 2.2. Data Structure 181 The following claims are used in the JWT access token data structure. 183 iss REQUIRED - as defined in Section 4.1.1 of [RFC7519]. 185 exp REQUIRED - as defined in Section 4.1.4 of [RFC7519]. 187 aud REQUIRED - as defined in Section 4.1.3 of [RFC7519]. See 188 Section 3 for indications on how an authorization server should 189 determine the value of "aud" depending on the request. 191 sub REQUIRED - as defined in Section 4.1.2 of [RFC7519]. In case of 192 access tokens obtained through grants where a resource owner is 193 involved, such as the authorization code grant, the value of "sub" 194 SHOULD correspond to the subject identifier of the resource owner. 195 In case of access tokens obtained through grants where no resource 196 owner is involved, such as the client credentials grant, the value 197 of "sub" SHOULD correspond to an identifier the authorization 198 server uses to indicate the client application. See Section 5 for 199 more details on this scenario. Also, see Section 6 for a 200 discussion about how different choices in assigning "sub" values 201 can impact privacy. 203 client_id REQUIRED - as defined in Section 4.3 of [RFC8693]. 205 iat REQUIRED - as defined in Section 4.1.6 of [RFC7519]. This claim 206 identifies the time at which the JWT access token was issued. 208 jti REQUIRED - as defined in Section 4.1.7 of [RFC7519]. 210 2.2.1. Authentication Information Claims 212 The claims listed in this section MAY be issued in the context of 213 authorization grants involving the resource owner, and reflect in the 214 access token the types and strength of authentication that the 215 authentication server enforced prior to returning the authorization 216 response to the client. Their values are fixed, and remain the same 217 across all access tokens that derive from a given authorization 218 response, whether the access token was obtained directly in the 219 response (e.g., via the implicit flow) or after one or more token 220 exchanges (e.g., obtaining a fresh access token using a refresh 221 token, or exchanging one access token for another via [RFC8693]). 223 auth_time OPTIONAL - as defined in Section 2 of [OpenID.Core]. 225 acr OPTIONAL - as defined in Section 2 of [OpenID.Core]. 227 amr OPTIONAL - as defined in Section 2 of [OpenID.Core]. 229 2.2.2. Identity Claims 231 In the context of authorization grants involving the resource owner, 232 commercial authorization servers will often include resource owner 233 attributes directly in access tokens, so that resource servers can 234 consume them directly for authorization or other purposes without any 235 further round trips to introspection ( [RFC7662]) or UserInfo ( 236 [OpenID.Core]) endpoints. This is particularly common in scenarios 237 where the client and the resource server belong to the same entity 238 and are part of the same solution, as is the case for first party 239 clients invoking their own backend API. 241 This profile does not introduce any mechanism for a client to 242 directly request the presence of specific claims in JWT access 243 tokens, as the authorization server can determine what additional 244 claims are required by a particular resource server by taking in 245 consideration the client_id of the client, the "scope" and the 246 "resource" parameters included in the request. 248 Any additional identity attribute whose semantic is well described by 249 an entry in the JSON Web Token (JWT) IANA registry introduced in 250 [RFC7519] SHOULD be encoded using the corresponding claim name. Note 251 that the JWT IANA registry includes the claims found in Section 5.1 252 of [OpenID.Core]. 254 Authorization servers MAY return arbitrary attributes not defined in 255 any existing specification, as long as the corresponding claim names 256 are collision resistant or the access tokens are meant to be used 257 only within a private subsystem. Please refer to Sections 4.2 and 258 4.3 of [RFC7519] for details. 260 Authorization servers including resource owner attributes in JWT 261 access tokens should exercise care and verify that all privacy 262 requirements are met, as discussed in Section 6. 264 2.2.3. Authorization Claims 266 If an authorization request includes a scope parameter, the 267 corresponding issued JWT access token SHOULD include a "scope" claim 268 as defined in Section 4.2 of [RFC8693]. 270 All the individual scope strings in the "scope" claim MUST have 271 meaning for the resources indicated in the "aud" claim. See 272 Section 5 for more considerations about the relationship between 273 scope strings and resources indicated by the "aud" claim. 275 2.2.3.1. Claims for Authorization Outside of Delegation Scenarios 277 Many authorization servers embed in the access tokens they issue 278 authorization attributes that go beyond the delegated scenarios 279 described by [RFC7519]. Typical examples include resource owner 280 memberships in roles and groups that are relevant to the resource 281 being accessed, entitlements assigned to the resource owner for the 282 targeted resource that the authorization server knows about, and so 283 on. 285 An authorization server wanting to include such attributes in a JWT 286 access token SHOULD use as claim types the "groups","roles" and 287 "entitlements" attributes of the "User" resource schema defined by 288 Section 4.1.2 of [RFC7643]). 290 Authorization servers SHOULD encode the corresponding claim values 291 according to the guidance defined in [RFC7643]. In particular, a 292 non-normative example of "groups" attribute can be found in 293 Section 8.2 of [RFC7643]. No specific vocabulary is provided for 294 "roles" and "entitlements". 296 Section 7 of this document provides entries for registering "groups", 297 "roles" and "entitlements" attributes from [RFC7643] as claim types 298 to be used in this profile. 300 3. Requesting a JWT Access Token 302 An authorization server can issue a JWT access token in response to 303 any authorization grant defined by [RFC6749] and subsequent 304 extensions meant to result in an access token. 306 If the request includes a "resource" parameter (as defined in 307 [RFC8707]), the resulting JWT access token "aud" claim SHOULD have 308 the same value as the "resource" parameter in the request. 310 Example request below: 312 GET /as/authorization.oauth2?response_type=code 313 &client_id=s6BhdRkqt3 314 &state=laeb 315 &scope=openid%20profile%20reademail 316 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 317 &resource=https%3A%2F%2Frs.example.com%2F HTTP/1.1 318 Host: authorization-server.example.com 320 Figure 1: Authorization Request with Resource and Scope Parameters 322 Once redeemed, the code obtained from the request above will result 323 in a JWT access token in the form shown below: 325 Header: 327 {"typ":"at+JWT","alg":"RS256","kid":"RjEwOwOA"} 329 Claims: 331 { 332 "iss": "https://authorization-server.example.com/", 333 "sub": " 5ba552d67", 334 "aud": "https://rs.example.com/", 335 "exp": 1544645174, 336 "client_id": "s6BhdRkqt3", 337 "scope": "openid profile reademail" 338 } 340 Figure 2: The Header and JWT Claims Set of a JWT Access Token 342 The authorization server MUST NOT issue a JWT access token if the 343 authorization granted by the token would be ambiguous. See Section 5 344 for more details about common cases that might lead to ambiguity and 345 strategies an authorization server can enact to prevent them. 347 If the request does not include a "resource" parameter, the 348 authorization server MUST use in the "aud" claim a default resource 349 indicator. If a "scope" parameter is present in the request, the 350 authorization server SHOULD use it to infer the value of the default 351 resource indicator to be used in the "aud" claim. The mechanism 352 through which scopes are associated to default resource indicator 353 values is outside the scope of this specification. If the values in 354 the "scope" parameter refer to different default resource indicator 355 values, the authorization server SHOULD reject the request with 356 "invalid_scope" as described in Section 4.1.2.1 of [RFC6749]. 358 4. Validating JWT Access Tokens 360 For the purpose of facilitating validation data retrieval, it is here 361 RECOMMENDED that authorization servers sign JWT access tokens with an 362 asymmetric algorithm. 364 Authorization servers SHOULD use OAuth 2.0 Authorization Server 365 Metadata [RFC8414] to advertise to resource servers their signing 366 keys via "jwks_uri" and what "iss" claim value to expect via the 367 issuer metadata value. Alternatively, authorization servers 368 implementing OpenID Connect MAY use the "OpenID Connect discovery 369 [OpenID.Discovery] document for the same purpose. If an 370 authorization server supports both OAuth 2.0 Authorization Server 371 Metadata and OpenID Connect discovery, the values provided MUST be 372 consistent across the two publication methods. 374 An authorization server MAY elect to use different keys to sign 375 OpenID Connect ID Tokens and JWT access tokens. This specification 376 does not provide a mechanism for identifying a specific key as the 377 one used to sign JWT access tokens. An authorization server can sign 378 JWT access tokens with any of the keys advertised via AS metadata or 379 OpenID Connect discovery. See Section 5 for further guidance on 380 security implications. 382 Resource servers receiving a JWT access token MUST validate it in the 383 following manner. 385 o The resource server MUST verify that the typ header value is 386 "at+jwt" or "application/at+jwt" and reject tokens carrying any 387 other value. 389 o If the JWT access token is encrypted, decrypt it using the keys 390 and algorithms that the resource server specified during 391 registration. If encryption was negotiated with the authorization 392 server at registration time and the incoming JWT access token is 393 not encrypted, the resource server SHOULD reject it. 395 o The Issuer Identifier for the authorization server (which is 396 typically obtained during discovery) MUST exactly match the value 397 of the "iss" claim. 399 o The resource server MUST validate that the "aud" claim contains a 400 resource indicator value corresponding to an identifier the 401 resource server expects for itself. The JWT access token MUST be 402 rejected if "aud" does not contain a resource indicator of the 403 current resource server as a valid audience. 405 o The resource server MUST validate the signature of all incoming 406 JWT access tokens according to [RFC7515] using the algorithm 407 specified in the JWT alg Header Parameter. The resource server 408 MUST reject any JWT in which the value of "alg" is "none". The 409 resource server MUST use the keys provided by the authorization 410 server. 412 o The current time MUST be before the time represented by the "exp" 413 claim. 415 The resource server MUST handle errors as described in Section 3.1 of 416 [RFC6750]. In particular, in case of any failure in the validation 417 checks listed above the authorization server response MUST include 418 the error code "invalid_token". 420 If the JWT access token includes authorization claims as described in 421 Section 2.2.3, the resource server SHOULD use them in combination 422 with any other contextual information available to determine whether 423 the current call should be authorized or rejected. Details about how 424 a resource server performs those checks is beyond the scope of this 425 profile specification. 427 5. Security Considerations 429 The JWT access token data layout described here is very similar to 430 the one of the id_token as defined by [OpenID.Core]. The explicit 431 typing required in this profile, in line with the recommendations in 432 [RFC8725] helps the resource server to distinguish between JWT access 433 tokens and OpenID Connect ID Tokens. 435 Authorization servers should prevent scenarios where clients can 436 affect the value of the "sub" claim in ways that could confuse 437 resource servers. For example, if the authorization server elects to 438 use the client_id as the "sub" value for access tokens issued client 439 credentials grant, the authorization server should prevent clients to 440 register an arbitrary client_id value, as this would allow malicious 441 clients to select the sub of a high privilege resource owner and 442 confuse any authorization logic on the resource server relying on the 443 "sub" value. For more details please refer to Section 4.14 of 444 [OAuth2.Security.BestPractices]. 446 To preventing cross-JWT confusion, authorization servers MUST use a 447 distinct identifier as "aud" claim value to uniquely identify access 448 tokens issued by the same issuer for distinct resources. For more 449 details on cross-JWT confusion please refer to Section 2.8 of 450 [RFC8725]. 452 Authorization servers should use particular care when handling 453 requests that might lead to ambiguous authorization grants. For 454 example: if a request includes multiple resource indicators, the 455 authorization server should ensure that each scope string included in 456 the resulting JWT access token, if any, can be unambiguously 457 correlated to a specific resource among the ones listed in the "aud" 458 claim. The details on how to recognize and mitigate this and other 459 ambiguous situations is highly scenario-dependent, hence out of scope 460 for this profile. 462 Authorization servers should not rely on the use of different keys 463 for signing OpenID Connect ID Tokens and JWT tokens as a method to 464 safeguard against the consequences of leaking specific keys. Given 465 that resource servers have no way of knowing what key should be used 466 to validate JWT access tokens in particular, they have to accept 467 signatures performed with any of the keys published in AS metadata or 468 OpenID Connect discovery: consequently, an attacker just needs to 469 compromise any key among the ones published to be able to generate 470 and sign JWTs that will be accepted as valid by the resource server. 472 6. Privacy Considerations 474 As JWT access tokens carry information by value, it now becomes 475 possible for clients and potentially even end users to directly peek 476 inside the token claims collection. 478 The client MUST NOT inspect the content of the access token: the 479 authorization server and the resource server might decide to change 480 token format at any time (for example by switching from this profile 481 to opaque tokens) hence any logic in the client relying on the 482 ability to read the access token content would break without 483 recourse. The OAuth 2.0 framework assumes that access tokens are 484 treated as opaque by clients. Administrators of authorization 485 servers should also take into account that the content of an access 486 token is visible to the client. Whenever client access to the access 487 token content presents privacy issues for a given scenario, the 488 authorization server should take explicit steps to prevent it. 490 In scenarios in which JWT access tokens are accessible to the end 491 user, it should be evaluated whether the information can be accessed 492 without privacy violations (for example, if an end user would simply 493 access his or her own personal information) or if steps must be taken 494 to enforce confidentiality. 496 Possible measures to prevent leakage of information to clients and 497 end users include: encrypting the access token, encrypting the 498 sensitive claims, omitting the sensitive claims or not using this 499 profile, falling back on opaque access tokens. 501 In every scenario, the content of the JWT access token will 502 eventually be accessible to the resource server. It's important to 503 evaluate whether the resource server gained the proper entitlement to 504 have access to any content received in form of claims, for example 505 through user consent in some form, policies and agreements with the 506 organization running the authorization servers, and so on. 508 This profile mandates the presence of the "sub" claim in every JWT 509 access token, making it possible for resource servers to rely on that 510 information for correlating incoming requests with data stored 511 locally for the authenticated principal. Although the ability to 512 correlate requests might be required by design in many scenarios, 513 there are scenarios where the authorization server might want to 514 prevent correlation. The "sub" claim should be populated by the 515 authorization servers according to a privacy impact assessment. For 516 instance, if a solution requires preventing tracking principal 517 activities across multiple resource servers, the authorization server 518 should ensure that JWT access tokens meant for different resource 519 servers have distinct "sub" values that cannot be correlated in the 520 event of resource servers collusion. Similarly, if a solution 521 requires preventing a resource server from correlating the 522 principal's activity within the resource itself, the authorization 523 server should assign different "sub" values for every JWT access 524 token issued. In turn, the client should obtain a new JWT access 525 token for every call to the resource server, to ensure that the 526 resource server receives different "sub" and "jti" values at every 527 call, thus preventing correlation between distinct requests. 529 7. IANA Considerations 531 7.1. Media Type Registration 533 7.1.1. Registry Content 535 This section registers the "application/at+jwt" media type [RFC2046] 536 in the "Media Types" registry [IANA.MediaTypes] in the manner 537 described in [RFC6838], which can be used to indicate that the 538 content is an access token encoded in JWT format. 540 o Type name: application 542 o Subtype name: at+jwt 544 o Required parameters: N/A 546 o Optional parameters: N/A 548 o Encoding considerations: binary; JWT values are encoded as a 549 series of base64url-encoded values (with trailing '=' characters 550 removed), some of which may be the empty string, separated by 551 period ('.') characters. 553 o Security considerations: See the Security Considerations 554 Section of [[TODO: update once there's a RFC number for the JWT AT 555 profile]] 557 o Interoperability considerations: N/A 559 o Published specification: [[TODO: update once there's a RFC number 560 for the JWT AT profile]] 562 o Applications that use this media type: Applications that access 563 resource servers using OAuth 2.0 access tokens encoded in JWT 564 format 566 o Fragment identifier considerations: N/A 568 o Additional information: Magic number(s): N/A File extension(s): N/ 569 A Macintosh file type code(s): N/A 571 o Person and email address to contact for further information: 572 Vittorio Bertocci, vittorio@auth0.com 574 o Intended usage: COMMON 576 o Restrictions on usage: none 578 o Author: Vittorio Bertocci, vittorio@auth0.com 580 o Change controller: IESG 582 o Provisional registration? No 584 7.2. Claims Registration 586 Section 2.2.3.1 of this specification refers to the attributes 587 "roles", "groups", "entitlements" defined in [RFC7643] to express 588 authorization information in JWT access tokens. This section 589 registers those attributes as claims in the JSON Web Token (JWT) IANA 590 registry introduced in [RFC7519]. 592 7.2.1. Registry Contents 594 o Claim Name: "roles" 596 o Claim Description: Roles 598 o Change Controller: IESG 600 o Specification Document(s): Section 4.1.2 of [RFC7643] and 601 Section 2.2.3.1 of [[this specification]] 603 o Claim Name: "groups" 605 o Claim Description: Groups 607 o Change Controller: IESG 608 o Specification Document(s): Section 4.1.2 of [RFC7643] and 609 Section 2.2.3.1 of [[this specification]] 611 o Claim Name: "entitlements" 613 o Claim Description: Entitlements 615 o Change Controller: IESG 617 o Specification Document(s): Section 4.1.2 of [RFC7643] and 618 Section 2.2.3.1 of [[this specification]] 620 8. References 622 8.1. Normative References 624 [OpenID.Core] 625 Sakimura, N., Bradley, J., Jones, M., Medeiros, B., and C. 626 Mortimore, "OpenID Connect Core 1.0", November 2014. 628 [OpenID.Discovery] 629 Sakimura, N., Bradley, J., Jones, M., and J. Jay, "OpenID 630 Connect Discovery 1.0", November 2014. 632 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 633 Extensions (MIME) Part Two: Media Types", RFC 2046, 634 DOI 10.17487/RFC2046, November 1996, 635 . 637 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 638 Requirement Levels", BCP 14, RFC 2119, 639 DOI 10.17487/RFC2119, March 1997, 640 . 642 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 643 RFC 6749, DOI 10.17487/RFC6749, October 2012, 644 . 646 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 647 Specifications and Registration Procedures", BCP 13, 648 RFC 6838, DOI 10.17487/RFC6838, January 2013, 649 . 651 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 652 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 653 2015, . 655 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 656 DOI 10.17487/RFC7518, May 2015, 657 . 659 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 660 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 661 . 663 [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 664 (JWT) Profile for OAuth 2.0 Client Authentication and 665 Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 666 2015, . 668 [RFC7643] Hunt, P., Ed., Grizzle, K., Wahlstroem, E., and C. 669 Mortimore, "System for Cross-domain Identity Management: 670 Core Schema", RFC 7643, DOI 10.17487/RFC7643, September 671 2015, . 673 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 674 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 675 May 2017, . 677 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 678 Authorization Server Metadata", RFC 8414, 679 DOI 10.17487/RFC8414, June 2018, 680 . 682 [RFC8693] Jones, M., Nadalin, A., Campbell, B., Ed., Bradley, J., 683 and C. Mortimore, "OAuth 2.0 Token Exchange", RFC 8693, 684 DOI 10.17487/RFC8693, January 2020, 685 . 687 [RFC8707] Campbell, B., Bradley, J., and H. Tschofenig, "Resource 688 Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, 689 February 2020, . 691 [RFC8725] Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best 692 Current Practices", BCP 225, RFC 8725, 693 DOI 10.17487/RFC8725, February 2020, 694 . 696 8.2. Informative References 698 [OAuth2.Security.BestPractices] 699 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 700 "OAuth 2.0 Security Best Current Practice", July 2019. 702 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 703 Framework: Bearer Token Usage", RFC 6750, 704 DOI 10.17487/RFC6750, October 2012, 705 . 707 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 708 RFC 7662, DOI 10.17487/RFC7662, October 2015, 709 . 711 Appendix A. Acknowledgements 713 The initial set of requirements informing this specification was 714 extracted by numerous examples of access tokens issued in JWT format 715 by production systems. Thanks to Dominick Baier (IdentityServer), 716 Brian Campbell (Ping Identity), Daniel Dobalian (Microsoft), Karl 717 Guinness (Okta) for providing sample tokens issued by their products 718 and services. Brian Campbell and Filip Skokan provided early 719 feedback that shaped the direction of the specification. This 720 profile was discussed at length during the OAuth Security Workshop 721 2019, with several individuals contributing ideas and feedback. The 722 author would like to acknowledge the contributions of: 724 John Bradley, Brian Campbell, Vladimir Dzhuvinov, Torsten 725 Lodderstedt, Nat Sakimura, Hannes Tschofenig and everyone who 726 actively participated in the unconference discussions. 728 The following individuals contributed useful feedback and insights on 729 the drafts, both on the IETF OAuth 2.0 WG DL and during the IIW28 730 conference: 732 Dale Olds, George Fletcher, David Waite, Michael Engan, Mike Jones, 733 Hans Zandbelt, Vladimir Dzhuvinov, Martin Schanzenbach , Aaron 734 Parecki, Annabelle Richard Backman, Dick Hardt, Denis Pinkas, 735 Benjamin Kaduk, Dominick Baier, Andrii Deinega, Mike Jones and 736 everyone who actively participated in the IIW28 unconference 737 discussions and the IETF OAuth 2.0 WG DL discussions. Thanks to 738 Roman Danyliw for the AD review, Joseph Salowey and Roni Even for the 739 SECDIR/GENART reviews. 741 Appendix B. Document History 743 [[ to be removed by the RFC Editor before publication as an RFC ]] 745 draft-ietf-oauth-access-token-jwt-12 747 o Editorial changes in the abstract. 748 o Updated the client_id value in the figures in Section 3. 750 o Added clarifying language in Section 1 positioning this 751 specification vs [RFC7523]. 752 o In section Section 2.1 added a sentence that makes RS256 support 753 mandatory for AS and RS. 755 draft-ietf-oauth-access-token-jwt-11 757 o Editorial updates and typo fixes in Section 1.2, Section 2.2, 758 Section 2.2.1, Section 2.2.2, Section 3, Section 4, Section 5, 759 Appendix A 760 o Updated language in Section 2.2.2 to explicitly refer to the JWT 761 IANA registry. 762 o Citation added in in Section 2.1 763 o Added a normative reference entry for OpenID Connect Discovery 1.0 764 and referenced it from Section 4 766 draft-ietf-oauth-access-token-jwt-10 768 o Updated Figure 2 in Section 3 to clarify that the intent of that 769 snippet is to describe the content rather than exact JWT AT 770 format. 771 o Updated registry references in Section 7.2.1 to point to 772 Section 2.2.3.1 773 o Modified Section 2.2.3.1 to make it easier for the reader to 774 understand what values and format is expected for the groups, 775 roles and entitlement claims. Minor formatting issues fixed. 777 draft-ietf-oauth-access-token-jwt-09 779 o Removed unused reference to http://www.iana.org/assignments/oauth- 780 parameters; moved the OAuth2 security BCP to the informative 781 references section. 782 o Restructured opening paragraphs in Section 6 for clarity. 784 draft-ietf-oauth-access-token-jwt-08 786 o Numerous edits for correcting typos, improving clarity and 787 precision of language. 788 o Moved RFC7519 to the normative section; eliminated unused 789 references RFC7644 and RFC3986. 791 draft-ietf-oauth-access-token-jwt-07 793 o In Section 2.1, added language that forbids use of none as alg 794 value, and references Section 4 where the same prohibition was 795 already expressed from the RS perspective. 797 o In the sub definition in Section 2.2, added a sentence that 798 clarifies what goes in the sub in the case of grants where a 799 resource owner is involved. 800 o Updated acknowledgements. 801 o Updated Section 2.2.1 to clarify that acr, amr and auth_type can 802 occur if the AT has been obtained by grants where the resource 803 owner is involved. 804 o Updated Section 2.2.2 to clarify that identity claims can occur if 805 the AT has been obtained by grants where the resource owner is 806 involved. 807 o In Section 2.2.3.1 eliminated the claim that SCIM doesn't provide 808 a vocabulary for the attributes listed there. 809 o In Section 5 added reference to 8725. 810 o In Section 4 added application/jwt+at as accepted typ value. 811 o Various typos and formatting issues fixed. 813 draft-ietf-oauth-access-token-jwt-06 815 o In Section 2.2 and Section 6 added a discussion about how 816 different sub values affect the privacy properties of a solution. 817 o In Section 2.2.3 and Section 3 eliminated language prohibiting JWT 818 AT requests featuring multiple resources, substituting it with the 819 prohibition for the AS to emit JWT ATs expressing ambiguous 820 authorization grants. In Section 5, added language warning 821 against scope confusion and mentioned the existence of other 822 ambiguous authorization grant. 823 o In Section 2.2 promoted claims iat and jti from RECOMMENDED to 824 REQUIRED. 825 o In Section 2.1 eliminated temporary note on the lack of 826 authenticated encryption methods specifications. 827 o Updated acknowledgements. 829 draft-ietf-oauth-access-token-jwt-05 831 o Varios typos, grammar issues and improper abbreviations fixed. 832 o Reworded the definition of at+jwt in Section 2.1. 833 o In Section 2.2, clarified that iat refers to the issuance time of 834 the JWT itself. 835 o In Section 2.2.2, added a reference to public/private claims 836 definitions (Sections 4.2, 4.3) of [RFC7519]. 837 o In Section 3, removed the paragrah stating that every JWT AT MUST 838 have an aud, as it is already defined in Section 2.2. 839 o Reworded description of the JWT AT adoption landscape in 840 Section 1. 841 o Simplified the individual descriptions of the claims list in 842 Section 2.2.1. 843 o Updated Section 4 and Section 5 to clarify that the AS can use any 844 of the published keys to sign JWT access tokens, and that the AS 845 should not rely on use of different signing keys per token type as 846 a security mechanism. 847 o In Section 2.2 promoted claims iat and jti from OPTIONAL to 848 RECOMMENDED 849 o In Section 4, switched the validation steps list type from numbers 850 to bullets. 851 o In Section 4, eliminated the auth_time instructions from the 852 validation steps list. 853 o In Section 2.2.2, added a reference to the JWT claims registry as 854 source of claims for JWT ATs 855 o In Section 4, clarified that failures in JWT AT validation checks 856 will result in invalid_token. 858 draft-ietf-oauth-access-token-jwt-04 860 o Eliminated reference to resource aliases list from the aud claim 861 description in Section 2. 862 o Eliminated references to resource aliases list from the aud 863 validation guidance in Section 4. 864 o Introduced a new subsection Section 2.2.1, moved the definitions 865 of auth_time, acr and amr there and incorporated the language 866 proposed by Annabelle and Brian on the WG mailing list. 867 o In section Section 3 softened (from MUST to SHOULD) the 868 requirement that ties the resource identifier in the request to 869 the value in the aud claim of the issued access token. 870 o Updated acknowledgements. 871 o In the section Section 3, the example request now has 872 response_type=code. 873 o Updated text in the Privacy Consideration section to clarify what 874 protection steps the text refers to. 875 o Updated the typ header discussion in Section 2.1 to clarify that 876 it helps preventing resources from accepting OpenID Connect ID 877 Tokens as JWT access tokens. 878 o Updated refrences to token exchange, resource indicators and JWT 879 best practices to reflect their RFC status (8693,8707,8725). 881 draft-ietf-oauth-access-token-jwt-03 883 o Varios typos fixed. 884 o In the security considerations section, relaxed the claim that the 885 typ header value "at+jwt" will prevent RS from misinterpreting JWT 886 ATs as idtokens. 887 o In the "Requesting JWT Access Tokens" section, added 888 "invalid_target" as a possible error returned for the multiple 889 resources request case. 890 o In the Validating JWT Access Tokens" section, disallowed JWTs with 891 "alg":"none" 893 o in the IANA registration entries for the SCIM claim types, 894 complemented the reference to the SCIM spec with a reference to 895 this spec so that the eventual registration entries have better 896 context. 897 o Updated acknowledgements. 898 o In the section Section 3, the example request now has 899 response_type=code. 900 o Updated text in the Privacy Consideration section to clarify what 901 protection steps the text refers to. 903 draft-ietf-oauth-access-token-jwt-02 905 o In 2.2.1, opened the sources of identity attributes to any 906 identity related specification. 907 o In 2.2.2, relaxed from MUST to SHOULD the requirement that 908 requests including a scope always result in access tkens 909 containing a corresponding scope claim. 910 o In the security considerations setting, added a requirement for 911 the authorization server to assing unique identifiers for 912 different resources- to prevent cross JWT confusion. 913 o Added IANA registration for the authorization attributes borrowed 914 from SCIM CORE 916 draft-ietf-oauth-access-token-jwt-01 918 o Added note on authenticated encryption. 919 o Added a mention to the 1st party clients scenarios in the identity 920 claims section. 921 o Changed the definition reference for the iss, exp, aud, sub, iat 922 claims from OpenID.Core to RFC7519. 923 o Added a mention of the client_id==sub case in the security 924 considerations section, added a reference to draft-ietf-oauth- 925 security-topics-13. Added a reference to the security 926 considerations from the sub claim definition section. 927 o Specified invalid_request as the error code the authorization 928 server should return in case of multiple resources in the access 929 token request. 930 o Specified invalid_scope as the error code the authorization server 931 should return in case it isn;t possible to determine to which 932 resource the requested scopes refers to. 933 o In the identity claims section, added a reference to introspection 934 as possible source of claim types and added language explicitly 935 stating that the AS can add arbitrary attributes as long as they 936 are collision resistant or private. 937 o Updated language for the auth_time claim to include the case in 938 which the AS reauthenticates the user mid-session (e.g. during 939 step up auth). 941 o Removed note about adding a mechanism for extablishing whether the 942 token was obtained on behalf or the resource owner or of the 943 client itself (client credentials grant). 944 o Removed note about adding a mechanism for indicating whether the 945 authorization server sent the resource owner to authenticate with 946 a federated identity provider, and the identity of that federated 947 provider. 948 o Removed the note in the security consideration sections about 949 discussing the purpose of aud, iss, exp validation (redundant). 950 o In the authorization claims section, stated intent to register 951 roles, groups and entitlements as claim types in IANA 952 o Clarified in the privacy considerations that clients should not 953 inspect access tokens. 954 o Expanded the privacy considerations with more explicit guidance 955 about privacy preserving approaches. 956 o Added IANA registry content for the at+JWT MIME type. 957 o Updated acknowledgements. 959 draft-ietf-oauth-access-token-jwt-00 961 o Initial draft to define a JWTt profile for OAuth 2.0 access 962 tokens. 964 Author's Address 966 Vittorio Bertocci 967 Auth0 969 Email: vittorio@auth0.com