idnits 2.17.1 draft-ietf-oauth-access-token-jwt-00.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 (April 22, 2019) is 1831 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 465, but no explicit reference was found in the text == Unused Reference: 'RFC7644' is defined on line 507, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'ResourceIndicators' -- Possible downref: Non-RFC (?) normative reference: ref. 'TokenExchange' Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). 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 22, 2019 5 Expires: October 24, 2019 7 JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens 8 draft-ietf-oauth-access-token-jwt-00 10 Abstract 12 This specification defines a profile for issuing OAuth2 access tokens 13 in JSON web token (JWT) format. Authorization servers and resource 14 servers from different vendors can leverage this profile to issue and 15 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 24, 2019. 34 Copyright Notice 36 Copyright (c) 2019 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 . . . . . . . . . 3 55 2.1. Header . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 2.2. Data Structure . . . . . . . . . . . . . . . . . . . . . 4 57 2.2.1. Identity Claims . . . . . . . . . . . . . . . . . . . 5 58 2.2.2. Authorization Claims . . . . . . . . . . . . . . . . 5 59 2.2.2.1. Claims for Authorization Outside of Delegation 60 Scenarios . . . . . . . . . . . . . . . . . . . . 5 61 3. Requesting a JWT Access Token . . . . . . . . . . . . . . . . 6 62 4. Validating JWT Access Tokens . . . . . . . . . . . . . . . . 7 63 5. Security Considerations . . . . . . . . . . . . . . . . . . . 9 64 6. Privacy Considerations . . . . . . . . . . . . . . . . . . . 9 65 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 66 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 67 8.1. Normative References . . . . . . . . . . . . . . . . . . 10 68 8.2. Informative References . . . . . . . . . . . . . . . . . 11 69 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 11 70 Appendix B. Document History . . . . . . . . . . . . . . . . . . 12 71 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12 73 1. Introduction 75 The original OAuth 2.0 Authorization Framework [RFC6749] 76 specification does not mandate any specific format for access tokens. 77 While that remains perfectly appropriate for many important scenario, 78 in-market use has shown that many commercial OAuth2 implementations 79 elected to issue access tokens using a format that can be parsed and 80 validated by resource servers directly, without further authorization 81 server involvement. The approach is particularly common in 82 topologies where the authorization server and resource server are not 83 co-located, are not ran by the same entity, or are otherwise 84 separated by some boundary. All of the known commercial 85 implementations known at this time leverage the JSON Web Tokens(JWT) 86 [RFC7519] format. 88 Most vendor specific JWT access tokens share the same functional 89 layout, including information in forms of claims meant to support the 90 same scenarios: token validation, transporting authorization 91 information in forms of scopes and entitlements, carrying identity 92 information about the subject, and so on. The differences are mostly 93 confined to the claim names and syntax used to represent the same 94 entities, suggesting that interoperability could be easily achieved 95 by standardizing on a common set of claims and validation rules. 97 The assumption that access tokens are associated to specific 98 information doesn't appear only in commercial implementations. 99 Various specifications in the OAuth2 family (such as resource 100 indicators [ResourceIndicators], bearer token usage [RFC6750] and 101 others) postulate the presence in access tokens of scoping 102 mechanisms, such as an audience. The family of specifications 103 associated to introspection also indirectly suggest a fundamental set 104 of information access tokens are expected to carry or at least be 105 associated with. 107 This specification aims to provide a standardized and interoperable 108 profile as an alternative to the proprietary JWT access tokens 109 layouts going forward. Besides defining a common set of mandatory 110 and optional claims, the profile provides clear indications on how 111 authorization requests parameters determine the content of the issued 112 JWT access token, how an authorization server can publish metadata 113 relevant to the JWT access tokens it issues, and how a resource 114 server should validate incoming JWT access tokens. 116 Finally, this specification provides security and privacy 117 considerations meant to prevent common mistakes and anti patterns 118 that are likely to occur in naive use of the JWT format to represent 119 access tokens. 121 1.1. Requirements Notation and Conventions 123 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 124 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 125 "OPTIONAL" in this document are to be interpreted as described in BCP 126 14 [RFC2119] [RFC8174] when, and only when, they appear in all 127 capitals, as shown here. 129 1.2. Terminology 131 JWT access token An OAuth 2.0 access token encoded in JWT format and 132 complying with the requirements described in this specification. 134 This specification uses the terms "access token", "refresh token", 135 "authorization server", "resource server", "authorization endpoint", 136 "authorization request", "authorization response", "token endpoint", 137 "grant type", "access token request", "access token response", and 138 "client" defined by The OAuth 2.0 Authorization Framework [RFC6749]. 140 2. JWT Access Token Header and Data Structure 142 JWT access tokens are regular JWT tokens complying with the 143 requirements described in this section. 145 2.1. Header 147 Although JWT access tokens can use any signing algorithm, use of 148 asymmetric algorithms is RECOMMENDED as it simplifies the process of 149 acquiring validation information for resource servers (see 150 Section 4). 152 The typ header parameter for a JWT access token MUST be at+jwt. See 153 the security considerations section for details on the importance of 154 preventing JWT access tokens to be interpreted as id_tokens. 156 2.2. Data Structure 158 The following claims are used in the JWT access token data structure. 160 iss REQUIRED - as defined in section 2 of [OpenID.Core]. 162 exp REQUIRED - as defined in section 2 of [OpenID.Core]. 164 aud REQUIRED - as defined in section 2 of [OpenID.Core]. See 165 Section 3 for indications on how an authorization server should 166 determine the value of aud depending on the request. [Note: some 167 vendors seem to rely on resource aliases. If we believe this to 168 be a valuable feature, here's some proposed language: The aud 169 claim MAY include a list of individual resource indicators if they 170 are all aliases referring to the same requested resource known by 171 the authorization server. ] 173 sub REQUIRED - as defined in section 2 of [OpenID.Core]. . In case 174 of access tokens obtained through grants where no resource owner 175 is involved, such as the client credentials grant, the value of 176 sub SHOULD correspond to an identifier the authorization server 177 uses to indicate the client application (such as the client_id). 179 client_id REQUIRED - as defined in section 4.3 of [TokenExchange]. 181 iat OPTIONAL - as defined in section 2 of [OpenID.Core]. 183 auth_time OPTIONAL - as defined in section 2 of [OpenID.Core]. 184 Important: as this claim represents the time at which the end user 185 authenticated, its value will remain the same for all the JWT 186 access tokens issued within that session. For example: all the 187 JWT access tokens obtained with a given refresh token will all 188 have the same value of auth_time, corresponding to the instant in 189 which the user first authenticated to obtain the refresh token. 191 jti OPTIONAL - as defined in section 4.1.7 of [RFC7519]. 193 acr, amr OPTIONAL - as defined in section 2 of [OpenID.Core]. The 194 same considerations presented for auth_time apply to acr and amr: 195 those values reflect the authentication context and method used 196 when the end user originally authenticated, and will remain 197 unchanged for the JWT access tokens issued within the context of 198 that session. 200 2.2.1. Identity Claims 202 Commercial authorization servers will often include resource owner 203 attributes directly in access tokens, so that resource servers can 204 consume them directly for authorization or other purposes without any 205 further roudtrips to introspection ([RFC7662]) or userinfo 206 ([OpenID.Core]) endpoints. 208 This profile does not introduce any mechanism for a client to 209 directly request the presence of specific claims in JWT access 210 tokens, as the authorization server can determine what additional 211 claims are required by a particular resource server by taking in 212 consideration the client_id of the client, the scope and the resource 213 parameters included in the request. 215 Any additional attributes whose semantic is well described by the 216 attributes description found in section 5.1 of [OpenID.Core] SHOULD 217 be codified in JWT access tokens via the corresponding claim names in 218 that section of the OpenID Connect specification. 220 Authorization servers including resource owner attributes in JWT 221 access tokens should exercise care and verify that all privacy 222 requirements are met, as discussed in Section 6. 224 2.2.2. Authorization Claims 226 If an authorization request includes a scope parameter, the 227 corresponding issued JWT access token MUST include a scope claim as 228 defined in section 4.2 of [TokenExchange]. 230 All the individual scopes strings in the scope claim MUST have 231 meaning for the resource indicated in the aud claim. 233 2.2.2.1. Claims for Authorization Outside of Delegation Scenarios 235 Many authorization servers embed in the access tokens they issue 236 authorization attributes that go beyond the delegated scenarios 237 described by [RFC7519]. Typical examples include resource owner 238 memberships in roles and groups that are relevant to the resource 239 being accessed, entitlements assigned to the resource owner for the 240 targeted resource that the authorization server knows about, and so 241 on. 243 An authorization server wanting to include such attributes in a JWT 244 access token SHOULD use as claim types the attributes described by 245 section 4.1.2 of SCIM Core ([RFC7643]) and in particular roles, 246 groups and entitlements. As in their original definition in 247 [RFC7643] , this profile does not provide a specific vocabulary for 248 those entities. 250 [[note 1 some commercial authorization server include claims 251 indicating whether the client authenticated with the authorization 252 server as a confidential client, for the purpose of determining 253 whether the client_id can be used as a reliable indicator of the 254 identity of the caller (and take thatinto account for authorization 255 decisions). Discussions at OSW2019 on how to achieve this were 256 inconclusive hence this was punted for further discussion]] 258 [[note 2 some commercial authorization server include claims 259 indicating whether the resource owner authenticated with a federated 260 identity provider rather than directly with the authorization server. 261 During discussions at OSW2019 there were lukewarm reactions. One 262 proposed line of investigation was to examine what 263 https://tools.ietf.org/html/draft-ietf-secevent-token-13#page-10 does 264 with the sub structure and see whether some mechanisms can be 265 applicable here; however for this early draft no further 266 investigation was made and no info is provided beyond this note]] 268 3. Requesting a JWT Access Token 270 An authorization server can issue a JWT access token in response to 271 any authorization grant defined by [RFC6749] and subsequent 272 extensions meant to result in an access token. 274 Every JWT access token MUST include an aud claim (see Section 2.2). 276 If the request includes a resource parameter (as defined in 277 [ResourceIndicators]), the resulting JWT access token aud claim MUST 278 have the same value as the resource parameter in the request. 280 Example request below: 282 GET /as/authorization.oauth2?response_type=token 283 &client_id=s6BhdRkqt3&state=laeb 284 &scope=openid%20profile%20reademail 285 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 286 &resource=https%3A%2F%2Frs.example.com%2F HTTP/1.1 287 Host: authorization-server.example.com 289 Figure 1: Authorization Request with Resource and Scope Parameters 291 Once redeemed, the code obtained from the request above will result 292 in a JWT access token in the form shown below: 294 {"typ":"at+JWT","alg":"RS256","kid":"RjEwOwOA"} 295 { 296 "iss": "https://authorization-server.example.com/", 297 "sub": " 5ba552d67", 298 "aud": "https://rs.example.com/", 299 "exp": 1544645174, 300 "client_id": "s6BhdRkqt3_", 301 "scope": "openid profile reademail" 302 } 304 Figure 2: A JWT Access Token 306 If it receives a request for an access token containing more than one 307 resource parameter, an authorization server issuing JWT access tokens 308 MUST reject the request and fail with [[TODO: select appropriate 309 error code]]. See Section 2.2 and Section 5 for more details on how 310 this measure ensures there's no confusion on to what resource the 311 access token granted scopes apply. 313 If the request does not include a resource parameter, the 314 authorization server MUST use in the aud claim a default resource 315 indicator. If a scope parameter is present in the request, the 316 authorization server SHOULD use it to infer the value of the default 317 resource indicator to be used in the aud claim. The mechanism 318 through which scopes are associated to default resource indicator 319 values is outside the scope of this specification. If the values in 320 the scope parameter refer to different default resource indicator 321 values, the authorization server SHOULD reject the request with 322 [[TODO: select appropriate error code]]. 324 4. Validating JWT Access Tokens 326 For the purpose of facilitating validation data retrieval, it is 327 RECOMMENDED that authorization servers sign JWT access tokens with an 328 asymmetric algorithm. 330 Authorization servers SHOULD implement OAuth 2.0 Authorization Server 331 Metadata [RFC8414] to advertise to resource servers its signing keys 332 via jwks_uri and what iss claim value to expect via the issuer 333 metadata value. Alternatively, authorization servers implementing 334 OpenID connect MAY use the Openid connect discovery document for the 335 same purpose. If an authorization server supports both AS metadata 336 and Openid discovery, the values provided MUST be consistent across 337 the two publication methods. 339 An authorization server MAY elect to use different keys to sign 340 id_tokens and JWT access tokens. 342 When invoked as described in OAuth2 bearer token usage, resource 343 servers receiving a JWT access token MUST validate it in the 344 following manner. 346 1. The resource server MUST verify that the typ header value is 347 at+jwt and reject tokens carrying any other value. 349 2. If the JWT access token is encrypted, decrypt it using the keys 350 and algorithms that the resource server specified during 351 registration. If encryption was negotiated with the 352 authorization server at registration time and the incoming JWT 353 access token is not encrypted, the resource server SHOULD reject 354 it. 356 3. The Issuer Identifier for the authorization server (which is 357 typically obtained during discovery) MUST exactly match the value 358 of the iss claim. 360 4. The resource server MUST validate that the aud claim contains the 361 resource indicator value corresponding to the identifier the 362 resource server expects for itself. The aud claim MAY contain an 363 array with more than one element. The JWT access token MUST be 364 rejected if aud does not list the resource indicator of the 365 current resource server as a valid audience, or if it contains 366 additional audiences that are not known aliases of the resource 367 indicator of the current resource server. 369 5. The resource server MUST validate the signature of all incoming 370 JWT access token according to [RFC7515] using the algorithm 371 specified in the JWT alg Header Parameter. The resource server 372 MUST use the keys provided by the authorization server. 374 6. The current time MUST be before the time represented by the exp 375 Claim. 377 7. If the auth_time claim is present, the resource server SHOULD 378 check the auth_time value and request re-authentication if it 379 determines too much time has elapsed since the last resource 380 owner authentication. 382 [[Note: I would like to express the requirement that the resource 383 server should not ignore authorization information when present in 384 the JWT access token. I don't know if this belongs here or 385 elsewhere. Here's some possible language: If the JWT access token 386 includes authorization claims as described in the authorization 387 claims section, the resource server SHOULD use them in combination 388 with any other contextual information available to determine whether 389 the current call should be authorized or rejected. Details about how 390 a resource server performs those checks is beyond the scope of this 391 profile specification.]] 393 5. Security Considerations 395 The JWT access token data layout described here is very similar to 396 the one of the id_token as defined by [OpenID.Core]. Without the 397 explicit typing required in this profile, in line with the 398 recommendations in [JWT.BestPractices] there would be the risk of 399 attackers using JWT access tokens in lieu of id_tokens. 401 This profile explicitly forbids the use of multi value aud claim when 402 the individual values refer to different resources, as that would 403 introduce confusion about what scopes apply to which resource- 404 possibly opening up avenues for elevation of delegated privileges 405 attacks. Alternative techniques to prevent scope confusion include 406 "scope stuffing", imposing to every individual scope string to 407 include a reference to the resource they are meant to be applied to, 408 but its application is problematic (scope opacity violations, size 409 inflation, more error conditions become possible when the combination 410 of requested scopes and resource indicators is invalid) and the 411 observed frequency of the scenario doesn't warrant complicating the 412 more common cases. 414 [[todo: expand on Audience, issuer and expiration validation checks 415 serve the usual purposes. What else?]] 417 6. Privacy Considerations 419 As JWT access tokens carry information by value, it now becomes 420 possible for requestors and receivers to directly peek inside the 421 token claims collection. 423 In scenarios in which JWT access tokens are accessible to the end 424 user, it should be evaluated whether the information can be accessed 425 without privacy violations (for example, if an end user would simply 426 access his or her own personal information) or if the token should be 427 encrypted. 429 In every scenario, the content of the JWT access token will 430 eventually be accessible to the resource server. It's important to 431 evaluate whether the resource server gained the proper entitlement to 432 have access to any content received in form of claims, for example 433 through user consent in some form, policies and agreements with the 434 organization running the authorization servers, and so on. 436 7. IANA Considerations 438 [[TODO: MIME type registration for at+jwt ]] 440 8. References 442 8.1. Normative References 444 [IANA.OAuth.Parameters] 445 IANA, "OAuth Parameters", 446 . 448 [JWT.BestPractices] 449 Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best 450 Current Practices", November 2018. 452 [OpenID.Core] 453 Sakimura, N., Bradley, J., Jones, M., Medeiros, B., and C. 454 Mortimore, "OpenID Connect Core 1.0", November 2014. 456 [ResourceIndicators] 457 Campbell, B., Bradley, J., and H. Tschofenig, "OAuth 2.0 458 Token Exchange", November 2016. 460 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 461 Requirement Levels", BCP 14, RFC 2119, 462 DOI 10.17487/RFC2119, March 1997, 463 . 465 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 466 Resource Identifier (URI): Generic Syntax", STD 66, 467 RFC 3986, DOI 10.17487/RFC3986, January 2005, 468 . 470 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 471 RFC 6749, DOI 10.17487/RFC6749, October 2012, 472 . 474 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 475 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 476 2015, . 478 [RFC7643] Hunt, P., Ed., Grizzle, K., Wahlstroem, E., and C. 479 Mortimore, "System for Cross-domain Identity Management: 480 Core Schema", RFC 7643, DOI 10.17487/RFC7643, September 481 2015, . 483 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 484 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 485 May 2017, . 487 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 488 Authorization Server Metadata", RFC 8414, 489 DOI 10.17487/RFC8414, June 2018, 490 . 492 [TokenExchange] 493 Nadalin, A., Bradley, J., Jones, M., Campbell, B., and C. 494 Mortimore, "OAuth 2.0 Token Exchange", October 2018. 496 8.2. Informative References 498 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 499 Framework: Bearer Token Usage", RFC 6750, 500 DOI 10.17487/RFC6750, October 2012, 501 . 503 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 504 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 505 . 507 [RFC7644] Hunt, P., Ed., Grizzle, K., Ansari, M., Wahlstroem, E., 508 and C. Mortimore, "System for Cross-domain Identity 509 Management: Protocol", RFC 7644, DOI 10.17487/RFC7644, 510 September 2015, . 512 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 513 RFC 7662, DOI 10.17487/RFC7662, October 2015, 514 . 516 Appendix A. Acknowledgements 518 The initial set of requirements informing this specification was 519 extracted by numerous examples of access tokens issued in JWT format 520 by production systems. Thanks to Dominick Bauer (IdentityServer), 521 Brian Campbell (PingIdentity), Daniel Dobalian (Microsoft), Karl 522 Guinness (Okta) for providing sample tokens issued by their products 523 and services. Brian Campbell and Filip Skokan provided early 524 feedback that shaped the direction of the specification. This 525 profile was discussed at lenght during the OAuth Security Workshop 526 2019, with several individuals contributing ideas and feedback. The 527 author would like to acknowledge the contributions of: 529 John Bradley, Brian Campbell Vladimir Dzhuvinov, Torsten Lodderstedt, 530 Nat Sakimura, Hannes Tschofenig and everyone who actively 531 participated in the unconference discussions. 533 Appendix B. Document History 535 [[ to be removed by the RFC Editor before publication as an RFC ]] 537 draft-ietf-oauth-access-token-jwt-00 539 o Initial draft to define a JWTt profile for OAuth 2.0 access 540 tokens. 542 Author's Address 544 Vittorio Bertocci 545 Auth0 547 Email: vittorio@auth0.com