idnits 2.17.1 draft-jones-json-web-token-10.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 12, 2012) is 4361 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) == Outdated reference: A later version (-06) exists of draft-ietf-oauth-urn-sub-ns-02 ** Downref: Normative reference to an Informational draft: draft-ietf-oauth-urn-sub-ns (ref. 'I-D.ietf-oauth-urn-sub-ns') -- Possible downref: Non-RFC (?) normative reference: ref. 'JWA' -- Possible downref: Non-RFC (?) normative reference: ref. 'JWE' -- Possible downref: Non-RFC (?) normative reference: ref. 'JWS' ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) -- Possible downref: Non-RFC (?) normative reference: ref. 'USA15' Summary: 3 errors (**), 0 flaws (~~), 2 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track D. Balfanz 5 Expires: November 13, 2012 Google 6 J. Bradley 7 Ping Identity 8 Y. Goland 9 Microsoft 10 J. Panzer 11 Google 12 N. Sakimura 13 NRI 14 P. Tarjan 15 Facebook 16 May 12, 2012 18 JSON Web Token (JWT) 19 draft-jones-json-web-token-10 21 Abstract 23 JSON Web Token (JWT) is a means of representing claims to be 24 transferred between two parties. The claims in a JWT are encoded as 25 a JSON object that is digitally signed or MACed using JSON Web 26 Signature (JWS) and/or encrypted using JSON Web Encryption (JWE). 28 The suggested pronunciation of JWT is the same as the English word 29 "jot". 31 Requirements Language 33 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 34 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 35 document are to be interpreted as described in RFC 2119 [RFC2119]. 37 Status of this Memo 39 This Internet-Draft is submitted in full conformance with the 40 provisions of BCP 78 and BCP 79. 42 Internet-Drafts are working documents of the Internet Engineering 43 Task Force (IETF). Note that other groups may also distribute 44 working documents as Internet-Drafts. The list of current Internet- 45 Drafts is at http://datatracker.ietf.org/drafts/current/. 47 Internet-Drafts are draft documents valid for a maximum of six months 48 and may be updated, replaced, or obsoleted by other documents at any 49 time. It is inappropriate to use Internet-Drafts as reference 50 material or to cite them other than as "work in progress." 52 This Internet-Draft will expire on November 13, 2012. 54 Copyright Notice 56 Copyright (c) 2012 IETF Trust and the persons identified as the 57 document authors. All rights reserved. 59 This document is subject to BCP 78 and the IETF Trust's Legal 60 Provisions Relating to IETF Documents 61 (http://trustee.ietf.org/license-info) in effect on the date of 62 publication of this document. Please review these documents 63 carefully, as they describe your rights and restrictions with respect 64 to this document. Code Components extracted from this document must 65 include Simplified BSD License text as described in Section 4.e of 66 the Trust Legal Provisions and are provided without warranty as 67 described in the Simplified BSD License. 69 Table of Contents 71 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 72 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 73 3. JSON Web Token (JWT) Overview . . . . . . . . . . . . . . . . 5 74 3.1. Example JWT . . . . . . . . . . . . . . . . . . . . . . . 6 75 4. JWT Claims . . . . . . . . . . . . . . . . . . . . . . . . . . 6 76 4.1. Reserved Claim Names . . . . . . . . . . . . . . . . . . . 7 77 4.1.1. "exp" (Expiration Time) Claim . . . . . . . . . . . . 7 78 4.1.2. "nbf" (Not Before) Claim . . . . . . . . . . . . . . . 7 79 4.1.3. "iat" (Issued At) Claim . . . . . . . . . . . . . . . 7 80 4.1.4. "iss" (Issuer) Claim . . . . . . . . . . . . . . . . . 8 81 4.1.5. "aud" (Audience) Claim . . . . . . . . . . . . . . . . 8 82 4.1.6. "prn" (Principal) Claim . . . . . . . . . . . . . . . 8 83 4.1.7. "jti" (JWT ID) Claim . . . . . . . . . . . . . . . . . 8 84 4.1.8. "typ" (Type) Claim . . . . . . . . . . . . . . . . . . 8 85 4.2. Public Claim Names . . . . . . . . . . . . . . . . . . . . 8 86 4.3. Private Claim Names . . . . . . . . . . . . . . . . . . . 9 87 5. JWT Header . . . . . . . . . . . . . . . . . . . . . . . . . . 9 88 5.1. "typ" (Type) Header Parameter . . . . . . . . . . . . . . 10 89 6. Plaintext JWTs . . . . . . . . . . . . . . . . . . . . . . . . 10 90 6.1. Example Plaintext JWT . . . . . . . . . . . . . . . . . . 10 91 7. Rules for Creating and Validating a JWT . . . . . . . . . . . 11 92 8. Cryptographic Algorithms . . . . . . . . . . . . . . . . . . . 13 93 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 94 9.1. JSON Web Token Claims Registry . . . . . . . . . . . . . . 14 95 9.2. Sub-Namespace Registration of 96 urn:ietf:params:oauth:token-type:jwt . . . . . . . . . . . 14 97 9.3. Registration of application/jwt MIME Media Type . . . . . 14 98 9.4. Registration of "JWT" Type Value . . . . . . . . . . . . . 15 99 10. Security Considerations . . . . . . . . . . . . . . . . . . . 16 100 11. Open Issues and Things To Be Done (TBD) . . . . . . . . . . . 16 101 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16 102 12.1. Normative References . . . . . . . . . . . . . . . . . . . 16 103 12.2. Informative References . . . . . . . . . . . . . . . . . . 17 104 Appendix A. Relationship of JWTs to SAML Tokens . . . . . . . . . 18 105 Appendix B. Relationship of JWTs to Simple Web Tokens (SWTs) . . 18 106 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 18 107 Appendix D. Document History . . . . . . . . . . . . . . . . . . 19 108 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 21 110 1. Introduction 112 JSON Web Token (JWT) is a compact token format intended for space 113 constrained environments such as HTTP Authorization headers and URI 114 query parameters. JWTs encode claims to be transmitted as a JSON 115 object (as defined in RFC 4627 [RFC4627]) that is base64url encoded 116 and digitally signed or MACed and/or encrypted. Signing and MACing 117 is performed using JSON Web Signature (JWS) [JWS]. Encryption is 118 performed using JSON Web Encryption (JWE) [JWE]. 120 The suggested pronunciation of JWT is the same as the English word 121 "jot". 123 2. Terminology 125 JSON Web Token (JWT) A string consisting of multiple parts, the 126 first being the Encoded JWT Header, plus additional parts 127 depending upon the contents of the header, with the parts being 128 separated by period ('.') characters, and each part containing 129 base64url encoded content. 131 JWT Header A string representing a JSON object that describes the 132 cryptographic operations applied to the JWT. When the JWT is 133 digitally signed or MACed, the JWT Header is a JWS Header. When 134 the JWT is encrypted, the JWT Header is a JWE Header. 136 Header Parameter Names The names of the members within the JWT 137 Header. 139 Header Parameter Values The values of the members within the JWT 140 Header. 142 JWT Claims Set A string representing a JSON object that contains the 143 claims conveyed by the JWT. When the JWT is digitally signed or 144 MACed, the bytes of the UTF-8 representation of the JWT Claims Set 145 are base64url encoded to create the Encoded JWS Payload. When the 146 JWT is encrypted, the bytes of the UTF-8 representation of the JWT 147 Claims Set are used as the JWE Plaintext. 149 Claim Names The names of the members of the JSON object represented 150 by the JWT Claims Set. 152 Claim Values The values of the members of the JSON object 153 represented by the JWT Claims Set. 155 Encoded JWT Header Base64url encoding of the bytes of the UTF-8 RFC 156 3629 [RFC3629] representation of the JWT Header. 158 Base64url Encoding For the purposes of this specification, this term 159 always refers to the URL- and filename-safe Base64 encoding 160 described in RFC 4648 [RFC4648], Section 5, with the (non URL- 161 safe) '=' padding characters omitted, as permitted by Section 3.2. 162 (See Appendix C of [JWS] for notes on implementing base64url 163 encoding without padding.) 165 StringOrURI A JSON string value, with the additional requirement 166 that while arbitrary string values MAY be used, any value 167 containing a ":" character MUST be a URI as defined in RFC 3986 168 [RFC3986]. 170 IntDate A JSON numeric value representing the number of seconds from 171 1970-01-01T0:0:0Z UTC until the specified UTC date/time. See RFC 172 3339 [RFC3339] for details regarding date/times in general and UTC 173 in particular. 175 3. JSON Web Token (JWT) Overview 177 JWTs represent a set of claims as a JSON object that is base64url 178 encoded and digitally signed or MACed and/or encrypted. The JWT 179 Claims Set represents this JSON object. As per RFC 4627 [RFC4627] 180 Section 2.2, the JSON object consists of zero or more name/value 181 pairs (or members), where the names are strings and the values are 182 arbitrary JSON values. These members are the claims represented by 183 the JWT. 185 The member names within the JWT Claims Set are referred to as Claim 186 Names. The corresponding values are referred to as Claim Values. 188 The bytes of the UTF-8 representation of the JWT Claims Set are 189 digitally signed or MACed in the manner described in JSON Web 190 Signature (JWS) [JWS] and/or encrypted in the manner described in 191 JSON Web Encryption (JWE) [JWE]. 193 The contents of the JWT Header describe the cryptographic operations 194 applied to the JWT Claims Set. If the JWT Header is a JWS Header, the 195 claims are digitally signed or MACed. If the JWT Header is a JWE 196 Header, the claims are encrypted. 198 A JWT is represented as a JWS or JWE. The number of parts is 199 dependent upon the representation of the resulting JWS or JWE. 201 3.1. Example JWT 203 The following example JWT Header declares that the encoded object is 204 a JSON Web Token (JWT) and the JWT is MACed using the HMAC SHA-256 205 algorithm: 206 {"typ":"JWT", 207 "alg":"HS256"} 209 Base64url encoding the bytes of the UTF-8 representation of the JWT 210 Header yields this Encoded JWS Header value, which is used as the 211 Encoded JWT Header: 212 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 214 The following is an example of a JWT Claims Set: 215 {"iss":"joe", 216 "exp":1300819380, 217 "http://example.com/is_root":true} 219 Base64url encoding the bytes of the UTF-8 representation of the JSON 220 Claims Set yields this Encoded JWS Payload (with line breaks for 221 display purposes only): 222 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly 223 9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ 225 Signing the Encoded JWS Header and Encoded JWS Payload with the HMAC 226 SHA-256 algorithm and base64url encoding the signature in the manner 227 specified in [JWS], yields this Encoded JWS Signature: 228 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 230 Concatenating these parts in this order with period characters 231 between the parts yields this complete JWT (with line breaks for 232 display purposes only): 233 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 234 . 235 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 236 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 237 . 238 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 240 This computation is illustrated in more detail in [JWS], Appendix 241 A.1. 243 4. JWT Claims 245 The JWT Claims Set represents a JSON object whose members are the 246 claims conveyed by the JWT. The Claim Names within this object MUST 247 be unique; JWTs with duplicate Claim Names MUST be rejected. Note 248 however, that the set of claims that a JWT must contain to be 249 considered valid is context-dependent and is outside the scope of 250 this specification. When used in a security-related context, 251 implementations MUST understand and support all of the claims 252 present; otherwise, the JWT MUST be rejected for processing. 254 There are three classes of JWT Claim Names: Reserved Claim Names, 255 Public Claim Names, and Private Claim Names. 257 4.1. Reserved Claim Names 259 The following claim names are reserved. None of the claims defined 260 below are intended to be mandatory, but rather, provide a starting 261 point for a set of useful, interoperable claims. All the names are 262 short because a core goal of JWTs is for the tokens to be compact. 263 Additional reserved claim names MAY be defined via the IANA JSON Web 264 Token Claims registry Section 9.1. 266 4.1.1. "exp" (Expiration Time) Claim 268 The "exp" (expiration time) claim identifies the expiration time on 269 or after which the token MUST NOT be accepted for processing. The 270 processing of the "exp" claim requires that the current date/time 271 MUST be before the expiration date/time listed in the "exp" claim. 272 Implementers MAY provide for some small leeway, usually no more than 273 a few minutes, to account for clock skew. Its value MUST be a number 274 containing an IntDate value. This claim is OPTIONAL. 276 4.1.2. "nbf" (Not Before) Claim 278 The "nbf" (not before) claim identifies the time before which the 279 token MUST NOT be accepted for processing. The processing of the 280 "nbf" claim requires that the current date/time MUST be after or 281 equal to the not-before date/time listed in the "nbf" claim. 282 Implementers MAY provide for some small leeway, usually no more than 283 a few minutes, to account for clock skew. Its value MUST be a number 284 containing an IntDate value. This claim is OPTIONAL. 286 4.1.3. "iat" (Issued At) Claim 288 The "iat" (issued at) claim identifies the time at which the JWT was 289 issued. This claim can be used to determine the age of the token. 290 Its value MUST be a number containing an IntDate value. This claim 291 is OPTIONAL. 293 4.1.4. "iss" (Issuer) Claim 295 The "iss" (issuer) claim identifies the principal that issued the 296 JWT. The processing of this claim is generally application specific. 297 The "iss" value is case sensitive. Its value MUST be a string 298 containing a StringOrURI value. This claim is OPTIONAL. 300 4.1.5. "aud" (Audience) Claim 302 The "aud" (audience) claim identifies the audience that the JWT is 303 intended for. The principal intended to process the JWT MUST be 304 identified with the value of the audience claim. If the principal 305 processing the claim does not identify itself with the identifier in 306 the "aud" claim value then the JWT MUST be rejected. The 307 interpretation of the audience value is generally application 308 specific. The "aud" value is case sensitive. Its value MUST be a 309 string containing a StringOrURI value. This claim is OPTIONAL. 311 4.1.6. "prn" (Principal) Claim 313 The "prn" (principal) claim identifies the subject of the JWT. The 314 processing of this claim is generally application specific. The 315 "prn" value is case sensitive. Its value MUST be a string containing 316 a StringOrURI value. This claim is OPTIONAL. 318 4.1.7. "jti" (JWT ID) Claim 320 The "jti" (JWT ID) claim provides a unique identifier for the JWT. 321 The identifier value MUST be assigned in a manner that ensures that 322 there is a negligible probability that the same value will be 323 accidentally assigned to a different data object. The "jti" claim 324 can be used to prevent the JWT from being replayed. The "jti" value 325 is case sensitive. Its value MUST be a string. This claim is 326 OPTIONAL. 328 4.1.8. "typ" (Type) Claim 330 The "typ" (type) claim is used to declare a type for the contents of 331 this JWT Claims Set. The "typ" value is case sensitive. Its value 332 MUST be a string. This claim is OPTIONAL. 334 The values used for the "typ" claim SHOULD come from the same value 335 space as the "typ" header parameter, with the same rules applying. 337 4.2. Public Claim Names 339 Claim names can be defined at will by those using JWTs. However, in 340 order to prevent collisions, any new claim name SHOULD either be 341 defined in the IANA JSON Web Token Claims registry Section 9.1 or be 342 a URI that contains a collision resistant namespace. Examples of 343 collision resistant namespaces include: 345 o Domain Names, 347 o Object Identifiers (OIDs) as defined in the ITU-T X.660 and X.670 348 Recommendation series, or 350 o Universally Unique IDentifier (UUID) as defined in RFC 4122 351 [RFC4122]. 353 In each case, the definer of the name or value needs to take 354 reasonable precautions to make sure they are in control of the part 355 of the namespace they use to define the claim name. 357 4.3. Private Claim Names 359 A producer and consumer of a JWT may agree to any claim name that is 360 not a Reserved Name Section 4.1 or a Public Name Section 4.2. Unlike 361 Public Names, these private names are subject to collision and should 362 be used with caution. 364 5. JWT Header 366 The members of the JSON object represented by the JWT Header describe 367 the cryptographic operations applied to the JWT and optionally, 368 additional properties of the JWT. The member names within the JWT 369 Header are referred to as Header Parameter Names. These names MUST 370 be unique; JWTs with duplicate Header Parameter Names MUST be 371 rejected. The corresponding values are referred to as Header 372 Parameter Values. 374 Implementations MUST understand the entire contents of the header; 375 otherwise, the JWT MUST be rejected for processing. 377 There are two ways of distinguishing whether the JWT is a JWS or JWE. 378 The first is by examining the "alg" (algorithm) header value. If the 379 value represents a signature algorithm, the JWT is a JWS; if it 380 represents an encryption algorithm, the JWT is a JWE. A second 381 method is determining whether an "enc" (encryption method) member 382 exists. If the "enc" member exists, the JWT is a JWE; otherwise, the 383 JWT is a JWS. Both methods will yield the same result. 385 JWS Header Parameters are defined by [JWS]. JWE Header Parameters 386 are defined by [JWE]. This specification further specifies the use 387 of the following header parameters in both the cases where the JWT is 388 a JWS and where it is a JWE. 390 5.1. "typ" (Type) Header Parameter 392 The "typ" (type) header parameter is used to declare structural 393 information about the JWT. In the normal case where nested signing 394 or encryption operations are not employed, the use of this header 395 parameter is OPTIONAL, and if present, it is RECOMMENDED that its 396 value be either "JWT" or "urn:ietf:params:oauth:token-type:jwt". In 397 the case that nested signing or encryption steps are employed, the 398 use of this header parameter is REQUIRED; in this case, the value 399 MUST either be "JWS", to indicate that a nested digitally signed or 400 MACed JWT is carried in this JWT or "JWE", to indicate that a nested 401 encrypted JWT is carried in this JWT. 403 6. Plaintext JWTs 405 To support use cases where the JWT content is secured by a means 406 other than a signature and/or encryption contained within the token 407 (such as a signature on a data structure containing the token), JWTs 408 MAY also be created without a signature or encryption. A plaintext 409 JWT is a JWS using the "none" JWS "alg" header parameter value 410 defined in JSON Web Algorithms (JWA) [JWA]; it is a JWS with an empty 411 JWS Signature value. 413 6.1. Example Plaintext JWT 415 The following example JWT Header declares that the encoded object is 416 a Plaintext JWT: 417 {"alg":"none"} 419 Base64url encoding the bytes of the UTF-8 representation of the JWT 420 Header yields this Encoded JWT Header: 421 eyJhbGciOiJub25lIn0 423 The following is an example of a JWT Claims Set: 424 {"iss":"joe", 425 "exp":1300819380, 426 "http://example.com/is_root":true} 428 Base64url encoding the bytes of the UTF-8 representation of the JSON 429 Claims Set yields this Encoded JWS Payload (with line breaks for 430 display purposes only): 431 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 432 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 434 The Encoded JWS Signature is the empty string. 436 Concatenating these parts in this order with period characters 437 between the parts yields this complete JWT (with line breaks for 438 display purposes only): 439 eyJhbGciOiJub25lIn0 440 . 441 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 442 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 443 . 445 7. Rules for Creating and Validating a JWT 447 To create a JWT, one MUST perform these steps. The order of the 448 steps is not significant in cases where there are no dependencies 449 between the inputs and outputs of the steps. 451 1. Create a JWT Claims Set containing the desired claims. Note that 452 white space is explicitly allowed in the representation and no 453 canonicalization is performed before encoding. 455 2. Let the Message be the bytes of the UTF-8 representation of the 456 JWT Claims Set. 458 3. Create a JWT Header containing the desired set of header 459 parameters. The JWT MUST conform to either the [JWS] or [JWE] 460 specifications. Note that white space is explicitly allowed in 461 the representation and no canonicalization is performed before 462 encoding. 464 4. Base64url encode the bytes of the UTF-8 representation of the JWT 465 Header. Let this be the Encoded JWT Header. 467 5. Depending upon whether the JWT is a JWS or JWE, there are two 468 cases: 470 * If the JWT is a JWS, create a JWS using the JWT Header as the 471 JWS Header and the Message as the JWS Payload; all steps 472 specified in [JWS] for creating a JWS MUST be followed. 474 * Else, if the JWT is a JWE, create a JWE using the JWT Header 475 as the JWE Header and the Message as the JWE Plaintext; all 476 steps specified in [JWE] for creating a JWE MUST be followed. 478 6. If a nested signing or encryption operation will be performed, 479 let the Message be the JWS or JWE, and return to Step 3, using a 480 "typ" value of either "JWS" or "JWE" respectively in the new JWT 481 Header created in that step. 483 7. Otherwise, let the resulting JWT be the JWS or JWE. 485 When validating a JWT the following steps MUST be taken. The order 486 of the steps is not significant in cases where there are no 487 dependencies between the inputs and outputs of the steps. If any of 488 the listed steps fails then the token MUST be rejected for 489 processing. 491 1. The JWT MUST contain at least one period character. 493 2. Let the Encoded JWT Header be the portion of the JWT before the 494 first period character. 496 3. The Encoded JWT Header MUST be successfully base64url decoded 497 following the restriction given in this specification that no 498 padding characters have been used. 500 4. The resulting JWT Header MUST be completely valid JSON syntax 501 conforming to RFC 4627 [RFC4627]. 503 5. The resulting JWT Header MUST be validated to only include 504 parameters and values whose syntax and semantics are both 505 understood and supported. 507 6. Determine whether the JWT is a JWS or a JWE by examining the 508 "alg" (algorithm) header value and optionally, the "enc" 509 (encryption method) header value, if present. 511 7. Depending upon whether the JWT is a JWS or JWE, there are two 512 cases: 514 * If the JWT is a JWS, all steps specified in [JWS] for 515 validating a JWS MUST be followed. Let the Message be the 516 result of base64url decoding the JWS Payload. 518 * Else, if the JWT is a JWE, all steps specified in [JWE] for 519 validating a JWE MUST be followed. Let the Message be the 520 JWE Plaintext. 522 8. If the JWT Header contains a "typ" value of either "JWS" or 523 "JWE", then the Message contains a JWT that was the subject of 524 nested signing or encryption operations, respectively. In this 525 case, return to Step 1, using the Message as the JWT. 527 9. Otherwise, let the JWT Claims Set be the Message. 529 10. The JWT Claims Set MUST be completely valid JSON syntax 530 conforming to RFC 4627 [RFC4627]. 532 11. When used in a security-related context, the JWT Claims Set MUST 533 be validated to only include claims whose syntax and semantics 534 are both understood and supported. 536 Processing a JWT inevitably requires comparing known strings to 537 values in the token. For example, in checking what the algorithm is, 538 the Unicode string encoding "alg" will be checked against the member 539 names in the JWT Header to see if there is a matching header 540 parameter name. A similar process occurs when determining if the 541 value of the "alg" header parameter represents a supported algorithm. 543 Comparisons between JSON strings and other Unicode strings MUST be 544 performed as specified below: 546 1. Remove any JSON applied escaping to produce an array of Unicode 547 code points. 549 2. Unicode Normalization [USA15] MUST NOT be applied at any point to 550 either the JSON string or to the string it is to be compared 551 against. 553 3. Comparisons between the two strings MUST be performed as a 554 Unicode code point to code point equality comparison. 556 8. Cryptographic Algorithms 558 JWTs use JSON Web Signature (JWS) [JWS] and JSON Web Encryption (JWE) 559 [JWE] to sign and/or encrypt the contents of the JWT. 561 Of the JWS signing algorithms, only HMAC SHA-256 and "none" MUST be 562 implemented by conforming JWT implementations. It is RECOMMENDED 563 that implementations also support the RSA SHA-256 and ECDSA P-256 564 SHA-256 algorithms. Support for other algorithms and key sizes is 565 OPTIONAL. 567 If an implementation provides encryption capabilities, of the JWE 568 encryption algorithms, only RSA-PKCS1-1.5 with 2048 bit keys, AES- 569 128-KW, AES-256-KW, AES-128-CBC, and AES-256-CBC MUST be implemented 570 by conforming implementations. It is RECOMMENDED that 571 implementations also support ECDH-ES with 256 bit keys, AES-128-GCM, 572 and AES-256-GCM. Support for other algorithms and key sizes is 573 OPTIONAL. 575 9. IANA Considerations 576 9.1. JSON Web Token Claims Registry 578 This specification establishes the IANA JSON Web Token Claims 579 registry for reserved JWT claim names. Inclusion in the registry is 580 RFC Required in the RFC 5226 [RFC5226] sense. The registry records 581 the reserved claim name and a reference to the RFC that defines it. 582 This specification registers the claim names defined in Section 4.1. 584 9.2. Sub-Namespace Registration of urn:ietf:params:oauth:token-type:jwt 586 This specification registers the value "token-type:jwt" in the 587 registry urn:ietf:params:oauth established in An IETF URN Sub- 588 Namespace for OAuth [I-D.ietf-oauth-urn-sub-ns]. 590 o URN: urn:ietf:params:oauth:token-type:jwt 592 o Common Name: JSON Web Token (JWT) Token Type 594 o Change controller: IETF 596 o Description: [[this document]] 598 9.3. Registration of application/jwt MIME Media Type 600 This specification registers the "application/jwt" MIME Media Type 601 RFC 2045 [RFC2045]. 603 Type name: 604 application 606 Subtype name: 607 jwt 609 Required parameters: 610 n/a 612 Optional parameters: 613 n/a 615 Encoding considerations: 616 n/a 618 Security considerations: 619 See the Security Considerations section of this document 621 Interoperability considerations: 622 n/a 624 Published specification: 625 [[ this document ]] 627 Applications that use this media type: 628 OpenID Connect, Mozilla Browser ID, Salesforce, Google, numerous 629 others 631 Additional information: 632 Magic number(s): n/a 633 File extension(s): n/a 634 Macintosh file type code(s): n/a 636 Person & email address to contact for further information: 637 Michael B. Jones 638 mbj@microsoft.com 640 Intended usage: 641 COMMON 643 Restrictions on usage: 644 none 646 Author: 647 Michael B. Jones 648 mbj@microsoft.com 650 Change controller: 651 Michael B. Jones 652 mbj@microsoft.com 654 9.4. Registration of "JWT" Type Value 656 This specification registers the following "typ" header parameter 657 value in the JSON Web Signature and Encryption "typ" Values registry 658 established by the JSON Web Algorithms (JWA) [JWA] specification: 660 "typ" header parameter value: 661 "JWT" 663 Abbreviation for MIME type: 664 application/jwt 666 Change controller: 667 Michael B. Jones 668 mbj@microsoft.com 670 Description: 671 [[ this document ]] 673 10. Security Considerations 675 All the security considerations in the JWS specification also apply 676 to JWT, as do the JWE security considerations when encryption is 677 employed. In particular, the JWS JSON Security Considerations and 678 Unicode Comparison Security Considerations apply equally to the JWT 679 Claims Set in the same manner that they do to the JWS Header. 681 11. Open Issues and Things To Be Done (TBD) 683 The following items remain to be done in this draft: 685 o Provide an example of an encrypted JWT. 687 12. References 689 12.1. Normative References 691 [I-D.ietf-oauth-urn-sub-ns] 692 Tschofenig, H., "An IETF URN Sub-Namespace for OAuth", 693 draft-ietf-oauth-urn-sub-ns-02 (work in progress), 694 January 2012. 696 [JWA] Jones, M., "JSON Web Algorithms (JWA)", May 2012. 698 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 699 Encryption (JWE)", May 2012. 701 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 702 Signature (JWS)", May 2012. 704 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 705 Extensions (MIME) Part One: Format of Internet Message 706 Bodies", RFC 2045, November 1996. 708 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 709 Requirement Levels", BCP 14, RFC 2119, March 1997. 711 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 712 Internet: Timestamps", RFC 3339, July 2002. 714 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 715 10646", STD 63, RFC 3629, November 2003. 717 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 718 Resource Identifier (URI): Generic Syntax", STD 66, 719 RFC 3986, January 2005. 721 [RFC4627] Crockford, D., "The application/json Media Type for 722 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 724 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 725 Encodings", RFC 4648, October 2006. 727 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 728 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 729 May 2008. 731 [USA15] Davis, M., Whistler, K., and M. Duerst, "Unicode 732 Normalization Forms", Unicode Standard Annex 15, 09 2009. 734 12.2. Informative References 736 [CanvasApp] 737 Facebook, "Canvas Applications", 2010. 739 [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", 740 September 2010. 742 [MagicSignatures] 743 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 744 Signatures", January 2011. 746 [OASIS.saml-core-2.0-os] 747 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 748 "Assertions and Protocol for the OASIS Security Assertion 749 Markup Language (SAML) V2.0", OASIS Standard saml-core- 750 2.0-os, March 2005. 752 [RFC3275] Eastlake, D., Reagle, J., and D. Solo, "(Extensible Markup 753 Language) XML-Signature Syntax and Processing", RFC 3275, 754 March 2002. 756 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 757 Unique IDentifier (UUID) URN Namespace", RFC 4122, 758 July 2005. 760 [SWT] Hardt, D. and Y. Goland, "Simple Web Token (SWT)", 761 Version 0.9.5.1, November 2009. 763 [W3C.CR-xml11-20021015] 764 Cowan, J., "Extensible Markup Language (XML) 1.1", W3C 765 CR CR-xml11-20021015, October 2002. 767 Appendix A. Relationship of JWTs to SAML Tokens 769 SAML 2.0 [OASIS.saml-core-2.0-os] provides a standard for creating 770 tokens with much greater expressivity and more security options than 771 supported by JWTs. However, the cost of this flexibility and 772 expressiveness is both size and complexity. In addition, SAML's use 773 of XML [W3C.CR-xml11-20021015] and XML DSIG [RFC3275] only 774 contributes to the size of SAML tokens. 776 JWTs are intended to provide a simple token format that is small 777 enough to fit into HTTP headers and query arguments in URIs. It does 778 this by supporting a much simpler token model than SAML and using the 779 JSON [RFC4627] object encoding syntax. It also supports securing 780 tokens using Message Authentication Codes (MACs) and digital 781 signatures using a smaller (and less flexible) format than XML DSIG. 783 Therefore, while JWTs can do some of the things SAML tokens do, JWTs 784 are not intended as a full replacement for SAML tokens, but rather as 785 a compromise token format to be used when space is at a premium. 787 Appendix B. Relationship of JWTs to Simple Web Tokens (SWTs) 789 Both JWTs and Simple Web Tokens SWT [SWT], at their core, enable sets 790 of claims to be communicated between applications. For SWTs, both 791 the claim names and claim values are strings. For JWTs, while claim 792 names are strings, claim values can be any JSON type. Both token 793 types offer cryptographic protection of their content: SWTs with HMAC 794 SHA-256 and JWTs with a choice of algorithms, including HMAC SHA-256, 795 RSA SHA-256, and ECDSA P-256 SHA-256. 797 Appendix C. Acknowledgements 799 The authors acknowledge that the design of JWTs was intentionally 800 influenced by the design and simplicity of Simple Web Tokens [SWT] 801 and ideas for JSON tokens that Dick Hardt discussed within the OpenID 802 community. 804 Solutions for signing JSON content were previously explored by Magic 805 Signatures [MagicSignatures], JSON Simple Sign [JSS], and Canvas 806 Applications [CanvasApp], all of which influenced this draft. 808 Appendix D. Document History 810 -10 812 o Clarified the relationship between "typ" header parameter values, 813 "typ" claim values, and MIME types. 815 o Clarified that JWTs with duplicate Header Parameter Names or 816 Duplicate Claim names MUST be rejected. 818 o Required implementation of AES-128-KW and AES-256-KW when the 819 implementation provides encryption capabilities. 821 o Registered "JWT" typ header parameter value. 823 o Generalized language to refer to Message Authentication Codes 824 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 825 unless in a context specific to HMAC algorithms. 827 o Reformatted to give each claim definition and header parameter its 828 own section heading. 830 -09 832 o Changed "http://openid.net/specs/jwt/1.0" to 833 "urn:ietf:params:oauth:token-type:jwt" in preparation for OAuth WG 834 draft. 836 -08 838 o Removed language that required that a JWT must have three parts. 839 Now the number of parts is explicitly dependent upon the 840 representation of the underlying JWS or JWE. 842 o Moved the "alg":"none" definition to the JWS spec. 844 o Registered the "application/jwt" MIME Media Type. 846 o Clarified that the order of the creation and validation steps is 847 not significant in cases where there are no dependencies between 848 the inputs and outputs of the steps. 850 o Corrected the Magic Signatures and Simple Web Token (SWT) 851 references. 853 -07 855 o Defined the "prn" (principal) claim to identify the subject of the 856 JWT. 858 o Defined the "jti" (JWT ID) claim to enable replay protection. 860 o Use the term "JWT Claims Set" rather than "JWT Claims Object" 861 since this is actually a string representing a JSON object and not 862 the JSON object itself. 864 o Moved "MUST" requirements from the Overview to later in the spec. 866 o Respect line length restrictions in examples. 868 o Applied other editorial improvements. 870 -06 872 o Reference and use content from [JWS] and [JWE], rather than 873 repeating it here. 875 o Simplified terminology to better match JWE, where the terms "JWT 876 Header" and "Encoded JWT Header" are now used, for instance, 877 rather than the previous terms "Decoded JWT Header Segment" and 878 "JWT Header Segment". Also changed to "Plaintext JWT" from 879 "Unsigned JWT". 881 o Describe how to perform nested encryption and signing operations. 883 o Changed "integer" to "number", since that is the correct JSON 884 type. 886 o Changed StringAndURI to StringOrURI. 888 -05 890 o Added the "nbf" (not before) claim and clarified the meaning of 891 the "iat" (issued at) claim. 893 -04 895 o Correct typo found by John Bradley: "the JWT Claim Segment is the 896 empty string" -> "the JWT Crypto Segment is the empty string". 898 -03 899 o Added "http://openid.net/specs/jwt/1.0" as a token type identifier 900 URI for JWTs. 902 o Added "iat" (issued at) claim. 904 o Changed RSA SHA-256 from MUST be supported to RECOMMENDED that it 905 be supported. Rationale: Several people have objected to the 906 requirement for implementing RSA SHA-256, some because they will 907 only be using HMACs and symmetric keys, and others because they 908 only want to use ECDSA when using asymmetric keys, either for 909 security or key length reasons, or both. 911 o Defined "alg" value "none" to represent unsigned JWTs. 913 -02 915 o Split signature specification out into separate 916 draft-jones-json-web-signature-00. This split introduced no 917 semantic changes. 919 o The JWT Compact Serialization is now the only token serialization 920 format specified in this draft. The JWT JSON Serialization can 921 continue to be defined in a companion specification. 923 -01 925 o Draft incorporating consensus decisions reached at IIW. 927 -00 929 o Public draft published before November 2010 IIW based upon the 930 JSON token convergence proposal incorporating input from several 931 implementers of related specifications. 933 Authors' Addresses 935 Michael B. Jones 936 Microsoft 938 Email: mbj@microsoft.com 939 URI: http://self-issued.info/ 940 Dirk Balfanz 941 Google 943 Email: balfanz@google.com 945 John Bradley 946 Ping Identity 948 Email: ve7jtb@ve7jtb.com 950 Yaron Y. Goland 951 Microsoft 953 Email: yarong@microsoft.com 955 John Panzer 956 Google 958 Email: jpanzer@google.com 960 Nat Sakimura 961 Nomura Research Institute 963 Email: n-sakimura@nri.co.jp 965 Paul Tarjan 966 Facebook 968 Email: pt@fb.com