idnits 2.17.1 draft-ietf-oauth-access-token-jwt-13.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 (May 25, 2021) is 1066 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 May 25, 2021 5 Expires: November 26, 2021 7 JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens 8 draft-ietf-oauth-access-token-jwt-13 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 November 26, 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 7.2.1.1. Roles . . . . . . . . . . . . . . . . . . . . . . 13 72 7.2.1.2. Groups . . . . . . . . . . . . . . . . . . . . . 14 73 7.2.1.3. Entitlements . . . . . . . . . . . . . . . . . . 14 74 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 75 8.1. Normative References . . . . . . . . . . . . . . . . . . 14 76 8.2. Informative References . . . . . . . . . . . . . . . . . 16 77 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 16 78 Appendix B. Document History . . . . . . . . . . . . . . . . . . 17 79 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 22 81 1. Introduction 83 The original OAuth 2.0 Authorization Framework [RFC6749] 84 specification does not mandate any specific format for access tokens. 85 While that remains perfectly appropriate for many important 86 scenarios, in-market use has shown that many commercial OAuth 2.0 87 implementations elected to issue access tokens using a format that 88 can be parsed and validated by resource servers directly, without 89 further authorization server involvement. The approach is 90 particularly common in topologies where the authorization server and 91 resource server are not co-located, are not run by the same entity, 92 or are otherwise separated by some boundary. At the time of writing, 93 many commercial implementations leverage the JSON Web Tokens (JWT) 94 [RFC7519] format. 96 Many vendor specific JWT access tokens share the same functional 97 layout, using JWT claims to convey the information needed to support 98 a common set of use cases: token validation, transporting 99 authorization information in forms of scopes and entitlements, 100 carrying identity information about the subject, and so on. The 101 differences are mostly confined to the claim names and syntax used to 102 represent the same entities, suggesting that interoperability could 103 be easily achieved by standardizing on a common set of claims and 104 validation rules. 106 The assumption that access tokens are associated to specific 107 information doesn't appear only in commercial implementations. 108 Various specifications in the OAuth 2.0 family (such as resource 109 indicators [RFC8707], OAuth 2.0 bearer token usage [RFC6750] and 110 others) postulate the presence in access tokens of scoping 111 mechanisms, such as an audience. The family of specifications 112 associated to introspection also indirectly suggest a fundamental set 113 of information access tokens are expected to carry or at least be 114 associated with. 116 This specification aims to provide a standardized and interoperable 117 profile as an alternative to the proprietary JWT access token layouts 118 going forward. Besides defining a common set of mandatory and 119 optional claims, the profile provides clear indications on how 120 authorization request parameters determine the content of the issued 121 JWT access token, how an authorization server can publish metadata 122 relevant to the JWT access tokens it issues, and how a resource 123 server should validate incoming JWT access tokens. 125 Finally, this specification provides security and privacy 126 considerations meant to prevent common mistakes and anti patterns 127 that are likely to occur in naive use of the JWT format to represent 128 access tokens. 130 Please note: although both this document and [RFC7523] use JSON Web 131 Tokens in the context of the OAuth2 framework, the two specifications 132 differ in both intent and mechanics. Whereas [RFC7523] defines how a 133 JWT Bearer Token can be used to request an access token, this 134 documents describes how to encode access tokens in JWT format. 136 1.1. Requirements Notation and Conventions 138 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 139 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 140 "OPTIONAL" in this document are to be interpreted as described in BCP 141 14 [RFC2119] [RFC8174] when, and only when, they appear in all 142 capitals, as shown here. 144 1.2. Terminology 146 JWT access token: An OAuth 2.0 access token encoded in JWT format 147 and complying with the requirements described in this 148 specification. 150 This specification uses the terms "access token", "refresh token", 151 "authorization server", "resource server", "authorization endpoint", 152 "authorization request", "authorization response", "token endpoint", 153 "grant type", "access token request", "access token response", and 154 "client" defined by The OAuth 2.0 Authorization Framework [RFC6749]. 156 2. JWT Access Token Header and Data Structure 158 2.1. Header 160 JWT access tokens MUST be signed. Although JWT access tokens can use 161 any signing algorithm, use of asymmetric cryptography is RECOMMENDED 162 as it simplifies the process of acquiring validation information for 163 resource servers (see Section 4). JWT access tokens MUST NOT use 164 "none" as the signing algorithm. See Section 4 for more details. 166 Authorization servers and resource servers conforming to this 167 specification MUST include RS256 (as defined in [RFC7518]) among 168 their supported signature algorithms. 170 This specification registers the "application/at+jwt" media type, 171 which can be used to indicate that the content is a JWT access token. 172 JWT access tokens MUST include this media type in the "typ" header 173 parameter to explicitly declare that the JWT represents an access 174 token complying with this profile. Per the definition of "typ" in 175 Section 4.1.9 of [RFC7515], it is RECOMMENDED that the "application/" 176 prefix be omitted. Therefore, the "typ" value used SHOULD be 177 "at+jwt". See the security considerations section for details on the 178 importance of preventing OpenID Connect ID Tokens (as defined by 179 Section 2 of [OpenID.Core]) from being accepted as access tokens by 180 resource servers implementing this profile. 182 2.2. Data Structure 184 The following claims are used in the JWT access token data structure. 186 iss REQUIRED - as defined in Section 4.1.1 of [RFC7519]. 188 exp REQUIRED - as defined in Section 4.1.4 of [RFC7519]. 190 aud REQUIRED - as defined in Section 4.1.3 of [RFC7519]. See 191 Section 3 for indications on how an authorization server should 192 determine the value of "aud" depending on the request. 194 sub REQUIRED - as defined in Section 4.1.2 of [RFC7519]. In case of 195 access tokens obtained through grants where a resource owner is 196 involved, such as the authorization code grant, the value of "sub" 197 SHOULD correspond to the subject identifier of the resource owner. 198 In case of access tokens obtained through grants where no resource 199 owner is involved, such as the client credentials grant, the value 200 of "sub" SHOULD correspond to an identifier the authorization 201 server uses to indicate the client application. See Section 5 for 202 more details on this scenario. Also, see Section 6 for a 203 discussion about how different choices in assigning "sub" values 204 can impact privacy. 206 client_id REQUIRED - as defined in Section 4.3 of [RFC8693]. 208 iat REQUIRED - as defined in Section 4.1.6 of [RFC7519]. This claim 209 identifies the time at which the JWT access token was issued. 211 jti REQUIRED - as defined in Section 4.1.7 of [RFC7519]. 213 2.2.1. Authentication Information Claims 215 The claims listed in this section MAY be issued in the context of 216 authorization grants involving the resource owner, and reflect in the 217 access token the types and strength of authentication that the 218 authentication server enforced prior to returning the authorization 219 response to the client. Their values are fixed, and remain the same 220 across all access tokens that derive from a given authorization 221 response, whether the access token was obtained directly in the 222 response (e.g., via the implicit flow) or after one or more token 223 exchanges (e.g., obtaining a fresh access token using a refresh 224 token, or exchanging one access token for another via [RFC8693] 225 procedures). 227 auth_time OPTIONAL - as defined in Section 2 of [OpenID.Core]. 229 acr OPTIONAL - as defined in Section 2 of [OpenID.Core]. 231 amr OPTIONAL - as defined in Section 2 of [OpenID.Core]. 233 2.2.2. Identity Claims 235 In the context of authorization grants involving the resource owner, 236 commercial authorization servers will often include resource owner 237 attributes directly in access tokens, so that resource servers can 238 consume them directly for authorization or other purposes without any 239 further round trips to introspection ( [RFC7662]) or UserInfo ( 240 [OpenID.Core]) endpoints. This is particularly common in scenarios 241 where the client and the resource server belong to the same entity 242 and are part of the same solution, as is the case for first party 243 clients invoking their own backend API. 245 This profile does not introduce any mechanism for a client to 246 directly request the presence of specific claims in JWT access 247 tokens, as the authorization server can determine what additional 248 claims are required by a particular resource server by taking in 249 consideration the client_id of the client, the "scope" and the 250 "resource" parameters included in the request. 252 Any additional identity attribute whose semantic is well described by 253 an entry in the JSON Web Token (JWT) IANA registry introduced in 254 [RFC7519] SHOULD be encoded using the corresponding claim name, if 255 that attribute is to be included in the JWT access token. Note that 256 the JWT IANA registry includes the claims found in Section 5.1 of 257 [OpenID.Core]. 259 Authorization servers MAY return arbitrary attributes not defined in 260 any existing specification, as long as the corresponding claim names 261 are collision resistant or the access tokens are meant to be used 262 only within a private subsystem. Please refer to Sections 4.2 and 263 4.3 of [RFC7519] for details. 265 Authorization servers including resource owner attributes in JWT 266 access tokens need to exercise care and verify that all privacy 267 requirements are met, as discussed in Section 6. 269 2.2.3. Authorization Claims 271 If an authorization request includes a scope parameter, the 272 corresponding issued JWT access token SHOULD include a "scope" claim 273 as defined in Section 4.2 of [RFC8693]. 275 All the individual scope strings in the "scope" claim MUST have 276 meaning for the resources indicated in the "aud" claim. See 277 Section 5 for more considerations about the relationship between 278 scope strings and resources indicated by the "aud" claim. 280 2.2.3.1. Claims for Authorization Outside of Delegation Scenarios 282 Many authorization servers embed in the access tokens they issue 283 authorization attributes that go beyond the delegated scenarios 284 described by [RFC7519]. Typical examples include resource owner 285 memberships in roles and groups that are relevant to the resource 286 being accessed, entitlements assigned to the resource owner for the 287 targeted resource that the authorization server knows about, and so 288 on. 290 An authorization server wanting to include such attributes in a JWT 291 access token SHOULD use as claim types the "groups","roles" and 292 "entitlements" attributes of the "User" resource schema defined by 293 Section 4.1.2 of [RFC7643]). 295 Authorization servers SHOULD encode the corresponding claim values 296 according to the guidance defined in [RFC7643]. In particular, a 297 non-normative example of "groups" attribute can be found in 298 Section 8.2 of [RFC7643]. No specific vocabulary is provided for 299 "roles" and "entitlements". 301 Section 7 of this document provides entries for registering "groups", 302 "roles" and "entitlements" attributes from [RFC7643] as claim types 303 to be used in this profile. 305 3. Requesting a JWT Access Token 307 An authorization server can issue a JWT access token in response to 308 any authorization grant defined by [RFC6749] and subsequent 309 extensions meant to result in an access token. 311 If the request includes a "resource" parameter (as defined in 312 [RFC8707]), the resulting JWT access token "aud" claim SHOULD have 313 the same value as the "resource" parameter in the request. 315 Example request below: 317 GET /as/authorization.oauth2?response_type=code 318 &client_id=s6BhdRkqt3 319 &state=xyz 320 &scope=openid%20profile%20reademail 321 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 322 &resource=https%3A%2F%2Frs.example.com%2F HTTP/1.1 323 Host: authorization-server.example.com 325 Figure 1: Authorization Request with Resource and Scope Parameters 327 Once redeemed, the code obtained from the request above will result 328 in a JWT access token in the form shown below: 330 Header: 332 {"typ":"at+JWT","alg":"RS256","kid":"RjEwOwOA"} 334 Claims: 336 { 337 "iss": "https://authorization-server.example.com/", 338 "sub": "5ba552d67", 339 "aud": "https://rs.example.com/", 340 "exp": 1639528912, 341 "iat": 1618354090, 342 "jti" : "dbe39bf3a3ba4238a513f51d6e1691c4", 343 "client_id": "s6BhdRkqt3", 344 "scope": "openid profile reademail" 345 } 347 Figure 2: The Header and JWT Claims Set of a JWT Access Token 349 The authorization server MUST NOT issue a JWT access token if the 350 authorization granted by the token would be ambiguous. See Section 5 351 for more details about common cases that might lead to ambiguity and 352 strategies an authorization server can enact to prevent them. 354 If the request does not include a "resource" parameter, the 355 authorization server MUST use in the "aud" claim a default resource 356 indicator. If a "scope" parameter is present in the request, the 357 authorization server SHOULD use it to infer the value of the default 358 resource indicator to be used in the "aud" claim. The mechanism 359 through which scopes are associated to default resource indicator 360 values is outside the scope of this specification. If the values in 361 the "scope" parameter refer to different default resource indicator 362 values, the authorization server SHOULD reject the request with 363 "invalid_scope" as described in Section 4.1.2.1 of [RFC6749]. 365 4. Validating JWT Access Tokens 367 For the purpose of facilitating validation data retrieval, it is here 368 RECOMMENDED that authorization servers sign JWT access tokens with an 369 asymmetric algorithm. 371 Authorization servers SHOULD use OAuth 2.0 Authorization Server 372 Metadata [RFC8414] to advertise to resource servers their signing 373 keys via "jwks_uri" and what "iss" claim value to expect via the 374 "issuer" metadata value. Alternatively, authorization servers 375 implementing OpenID Connect MAY use the "OpenID Connect discovery 376 [OpenID.Discovery] document for the same purpose. If an 377 authorization server supports both OAuth 2.0 Authorization Server 378 Metadata and OpenID Connect discovery, the values provided MUST be 379 consistent across the two publication methods. 381 An authorization server MAY elect to use different keys to sign 382 OpenID Connect ID Tokens and JWT access tokens. This specification 383 does not provide a mechanism for identifying a specific key as the 384 one used to sign JWT access tokens. An authorization server can sign 385 JWT access tokens with any of the keys advertised via AS metadata or 386 OpenID Connect discovery. See Section 5 for further guidance on 387 security implications. 389 Resource servers receiving a JWT access token MUST validate it in the 390 following manner. 392 o The resource server MUST verify that the typ header value is 393 "at+jwt" or "application/at+jwt" and reject tokens carrying any 394 other value. 396 o If the JWT access token is encrypted, decrypt it using the keys 397 and algorithms that the resource server specified during 398 registration. If encryption was negotiated with the authorization 399 server at registration time and the incoming JWT access token is 400 not encrypted, the resource server SHOULD reject it. 402 o The Issuer Identifier for the authorization server (which is 403 typically obtained during discovery) MUST exactly match the value 404 of the "iss" claim. 406 o The resource server MUST validate that the "aud" claim contains a 407 resource indicator value corresponding to an identifier the 408 resource server expects for itself. The JWT access token MUST be 409 rejected if "aud" does not contain a resource indicator of the 410 current resource server as a valid audience. 412 o The resource server MUST validate the signature of all incoming 413 JWT access tokens according to [RFC7515] using the algorithm 414 specified in the JWT alg Header Parameter. The resource server 415 MUST reject any JWT in which the value of "alg" is "none". The 416 resource server MUST use the keys provided by the authorization 417 server. 419 o The current time MUST be before the time represented by the "exp" 420 claim. Implementers MAY provide for some small leeway, usually no 421 more than a few minutes, to account for clock skew. 423 The resource server MUST handle errors as described in Section 3.1 of 424 [RFC6750]. In particular, in case of any failure in the validation 425 checks listed above the authorization server response MUST include 426 the error code "invalid_token". Please note that this requirement 427 does not prevent JWT access tokens to use authentications schemes 428 other than Bearer. 430 If the JWT access token includes authorization claims as described in 431 Section 2.2.3, the resource server SHOULD use them in combination 432 with any other contextual information available to determine whether 433 the current call should be authorized or rejected. Details about how 434 a resource server performs those checks is beyond the scope of this 435 profile specification. 437 5. Security Considerations 439 The JWT access token data layout described here is very similar to 440 the one of the id_token as defined by [OpenID.Core]. The explicit 441 typing required in this profile, in line with the recommendations in 442 [RFC8725] helps the resource server to distinguish between JWT access 443 tokens and OpenID Connect ID Tokens. 445 Authorization servers should prevent scenarios where clients can 446 affect the value of the "sub" claim in ways that could confuse 447 resource servers. For example, if the authorization server elects to 448 use the client_id as the "sub" value for access tokens issued using 449 the client credentials grant, the authorization server should prevent 450 clients from registering an arbitrary client_id value, as this would 451 allow malicious clients to select the sub of a high privilege 452 resource owner and confuse any authorization logic on the resource 453 server relying on the "sub" value. For more details please refer to 454 Section 4.14 of [OAuth2.Security.BestPractices]. 456 To prevent cross-JWT confusion, authorization servers MUST use a 457 distinct identifier as "aud" claim value to uniquely identify access 458 tokens issued by the same issuer for distinct resources. For more 459 details on cross-JWT confusion please refer to Section 2.8 of 460 [RFC8725]. 462 Authorization servers should use particular care when handling 463 requests that might lead to ambiguous authorization grants. For 464 example: if a request includes multiple resource indicators, the 465 authorization server should ensure that each scope string included in 466 the resulting JWT access token, if any, can be unambiguously 467 correlated to a specific resource among the ones listed in the "aud" 468 claim. The details on how to recognize and mitigate this and other 469 ambiguous situations is highly scenario-dependent, hence out of scope 470 for this profile. 472 Authorization servers cannot rely on the use of different keys for 473 signing OpenID Connect ID Tokens and JWT tokens as a method to 474 safeguard against the consequences of leaking specific keys. Given 475 that resource servers have no way of knowing what key should be used 476 to validate JWT access tokens in particular, they have to accept 477 signatures performed with any of the keys published in AS metadata or 478 OpenID Connect discovery: consequently, an attacker just needs to 479 compromise any key among the ones published to be able to generate 480 and sign JWTs that will be accepted as valid by the resource server. 482 6. Privacy Considerations 484 As JWT access tokens carry information by value, it now becomes 485 possible for clients and potentially even end users to directly peek 486 inside the token claims collection of unencrypted tokens. 488 The client MUST NOT inspect the content of the access token: the 489 authorization server and the resource server might decide to change 490 token format at any time (for example by switching from this profile 491 to opaque tokens) hence any logic in the client relying on the 492 ability to read the access token content would break without 493 recourse. The OAuth 2.0 framework assumes that access tokens are 494 treated as opaque by clients. Administrators of authorization 495 servers should also take into account that the content of an access 496 token is visible to the client. Whenever client access to the access 497 token content presents privacy issues for a given scenario, the 498 authorization server needs to take explicit steps to prevent it. 500 In scenarios in which JWT access tokens are accessible to the end 501 user, it should be evaluated whether the information can be accessed 502 without privacy violations (for example, if an end user would simply 503 access his or her own personal information) or if steps must be taken 504 to enforce confidentiality. 506 Possible measures to prevent leakage of information to clients and 507 end users include: encrypting the access token, encrypting the 508 sensitive claims, omitting the sensitive claims or not using this 509 profile, falling back on opaque access tokens. 511 In every scenario, the content of the JWT access token will 512 eventually be accessible to the resource server. It's important to 513 evaluate whether the resource server gained the proper entitlement to 514 have access to any content received in form of claims, for example 515 through user consent in some form, policies and agreements with the 516 organization running the authorization servers, and so on. For 517 example, a user might not wish to consent to granting a given 518 resource server information about any of the non-mandatory claims 519 enumerated in Section 2 (and subsections)." 520 This profile mandates the presence of the "sub" claim in every JWT 521 access token, making it possible for resource servers to rely on that 522 information for correlating incoming requests with data stored 523 locally for the authenticated principal. Although the ability to 524 correlate requests might be required by design in many scenarios, 525 there are scenarios where the authorization server might want to 526 prevent correlation. The "sub" claim should be populated by the 527 authorization servers according to a privacy impact assessment. For 528 instance, if a solution requires preventing tracking principal 529 activities across multiple resource servers, the authorization server 530 should ensure that JWT access tokens meant for different resource 531 servers have distinct "sub" values that cannot be correlated in the 532 event of resource servers collusion. Similarly, if a solution 533 requires preventing a resource server from correlating the 534 principal's activity within the resource itself, the authorization 535 server should assign different "sub" values for every JWT access 536 token issued. In turn, the client should obtain a new JWT access 537 token for every call to the resource server, to ensure that the 538 resource server receives different "sub" and "jti" values at every 539 call, thus preventing correlation between distinct requests. 541 7. IANA Considerations 543 7.1. Media Type Registration 545 7.1.1. Registry Content 547 This section registers the "application/at+jwt" media type [RFC2046] 548 in the "Media Types" registry [IANA.MediaTypes] in the manner 549 described in [RFC6838], which can be used to indicate that the 550 content is an access token encoded in JWT format. 552 o Type name: application 554 o Subtype name: at+jwt 556 o Required parameters: N/A 558 o Optional parameters: N/A 560 o Encoding considerations: binary; JWT values are encoded as a 561 series of base64url-encoded values (with trailing '=' characters 562 removed), some of which may be the empty string, separated by 563 period ('.') characters. 565 o Security considerations: See the Security Considerations 566 Section of [[TODO: update once there's a RFC number for the JWT AT 567 profile]] 569 o Interoperability considerations: N/A 571 o Published specification: [[TODO: update once there's a RFC number 572 for the JWT AT profile]] 574 o Applications that use this media type: Applications that access 575 resource servers using OAuth 2.0 access tokens encoded in JWT 576 format 578 o Fragment identifier considerations: N/A 580 o Additional information: Magic number(s): N/A File extension(s): N/ 581 A Macintosh file type code(s): N/A 583 o Person and email address to contact for further information: 584 Vittorio Bertocci, vittorio@auth0.com 586 o Intended usage: COMMON 588 o Restrictions on usage: none 590 o Author: Vittorio Bertocci, vittorio@auth0.com 592 o Change controller: IESG 594 o Provisional registration? No 596 7.2. Claims Registration 598 Section 2.2.3.1 of this specification refers to the attributes 599 "roles", "groups", "entitlements" defined in [RFC7643] to express 600 authorization information in JWT access tokens. This section 601 registers those attributes as claims in the JSON Web Token (JWT) IANA 602 registry introduced in [RFC7519]. 604 7.2.1. Registry Contents 606 7.2.1.1. Roles 608 o Claim Name: "roles" 610 o Claim Description: Roles 612 o Change Controller: IESG 614 o Specification Document(s): Section 4.1.2 of [RFC7643] and 615 Section 2.2.3.1 of [[this specification]] 617 7.2.1.2. Groups 619 o Claim Name: "groups" 621 o Claim Description: Groups 623 o Change Controller: IESG 625 o Specification Document(s): Section 4.1.2 of [RFC7643] and 626 Section 2.2.3.1 of [[this specification]] 628 7.2.1.3. Entitlements 630 o Claim Name: "entitlements" 632 o Claim Description: Entitlements 634 o Change Controller: IESG 636 o Specification Document(s): Section 4.1.2 of [RFC7643] and 637 Section 2.2.3.1 of [[this specification]] 639 8. References 641 8.1. Normative References 643 [OpenID.Core] 644 Sakimura, N., Bradley, J., Jones, M., Medeiros, B., and C. 645 Mortimore, "OpenID Connect Core 1.0", November 2014, 646 . 648 [OpenID.Discovery] 649 Sakimura, N., Bradley, J., Jones, M., and J. Jay, "OpenID 650 Connect Discovery 1.0", November 2014, 651 . 654 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 655 Extensions (MIME) Part Two: Media Types", RFC 2046, 656 DOI 10.17487/RFC2046, November 1996, 657 . 659 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 660 Requirement Levels", BCP 14, RFC 2119, 661 DOI 10.17487/RFC2119, March 1997, 662 . 664 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 665 RFC 6749, DOI 10.17487/RFC6749, October 2012, 666 . 668 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 669 Specifications and Registration Procedures", BCP 13, 670 RFC 6838, DOI 10.17487/RFC6838, January 2013, 671 . 673 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 674 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 675 2015, . 677 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 678 DOI 10.17487/RFC7518, May 2015, 679 . 681 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 682 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 683 . 685 [RFC7643] Hunt, P., Ed., Grizzle, K., Wahlstroem, E., and C. 686 Mortimore, "System for Cross-domain Identity Management: 687 Core Schema", RFC 7643, DOI 10.17487/RFC7643, September 688 2015, . 690 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 691 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 692 May 2017, . 694 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 695 Authorization Server Metadata", RFC 8414, 696 DOI 10.17487/RFC8414, June 2018, 697 . 699 [RFC8693] Jones, M., Nadalin, A., Campbell, B., Ed., Bradley, J., 700 and C. Mortimore, "OAuth 2.0 Token Exchange", RFC 8693, 701 DOI 10.17487/RFC8693, January 2020, 702 . 704 [RFC8707] Campbell, B., Bradley, J., and H. Tschofenig, "Resource 705 Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, 706 February 2020, . 708 [RFC8725] Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best 709 Current Practices", BCP 225, RFC 8725, 710 DOI 10.17487/RFC8725, February 2020, 711 . 713 8.2. Informative References 715 [OAuth2.Security.BestPractices] 716 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 717 "OAuth 2.0 Security Best Current Practice", July 2019, 718 . 721 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 722 Framework: Bearer Token Usage", RFC 6750, 723 DOI 10.17487/RFC6750, October 2012, 724 . 726 [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 727 (JWT) Profile for OAuth 2.0 Client Authentication and 728 Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 729 2015, . 731 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 732 RFC 7662, DOI 10.17487/RFC7662, October 2015, 733 . 735 Appendix A. Acknowledgements 737 The initial set of requirements informing this specification was 738 extracted by numerous examples of access tokens issued in JWT format 739 by production systems. Thanks to Dominick Baier (IdentityServer), 740 Brian Campbell (Ping Identity), Daniel Dobalian (Microsoft), Karl 741 Guinness (Okta) for providing sample tokens issued by their products 742 and services. Brian Campbell and Filip Skokan provided early 743 feedback that shaped the direction of the specification. This 744 profile was discussed at length during the OAuth Security Workshop 745 2019, with several individuals contributing ideas and feedback. The 746 author would like to acknowledge the contributions of: 748 John Bradley, Brian Campbell, Vladimir Dzhuvinov, Torsten 749 Lodderstedt, Nat Sakimura, Hannes Tschofenig and everyone who 750 actively participated in the unconference discussions. 752 The following individuals contributed useful feedback and insights on 753 the drafts, both on the IETF OAuth 2.0 WG DL and during the IIW28 754 conference: 756 Dale Olds, George Fletcher, David Waite, Michael Engan, Mike Jones, 757 Hans Zandbelt, Vladimir Dzhuvinov, Martin Schanzenbach , Aaron 758 Parecki, Annabelle Richard Backman, Dick Hardt, Denis Pinkas, 759 Benjamin Kaduk, Dominick Baier, Andrii Deinega, Mike Jones and 760 everyone who actively participated in the IIW28 unconference 761 discussions and the IETF OAuth 2.0 WG DL discussions. Thanks to 762 Roman Danyliw for the AD review, Joseph Salowey and Roni Even for the 763 SECDIR/GENART reviews, Francesca Palomini, Lars Eggert, Murray 764 Kucherawy, Roberto Polli, Martin Duke, Benjamin Kaduk for the IESG 765 reviews. 767 Appendix B. Document History 769 [[ to be removed by the RFC Editor before publication as an RFC ]] 771 draft-ietf-oauth-access-token-jwt-13 773 o Added an explicit requirement for the JWT access tokens to be 774 signed in Section 2.1. 775 o Added sections in Section 7.2 for improving readability. 776 o In Figure 2, added jti and iat claims. 777 o Editorial fixes in Section 2.2.1 and Section 4. 778 o Clarified that additional claims are to be added only if necessary 779 - in Section 2.2.2. Editorial changes in the same section. 780 o Updates sample values in Section 3. 781 o Added leeway language to the exp validation step in Section 4. 782 o In Section 4, clarified that the use of RFC6750 error codes does 783 not imply that JWT ATs can only be Bearer tokens. 784 o Various edits and nits in Section 5 and Section 6. 785 o Added clarifying language in Section 6 regarding what claims in 786 the AT might require explicit user consent. 787 o Added URLs for the OpenID references and the oauth security BCP. 788 Moved RFC7523 to the informative references section. 790 draft-ietf-oauth-access-token-jwt-12 792 o Editorial changes in the abstract. 793 o Updated the client_id value in the figures in Section 3. 794 o Added clarifying language in Section 1 positioning this 795 specification vs [RFC7523]. 796 o In section Section 2.1 added a sentence that makes RS256 support 797 mandatory for AS and RS. 799 draft-ietf-oauth-access-token-jwt-11 801 o Editorial updates and typo fixes in Section 1.2, Section 2.2, 802 Section 2.2.1, Section 2.2.2, Section 3, Section 4, Section 5, 803 Appendix A 804 o Updated language in Section 2.2.2 to explicitly refer to the JWT 805 IANA registry. 806 o Citation added in in Section 2.1 807 o Added a normative reference entry for OpenID Connect Discovery 1.0 808 and referenced it from Section 4 810 o Updated Figure 2 in Section 3 to clarify that the intent of that 811 snippet is to describe the content rather than exact JWT AT 812 format. 813 o Updated registry references in Section 7.2.1 to point to 814 Section 2.2.3.1 815 o Modified Section 2.2.3.1 to make it easier for the reader to 816 understand what values and format is expected for the groups, 817 roles and entitlement claims. Minor formatting issues fixed. 819 draft-ietf-oauth-access-token-jwt-09 821 o Removed unused reference to http://www.iana.org/assignments/oauth- 822 parameters; moved the OAuth2 security BCP to the informative 823 references section. 824 o Restructured opening paragraphs in Section 6 for clarity. 826 draft-ietf-oauth-access-token-jwt-08 828 o Numerous edits for correcting typos, improving clarity and 829 precision of language. 830 o Moved RFC7519 to the normative section; eliminated unused 831 references RFC7644 and RFC3986. 833 draft-ietf-oauth-access-token-jwt-07 835 o In Section 2.1, added language that forbids use of none as alg 836 value, and references Section 4 where the same prohibition was 837 already expressed from the RS perspective. 838 o In the sub definition in Section 2.2, added a sentence that 839 clarifies what goes in the sub in the case of grants where a 840 resource owner is involved. 841 o Updated acknowledgements. 842 o Updated Section 2.2.1 to clarify that acr, amr and auth_type can 843 occur if the AT has been obtained by grants where the resource 844 owner is involved. 845 o Updated Section 2.2.2 to clarify that identity claims can occur if 846 the AT has been obtained by grants where the resource owner is 847 involved. 848 o In Section 2.2.3.1 eliminated the claim that SCIM doesn't provide 849 a vocabulary for the attributes listed there. 850 o In Section 5 added reference to 8725. 851 o In Section 4 added application/jwt+at as accepted typ value. 852 o Various typos and formatting issues fixed. 854 draft-ietf-oauth-access-token-jwt-06 855 o In Section 2.2 and Section 6 added a discussion about how 856 different sub values affect the privacy properties of a solution. 857 o In Section 2.2.3 and Section 3 eliminated language prohibiting JWT 858 AT requests featuring multiple resources, substituting it with the 859 prohibition for the AS to emit JWT ATs expressing ambiguous 860 authorization grants. In Section 5, added language warning 861 against scope confusion and mentioned the existence of other 862 ambiguous authorization grant. 863 o In Section 2.2 promoted claims iat and jti from RECOMMENDED to 864 REQUIRED. 865 o In Section 2.1 eliminated temporary note on the lack of 866 authenticated encryption methods specifications. 867 o Updated acknowledgements. 869 draft-ietf-oauth-access-token-jwt-05 871 o Varios typos, grammar issues and improper abbreviations fixed. 872 o Reworded the definition of at+jwt in Section 2.1. 873 o In Section 2.2, clarified that iat refers to the issuance time of 874 the JWT itself. 875 o In Section 2.2.2, added a reference to public/private claims 876 definitions (Sections 4.2, 4.3) of [RFC7519]. 877 o In Section 3, removed the paragrah stating that every JWT AT MUST 878 have an aud, as it is already defined in Section 2.2. 879 o Reworded description of the JWT AT adoption landscape in 880 Section 1. 881 o Simplified the individual descriptions of the claims list in 882 Section 2.2.1. 883 o Updated Section 4 and Section 5 to clarify that the AS can use any 884 of the published keys to sign JWT access tokens, and that the AS 885 should not rely on use of different signing keys per token type as 886 a security mechanism. 887 o In Section 2.2 promoted claims iat and jti from OPTIONAL to 888 RECOMMENDED 889 o In Section 4, switched the validation steps list type from numbers 890 to bullets. 891 o In Section 4, eliminated the auth_time instructions from the 892 validation steps list. 893 o In Section 2.2.2, added a reference to the JWT claims registry as 894 source of claims for JWT ATs 895 o In Section 4, clarified that failures in JWT AT validation checks 896 will result in invalid_token. 898 draft-ietf-oauth-access-token-jwt-04 900 o Eliminated reference to resource aliases list from the aud claim 901 description in Section 2. 903 o Eliminated references to resource aliases list from the aud 904 validation guidance in Section 4. 905 o Introduced a new subsection Section 2.2.1, moved the definitions 906 of auth_time, acr and amr there and incorporated the language 907 proposed by Annabelle and Brian on the WG mailing list. 908 o In section Section 3 softened (from MUST to SHOULD) the 909 requirement that ties the resource identifier in the request to 910 the value in the aud claim of the issued access token. 911 o Updated acknowledgements. 912 o In the section Section 3, the example request now has 913 response_type=code. 914 o Updated text in the Privacy Consideration section to clarify what 915 protection steps the text refers to. 916 o Updated the typ header discussion in Section 2.1 to clarify that 917 it helps preventing resources from accepting OpenID Connect ID 918 Tokens as JWT access tokens. 919 o Updated refrences to token exchange, resource indicators and JWT 920 best practices to reflect their RFC status (8693,8707,8725). 922 draft-ietf-oauth-access-token-jwt-03 924 o Varios typos fixed. 925 o In the security considerations section, relaxed the claim that the 926 typ header value "at+jwt" will prevent RS from misinterpreting JWT 927 ATs as idtokens. 928 o In the "Requesting JWT Access Tokens" section, added 929 "invalid_target" as a possible error returned for the multiple 930 resources request case. 931 o In the Validating JWT Access Tokens" section, disallowed JWTs with 932 "alg":"none" 933 o in the IANA registration entries for the SCIM claim types, 934 complemented the reference to the SCIM spec with a reference to 935 this spec so that the eventual registration entries have better 936 context. 937 o Updated acknowledgements. 938 o In the section Section 3, the example request now has 939 response_type=code. 940 o Updated text in the Privacy Consideration section to clarify what 941 protection steps the text refers to. 943 draft-ietf-oauth-access-token-jwt-02 945 o In 2.2.1, opened the sources of identity attributes to any 946 identity related specification. 947 o In 2.2.2, relaxed from MUST to SHOULD the requirement that 948 requests including a scope always result in access tkens 949 containing a corresponding scope claim. 951 o In the security considerations setting, added a requirement for 952 the authorization server to assing unique identifiers for 953 different resources- to prevent cross JWT confusion. 954 o Added IANA registration for the authorization attributes borrowed 955 from SCIM CORE 957 draft-ietf-oauth-access-token-jwt-01 959 o Added note on authenticated encryption. 960 o Added a mention to the 1st party clients scenarios in the identity 961 claims section. 962 o Changed the definition reference for the iss, exp, aud, sub, iat 963 claims from OpenID.Core to RFC7519. 964 o Added a mention of the client_id==sub case in the security 965 considerations section, added a reference to draft-ietf-oauth- 966 security-topics-13. Added a reference to the security 967 considerations from the sub claim definition section. 968 o Specified invalid_request as the error code the authorization 969 server should return in case of multiple resources in the access 970 token request. 971 o Specified invalid_scope as the error code the authorization server 972 should return in case it isn;t possible to determine to which 973 resource the requested scopes refers to. 974 o In the identity claims section, added a reference to introspection 975 as possible source of claim types and added language explicitly 976 stating that the AS can add arbitrary attributes as long as they 977 are collision resistant or private. 978 o Updated language for the auth_time claim to include the case in 979 which the AS reauthenticates the user mid-session (e.g. during 980 step up auth). 981 o Removed note about adding a mechanism for extablishing whether the 982 token was obtained on behalf or the resource owner or of the 983 client itself (client credentials grant). 984 o Removed note about adding a mechanism for indicating whether the 985 authorization server sent the resource owner to authenticate with 986 a federated identity provider, and the identity of that federated 987 provider. 988 o Removed the note in the security consideration sections about 989 discussing the purpose of aud, iss, exp validation (redundant). 990 o In the authorization claims section, stated intent to register 991 roles, groups and entitlements as claim types in IANA 992 o Clarified in the privacy considerations that clients should not 993 inspect access tokens. 994 o Expanded the privacy considerations with more explicit guidance 995 about privacy preserving approaches. 996 o Added IANA registry content for the at+JWT MIME type. 997 o Updated acknowledgements. 999 o Initial draft to define a JWTt profile for OAuth 2.0 access 1000 tokens. 1002 Author's Address 1004 Vittorio Bertocci 1005 Auth0 1007 Email: vittorio@auth0.com