idnits 2.17.1 draft-jones-json-web-token-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 16 instances of too long lines in the document, the longest one being 275 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (January 04, 2011) is 4862 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) -- Looks like a reference, but probably isn't: '123' on line 1506 -- Looks like a reference, but probably isn't: '34' on line 1506 -- Looks like a reference, but probably isn't: '97' on line 1506 -- Looks like a reference, but probably isn't: '108' on line 1506 -- Looks like a reference, but probably isn't: '103' on line 1506 -- Looks like a reference, but probably isn't: '58' on line 1506 -- Looks like a reference, but probably isn't: '82' on line 1333 -- Looks like a reference, but probably isn't: '83' on line 1506 -- Looks like a reference, but probably isn't: '50' on line 1506 -- Looks like a reference, but probably isn't: '53' on line 1506 -- Looks like a reference, but probably isn't: '54' on line 1506 -- Looks like a reference, but probably isn't: '125' on line 1506 -- Looks like a reference, but probably isn't: '1' on line 1390 -- Looks like a reference, but probably isn't: '0' on line 1693 -- Looks like a reference, but probably isn't: '69' on line 1506 ** Obsolete normative reference: RFC 1738 (Obsoleted by RFC 4248, RFC 4266) ** Downref: Normative reference to an Informational RFC: RFC 2104 ** Obsolete normative reference: RFC 3447 (Obsoleted by RFC 8017) ** 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: 6 errors (**), 0 flaws (~~), 1 warning (==), 17 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: July 8, 2011 Google 6 J. Bradley 7 independent 8 Y. Goland 9 Microsoft 10 J. Panzer 11 Google 12 N. Sakimura 13 Nomura Research Institute 14 P. Tarjan 15 Facebook 16 January 04, 2011 18 JSON Web Token (JWT) - Claims and Signing 19 draft-jones-json-web-token-01 21 Abstract 23 JSON Web Token (JWT) is a means of representing signed content using 24 JSON data structures, including claims to be transferred between two 25 parties. The claims in a JWT are encoded as a JSON object that is 26 digitally signed and optionally encrypted. Encryption for JWTs is 27 described in a separate companion specification. 29 The suggested pronunciation of JWT is the same as the English word 30 "jot". 32 Requirements Language 34 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 35 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 36 document are to be interpreted as described in RFC 2119 [RFC2119]. 38 Status of this Memo 40 This Internet-Draft is submitted in full conformance with the 41 provisions of BCP 78 and BCP 79. 43 Internet-Drafts are working documents of the Internet Engineering 44 Task Force (IETF). Note that other groups may also distribute 45 working documents as Internet-Drafts. The list of current Internet- 46 Drafts is at http://datatracker.ietf.org/drafts/current/. 48 Internet-Drafts are draft documents valid for a maximum of six months 49 and may be updated, replaced, or obsoleted by other documents at any 50 time. It is inappropriate to use Internet-Drafts as reference 51 material or to cite them other than as "work in progress." 53 This Internet-Draft will expire on July 8, 2011. 55 Copyright Notice 57 Copyright (c) 2011 IETF Trust and the persons identified as the 58 document authors. All rights reserved. 60 This document is subject to BCP 78 and the IETF Trust's Legal 61 Provisions Relating to IETF Documents 62 (http://trustee.ietf.org/license-info) in effect on the date of 63 publication of this document. Please review these documents 64 carefully, as they describe your rights and restrictions with respect 65 to this document. Code Components extracted from this document must 66 include Simplified BSD License text as described in Section 4.e of 67 the Trust Legal Provisions and are provided without warranty as 68 described in the Simplified BSD License. 70 Table of Contents 72 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 73 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 74 3. JSON Web Token (JWT) Overview . . . . . . . . . . . . . . . . 7 75 3.1. Example JWT . . . . . . . . . . . . . . . . . . . . . . . 7 76 4. JWT Claims . . . . . . . . . . . . . . . . . . . . . . . . . . 8 77 4.1. Reserved Claim Names . . . . . . . . . . . . . . . . . . . 8 78 4.2. Public Claim Names . . . . . . . . . . . . . . . . . . . . 10 79 4.3. Private Claim Names . . . . . . . . . . . . . . . . . . . 11 80 5. JWT Header . . . . . . . . . . . . . . . . . . . . . . . . . . 11 81 5.1. Reserved Header Parameter Names . . . . . . . . . . . . . 11 82 5.2. Public Header Parameter Names . . . . . . . . . . . . . . 13 83 5.3. Private Header Parameter Names . . . . . . . . . . . . . . 13 84 6. Rules for Creating and Validating a JWT . . . . . . . . . . . 13 85 7. Base64url encoding as used by JWTs . . . . . . . . . . . . . . 17 86 8. Signing JWTs with Cryptographic Algorithms . . . . . . . . . . 17 87 8.1. Signing a JWT with HMAC SHA-256 . . . . . . . . . . . . . 18 88 8.2. Signing a JWT with RSA SHA-256 . . . . . . . . . . . . . . 19 89 8.3. Signing a JWT with ECDSA P-256 SHA-256 . . . . . . . . . . 20 90 8.4. Additional Algorithms . . . . . . . . . . . . . . . . . . 21 91 9. JWT Serialization Formats . . . . . . . . . . . . . . . . . . 21 92 9.1. JWT Compact Serialization . . . . . . . . . . . . . . . . 21 93 9.2. JWT JSON Serialization . . . . . . . . . . . . . . . . . . 22 94 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 95 11. Security Considerations . . . . . . . . . . . . . . . . . . . 23 96 11.1. Unicode Comparison Security Issues . . . . . . . . . . . . 23 97 12. Open Issues and Things To Be Done (TBD) . . . . . . . . . . . 24 98 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 26 99 13.1. Normative References . . . . . . . . . . . . . . . . . . . 26 100 13.2. Informative References . . . . . . . . . . . . . . . . . . 27 101 Appendix A. JWT Examples . . . . . . . . . . . . . . . . . . . . 27 102 A.1. JWT using HMAC SHA-256 . . . . . . . . . . . . . . . . . . 27 103 A.1.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 28 104 A.1.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 29 105 A.1.3. Validating . . . . . . . . . . . . . . . . . . . . . . 30 106 A.2. JWT using RSA SHA-256 . . . . . . . . . . . . . . . . . . 30 107 A.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 30 108 A.2.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 34 109 A.2.3. Validating . . . . . . . . . . . . . . . . . . . . . . 35 110 A.3. JWT using ECDSA P-256 SHA-256 . . . . . . . . . . . . . . 35 111 A.3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 35 112 A.3.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 37 113 A.3.3. Validating . . . . . . . . . . . . . . . . . . . . . . 37 114 A.4. JWT using JSON Serialization . . . . . . . . . . . . . . . 38 115 A.4.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 38 116 A.4.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 39 117 A.4.3. Validating . . . . . . . . . . . . . . . . . . . . . . 39 119 Appendix B. Notes on implementing base64url encoding without 120 padding . . . . . . . . . . . . . . . . . . . . . . . 39 121 Appendix C. Relationship of JWTs to SAML Tokens . . . . . . . . . 40 122 Appendix D. Relationship of JWTs to Simple Web Tokens (SWTs) . . 41 123 Appendix E. Acknowledgements . . . . . . . . . . . . . . . . . . 41 124 Appendix F. Document History . . . . . . . . . . . . . . . . . . 41 125 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 42 127 1. Introduction 129 JSON Web Token (JWT) is a compact token format intended for space 130 constrained environments such as HTTP Authorization headers and URI 131 query parameters. JWTs encode claims to be transmitted as a JSON 132 object (as defined in RFC 4627 [RFC4627]) that is base64url encoded 133 and digitally signed. The JWT signature mechanisms are independent 134 of the type of content being signed, allowing arbitrary content to be 135 signed. Encryption for JWTs is described in a separate companion 136 specification. 138 The suggested pronunciation of JWT is the same as the English word 139 "jot". 141 2. Terminology 143 JSON Web Token (JWT) A data structure containing three JWT Token 144 Segments: the JWT Header Segment, the JWT Payload Segment, and the 145 JWT Crypto Segment. The JWT Payload Segment typically represents 146 a set of claims convened by the JWT as a JSON object, but in the 147 general case, may represent arbitrary signed content. 149 JWT Compact Serialization A data structure representing a JWT as a 150 string consisting of three JWT Token Segments: the JWT Header 151 Segment, the JWT Payload Segment, and the JWT Crypto Segment, in 152 that order, with the segments being separated by period ('.') 153 characters. 155 JWT JSON Serialization A data structure representing a JWT as a JSON 156 object with members for each of three kinds of JWT Token Segments: 157 a "header" member whose value is a non-empty array of JWT Header 158 Segments, a "payload" member whose value is the JWT Payload 159 Segment, and a "signature" member whose value is a non-empty array 160 of JWT Crypto Segments, where the cardinality of both arrays is 161 the same. 163 JWT Token Segment One of the three parts that make up a JSON Web 164 Token (JWT). JWT Token Segments are always base64url encoded 165 values. 167 JWT Header Segment A JWT Token Segment containing a base64url 168 encoded JSON object that describes the signature applied to the 169 JWT Header Segment and the JWT Payload Segment. 171 JWT Payload Segment A JWT Token Segment containing base64url encoded 172 content. This may be a JWT Claims Object. 174 JWT Crypto Segment A JWT Token Segment containing base64url encoded 175 cryptographic signature material that secures the JWT Header 176 Segment's and the JWT Payload Segment's contents. 178 Decoded JWT Header Segment A JWT Header Segment that has been 179 base64url decoded back into a JSON object. 181 Decoded JWT Payload Segment A JWT Payload Segment that has been 182 base64url decoded. If the corresponding JWT Payload Segment is a 183 JWT Claims Object, this will be a Decoded JWT Claims Object. 185 Decoded JWT Crypto Segment A JWT Crypto Segment that has been 186 base64url decoded back into cryptographic material. 188 JWT Claims Object A base64url encoded JSON object that represents 189 the claims contained in the JWT. 191 Decoded JWT Claims Object A JSON object that represents the claims 192 contained in the JWT. 194 JWT Signing Input The concatenation of the JWT Header Segment, a 195 period ('.') character, and the JWT Payload Segment. 197 Digital Signature For the purposes of this specification, we use 198 this term to encompass both Hash-based Message Authentication 199 Codes (HMACs), which can provide authenticity but not non- 200 repudiation, and digital signatures using public key algorithms, 201 which can provide both. Readers should be aware of this 202 distinction, despite the decision to use a single term for both 203 concepts to improve readability of the specification. 205 Base64url Encoding For the purposes of this specification, this term 206 always refers to the he URL- and filename-safe Base64 encoding 207 described in RFC 4648 [RFC4648], Section 5, with the '=' padding 208 characters omitted, as permitted by Section 3.2; see Section 7 for 209 more details. 211 Header Parameter Names The names of the members within the JSON 212 object represented in a JWT Header Segment. 214 Header Parameter Values The values of the members within the JSON 215 object represented in a JWT Header Segment. 217 Claim Names The names of the members of the JSON object represented 218 in a JWT Claims Object. 220 Claim Values The values of the members of the JSON object 221 represented in a JWT Claims Object. 223 3. JSON Web Token (JWT) Overview 225 JWTs represent content that is base64url encoded and digitally 226 signed, and optionally encrypted, using JSON data structures; this 227 content is typically a set of claims represented as a JSON object. 229 When the JWT payload is a set of claims, the claims are represented 230 as name/value pairs that are members of a JSON object. The JSON 231 object is base64url encoded to produce the JWT Claims Object, which 232 is used as the JWT Payload Segment. An accompanying base64url 233 encoded JSON header - the JWT Header Segment - describes the 234 signature method used. 236 The names within the header object MUST be unique. The names within 237 the header object are referred to as Header Parameter Names. The 238 corresponding values are referred to as Header Parameter Values. 239 Likewise, if the payload represents a JWT Claims Object, the names 240 within the claims object MUST be unique. The names within the claims 241 object are referred to as Claim Names. The corresponding values are 242 referred to as Claim Values. 244 JWTs contain a signature that ensures the integrity of the content of 245 the JWT Header Segment and the JWT Payload Segment. This signature 246 value is carried in the JWT Crypto Segment. The JSON Header object 247 MUST contain an "alg" parameter, the value of which is a string that 248 unambiguously identifies the algorithm used to sign the JWT Header 249 Segment and the JWT Payload Segment to produce the JWT Crypto 250 Segment. 252 3.1. Example JWT 254 The following is an example of a JSON object that can be encoded to 255 produce a JWT Claims Object: 256 {"iss":"joe", 257 "exp":1300819380, 258 "http://example.com/is_root":true} 260 Base64url encoding the UTF-8 representation of the JSON object yields 261 this JWT Claims Object, which is used as the JWT Payload Segment: 262 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ 263 The following example JSON header object declares that the encoded 264 object is a JSON Web Token (JWT) and the JWT Header Segment and the 265 JWT Payload Segment are signed using the HMAC SHA-256 algorithm: 266 {"typ":"JWT", 267 "alg":"HS256"} 269 Base64url encoding the UTF-8 representation of the JSON header object 270 yields this JWT Header Segment value: 271 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 273 Signing the UTF-8 representation of the JWT Signing Input (the 274 concatenation of the JWT Header Segment, a period ('.') character, 275 and the JWT Payload Segment) with the HMAC SHA-256 algorithm and 276 base64url encoding the result, as per Section 8.1, yields this JWT 277 Crypto Segment value: 278 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 280 Concatenating these segments in the order Header.Payload.Signature 281 with period characters between the segments yields this complete JWT 282 using the JWT Compact Serialization (with line breaks for display 283 purposes only): 284 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 285 . 286 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ 287 . 288 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 290 This computation is illustrated in more detail in Appendix A.1. 292 4. JWT Claims 294 If the JWT contains a set of claims represented as a JSON object, 295 then the members of the JSON object represented by the Decoded JWT 296 Claims Object decoded from the JWT Payload Segment contain the 297 claims. Note however, that the set of claims a JWT must contain to 298 be considered valid is context-dependent and is outside the scope of 299 this specification. When used in a security-related context, 300 implementations MUST understand and support all of the claims 301 present; otherwise, the JWT MUST be rejected for processing. 303 There are three classes of JWT Claim Names: Reserved Claim Names, 304 Public Claim Names, and Private Claim Names. 306 4.1. Reserved Claim Names 308 The following claim names are reserved. None of the claims defined 309 in the table below are intended to be mandatory, but rather, provide 310 a starting point for a set of useful, interoperable claims. All the 311 names are short because a core goal of JWTs is for the tokens 312 themselves to be short. 314 +-------+---------+--------------+----------------------------------+ 315 | Claim | JSON | Claim Syntax | Claim Semantics | 316 | Name | Value | | | 317 | | Type | | | 318 +-------+---------+--------------+----------------------------------+ 319 | exp | integer | IntDate | The "exp" (expiration time) | 320 | | | | claim identifies the expiration | 321 | | | | time on or after which the token | 322 | | | | MUST NOT be accepted for | 323 | | | | processing. The processing of | 324 | | | | the "exp" claim requires that | 325 | | | | the current date/time MUST be | 326 | | | | before the expiration date/time | 327 | | | | listed in the "exp" claim. | 328 | | | | Implementers MAY provide for | 329 | | | | some small leeway, usually no | 330 | | | | more than a few minutes, to | 331 | | | | account for clock skew. This | 332 | | | | claim is OPTIONAL. | 333 | iss | string | StringAndURI | The "iss" (issuer) claim | 334 | | | | identifies the principal that | 335 | | | | issued the JWT. The processing | 336 | | | | of this claim is generally | 337 | | | | application specific. This | 338 | | | | claim is OPTIONAL. | 339 | aud | string | StringAndURI | The "aud" (audience) claim | 340 | | | | identifies the audience that the | 341 | | | | JWT is intended for. The | 342 | | | | principal intended to process | 343 | | | | the JWT MUST be identified by | 344 | | | | the value of the audience claim. | 345 | | | | If the principal processing the | 346 | | | | claim does not identify itself | 347 | | | | with the identifier in the "aud" | 348 | | | | claim value then the JWT MUST be | 349 | | | | rejected. The interpretation of | 350 | | | | the contents of the audience | 351 | | | | value is generally application | 352 | | | | specific. This claim is | 353 | | | | OPTIONAL. | 354 | typ | string | String | The "typ" (type) claim is used | 355 | | | | to declare a type for the | 356 | | | | contents of this JWT. This | 357 | | | | claim is OPTIONAL. | 358 +-------+---------+--------------+----------------------------------+ 360 Table 1: Reserved Claim Definitions 362 Additional reserved claim names MAY be defined via the IANA JSON Web 363 Token Claims registry, as per Section 10. The syntax values used 364 above and in Table 3 are defined as follows: 366 +--------------+----------------------------------------------------+ 367 | Syntax Name | Syntax Definition | 368 +--------------+----------------------------------------------------+ 369 | IntDate | The number of seconds from 1970-01-01T0:0:0Z as | 370 | | measured in UTC until the desired date/time. See | 371 | | RFC 3339 [RFC3339] for details regarding | 372 | | date/times in general and UTC in particular. | 373 | String | Any string value MAY be used. | 374 | StringAndURI | Any string value MAY be used but a value | 375 | | containing a ":" character MUST be a URI as | 376 | | defined in RFC 3986 [RFC3986]. | 377 | URI | A URI as defined in RFC 3986 [RFC3986]. | 378 | URL | A URL as defined in RFC 1738 [RFC1738]. | 379 +--------------+----------------------------------------------------+ 381 Table 2 383 4.2. Public Claim Names 385 Claim names can be defined at will by those using JWTs. However, in 386 order to prevent collisions, any new claim name SHOULD either be 387 defined in the IANA JSON Web Token Claims registry or be defined as a 388 URI that contains a collision resistant namespace. Examples of 389 collision resistant namespaces include: 391 o Domain Names, 393 o Object Identifiers (OIDs) as defined in the ITU-T X 660 and X 670 394 Recommendation series or 396 o Universally Unique IDentifier (UUID) as defined in RFC 4122 397 [RFC4122]. 399 In each case, the definer of the name or value MUST take reasonable 400 precautions to make sure they are in control of the part of the 401 namespace they use to define the claim name. 403 4.3. Private Claim Names 405 A producer and consumer of a JWT may agree to any claim name that is 406 not a Reserved Name Section 4.1 or a Public Name Section 4.2. Unlike 407 Public Names, these private names are subject to collision and should 408 be used with caution. 410 5. JWT Header 412 The members of the JSON object represented by the Decoded JWT Header 413 Segment describe the signature applied to the JWT Header Segment and 414 the JWT Payload Segment and optionally additional properties of the 415 JWT. Implementations MUST understand the entire contents of the 416 header; otherwise, the JWT MUST be rejected for processing. 418 5.1. Reserved Header Parameter Names 420 The following header parameter names are reserved. All the names are 421 short because a core goal of JWTs is for the tokens themselves to be 422 short. 424 +-----------+--------+--------------+-------------------------------+ 425 | Header | JSON | Header | Header Parameter Semantics | 426 | Parameter | Value | Parameter | | 427 | Name | Type | Syntax | | 428 +-----------+--------+--------------+-------------------------------+ 429 | alg | string | StringAndURI | The "alg" (algorithm) header | 430 | | | | parameter identifies the | 431 | | | | cryptographic algorithm used | 432 | | | | to secure the JWT. A list of | 433 | | | | reserved alg values is in | 434 | | | | Table 4. The processing of | 435 | | | | the "alg" (algorithm) header | 436 | | | | parameter, if present, | 437 | | | | requires that the value of | 438 | | | | the "alg" header parameter | 439 | | | | MUST be one that is both | 440 | | | | supported and for which there | 441 | | | | exists a key for use with | 442 | | | | that algorithm associated | 443 | | | | with the issuer of the JWT. | 444 | | | | This header parameter is | 445 | | | | REQUIRED. | 446 | typ | string | String | The "typ" (type) header | 447 | | | | parameter is used to declare | 448 | | | | that this data structure is a | 449 | | | | JWT. If a "typ" parameter is | 450 | | | | present, it is RECOMMENDED | 451 | | | | that its value be "JWT". | 452 | | | | This header parameter is | 453 | | | | OPTIONAL. | 454 | jku | string | URL | The "jku" (JSON Key URL) | 455 | | | | header parameter is a URL | 456 | | | | that points to JSON-encoded | 457 | | | | public key certificates that | 458 | | | | can be used to validate the | 459 | | | | signature. The specification | 460 | | | | for this encoding is TBD. | 461 | | | | This header parameter is | 462 | | | | OPTIONAL. | 463 | kid | string | String | The "kid" (key ID) header | 464 | | | | parameter is a hint | 465 | | | | indicating which specific key | 466 | | | | owned by the signer should be | 467 | | | | used to validate the | 468 | | | | signature. This allows | 469 | | | | signers to explicitly signal | 470 | | | | a change of key to | 471 | | | | recipients. Omitting this | 472 | | | | parameter is equivalent to | 473 | | | | setting it to an empty | 474 | | | | string. The interpretation | 475 | | | | of the contents of the "kid" | 476 | | | | parameter is unspecified. | 477 | | | | This header parameter is | 478 | | | | OPTIONAL. | 479 | x5u | string | URL | The "x5u" (X.509 URL) header | 480 | | | | parameter is a URL that | 481 | | | | points to an X.509 public key | 482 | | | | certificate that can be used | 483 | | | | to validate the signature. | 484 | | | | This certificate MUST conform | 485 | | | | to RFC 5280 [RFC5280]. This | 486 | | | | header parameter is OPTIONAL. | 487 | x5t | string | String | The "x5t" (x.509 certificate | 488 | | | | thumbprint) header parameter | 489 | | | | provides a base64url encoded | 490 | | | | SHA-256 thumbprint (a.k.a. | 491 | | | | digest) of the DER encoding | 492 | | | | of an X.509 certificate that | 493 | | | | can be used to match a | 494 | | | | certificate. This header | 495 | | | | parameter is OPTIONAL. | 496 +-----------+--------+--------------+-------------------------------+ 498 Table 3: Reserved Header Parameter Definitions 500 Additional reserved header parameter names MAY be defined via the 501 IANA JSON Web Token Header Parameters registry, as per Section 10. 502 The syntax values used above and in Table 1 are defined in Table 2. 504 5.2. Public Header Parameter Names 506 Additional header parameter names can be defined by those using JWTs. 507 However, in order to prevent collisions, any new header parameter 508 name or algorithm value SHOULD either be defined in the IANA JSON Web 509 Token Header Parameters registry or be defined as a URI that contains 510 a collision resistant namespace. In each case, the definer of the 511 name or value MUST take reasonable precautions to make sure they are 512 in control of the part of the namespace they use to define the header 513 parameter name. 515 New header parameters should be introduced sparingly, as they can 516 result in non-interoperable JWTs. Nonetheless, some extensions 517 needed for some use cases may require them, such as an extension to 518 enable the inclusion of multiple signatures. 520 5.3. Private Header Parameter Names 522 A producer and consumer of a JWT may agree to any header parameter 523 name that is not a Reserved Name Section 5.1 or a Public Name 524 Section 5.2. Unlike Public Names, these private names are subject to 525 collision and should be used with caution. 527 New header parameters should be introduced sparingly, as they can 528 result in non-interoperable JWTs. 530 6. Rules for Creating and Validating a JWT 532 To create a JWT one MUST follow these steps: 534 1. Create the payload content to be encoded as the Decoded JWT 535 Payload Segment. If the payload represents a JWT Claims Object, 536 then these steps for creating the Decoded JWT Payload Segment 537 also apply: 539 * Create a JSON object containing the desired claims. Note that 540 white space is explicitly allowed in the representation and no 541 canonicalization is performed before encoding. 543 * Translate this JSON object's Unicode code points into UTF-8, 544 as defined in RFC 3629 [RFC3629]. This is the Decoded JWT 545 Payload Segment. 547 2. Base64url encode the Decoded JWT Payload Segment. This encoding 548 becomes the JWT Payload Segment. 550 3. Create a JSON object containing a set of desired header 551 parameters. Note that white space is explicitly allowed in the 552 representation and no canonicalization is performed before 553 encoding. 555 4. Translate this JSON object's Unicode code points into UTF-8, as 556 defined in RFC 3629 [RFC3629]. 558 5. Base64url encode the UTF-8 representation of this JSON object as 559 defined in this specification (without padding). This encoding 560 becomes a JWT Header Segment. 562 6. Construct a JWT Crypto Segment as defined for the particular 563 algorithm being used. The JWT Signing Input is always the 564 concatenation of a JWT Header Segment, a period ('.') character, 565 and the JWT Payload Segment. The "alg" header parameter MUST be 566 present in the JSON Header Segment, with the algorithm value 567 accurately representing the algorithm used to construct the JWT 568 Crypto Segment. 570 7. If the JWT Compact Serialization is being used, then: 572 * Concatenate the JWT Header Segment, the JWT Payload Segment 573 and then the JWT Crypto Segment in that order, separating each 574 by period characters, to create the JWT. 576 Else if the JWT JSON Serialization is being used, then: 578 * Create a JSON object with these three members: a "header" 579 member whose value is an array of JWT Header Segments, a 580 "payload" member whose value is the JWT Payload Segment, and a 581 "signature" member whose value is an array of JWT Crypto 582 Segments. 584 * If more than one signature is present, then repeat steps 3 585 through 6 for each header and crypto segment to produce 586 additional values for the header and signature arrays. 588 * The header and signature arrays must have the same number of 589 values, with each header value and corresponding signature 590 value being located at the same array index. 592 When validating a JWT the following steps MUST be taken. If any of 593 the listed steps fails then the token MUST be rejected for 594 processing. 596 1. If the JWT Compact Serialization is being used, then: 598 * The JWT MUST contain two period characters. 600 * The JWT MUST be split on the two period characters resulting 601 in three non-empty segments. The first segment is the JWT 602 Header Segment; the second is the JWT Payload Segment; the 603 third is the JWT Crypto Segment. 605 Else if the JWT JSON Serialization is being used, then: 607 * The JSON MUST contain the three members "header", "payload", 608 and "signature" and MAY contain others, which MUST be ignored. 609 The payload member MUST be a string and the header and 610 signature members MUST be non-empty arrays of strings with 611 equal cardinality. 613 * Use a "header" member array value as the JWT Header Segment; 614 use the "payload" member value as the JWT Payload Segment; use 615 a "signature" member array value with the same index as the 616 "header" member array value used as the JWT Crypto Segment. 618 2. The JWT Payload Segment MUST be successfully base64url decoded 619 following the restriction given in this spec that no padding 620 characters have been used. 622 3. If the payload represents a JWT Claims Object, then these steps 623 for validating the Decoded JWT Payload Segment also apply: 625 * The Decoded JWT Payload Segment, which is the Decoded JWT 626 Claims Object, MUST be completely valid JSON syntax conforming 627 to RFC 4627 [RFC4627]. 629 * When used in a security-related context, the Decoded JWT 630 Claims Object MUST be validated to only include claims whose 631 syntax and semantics are both understood and supported. 633 4. The JWT Header Segment MUST be successfully base64url decoded 634 following the restriction given in this spec that no padding 635 characters have been used. 637 5. The Decoded JWT Header Segment MUST be completely valid JSON 638 syntax conforming to RFC 4627 [RFC4627]. 640 6. The JWT Crypto Segment MUST be successfully base64url decoded 641 following the restriction given in this spec that no padding 642 characters have been used. 644 7. The JWT Header Segment MUST be validated to only include 645 parameters and values whose syntax and semantics are both 646 understood and supported. 648 8. The JWT Crypto Segment MUST be successfully validated against the 649 JWT Header Segment and JWT Payload Segment in the manner defined 650 for the algorithm being used, which MUST be accurately 651 represented by the value of the "alg" header parameter, which 652 MUST be present. 654 9. If the JWT JSON Serialization is being used, then repeat steps 4 655 to 8 for each element of the header and signature arrays. 657 Processing a JWT inevitably requires comparing known strings to 658 values in the token. For example, in checking what the algorithm is, 659 the Unicode string encoding "alg" will be checked against the member 660 names in the Decoded JWT Header Segment to see if there is a matching 661 header parameter name. A similar process occurs when determining if 662 the value of the "alg" header parameter represents a supported 663 algorithm. Comparing Unicode strings, however, has significant 664 security implications, as per Section 11. 666 Comparisons between JSON strings and other Unicode strings MUST be 667 performed as specified below: 669 1. Remove any JSON applied escaping to produce an array of Unicode 670 code points. 672 2. Unicode Normalization [USA15] MUST NOT be applied at any point to 673 either the JSON string or to the string it is to be compared 674 against. 676 3. Comparisons between the two strings MUST be performed as a 677 Unicode code point to code point equality comparison. 679 7. Base64url encoding as used by JWTs 681 JWTs make use of the base64url encoding as defined in RFC 4648 682 [RFC4648]. As allowed by Section 3.2 of the RFC, this specification 683 mandates that base64url encoding when used with JWTs MUST NOT use 684 padding. The reason for this restriction is that the padding 685 character ('=') is not URL safe. 687 For notes on implementing base64url encoding without padding, see 688 Appendix B. 690 8. Signing JWTs with Cryptographic Algorithms 692 JWTs use specific cryptographic algorithms to sign the contents of 693 the JWT Header Segment and the JWT Payload Segment. The use of the 694 following algorithms for producing JWTs is defined in this section. 695 The table below is the list of "alg" header parameter values reserved 696 by this specification, each of which is explained in more detail in 697 the following sections: 699 +--------------------+----------------------------------------------+ 700 | Alg Parameter | Algorithm | 701 | Value | | 702 +--------------------+----------------------------------------------+ 703 | HS256 | HMAC using SHA-256 hash algorithm | 704 | HS384 | HMAC using SHA-384 hash algorithm | 705 | HS512 | HMAC using SHA-512 hash algorithm | 706 | RS256 | RSA using SHA-256 hash algorithm | 707 | RS384 | RSA using SHA-384 hash algorithm | 708 | RS512 | RSA using SHA-512 hash algorithm | 709 | ES256 | ECDSA using P-256 curve and SHA-256 hash | 710 | | algorithm | 711 | ES384 | ECDSA using P-384 curve and SHA-384 hash | 712 | | algorithm | 713 | ES512 | ECDSA using P-521 curve and SHA-512 hash | 714 | | algorithm | 715 +--------------------+----------------------------------------------+ 717 Table 4: JSON Web Token Reserved Algorithm Values 719 Of these algorithms, only HMAC SHA-256 and RSA SHA-256 MUST be 720 implemented by conforming implementations. It is RECOMMENDED that 721 implementations also support the ECDSA P-256 SHA-256 algorithm. 723 Support for other algorithms is OPTIONAL. 725 The portion of a JWT that is signed is the same for all algorithms: 726 the concatenation of the JWT Header Segment, a period ('.') 727 character, and the JWT Payload Segment. This character sequence is 728 referred to as the JWT Signing Input. Note that in the JWT Compact 729 Serialization, this corresponds to the portion of the JWT 730 representation preceding the second period character. The UTF-8 731 representation of the JWT Signing Input is passed to the respective 732 signing algorithms. 734 8.1. Signing a JWT with HMAC SHA-256 736 Hash based Message Authentication Codes (HMACs) enable one to use a 737 secret plus a cryptographic hash function to generate a Message 738 Authentication Code (MAC). This can be used to demonstrate that the 739 MAC matches the hashed content, in this case the JWT Signing Input, 740 which therefore demonstrates that whoever generated the MAC was in 741 possession of the secret. 743 The algorithm for implementing and validating HMACs is provided in 744 RFC 2104 [RFC2104]. Although any HMAC can be used with JWTs, this 745 section defines the use of the SHA-256 cryptographic hash function as 746 defined in FIPS 180-3 [FIPS.180-3]. The reserved "alg" header 747 parameter value "HS256" is used in the JWT Header Segment to indicate 748 that the JWT Crypto Segment contains a base64url encoded HMAC SHA-256 749 HMAC value. 751 The HMAC SHA-256 MAC is generated as follows: 753 1. Apply the HMAC SHA-256 algorithm to the UTF-8 representation of 754 the JWT Signing Input using the shared key to produce an HMAC. 756 2. Base64url encode the HMAC as defined in this document. 758 The output is placed in the JWT Crypto Segment for that JWT. 760 The HMAC SHA-256 MAC on a JWT is validated as follows: 762 1. Apply the HMAC SHA-256 algorithm to the UTF-8 representation of 763 the JWT Signing Input of the JWT using the shared key. 765 2. Base64url encode the previously generated HMAC as defined in this 766 document. 768 3. If the JWT Crypto Segment and the previously calculated value 769 exactly match, then one has confirmation that the key was used to 770 generate the HMAC on the JWT and that the contents of the JWT 771 have not be tampered with. 773 4. If the validation fails, the token MUST be rejected. 775 Signing with the HMAC SHA-384 and HMAC SHA-512 algorithms is 776 performed identically to the procedure for HMAC SHA-256 - just with 777 correspondingly longer key and result values. 779 8.2. Signing a JWT with RSA SHA-256 781 This section defines the use of the RSASSA-PKCS1-v1_5 signature 782 algorithm as defined in RFC 3447 [RFC3447], Section 8.2 (commonly 783 known as PKCS#1), using SHA-256 as the hash function. Note that the 784 use of the RSASSA-PKCS1-v1_5 algorithm is described in FIPS 186-3 785 [FIPS.186-3], Section 5.5, as is the SHA-256 cryptographic hash 786 function, which is defined in FIPS 180-3 [FIPS.180-3]. The reserved 787 "alg" header parameter value "RS256" is used in the JWT Header 788 Segment to indicate that the JWT Crypto Segment contains an RSA SHA- 789 256 signature. 791 A 2048-bit or longer key length MUST be used with this algorithm. 793 The RSA SHA-256 signature is generated as follows: 795 1. Let K be the signer's RSA private key and let M be the UTF-8 796 representation of the JWT Signing Input. 798 2. Compute the octet string S = RSASSA-PKCS1-V1_5-SIGN (K, M) using 799 SHA-256 as the hash function. 801 3. Base64url encode the octet string S, as defined in this document. 803 The output is placed in the JWT Crypto Segment for that JWT. 805 The RSA SHA-256 signature on a JWT is validated as follows: 807 1. Take the JWT Crypto Segment and base64url decode it into an octet 808 string S. If decoding fails, then the token MUST be rejected. 810 2. Let M be the UTF-8 representation of the JWT Signing Input and 811 let (n, e) be the public key corresponding to the private key 812 used by the signer. 814 3. Validate the signature with RSASSA-PKCS1-V1_5-VERIFY ((n, e), M, 815 S) using SHA-256 as the hash function. 817 4. If the validation fails, the token MUST be rejected. 819 Signing with the RSA SHA-384 and RSA SHA-512 algorithms is performed 820 identically to the procedure for RSA SHA-256 - just with 821 correspondingly longer key and result values. 823 8.3. Signing a JWT with ECDSA P-256 SHA-256 825 The Elliptic Curve Digital Signature Algorithm (ECDSA) is defined by 826 FIPS 186-3 [FIPS.186-3]. ECDSA provides for the use of Elliptic 827 Curve cryptography, which is able to provide equivalent security to 828 RSA cryptography but using shorter key lengths and with greater 829 processing speed. This means that ECDSA signatures will be 830 substantially smaller in terms of length than equivalently strong RSA 831 Digital Signatures. 833 This specification defines the use of ECDSA with the P-256 curve and 834 the SHA-256 cryptographic hash function. The P-256 curve is also 835 defined in FIPS 186-3. The reserved "alg" header parameter value 836 "ES256" is used in the JWT Header Segment to indicate that the JWT 837 Crypto Segment contains an ECDSA P-256 SHA-256 signature. 839 A JWT is signed with an ECDSA P-256 SHA-256 signature as follows: 841 1. Generate a digital signature of the UTF-8 representation of the 842 JWT Signing Input using ECDSA P-256 SHA-256 with the desired 843 private key. The output will be the EC point (R, S), where R and 844 S are unsigned integers. 846 2. Turn R and S into byte arrays in big endian order. Each array 847 will be 32 bytes long. 849 3. Concatenate the two byte arrays in the order R and then S. 851 4. Base64url encode the 64 byte array as defined in this 852 specification. 854 The output becomes the JWT Crypto Segment for the JWT. 856 The following procedure is used to validate the ECDSA signature of a 857 JWT: 859 1. Take the JWT Crypto Segment and base64url decode it into a byte 860 array. If decoding fails, the token MUST be rejected. 862 2. The output of the base64url decoding MUST be a 64 byte array. 864 3. Split the 64 byte array into two 32 byte arrays. The first array 865 will be R and the second S. Remember that the byte arrays are in 866 big endian byte order; please check the ECDSA validator in use to 867 see what byte order it requires. 869 4. Submit the UTF-8 representation of the JWT Signing Input, R, S 870 and the public key (x, y) to the ECDSA P-256 SHA-256 validator. 872 5. If the validation fails, the token MUST be rejected. 874 The ECDSA validator will then determine if the digital signature is 875 valid, given the inputs. Note that ECDSA digital signature contains 876 a value referred to as K, which is a random number generated for each 877 digital signature instance. This means that two ECDSA digital 878 signatures using exactly the same input parameters will output 879 different signatures because their K values will be different. The 880 consequence of this is that one must validate an ECDSA signature by 881 submitting the previously specified inputs to an ECDSA validator. 883 Signing with the ECDSA P-384 SHA-384 and ECDSA P-521 SHA-512 884 algorithms is performed identically to the procedure for ECDSA P-256 885 SHA-256 - just with correspondingly longer key and result values. 887 8.4. Additional Algorithms 889 Additional algorithms MAY be used to protect JWTs with corresponding 890 "alg" header parameter values being defined to refer to them. Like 891 claim names, new "alg" header parameter values SHOULD either be 892 defined in the IANA JSON Web Token Algorithms registry or be a URI 893 that contains a collision resistant namespace. In particular, the 894 use of algorithm identifiers defined in XML DSIG [RFC3275] and 895 related specifications is permitted. 897 9. JWT Serialization Formats 899 JSON Web Tokens (JWTs) support two serialization formats: the JWT 900 Compact Serialization, which is more space efficient and intended for 901 uses where the token is passed as a simple string-valued parameter, 902 and the JWT JSON Serialization, which is more general, being able to 903 contain multiple signatures over the same content. The two 904 serialization formats are intended for use in different contexts. 906 9.1. JWT Compact Serialization 908 The JWT Compact Serialization represents a JWT as a string consisting 909 of three JWT Token Segments: the JWT Header Segment, the JWT Payload 910 Segment, and the JWT Crypto Segment, in that order, with the segments 911 being separated by period ('.') characters. It is intended for uses 912 where the token is passed as a simple string-valued parameter, 913 including in URLs. 915 The Compact Serialization contains only one signature to keep this 916 format simple. The example JWT in Section 3.1 uses the Compact 917 Serialization. 919 9.2. JWT JSON Serialization 921 The JWT JSON Serialization represents a JWT as a JSON object with 922 members for each of three kinds of JWT Token Segments: a "header" 923 member whose value is a non-empty array of JWT Header Segments, a 924 "payload" member whose value is the JWT Payload Segment, and a 925 "signature" member whose value is a non-empty array of JWT Crypto 926 Segments, where the cardinality of both arrays is the same. 928 Unlike the Compact Serialization, JWTs using the JSON Serialization 929 MAY contain multiple signatures. Each signature is represented as a 930 JWT Crypto Segment in the "signature" member array. For each 931 signature, there is a corresponding "header" member array element 932 that specifies the signature algorithm for that signature, and 933 potentially other information as well. Therefore, the syntax is: 934 {"header":["
",...,"
"], 935 "payload":"", 936 "signature":["",...,""] 937 } 939 The i'th signature is computed on the concatenation of
.. 942 Appendix A.4 contains an example JWT using the JSON Serialization. 944 10. IANA Considerations 946 This specification calls for: 948 o A new IANA registry entitled "JSON Web Token Claims" for reserved 949 claim names is defined in Section 4.1. Inclusion in the registry 950 is RFC Required in the RFC 5226 [RFC5226] sense for reserved JWT 951 claim names that are intended to be interoperable between 952 implementations. The registry will just record the reserved claim 953 name and a pointer to the RFC that defines it. This specification 954 defines inclusion of the claim names defined in Table 1. 956 o A new IANA registry entitled "JSON Web Token Header Parameters" 957 for reserved header parameter names is defined in Section 5.1. 958 Inclusion in the registry is RFC Required in the RFC 5226 959 [RFC5226] sense for reserved JWT header parameter names that are 960 intended to be interoperable between implementations. The 961 registry will just record the reserved header parameter name and a 962 pointer to the RFC that defines it. This specification defines 963 inclusion of the header parameter names defined in Table 3. 965 o A new IANA registry entitled "JSON Web Token Algorithms" for 966 reserved values used with the "alg" header parameter values is 967 defined in Section 8.4. Inclusion in the registry is RFC Required 968 in the RFC 5226 [RFC5226] sense. The registry will just record 969 the "alg" value and a pointer to the RFC that defines it. This 970 specification defines inclusion of the algorithm values defined in 971 Table 4. 973 11. Security Considerations 975 TBD: Lots of work to do here. We need to remember to look into any 976 issues relating to security and JSON parsing. One wonders just how 977 secure most JSON parsing libraries are. Were they ever hardened for 978 security scenarios? If not, what kind of holes does that open up? 979 Also, we need to walk through the JSON standard and see what kind of 980 issues we have especially around comparison of names. For instance, 981 comparisons of claim names and other parameters must occur after they 982 are unescaped. Need to also put in text about: Importance of keeping 983 secrets secret. Rotating keys. Strengths and weaknesses of the 984 different algorithms. 986 TBD: Need to put in text about why strict JSON validation is 987 necessary. Basically, that if malformed JSON is received then the 988 intent of the sender is impossible to reliably discern. While in 989 non-security contexts it's o.k. to be generous in what one accepts, 990 in security contexts this can lead to serious security holes. For 991 example, malformed JSON might indicate that someone has managed to 992 find a security hole in the issuer's code and is leveraging it to get 993 the issuer to issue "bad" tokens whose content the attacker can 994 control. 996 11.1. Unicode Comparison Security Issues 998 Claim names in JWTs are Unicode strings. For security reasons, the 999 representations of these names must be compared verbatim after 1000 performing any escape processing (as per RFC 4627 [RFC4627], Section 1001 2.5). 1003 This means, for instance, that these JSON strings must compare as 1004 being equal ("JWT", "\u004aWT"), whereas these must all compare as 1005 being not equal to the first set or to each other ("jwt", "Jwt", 1006 "JW\u0074"). 1008 JSON strings MAY contain characters outside the Unicode Basic 1009 Multilingual Plane. For instance, the G clef character (U+1D11E) may 1010 be represented in a JSON string as "\uD834\uDD1E". Ideally, JWT 1011 implementations SHOULD ensure that characters outside the Basic 1012 Multilingual Plane are preserved and compared correctly; 1013 alternatively, if this is not possible due to these characters 1014 exercising limitations present in the underlying JSON implementation, 1015 then input containing them MUST be rejected. 1017 12. Open Issues and Things To Be Done (TBD) 1019 The following items remain to be done in this draft (and related 1020 drafts): 1022 o The specification will be a lot clearer if the signature portions 1023 are cleanly separated from the claims token format and 1024 serialization portions. Having tried it this way and being 1025 dissatisfied with the sometimes unwieldy readability of the 1026 result, I plan to perform the separation in the next draft. 1028 o Consider whether there is a better term than "Digital Signature" 1029 for the concept that includes both HMACs and digital signatures 1030 using public keys. 1032 o Consider whether we really want to allow private claim names and 1033 header parameters that are not registered with IANA and are not in 1034 collision-resistant namespaces. Eventually this could result in 1035 interop nightmares where you need to have different code to talk 1036 to different endpoints that "knows" about each endpoints' private 1037 parameters. 1039 o Clarify the optional ability to provide type information JWTs 1040 and/or their segments. Specifically, clarify the intended use of 1041 the "typ" Header Parameter and the "typ" claim, whether they 1042 convey syntax or semantics, and indeed, whether this is the right 1043 approach. Also clarify the relationship between these type values 1044 and MIME [RFC2045] types. 1046 o Clarify the semantics of the "kid" (key ID) header parameter. 1047 Open issues include: What happens if a kid header is received with 1048 an unrecognized value? Is that an error? Should it be treated as 1049 if it's empty? What happens if the header has a recognized value 1050 but the value doesn't match the key associated with that value, 1051 but it does match another key that is associated with the issuer? 1052 Is that an error? 1054 o The "x5t" parameter is currently specified as "a base64url encoded 1055 SHA-256 thumbprint of the DER encoding of an X.509 certificate". 1057 SHA-1 was traditionally used for certificate digests but 1058 collisions are possible to create and can be used for denial of 1059 service attacks within multi-tenant services. We need to 1060 understand the compatibility issues of using SHA-256 thumbprints 1061 instead. We also likely want to specify the digest algorithm 1062 explicitly. 1064 o Several people have objected to the requirement for implementing 1065 RSA SHA-256, some because they will only be using HMACs and 1066 symmetric keys, and others because they only want to use ECDSA 1067 when using asymmetric keys, either for security or key length 1068 reasons, or both. I believe therefore, that we should consider 1069 changing the MUST for RSA SHA-256 to RECOMMENDED. 1071 o Since RFC 3447 Section 8 explicitly calls for people NOT to adopt 1072 RSASSA-PKCS1 for new applications and instead requests that people 1073 transition to RSASSA-PSS, we probably need some Security 1074 Considerations text explaining why RSASSA-PKCS1 is being used 1075 (it's what's commonly implemented) and what the potential 1076 consequences are. 1078 o Generalize the normative text on signing algorithms so that the 1079 descriptions apply equally to the use of various key lengths - not 1080 just HMAC SHA-256, RSA SHA-256, and ECDSA P-256 SHA-256. 1082 o Add a table cross-referencing the algorithm name strings used in 1083 standard software packages and specifications. 1085 o Add Security Considerations text on timing attacks. 1087 o Finish the Security Considerations section. 1089 o Sort out what to do with the IANA registries if this is first 1090 standardized as an OpenID specification. 1092 o Write the related specification for encoding public keys using 1093 JSON, as per the agreement documented at 1094 http://self-issued.info/?p=390. This will be used by the "jku" 1095 (JSON Key URL) header parameter. 1097 o Write the companion encryption specification, per the agreements 1098 documented at http://self-issued.info/?p=378. 1100 13. References 1101 13.1. Normative References 1103 [FIPS.180-3] 1104 National Institute of Standards and Technology, "Secure 1105 Hash Standard (SHS)", FIPS PUB 180-3, October 2008. 1107 [FIPS.186-3] 1108 National Institute of Standards and Technology, "Digital 1109 Signature Standard (DSS)", FIPS PUB 186-3, June 2009. 1111 [RFC1738] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform 1112 Resource Locators (URL)", RFC 1738, December 1994. 1114 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1115 Extensions (MIME) Part One: Format of Internet Message 1116 Bodies", RFC 2045, November 1996. 1118 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 1119 Hashing for Message Authentication", RFC 2104, 1120 February 1997. 1122 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1123 Requirement Levels", BCP 14, RFC 2119, March 1997. 1125 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 1126 Internet: Timestamps", RFC 3339, July 2002. 1128 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 1129 Standards (PKCS) #1: RSA Cryptography Specifications 1130 Version 2.1", RFC 3447, February 2003. 1132 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1133 10646", STD 63, RFC 3629, November 2003. 1135 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1136 Resource Identifier (URI): Generic Syntax", STD 66, 1137 RFC 3986, January 2005. 1139 [RFC4627] Crockford, D., "The application/json Media Type for 1140 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1142 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1143 Encodings", RFC 4648, October 2006. 1145 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1146 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1147 May 2008. 1149 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1150 Housley, R., and W. Polk, "Internet X.509 Public Key 1151 Infrastructure Certificate and Certificate Revocation List 1152 (CRL) Profile", RFC 5280, May 2008. 1154 [USA15] Davis, M., Whistler, K., and M. Duerst, "Unicode 1155 Normalization Forms", Unicode Standard Annex 15, 09 2009. 1157 13.2. Informative References 1159 [CanvasApp] 1160 Facebook, "Canvas Applications", 2010. 1162 [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", 1163 September 2010. 1165 [MagicSignatures] 1166 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 1167 Signatures", August 2010. 1169 [OASIS.saml-core-2.0-os] 1170 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 1171 "Assertions and Protocol for the OASIS Security Assertion 1172 Markup Language (SAML) V2.0", OASIS Standard saml-core- 1173 2.0-os, March 2005. 1175 [RFC3275] Eastlake, D., Reagle, J., and D. Solo, "(Extensible Markup 1176 Language) XML-Signature Syntax and Processing", RFC 3275, 1177 March 2002. 1179 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1180 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1181 July 2005. 1183 [SWT] Hardt, D. and Y. Goland, "Simple Web Token (SWT)", 1184 Version 0.9.5.1, November 2009. 1186 [W3C.CR-xml11-20021015] 1187 Cowan, J., "Extensible Markup Language (XML) 1.1", W3C 1188 CR CR-xml11-20021015, October 2002. 1190 Appendix A. JWT Examples 1192 A.1. JWT using HMAC SHA-256 1193 A.1.1. Encoding 1195 The Decoded JWT Payload Segment used in this example is: 1196 {"iss":"joe", 1197 "exp":1300819380, 1198 "http://example.com/is_root":true} 1200 Note that white space is explicitly allowed in Decoded JWT Claims 1201 Objects and no canonicalization is performed before encoding. The 1202 following byte array contains the UTF-8 characters for the Decoded 1203 JWT Payload Segment: 1205 [123, 34, 105, 115, 115, 34, 58, 34, 106, 111, 101, 34, 44, 13, 10, 1206 32, 34, 101, 120, 112, 34, 58, 49, 51, 48, 48, 56, 49, 57, 51, 56, 1207 48, 44, 13, 10, 32, 34, 104, 116, 116, 112, 58, 47, 47, 101, 120, 97, 1208 109, 112, 108, 101, 46, 99, 111, 109, 47, 105, 115, 95, 114, 111, 1209 111, 116, 34, 58, 116, 114, 117, 101, 125] 1211 Base64url encoding the above yields the JWT Payload Segment value: 1212 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1214 The following example JSON header object declares that the data 1215 structure is a JSON Web Token (JWT) and the JWT Signing Input is 1216 signed using the HMAC SHA-256 algorithm: 1217 {"typ":"JWT", 1218 "alg":"HS256"} 1220 The following byte array contains the UTF-8 characters for the 1221 Decoded JWT Header Segment: 1223 [123, 34, 116, 121, 112, 34, 58, 34, 74, 87, 84, 34, 44, 13, 10, 32, 1224 34, 97, 108, 103, 34, 58, 34, 72, 83, 50, 53, 54, 34, 125] 1226 Base64url encoding this UTF-8 representation yields this JWT Header 1227 Segment value: 1228 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 1230 Concatenating the JWT Header Segment, a period character, and the JWT 1231 Payload Segment yields this JWT Signing Input value (with line breaks 1232 for display purposes only): 1233 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 1234 . 1235 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1237 The UTF-8 representation of the JWT Signing Input is the following 1238 byte array: 1240 [101, 121, 74, 48, 101, 88, 65, 105, 79, 105, 74, 75, 86, 49, 81, 1241 105, 76, 65, 48, 75, 73, 67, 74, 104, 98, 71, 99, 105, 79, 105, 74, 1242 73, 85, 122, 73, 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 1243 77, 105, 79, 105, 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 1244 74, 108, 101, 72, 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 1245 107, 122, 79, 68, 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 1246 72, 65, 54, 76, 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 1247 109, 78, 118, 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 1248 106, 112, 48, 99, 110, 86, 108, 102, 81] 1250 HMACs are generated using keys. This example used the key 1251 represented by the following byte array: 1253 [3, 35, 53, 75, 43, 15, 165, 188, 131, 126, 6, 101, 119, 123, 166, 1254 143, 90, 179, 40, 230, 240, 84, 201, 40, 169, 15, 132, 178, 210, 80, 1255 46, 191, 211, 251, 90, 146, 210, 6, 71, 239, 150, 138, 180, 195, 119, 1256 98, 61, 34, 61, 46, 33, 114, 5, 46, 79, 8, 192, 205, 154, 245, 103, 1257 208, 128, 163] 1259 Running the HMAC SHA-256 algorithm on the UTF-8 representation of the 1260 JWT Signing Input with this key yields the following byte array: 1262 [116, 24, 223, 180, 151, 153, 224, 37, 79, 250, 96, 125, 216, 173, 1263 187, 186, 22, 212, 37, 77, 105, 214, 191, 240, 91, 88, 5, 88, 83, 1264 132, 141, 121] 1266 Base64url encoding the above HMAC output yields the JWT Crypto 1267 Segment value: 1268 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 1270 Combining these segments in the order Header.Payload.Signature with 1271 period characters between the segments yields this complete JWT using 1272 the JWT Compact Serialization (with line breaks for display purposes 1273 only): 1274 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 1275 . 1276 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1277 . 1278 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 1280 A.1.2. Decoding 1282 Decoding the JWT first requires removing the base64url encoding from 1283 the JWT Header Segment, the JWT Payload Segment, and the JWT Crypto 1284 Segment. We base64url decode the segments per Section 7 and turn 1285 them into the corresponding byte arrays. We translate the header 1286 segment byte array containing UTF-8 encoded characters into the 1287 Decoded JWT Header Segment string. Likewise, if the payload 1288 represents a JWT Claims Object, we translate the payload segment byte 1289 array containing UTF-8 encoded characters into a Decoded JWT Claims 1290 Object string. 1292 A.1.3. Validating 1294 Next we validate the decoded results. Since the "alg" parameter in 1295 the header is "HS256", we validate the HMAC SHA-256 signature 1296 contained in the JWT Crypto Segment. If any of the validation steps 1297 fail, the token MUST be rejected. 1299 First, we validate that the decoded JWT Header Segment string is 1300 legal JSON. 1302 If the payload represents a JWT Claims Object, we also validate that 1303 the decoded JWT Payload Segment string is legal JSON. 1305 To validate the signature, we repeat the previous process of using 1306 the correct key and the UTF-8 representation of the JWT Signing Input 1307 as input to a SHA-256 HMAC function and then taking the output and 1308 determining if it matches the Decoded JWT Crypto Segment. If it 1309 matches exactly, the token has been validated. 1311 A.2. JWT using RSA SHA-256 1313 A.2.1. Encoding 1315 The Decoded JWT Payload Segment used in this example is the same as 1316 in the previous example: 1317 {"iss":"joe", 1318 "exp":1300819380, 1319 "http://example.com/is_root":true} 1321 Since the JWT Payload Segment will therefore be the same, its 1322 computation is not repeated here. However, the Decoded JWT Header 1323 Segment is different in two ways: First, because a different 1324 algorithm is being used, the "alg" value is different. Second, for 1325 illustration purposes only, the optional "typ" parameter is not used. 1326 (This difference is not related to the signature algorithm employed.) 1327 The Decoded JWT Header Segment used is: 1328 {"alg":"RS256"} 1330 The following byte array contains the UTF-8 characters for the 1331 Decoded JWT Header Segment: 1333 [123, 34, 97, 108, 103, 34, 58, 34, 82, 83, 50, 53, 54, 34, 125] 1335 Base64url encoding this UTF-8 representation yields this JWT Header 1336 Segment value: 1338 eyJhbGciOiJSUzI1NiJ9 1340 Concatenating the JWT Header Segment, a period character, and the JWT 1341 Payload Segment yields this JWT Signing Input value (with line breaks 1342 for display purposes only): 1343 eyJhbGciOiJSUzI1NiJ9 1344 . 1345 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1347 The UTF-8 representation of the JWT Signing Input is the following 1348 byte array: 1350 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 122, 73, 1351 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 77, 105, 79, 105, 1352 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 74, 108, 101, 72, 1353 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 107, 122, 79, 68, 1354 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 72, 65, 54, 76, 1355 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 109, 78, 118, 1356 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 106, 112, 48, 1357 99, 110, 86, 108, 102, 81] 1359 The RSA key consists of a public part (n, e), and a private exponent 1360 d. The values of the RSA key used in this example, presented as the 1361 byte arrays representing big endian integers are: 1363 +-----------+-------------------------------------------------------+ 1364 | Parameter | Value | 1365 | Name | | 1366 +-----------+-------------------------------------------------------+ 1367 | n | [161, 248, 22, 10, 226, 227, 201, 180, 101, 206, 141, | 1368 | | 45, 101, 98, 99, 54, 43, 146, 125, 190, 41, 225, 240, | 1369 | | 36, 119, 252, 22, 37, 204, 144, 161, 54, 227, 139, | 1370 | | 217, 52, 151, 197, 182, 234, 99, 221, 119, 17, 230, | 1371 | | 124, 116, 41, 249, 86, 176, 251, 138, 143, 8, 154, | 1372 | | 220, 75, 105, 137, 60, 193, 51, 63, 83, 237, 208, 25, | 1373 | | 184, 119, 132, 37, 47, 236, 145, 79, 228, 133, 119, | 1374 | | 105, 89, 75, 234, 66, 128, 211, 44, 15, 85, 191, 98, | 1375 | | 148, 79, 19, 3, 150, 188, 110, 155, 223, 110, 189, | 1376 | | 210, 189, 163, 103, 142, 236, 160, 198, 104, 247, 1, | 1377 | | 179, 141, 191, 251, 56, 200, 52, 44, 226, 254, 109, | 1378 | | 39, 250, 222, 74, 90, 72, 116, 151, 157, 212, 185, | 1379 | | 207, 154, 222, 196, 199, 91, 5, 133, 44, 44, 15, 94, | 1380 | | 248, 165, 193, 117, 3, 146, 249, 68, 232, 237, 100, | 1381 | | 193, 16, 198, 182, 71, 96, 154, 164, 120, 58, 235, | 1382 | | 156, 108, 154, 215, 85, 49, 48, 80, 99, 139, 131, | 1383 | | 102, 92, 111, 111, 122, 130, 163, 150, 112, 42, 31, | 1384 | | 100, 27, 130, 211, 235, 242, 57, 34, 25, 73, 31, 182, | 1385 | | 134, 135, 44, 87, 22, 245, 10, 248, 53, 141, 154, | 1386 | | 139, 157, 23, 195, 64, 114, 143, 127, 135, 216, 154, | 1387 | | 24, 216, 252, 171, 103, 173, 132, 89, 12, 46, 207, | 1388 | | 117, 147, 57, 54, 60, 7, 3, 77, 111, 96, 111, 158, | 1389 | | 33, 224, 84, 86, 202, 229, 233, 161] | 1390 | e | [1, 0, 1] | 1391 | d | [18, 174, 113, 164, 105, 205, 10, 43, 195, 126, 82, | 1392 | | 108, 69, 0, 87, 31, 29, 97, 117, 29, 100, 233, 73, | 1393 | | 112, 123, 98, 89, 15, 157, 11, 165, 124, 150, 60, 64, | 1394 | | 30, 63, 207, 47, 44, 211, 189, 236, 136, 229, 3, 191, | 1395 | | 198, 67, 155, 11, 40, 200, 47, 125, 55, 151, 103, 31, | 1396 | | 82, 19, 238, 216, 193, 90, 37, 216, 213, 206, 160, 2, | 1397 | | 94, 227, 171, 46, 139, 127, 121, 33, 111, 198, 59, | 1398 | | 234, 86, 39, 83, 180, 6, 68, 198, 161, 81, 39, 217, | 1399 | | 178, 149, 69, 64, 160, 187, 225, 163, 5, 86, 152, 45, | 1400 | | 78, 159, 222, 95, 100, 37, 241, 77, 75, 113, 52, 65, | 1401 | | 181, 93, 199, 59, 155, 74, 237, 204, 146, 172, 227, | 1402 | | 146, 126, 55, 245, 125, 12, 253, 94, 117, 129, 250, | 1403 | | 81, 44, 143, 73, 97, 169, 235, 11, 128, 248, 168, 7, | 1404 | | 70, 114, 138, 85, 255, 70, 71, 31, 52, 37, 6, 59, | 1405 | | 157, 83, 100, 47, 94, 222, 30, 132, 214, 19, 8, 26, | 1406 | | 250, 92, 34, 208, 81, 40, 91, 214, 59, 148, 59, 86, | 1407 | | 93, 137, 138, 5, 104, 84, 19, 229, 60, 60, 108, 101, | 1408 | | 37, 255, 31, 227, 78, 61, 220, 112, 240, 213, 100, | 1409 | | 80, 253, 164, 139, 161, 46, 16, 78, 157, 235, 159, | 1410 | | 184, 24, 129, 225, 196, 189, 242, 93, 146, 71, 244, | 1411 | | 80, 200, 101, 146, 121, 104, 231, 115, 52, 244, 65, | 1412 | | 79, 117, 167, 80, 225, 57, 84, 110, 58, 138, 115, | 1413 | | 157] | 1414 +-----------+-------------------------------------------------------+ 1416 The RSA private key (n, d) is then passed to the RSA signing 1417 function, which also takes the hash type, SHA-256, and the UTF-8 1418 representation of the JWT Signing Input as inputs. The result of the 1419 signature is a byte array S, which represents a big endian integer. 1420 In this example, S is: 1422 +--------+----------------------------------------------------------+ 1423 | Result | Value | 1424 | Name | | 1425 +--------+----------------------------------------------------------+ 1426 | S | [112, 46, 33, 137, 67, 232, 143, 209, 30, 181, 216, 45, | 1427 | | 191, 120, 69, 243, 65, 6, 174, 27, 129, 255, 247, 115, | 1428 | | 17, 22, 173, 209, 113, 125, 131, 101, 109, 66, 10, 253, | 1429 | | 60, 150, 238, 221, 115, 162, 102, 62, 81, 102, 104, 123, | 1430 | | 0, 11, 135, 34, 110, 1, 135, 237, 16, 115, 249, 69, 229, | 1431 | | 130, 173, 252, 239, 22, 216, 90, 121, 142, 232, 198, | 1432 | | 109, 219, 61, 184, 151, 91, 23, 208, 148, 2, 190, 237, | 1433 | | 213, 217, 217, 112, 7, 16, 141, 178, 129, 96, 213, 248, | 1434 | | 4, 12, 167, 68, 87, 98, 184, 31, 190, 127, 249, 217, 46, | 1435 | | 10, 231, 111, 36, 242, 91, 51, 187, 230, 244, 74, 230, | 1436 | | 30, 177, 4, 10, 203, 32, 4, 77, 62, 249, 18, 142, 212, | 1437 | | 1, 48, 121, 91, 212, 189, 59, 65, 238, 202, 208, 102, | 1438 | | 171, 101, 25, 129, 253, 228, 141, 247, 127, 55, 45, 195, | 1439 | | 139, 159, 175, 221, 59, 239, 177, 139, 93, 163, 204, 60, | 1440 | | 46, 176, 47, 158, 58, 65, 214, 18, 202, 173, 21, 145, | 1441 | | 18, 115, 160, 95, 35, 185, 232, 56, 250, 175, 132, 157, | 1442 | | 105, 132, 41, 239, 90, 30, 136, 121, 130, 54, 195, 212, | 1443 | | 14, 96, 69, 34, 165, 68, 200, 242, 122, 122, 45, 184, 6, | 1444 | | 99, 209, 108, 247, 202, 234, 86, 222, 64, 92, 178, 33, | 1445 | | 90, 69, 178, 194, 85, 102, 181, 90, 193, 167, 72, 160, | 1446 | | 112, 223, 200, 163, 42, 70, 149, 67, 208, 25, 238, 251, | 1447 | | 71] | 1448 +--------+----------------------------------------------------------+ 1450 Base64url encoding the signature produces this value for the JWT 1451 Crypto Segment: 1452 cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZmh7AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjbKBYNX4BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHlb1L07Qe7K0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZESc6BfI7noOPqvhJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AXLIhWkWywlVmtVrBp0igcN_IoypGlUPQGe77Rw 1454 Combining these segments in the order Header.Payload.Signature with 1455 period characters between the segments yields this complete JWT using 1456 the JWT Compact Serialization (with line breaks for display purposes 1457 only): 1458 eyJhbGciOiJSUzI1NiJ9 1459 . 1460 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1461 . 1462 cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZmh7AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjbKBYNX4BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHlb1L07Qe7K0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZESc6BfI7noOPqvhJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AXLIhWkWywlVmtVrBp0igcN_IoypGlUPQGe77Rw 1464 A.2.2. Decoding 1466 Decoding the JWT from this example requires processing the JWT Header 1467 Segment and JWT Payload Segment exactly as done in the first example. 1469 A.2.3. Validating 1471 Since the "alg" parameter in the header is "RS256", we validate the 1472 RSA SHA-256 signature contained in the JWT Crypto Segment. If any of 1473 the validation steps fail, the token MUST be rejected. 1475 First, we validate that the decoded JWT Header Segment string is 1476 legal JSON. 1478 If the payload represents a JWT Claims Object, we also validate that 1479 the decoded JWT Payload Segment string is legal JSON. 1481 Validating the JWT Crypto Segment is a little different from the 1482 previous example. First, we base64url decode the JWT Crypto Segment 1483 to produce a signature S to check. We then pass (n, e), S and the 1484 UTF-8 representation of the JWT Signing Input to an RSA signature 1485 verifier that has been configured to use the SHA-256 hash function. 1487 A.3. JWT using ECDSA P-256 SHA-256 1489 A.3.1. Encoding 1491 The Decoded JWT Payload Segment used in this example is the same as 1492 in the previous examples: 1493 {"iss":"joe", 1494 "exp":1300819380, 1495 "http://example.com/is_root":true} 1497 Since the JWT Payload Segment will therefore be the same, its 1498 computation is not repeated here. However, the Decoded JWT Header 1499 Segment is differs from the previous example because a different 1500 algorithm is being used. The Decoded JWT Header Segment used is: 1501 {"alg":"ES256"} 1503 The following byte array contains the UTF-8 characters for the 1504 Decoded JWT Header Segment: 1506 [123, 34, 97, 108, 103, 34, 58, 34, 69, 83, 50, 53, 54, 34, 125] 1508 Base64url encoding this UTF-8 representation yields this JWT Header 1509 Segment value: 1510 eyJhbGciOiJFUzI1NiJ9 1512 Concatenating the JWT Header Segment, a period character, and the JWT 1513 Payload Segment yields this JWT Signing Input value (with line breaks 1514 for display purposes only): 1516 eyJhbGciOiJFUzI1NiJ9 1517 . 1518 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1520 The UTF-8 representation of the JWT Signing Input is the following 1521 byte array: 1523 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 70, 85, 122, 73, 1524 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 77, 105, 79, 105, 1525 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 74, 108, 101, 72, 1526 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 107, 122, 79, 68, 1527 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 72, 65, 54, 76, 1528 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 109, 78, 118, 1529 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 106, 112, 48, 1530 99, 110, 86, 108, 102, 81] 1532 The ECDSA key consists of a public part, the EC point (x, y), and a 1533 private part d. The values of the ECDSA key used in this example, 1534 presented as the byte arrays representing big endian integers are: 1536 +-----------+-------------------------------------------------------+ 1537 | Parameter | Value | 1538 | Name | | 1539 +-----------+-------------------------------------------------------+ 1540 | x | [127, 205, 206, 39, 112, 246, 196, 93, 65, 131, 203, | 1541 | | 238, 111, 219, 75, 123, 88, 7, 51, 53, 123, 233, 239, | 1542 | | 19, 186, 207, 110, 60, 123, 209, 84, 69] | 1543 | y | [199, 241, 68, 205, 27, 189, 155, 126, 135, 44, 223, | 1544 | | 237, 185, 238, 185, 244, 179, 105, 93, 110, 169, 11, | 1545 | | 36, 173, 138, 70, 35, 40, 133, 136, 229, 173] | 1546 | d | [142, 155, 16, 158, 113, 144, 152, 191, 152, 4, 135, | 1547 | | 223, 31, 93, 119, 233, 203, 41, 96, 110, 190, 210, | 1548 | | 38, 59, 95, 87, 194, 19, 223, 132, 244, 178] | 1549 +-----------+-------------------------------------------------------+ 1551 The ECDSA private part d is then passed to an ECDSA signing function, 1552 which also takes the curve type, P-256, the hash type, SHA-256, and 1553 the UTF-8 representation of the JWT Signing Input as inputs. The 1554 result of the signature is the EC point (R, S), where R and S are 1555 unsigned integers. In this example, the R and S values, given as 1556 byte arrays representing big endian integers are: 1558 +--------+----------------------------------------------------------+ 1559 | Result | Value | 1560 | Name | | 1561 +--------+----------------------------------------------------------+ 1562 | R | [14, 209, 33, 83, 121, 99, 108, 72, 60, 47, 127, 21, 88, | 1563 | | 7, 212, 2, 163, 178, 40, 3, 58, 249, 124, 126, 23, 129, | 1564 | | 154, 195, 22, 158, 166, 101] | 1565 | S | [197, 10, 7, 211, 140, 60, 112, 229, 216, 241, 45, 175, | 1566 | | 8, 74, 84, 128, 166, 101, 144, 197, 242, 147, 80, 154, | 1567 | | 143, 63, 127, 138, 131, 163, 84, 213] | 1568 +--------+----------------------------------------------------------+ 1570 Concatenating the S array to the end of the R array and base64url 1571 encoding the result produces this value for the JWT Crypto Segment: 1572 DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8ISlSApmWQxfKTUJqPP3-Kg6NU1Q 1574 Combining these segments in the order Header.Payload.Signature with 1575 period characters between the segments yields this complete JWT using 1576 the JWT Compact Serialization (with line breaks for display purposes 1577 only): 1578 eyJhbGciOiJFUzI1NiJ9 1579 . 1580 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1581 . 1582 DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8ISlSApmWQxfKTUJqPP3-Kg6NU1Q 1584 A.3.2. Decoding 1586 Decoding the JWT from this example requires processing the JWT Header 1587 Segment and JWT Payload Segment exactly as done in the first example. 1589 A.3.3. Validating 1591 Since the "alg" parameter in the header is "ES256", we validate the 1592 ECDSA P-256 SHA-256 signature contained in the JWT Crypto Segment. 1593 If any of the validation steps fail, the token MUST be rejected. 1595 First, we validate that the decoded JWT Header Segment string is 1596 legal JSON. 1598 If the payload represents a JWT Claims Object, we also validate that 1599 the decoded JWT Payload Segment string is legal JSON. 1601 Validating the JWT Crypto Segment is a little different from the 1602 first example. First, we base64url decode the JWT Crypto Segment as 1603 in the previous examples but we then need to split the 64 member byte 1604 array that must result into two 32 byte arrays, the first R and the 1605 second S. We then pass (x, y), (R, S) and the UTF-8 representation of 1606 the JWT Signing Input to an ECDSA signature verifier that has been 1607 configured to use the P-256 curve with the SHA-256 hash function. 1609 As explained in Section 8.3, the use of the k value in ECDSA means 1610 that we cannot validate the correctness of the signature in the same 1611 way we validated the correctness of the HMAC. Instead, 1612 implementations MUST use an ECDSA validator to validate the 1613 signature. 1615 A.4. JWT using JSON Serialization 1617 Previous example JWTs shown have used the JWT Compact Serialization. 1618 This section contains an example JWT using the JWT JSON 1619 Serialization. This example demonstrates the capability for 1620 conveying multiple signatures for the same JWT. 1622 A.4.1. Encoding 1624 The Decoded JWT Payload Segment used in this example is the same as 1625 in the previous examples: 1626 {"iss":"joe", 1627 "exp":1300819380, 1628 "http://example.com/is_root":true} 1630 Two signatures are used in this JWT: an RSA SHA-256 signature, for 1631 which the header and signature values are the same as in 1632 Appendix A.2, and an ECDSA P-256 SHA-256 signature, for which the 1633 header and signature values are the same as in Appendix A.3. The two 1634 Decoded JWT Header Segments used are: 1635 {"alg":"RS256"} 1637 and: 1638 {"alg":"ES256"} 1640 Since the computations for all JWT Token Segments used in this 1641 example were already presented in previous examples, they are not 1642 repeated here. 1644 A JSON Serialization of this JWT is as follows: 1645 {"header":[ 1646 "eyJhbGciOiJSUzI1NiJ9", 1647 "eyJhbGciOiJFUzI1NiJ9"], 1648 "payload":"eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ", 1649 "signature":[ 1650 "cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZmh7AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjbKBYNX4BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHlb1L07Qe7K0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZESc6BfI7noOPqvhJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AXLIhWkWywlVmtVrBp0igcN_IoypGlUPQGe77Rw", 1651 "DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8ISlSApmWQxfKTUJqPP3-Kg6NU1Q"] 1652 } 1653 A.4.2. Decoding 1655 Decoding the JWT first requires removing the base64url encoding from 1656 the array of JWT Header Segments, the JWT Payload Segment, and the 1657 array of JWT Crypto Segments. We base64url decode the segments per 1658 Section 7 and turn them into the corresponding byte arrays. We 1659 translate the header segment byte arrays containing UTF-8 encoded 1660 characters into Decoded JWT Header Segment strings. Likewise, if the 1661 payload represents a JWT Claims Object, we translate the payload 1662 segment byte array into a Decoded JWT Claims Object string. 1664 A.4.3. Validating 1666 If any of the validation steps fail, the token MUST be rejected. 1668 First, we validate that the header and signature arrays contain the 1669 same number of elements. 1671 Next, we validate that the Decoded JWT Header Segment strings are all 1672 legal JSON. 1674 If the payload represents a JWT Claims Object, we also validate that 1675 the decoded JWT Payload Segment string is legal JSON. 1677 Finally, for each Decoded JWT Header Segment, we validate the 1678 corresponding signature using the algorithm specified in the "alg" 1679 parameter, which must be present. 1681 Appendix B. Notes on implementing base64url encoding without padding 1683 This appendix describes how to implement base64url encoding and 1684 decoding functions without padding based upon standard base64 1685 encoding and decoding functions that do use padding. 1687 To be concrete, example C# code implementing these functions is shown 1688 below. Similar code could be used in other languages. 1690 static string base64urlencode(byte [] arg) 1691 { 1692 string s = Convert.ToBase64String(arg); // Standard base64 encoder 1693 s = s.Split('=')[0]; // Remove any trailing '='s 1694 s = s.Replace('+', '-'); // 62nd char of encoding 1695 s = s.Replace('/', '_'); // 63rd char of encoding 1696 return s; 1697 } 1699 static byte [] base64urldecode(string arg) 1700 { 1701 string s = arg; 1702 s = s.Replace('-', '+'); // 62nd char of encoding 1703 s = s.Replace('_', '/'); // 63rd char of encoding 1704 switch (s.Length % 4) // Pad with trailing '='s 1705 { 1706 case 0: break; // No pad chars in this case 1707 case 2: s += "=="; break; // Two pad chars 1708 case 3: s += "="; break; // One pad char 1709 default: throw new System.Exception( 1710 "Illegal base64url string!"); 1711 } 1712 return Convert.FromBase64String(s); // Standard base64 decoder 1713 } 1715 As per the example code above, the number of '=' padding characters 1716 that needs to be added to the end of a base64url encoded string 1717 without padding to turn it into one with padding is a deterministic 1718 function of the length of the encoded string. Specifically, if the 1719 length mod 4 is 0, no padding is added; if the length mod 4 is 2, two 1720 '=' padding characters are added; if the length mod 4 is 3, one '=' 1721 padding character is added; if the length mod 4 is 1, the input is 1722 malformed. 1724 An example correspondence between unencoded and encoded values 1725 follows. The byte sequence below encodes into the string below, 1726 which when decoded, reproduces the byte sequence. 1727 3 236 255 224 193 1728 A-z_4ME 1730 Appendix C. Relationship of JWTs to SAML Tokens 1732 SAML 2.0 [OASIS.saml-core-2.0-os] provides a standard for creating 1733 tokens with much greater expressivity and more security options than 1734 supported by JWTs. However, the cost of this flexibility and 1735 expressiveness is both size and complexity. In addition, SAML's use 1736 of XML [W3C.CR-xml11-20021015] and XML DSIG [RFC3275] only 1737 contributes to the size of SAML tokens. 1739 JWTs are intended to provide a simple token format that is small 1740 enough to fit into HTTP headers and query arguments in URIs. It does 1741 this by supporting a much simpler token model than SAML and using the 1742 JSON [RFC4627] object encoding syntax. It also supports securing 1743 tokens using Hash-based Message Authentication Codes (HMACs) and 1744 digital signatures using a smaller (and less flexible) format than 1745 XML DSIG. 1747 Therefore, while JWTs can do some of the things SAML tokens do, JWTs 1748 are not intended as a full replacement for SAML tokens, but rather as 1749 a compromise token format to be used when space is at a premium. 1751 Appendix D. Relationship of JWTs to Simple Web Tokens (SWTs) 1753 Both JWTs and Simple Web Tokens SWT [SWT], at their core, enable sets 1754 of claims to be communicated between applications. For SWTs, both 1755 the claim names and claim values are strings. For JWTs, while claim 1756 names are strings, claim values can be any JSON type. Both token 1757 types offer cryptographic protection of their content: SWTs with HMAC 1758 SHA-256 and JWTs with a choice of algorithms, including HMAC SHA-256, 1759 RSA SHA-256, and ECDSA P-256 SHA-256. The signed content of a SWT 1760 must be a set of claims, whereas the payload of a JWT, in general, 1761 can be any base64url encoded content. 1763 Appendix E. Acknowledgements 1765 The authors acknowledge that the design of JWTs was intentionally 1766 influenced by the design and simplicity of Simple Web Tokens [SWT]. 1767 Solutions for signing JSON tokens were also previously explored by 1768 Magic Signatures [MagicSignatures], JSON Simple Sign [JSS], and 1769 Canvas Applications [CanvasApp], all of which influenced this draft. 1771 Appendix F. Document History 1773 -01 1775 o Draft incorporating consensus decisions reached at IIW. 1777 -00 1779 o Public draft published before November 2010 IIW based upon the 1780 JSON token convergence proposal incorporating input from several 1781 implementers of related specifications. 1783 Authors' Addresses 1785 Michael B. Jones 1786 Microsoft 1788 Email: mbj@microsoft.com 1789 URI: http://self-issued.info/ 1791 Dirk Balfanz 1792 Google 1794 Email: balfanz@google.com 1796 John Bradley 1797 independent 1799 Email: ve7jtb@ve7jtb.com 1801 Yaron Y. Goland 1802 Microsoft 1804 Email: yarong@microsoft.com 1806 John Panzer 1807 Google 1809 Email: jpanzer@google.com 1811 Nat Sakimura 1812 Nomura Research Institute 1814 Email: n-sakimura@nri.co.jp 1816 Paul Tarjan 1817 Facebook 1819 Email: paul.tarjan@facebook.com