idnits 2.17.1 draft-jones-json-web-token-09.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 8, 2012) is 4365 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 9, 2012 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 May 8, 2012 18 JSON Web Token (JWT) 19 draft-jones-json-web-token-09 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 HMACed 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 9, 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 . . . . . . . . . . . . . . . . . . . . . . . 5 75 4. JWT Claims . . . . . . . . . . . . . . . . . . . . . . . . . . 6 76 4.1. Reserved Claim Names . . . . . . . . . . . . . . . . . . . 7 77 4.2. Public Claim Names . . . . . . . . . . . . . . . . . . . . 9 78 4.3. Private Claim Names . . . . . . . . . . . . . . . . . . . 9 79 5. JWT Header . . . . . . . . . . . . . . . . . . . . . . . . . . 10 80 6. Plaintext JWTs . . . . . . . . . . . . . . . . . . . . . . . . 11 81 6.1. Example Plaintext JWT . . . . . . . . . . . . . . . . . . 11 82 7. Rules for Creating and Validating a JWT . . . . . . . . . . . 12 83 8. Cryptographic Algorithms . . . . . . . . . . . . . . . . . . . 14 84 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 85 9.1. JSON Web Token Claims Registry . . . . . . . . . . . . . . 15 86 9.2. Sub-Namespace Registration of 87 urn:ietf:params:oauth:token-type:jwt . . . . . . . . . . . 15 88 9.3. Registration of application/jwt MIME Media Type . . . . . 15 89 10. Security Considerations . . . . . . . . . . . . . . . . . . . 17 90 10.1. Unicode Comparison Security Issues . . . . . . . . . . . . 17 91 11. Open Issues and Things To Be Done (TBD) . . . . . . . . . . . 18 92 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 93 12.1. Normative References . . . . . . . . . . . . . . . . . . . 18 94 12.2. Informative References . . . . . . . . . . . . . . . . . . 19 95 Appendix A. Relationship of JWTs to SAML Tokens . . . . . . . . . 20 96 Appendix B. Relationship of JWTs to Simple Web Tokens (SWTs) . . 20 97 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 21 98 Appendix D. Document History . . . . . . . . . . . . . . . . . . 21 99 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 23 101 1. Introduction 103 JSON Web Token (JWT) is a compact token format intended for space 104 constrained environments such as HTTP Authorization headers and URI 105 query parameters. JWTs encode claims to be transmitted as a JSON 106 object (as defined in RFC 4627 [RFC4627]) that is base64url encoded 107 and digitally signed or HMACed and/or encrypted. Signing and HMACing 108 is performed using JSON Web Signature (JWS) [JWS]. Encryption is 109 performed using JSON Web Encryption (JWE) [JWE]. 111 The suggested pronunciation of JWT is the same as the English word 112 "jot". 114 2. Terminology 116 JSON Web Token (JWT) A string consisting of multiple parts, the 117 first being the Encoded JWT Header, plus additional parts 118 depending upon the contents of the header, with the parts being 119 separated by period ('.') characters, and each part containing 120 base64url encoded content. 122 JWT Header A string representing a JSON object that describes the 123 cryptographic operations applied to the JWT. When the JWT is 124 digitally signed or HMACed, the JWT Header is a JWS Header. When 125 the JWT is encrypted, the JWT Header is a JWE Header. 127 Header Parameter Names The names of the members within the JWT 128 Header. 130 Header Parameter Values The values of the members within the JWT 131 Header. 133 JWT Claims Set A string representing a JSON object that contains the 134 claims conveyed by the JWT. When the JWT is digitally signed or 135 HMACed, the bytes of the UTF-8 representation of the JWT Claims 136 Set are base64url encoded to create the Encoded JWS Payload. When 137 the JWT is encrypted, the bytes of the UTF-8 representation of the 138 JWT Claims Set are used as the JWE Plaintext. 140 Claim Names The names of the members of the JSON object represented 141 by the JWT Claims Set. 143 Claim Values The values of the members of the JSON object 144 represented by the JWT Claims Set. 146 Encoded JWT Header Base64url encoding of the bytes of the UTF-8 RFC 147 3629 [RFC3629] representation of the JWT Header. 149 Base64url Encoding For the purposes of this specification, this term 150 always refers to the URL- and filename-safe Base64 encoding 151 described in RFC 4648 [RFC4648], Section 5, with the (non URL- 152 safe) '=' padding characters omitted, as permitted by Section 3.2. 153 (See Appendix C of [JWS] for notes on implementing base64url 154 encoding without padding.) 156 3. JSON Web Token (JWT) Overview 158 JWTs represent a set of claims as a JSON object that is base64url 159 encoded and digitally signed or HMACed and/or encrypted. The JWT 160 Claims Set represents this JSON object. As per RFC 4627 [RFC4627] 161 Section 2.2, the JSON object consists of zero or more name/value 162 pairs (or members), where the names are strings and the values are 163 arbitrary JSON values. These members are the claims represented by 164 the JWT. 166 The member names within the JWT Claims Set are referred to as Claim 167 Names. The corresponding values are referred to as Claim Values. 169 The bytes of the UTF-8 representation of the JWT Claims Set are 170 digitally signed or HMACed in the manner described in JSON Web 171 Signature (JWS) [JWS] and/or encrypted in the manner described in 172 JSON Web Encryption (JWE) [JWE]. 174 The contents of the JWT Header describe the cryptographic operations 175 applied to the JWT Claims Set. If the JWT Header is a JWS Header, the 176 claims are digitally signed or HMACed. If the JWT Header is a JWE 177 Header, the claims are encrypted. 179 A JWT is represented as a JWS or JWE. The number of parts is 180 dependent upon the representation of the resulting JWS or JWE. 182 3.1. Example JWT 184 The following example JWT Header declares that the encoded object is 185 a JSON Web Token (JWT) and the JWT is HMACed using the HMAC SHA-256 186 algorithm: 187 {"typ":"JWT", 188 "alg":"HS256"} 190 Base64url encoding the bytes of the UTF-8 representation of the JWT 191 Header yields this Encoded JWS Header value, which is used as the 192 Encoded JWT Header: 194 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 196 The following is an example of a JWT Claims Set: 197 {"iss":"joe", 198 "exp":1300819380, 199 "http://example.com/is_root":true} 201 Base64url encoding the bytes of the UTF-8 representation of the JSON 202 Claims Set yields this Encoded JWS Payload (with line breaks for 203 display purposes only): 204 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly 205 9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ 207 Signing the Encoded JWS Header and Encoded JWS Payload with the HMAC 208 SHA-256 algorithm and base64url encoding the signature in the manner 209 specified in [JWS], yields this Encoded JWS Signature: 210 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 212 Concatenating these parts in this order with period characters 213 between the parts yields this complete JWT (with line breaks for 214 display purposes only): 215 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 216 . 217 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 218 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 219 . 220 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 222 This computation is illustrated in more detail in [JWS], Appendix 223 A.1. 225 4. JWT Claims 227 The JWT Claims Set represents a JSON object whose members are the 228 claims conveyed by the JWT. The Claim Names within this object MUST 229 be unique. Note however, that the set of claims that a JWT must 230 contain to be considered valid is context-dependent and is outside 231 the scope of this specification. When used in a security-related 232 context, implementations MUST understand and support all of the 233 claims present; otherwise, the JWT MUST be rejected for processing. 235 There are three classes of JWT Claim Names: Reserved Claim Names, 236 Public Claim Names, and Private Claim Names. 238 4.1. Reserved Claim Names 240 The following claim names are reserved. None of the claims defined 241 in the table below are intended to be mandatory, but rather, provide 242 a starting point for a set of useful, interoperable claims. All the 243 names are short because a core goal of JWTs is for the tokens to be 244 compact. 246 +-------+--------+-------------+------------------------------------+ 247 | Claim | JSON | Claim | Claim Semantics | 248 | Name | Value | Syntax | | 249 | | Type | | | 250 +-------+--------+-------------+------------------------------------+ 251 | exp | number | IntDate | The "exp" (expiration time) claim | 252 | | | | identifies the expiration time on | 253 | | | | or after which the token MUST NOT | 254 | | | | be accepted for processing. The | 255 | | | | processing of the "exp" claim | 256 | | | | requires that the current | 257 | | | | date/time MUST be before the | 258 | | | | expiration date/time listed in the | 259 | | | | "exp" claim. Implementers MAY | 260 | | | | provide for some small leeway, | 261 | | | | usually no more than a few | 262 | | | | minutes, to account for clock | 263 | | | | skew. This claim is OPTIONAL. | 264 | nbf | number | IntDate | The "nbf" (not before) claim | 265 | | | | identifies the time before which | 266 | | | | the token MUST NOT be accepted for | 267 | | | | processing. The processing of the | 268 | | | | "nbf" claim requires that the | 269 | | | | current date/time MUST be after or | 270 | | | | equal to the not-before date/time | 271 | | | | listed in the "nbf" claim. | 272 | | | | Implementers MAY provide for some | 273 | | | | small leeway, usually no more than | 274 | | | | a few minutes, to account for | 275 | | | | clock skew. This claim is | 276 | | | | OPTIONAL. | 277 | iat | number | IntDate | The "iat" (issued at) claim | 278 | | | | identifies the time at which the | 279 | | | | JWT was issued. This claim can be | 280 | | | | used to determine the age of the | 281 | | | | token. This claim is OPTIONAL. | 282 | iss | string | StringOrURI | The "iss" (issuer) claim | 283 | | | | identifies the principal that | 284 | | | | issued the JWT. The processing of | 285 | | | | this claim is generally | 286 | | | | application specific. The "iss" | 287 | | | | value is case sensitive. This | 288 | | | | claim is OPTIONAL. | 289 | aud | string | StringOrURI | The "aud" (audience) claim | 290 | | | | identifies the audience that the | 291 | | | | JWT is intended for. The | 292 | | | | principal intended to process the | 293 | | | | JWT MUST be identified with the | 294 | | | | value of the audience claim. If | 295 | | | | the principal processing the claim | 296 | | | | does not identify itself with the | 297 | | | | identifier in the "aud" claim | 298 | | | | value then the JWT MUST be | 299 | | | | rejected. The interpretation of | 300 | | | | the audience value is generally | 301 | | | | application specific. The "aud" | 302 | | | | value is case sensitive. This | 303 | | | | claim is OPTIONAL. | 304 | prn | string | StringOrURI | The "prn" (principal) claim | 305 | | | | identifies the subject of the JWT. | 306 | | | | The processing of this claim is | 307 | | | | generally application specific. | 308 | | | | The "prn" value is case sensitive. | 309 | | | | This claim is OPTIONAL. | 310 | jti | string | String | The "jti" (JWT ID) claim provides | 311 | | | | a unique identifier for the JWT. | 312 | | | | The identifier value MUST be | 313 | | | | assigned in a manner that ensures | 314 | | | | that there is a negligible | 315 | | | | probability that the same value | 316 | | | | will be accidentally assigned to a | 317 | | | | different data object. The "jti" | 318 | | | | claim can be used to prevent the | 319 | | | | JWT from being replayed. The | 320 | | | | "jti" value is case sensitive. | 321 | | | | This claim is OPTIONAL. | 322 | typ | string | String | The "typ" (type) claim is used to | 323 | | | | declare a type for the contents of | 324 | | | | this JWT Claims Set. The "typ" | 325 | | | | value is case sensitive. This | 326 | | | | claim is OPTIONAL. | 327 +-------+--------+-------------+------------------------------------+ 329 Table 1: Reserved Claim Definitions 331 Additional reserved claim names MAY be defined via the IANA JSON Web 332 Token Claims Registry Section 9.1. The syntax values used above are 333 defined as follows: 335 +-------------+-----------------------------------------------------+ 336 | Syntax Name | Syntax Definition | 337 +-------------+-----------------------------------------------------+ 338 | IntDate | The number of seconds from 1970-01-01T0:0:0Z as | 339 | | measured in UTC until the desired date/time. See | 340 | | RFC 3339 [RFC3339] for details regarding date/times | 341 | | in general and UTC in particular. | 342 | String | Any string value MAY be used. | 343 | StringOrURI | Any string value MAY be used but a value containing | 344 | | a ":" character MUST be a URI as defined in RFC | 345 | | 3986 [RFC3986]. | 346 +-------------+-----------------------------------------------------+ 348 Table 2: Claim Syntax Definitions 350 4.2. Public Claim Names 352 Claim names can be defined at will by those using JWTs. However, in 353 order to prevent collisions, any new claim name SHOULD either be 354 defined in the IANA JSON Web Token Claims Registry Section 9.1 or be 355 defined as a URI that contains a collision resistant namespace. 356 Examples of collision resistant namespaces include: 358 o Domain Names, 360 o Object Identifiers (OIDs) as defined in the ITU-T X.660 and X.670 361 Recommendation series, or 363 o Universally Unique IDentifier (UUID) as defined in RFC 4122 364 [RFC4122]. 366 In each case, the definer of the name or value needs to take 367 reasonable precautions to make sure they are in control of the part 368 of the namespace they use to define the claim name. 370 4.3. Private Claim Names 372 A producer and consumer of a JWT may agree to any claim name that is 373 not a Reserved Name Section 4.1 or a Public Name Section 4.2. Unlike 374 Public Names, these private names are subject to collision and should 375 be used with caution. 377 5. JWT Header 379 The members of the JSON object represented by the JWT Header describe 380 the cryptographic operations applied to the JWT and optionally, 381 additional properties of the JWT. The member names within the JWT 382 Header are referred to as Header Parameter Names. These names MUST 383 be unique. The corresponding values are referred to as Header 384 Parameter Values. 386 Implementations MUST understand the entire contents of the header; 387 otherwise, the JWT MUST be rejected for processing. 389 There are two ways of distinguishing whether the JWT is a JWS or JWE. 390 The first is by examining the "alg" (algorithm) header value. If the 391 value represents a signature algorithm, the JWT is a JWS; if it 392 represents an encryption algorithm, the JWT is a JWE. A second 393 method is determining whether an "enc" (encryption method) member 394 exists. If the "enc" member exists, the JWT is a JWE; otherwise, the 395 JWT is a JWS. Both methods will yield the same result. 397 JWS Header Parameters are defined by [JWS]. JWE Header Parameters 398 are defined by [JWE]. This specification further specifies the use 399 of the following header parameters in both the cases where the JWT is 400 a JWS and where it is a JWE. 402 +----------+-------+----------+-------------------------------------+ 403 | Header | JSON | Header | Header Parameter Semantics | 404 | Paramete | Value | Paramete | | 405 | rName | Type | rSyntax | | 406 +----------+-------+----------+-------------------------------------+ 407 | typ | strin | String | The "typ" (type) header parameter | 408 | | g | | is used to declare structural | 409 | | | | information about the JWT. In the | 410 | | | | normal case where nested signing or | 411 | | | | encryption operations are not | 412 | | | | employed, the use of this header | 413 | | | | parameter is OPTIONAL, and if | 414 | | | | present, it is RECOMMENDED that its | 415 | | | | value be either "JWT" or | 416 | | | | "urn:ietf:params:oauth:token-type:j | 417 | | | | wt". In the case that nested | 418 | | | | signing or encryption steps are | 419 | | | | employed, the use of this header | 420 | | | | parameter is REQUIRED; in this | 421 | | | | case, the value MUST either be | 422 | | | | "JWS", to indicate that a nested | 423 | | | | digitally signed or HMACed JWT is | 424 | | | | carried in this JWT or "JWE", to | 425 | | | | indicate that a nested encrypted | 426 | | | | JWT is carried in this JWT. | 427 +----------+-------+----------+-------------------------------------+ 429 Table 3: Reserved Header Parameter Usage 431 6. Plaintext JWTs 433 To support use cases where the JWT content is secured by a means 434 other than a signature and/or encryption contained within the token 435 (such as a signature on a data structure containing the token), JWTs 436 MAY also be created without a signature or encryption. A plaintext 437 JWT is a JWS using the "none" JWS "alg" header parameter value 438 defined in JSON Web Algorithms (JWA) [JWA]; it is a JWS with an empty 439 JWS Signature value. 441 6.1. Example Plaintext JWT 443 The following example JWT Header declares that the encoded object is 444 a Plaintext JWT: 445 {"alg":"none"} 447 Base64url encoding the bytes of the UTF-8 representation of the JWT 448 Header yields this Encoded JWT Header: 450 eyJhbGciOiJub25lIn0 452 The following is an example of a JWT Claims Set: 453 {"iss":"joe", 454 "exp":1300819380, 455 "http://example.com/is_root":true} 457 Base64url encoding the bytes of the UTF-8 representation of the JSON 458 Claims Set yields this Encoded JWS Payload (with line breaks for 459 display purposes only): 460 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 461 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 463 The Encoded JWS Signature is the empty string. 465 Concatenating these parts in this order with period characters 466 between the parts yields this complete JWT (with line breaks for 467 display purposes only): 468 eyJhbGciOiJub25lIn0 469 . 470 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 471 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 472 . 474 7. Rules for Creating and Validating a JWT 476 To create a JWT, one MUST perform these steps. The order of the 477 steps is not significant in cases where there are no dependencies 478 between the inputs and outputs of the steps. 480 1. Create a JWT Claims Set containing the desired claims. Note that 481 white space is explicitly allowed in the representation and no 482 canonicalization is performed before encoding. 484 2. Let the Message be the bytes of the UTF-8 representation of the 485 JWT Claims Set. 487 3. Create a JWT Header containing the desired set of header 488 parameters. The JWT MUST conform to either the [JWS] or [JWE] 489 specifications. Note that white space is explicitly allowed in 490 the representation and no canonicalization is performed before 491 encoding. 493 4. Base64url encode the bytes of the UTF-8 representation of the JWT 494 Header. Let this be the Encoded JWT Header. 496 5. Depending upon whether the JWT is a JWS or JWE, there are two 497 cases: 499 * If the JWT is a JWS, create a JWS using the JWT Header as the 500 JWS Header and the Message as the JWS Payload; all steps 501 specified in [JWS] for creating a JWS MUST be followed. 503 * Else, if the JWT is a JWE, create a JWE using the JWT Header 504 as the JWE Header and the Message as the JWE Plaintext; all 505 steps specified in [JWE] for creating a JWE MUST be followed. 507 6. If a nested signing or encryption operation will be performed, 508 let the Message be the JWS or JWE, and return to Step 3, using a 509 "typ" value of either "JWS" or "JWE" respectively in the new JWT 510 Header created in that step. 512 7. Otherwise, let the resulting JWT be the JWS or JWE. 514 When validating a JWT the following steps MUST be taken. The order 515 of the steps is not significant in cases where there are no 516 dependencies between the inputs and outputs of the steps. If any of 517 the listed steps fails then the token MUST be rejected for 518 processing. 520 1. The JWT MUST contain at least one period character. 522 2. Let the Encoded JWT Header be the portion of the JWT before the 523 first period character. 525 3. The Encoded JWT Header MUST be successfully base64url decoded 526 following the restriction given in this specification that no 527 padding characters have been used. 529 4. The JWT Header MUST be completely valid JSON syntax conforming 530 to RFC 4627 [RFC4627]. 532 5. The JWT Header MUST be validated to only include parameters and 533 values whose syntax and semantics are both understood and 534 supported. 536 6. Determine whether the JWT is a JWS or a JWE by examining the 537 "alg" (algorithm) header value and optionally, the "enc" 538 (encryption method) header value, if present. 540 7. Depending upon whether the JWT is a JWS or JWE, there are two 541 cases: 543 * If the JWT is a JWS, all steps specified in [JWS] for 544 validating a JWS MUST be followed. Let the Message be the 545 result of base64url decoding the JWS Payload. 547 * Else, if the JWT is a JWE, all steps specified in [JWE] for 548 validating a JWE MUST be followed. Let the Message be the 549 JWE Plaintext. 551 8. If the JWT Header contains a "typ" value of either "JWS" or 552 "JWE", then the Message contains a JWT that was the subject of 553 nested signing or encryption operations, respectively. In this 554 case, return to Step 1, using the Message as the JWT. 556 9. Otherwise, let the JWT Claims Set be the Message. 558 10. The JWT Claims Set MUST be completely valid JSON syntax 559 conforming to RFC 4627 [RFC4627]. 561 11. When used in a security-related context, the JWT Claims Set MUST 562 be validated to only include claims whose syntax and semantics 563 are both understood and supported. 565 Processing a JWT inevitably requires comparing known strings to 566 values in the token. For example, in checking what the algorithm is, 567 the Unicode string encoding "alg" will be checked against the member 568 names in the JWT Header to see if there is a matching header 569 parameter name. A similar process occurs when determining if the 570 value of the "alg" header parameter represents a supported algorithm. 572 Comparisons between JSON strings and other Unicode strings MUST be 573 performed as specified below: 575 1. Remove any JSON applied escaping to produce an array of Unicode 576 code points. 578 2. Unicode Normalization [USA15] MUST NOT be applied at any point to 579 either the JSON string or to the string it is to be compared 580 against. 582 3. Comparisons between the two strings MUST be performed as a 583 Unicode code point to code point equality comparison. 585 8. Cryptographic Algorithms 587 JWTs use JSON Web Signature (JWS) [JWS] and JSON Web Encryption (JWE) 588 [JWE] to sign and/or encrypt the contents of the JWT. 590 Of the JWS signing algorithms, only HMAC SHA-256 and "none" MUST be 591 implemented by conforming JWT implementations. It is RECOMMENDED 592 that implementations also support the RSA SHA-256 and ECDSA P-256 593 SHA-256 algorithms. Support for other algorithms and key sizes is 594 OPTIONAL. 596 If an implementation provides encryption capabilities, of the JWE 597 encryption algorithms, only RSA-PKCS1-1.5 with 2048 bit keys, AES- 598 128-CBC, and AES-256-CBC MUST be implemented by conforming 599 implementations. It is RECOMMENDED that implementations also support 600 ECDH-ES with 256 bit keys, AES-128-GCM, and AES-256-GCM. Support for 601 other algorithms and key sizes is OPTIONAL. 603 9. IANA Considerations 605 9.1. JSON Web Token Claims Registry 607 The IANA registry entitled "JSON Web Token Claims" for reserved JWT 608 claim names is defined in Section 4.1. Inclusion in the registry is 609 RFC Required in the RFC 5226 [RFC5226] sense for reserved JWT claim 610 names that are intended to be interoperable between implementations. 611 The registry will just record the reserved claim name and a pointer 612 to the RFC that defines it. This specification defines inclusion of 613 the claim names defined in Section 4.1. 615 9.2. Sub-Namespace Registration of urn:ietf:params:oauth:token-type:jwt 617 This is a request to IANA to register the value "token-type:jwt" in 618 the registry urn:ietf:params:oauth established in An IETF URN Sub- 619 Namespace for OAuth [I-D.ietf-oauth-urn-sub-ns]. 621 o URN: urn:ietf:params:oauth:token-type:jwt 623 o Common Name: JSON Web Token (JWT) Token Type 625 o Change controller: IETF 627 o Description: [[this document]] 629 9.3. Registration of application/jwt MIME Media Type 631 This specification registers the "application/jwt" MIME Media Type. 633 Type name: 634 application 636 Subtype name: 637 jwt 639 Required parameters: 640 n/a 642 Optional parameters: 643 n/a 645 Encoding considerations: 646 n/a 648 Security considerations: 649 See the Security Considerations section of this document 651 Interoperability considerations: 652 n/a 654 Published specification: 655 [[ this document ]] 657 Applications that use this media type: 658 OpenID Connect, Mozilla Browser ID, Salesforce, Google, numerous 659 others 661 Additional information: 662 Magic number(s): n/a 663 File extension(s): n/a 664 Macintosh file type code(s): n/a 666 Person & email address to contact for further information: 667 Michael B. Jones 668 mbj@microsoft.com 670 Intended usage: 671 COMMON 673 Restrictions on usage: 674 none 676 Author: 677 Michael B. Jones 678 mbj@microsoft.com 680 Change controller: 681 Michael B. Jones 682 mbj@microsoft.com 684 10. Security Considerations 686 TBD: Lots of work to do here. We need to remember to look into any 687 issues relating to security and JSON parsing. One wonders just how 688 secure most JSON parsing libraries are. Were they ever hardened for 689 security scenarios? If not, what kind of holes does that open up? 690 Also, we need to walk through the JSON standard and see what kind of 691 issues we have especially around comparison of names. For instance, 692 comparisons of claim names and other parameters must occur after they 693 are unescaped. Need to also put in text about: Importance of keeping 694 secrets secret. Rotating keys. Strengths and weaknesses of the 695 different algorithms. 697 TBD: Need to put in text about why strict JSON validation is 698 necessary. Basically, that if malformed JSON is received then the 699 intent of the sender is impossible to reliably discern. One example 700 of malformed JSON that MUST be rejected is an object in which the 701 same member name occurs multiple times. While in non-security 702 contexts it's o.k. to be generous in what one accepts, in security 703 contexts this can lead to serious security holes. For example, 704 malformed JSON might indicate that someone has managed to find a 705 security hole in the issuer's code and is leveraging it to get the 706 issuer to issue "bad" tokens whose content the attacker can control. 708 TBD: Write about the need to secure the token content if a signature 709 is not contained in the JWT itself. 711 10.1. Unicode Comparison Security Issues 713 Claim names in JWTs are Unicode strings. For security reasons, the 714 representations of these names must be compared verbatim after 715 performing any escape processing (as per RFC 4627 [RFC4627], Section 716 2.5). 718 This means, for instance, that these JSON strings must compare as 719 being equal ("JWT", "\u004aWT"), whereas these must all compare as 720 being not equal to the first set or to each other ("jwt", "Jwt", 721 "JW\u0074"). 723 JSON strings MAY contain characters outside the Unicode Basic 724 Multilingual Plane. For instance, the G clef character (U+1D11E) may 725 be represented in a JSON string as "\uD834\uDD1E". Ideally, JWT 726 implementations SHOULD ensure that characters outside the Basic 727 Multilingual Plane are preserved and compared correctly; 728 alternatively, if this is not possible due to these characters 729 exercising limitations present in the underlying JSON implementation, 730 then input containing them MUST be rejected. 732 11. Open Issues and Things To Be Done (TBD) 734 The following items remain to be done in this draft: 736 o EDITORIAL: Give each claim name and header parameter definition 737 its own section. This will let them appear in the index, will 738 give space for examples when needed, and will get rid of the way- 739 too-cramped tables. 741 o Add normative text that requires rejecting headers and Claim Sets 742 in which member names occur multiple times, as apparently this is 743 legal JSON. 745 o Provide an example of an encrypted JWT. 747 o Clarify the intended use of the "typ" Header Parameter across the 748 JWS, JWE, and JWT specifications. Decide whether a registry of 749 "typ" values is appropriate. 751 o EDITORIAL: Think about how to best describe the concept currently 752 described as "the bytes of the UTF-8 representation of". Possible 753 terms to use instead of "bytes of" include "byte sequence", "octet 754 series", and "octet sequence". Also consider whether we want to 755 add an overall clarifying statement somewhere in each spec 756 something like "every place we say 'the UTF-8 representation of 757 X', we mean 'the bytes of the UTF-8 representation of X'". That 758 would potentially allow us to omit the "the bytes of" part 759 everywhere else. 761 o Finish the Security Considerations section. 763 o Possibly write a companion specification that uses the JWS and JWE 764 JSON Serializations. 766 12. References 768 12.1. Normative References 770 [I-D.ietf-oauth-urn-sub-ns] 771 Tschofenig, H., "An IETF URN Sub-Namespace for OAuth", 772 draft-ietf-oauth-urn-sub-ns-02 (work in progress), 773 January 2012. 775 [JWA] Jones, M., "JSON Web Algorithms (JWA)", March 2012. 777 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 778 Encryption (JWE)", March 2012. 780 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 781 Signature (JWS)", March 2012. 783 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 784 Requirement Levels", BCP 14, RFC 2119, March 1997. 786 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 787 Internet: Timestamps", RFC 3339, July 2002. 789 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 790 10646", STD 63, RFC 3629, November 2003. 792 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 793 Resource Identifier (URI): Generic Syntax", STD 66, 794 RFC 3986, January 2005. 796 [RFC4627] Crockford, D., "The application/json Media Type for 797 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 799 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 800 Encodings", RFC 4648, October 2006. 802 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 803 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 804 May 2008. 806 [USA15] Davis, M., Whistler, K., and M. Duerst, "Unicode 807 Normalization Forms", Unicode Standard Annex 15, 09 2009. 809 12.2. Informative References 811 [CanvasApp] 812 Facebook, "Canvas Applications", 2010. 814 [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", 815 September 2010. 817 [MagicSignatures] 818 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 819 Signatures", January 2011. 821 [OASIS.saml-core-2.0-os] 822 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 823 "Assertions and Protocol for the OASIS Security Assertion 824 Markup Language (SAML) V2.0", OASIS Standard saml-core- 825 2.0-os, March 2005. 827 [RFC3275] Eastlake, D., Reagle, J., and D. Solo, "(Extensible Markup 828 Language) XML-Signature Syntax and Processing", RFC 3275, 829 March 2002. 831 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 832 Unique IDentifier (UUID) URN Namespace", RFC 4122, 833 July 2005. 835 [SWT] Hardt, D. and Y. Goland, "Simple Web Token (SWT)", 836 Version 0.9.5.1, November 2009. 838 [W3C.CR-xml11-20021015] 839 Cowan, J., "Extensible Markup Language (XML) 1.1", W3C 840 CR CR-xml11-20021015, October 2002. 842 Appendix A. Relationship of JWTs to SAML Tokens 844 SAML 2.0 [OASIS.saml-core-2.0-os] provides a standard for creating 845 tokens with much greater expressivity and more security options than 846 supported by JWTs. However, the cost of this flexibility and 847 expressiveness is both size and complexity. In addition, SAML's use 848 of XML [W3C.CR-xml11-20021015] and XML DSIG [RFC3275] only 849 contributes to the size of SAML tokens. 851 JWTs are intended to provide a simple token format that is small 852 enough to fit into HTTP headers and query arguments in URIs. It does 853 this by supporting a much simpler token model than SAML and using the 854 JSON [RFC4627] object encoding syntax. It also supports securing 855 tokens using Hash-based Message Authentication Codes (HMACs) and 856 digital signatures using a smaller (and less flexible) format than 857 XML DSIG. 859 Therefore, while JWTs can do some of the things SAML tokens do, JWTs 860 are not intended as a full replacement for SAML tokens, but rather as 861 a compromise token format to be used when space is at a premium. 863 Appendix B. Relationship of JWTs to Simple Web Tokens (SWTs) 865 Both JWTs and Simple Web Tokens SWT [SWT], at their core, enable sets 866 of claims to be communicated between applications. For SWTs, both 867 the claim names and claim values are strings. For JWTs, while claim 868 names are strings, claim values can be any JSON type. Both token 869 types offer cryptographic protection of their content: SWTs with HMAC 870 SHA-256 and JWTs with a choice of algorithms, including HMAC SHA-256, 871 RSA SHA-256, and ECDSA P-256 SHA-256. 873 Appendix C. Acknowledgements 875 The authors acknowledge that the design of JWTs was intentionally 876 influenced by the design and simplicity of Simple Web Tokens [SWT] 877 and ideas for JSON tokens that Dick Hardt discussed within the OpenID 878 community. 880 Solutions for signing JSON content were previously explored by Magic 881 Signatures [MagicSignatures], JSON Simple Sign [JSS], and Canvas 882 Applications [CanvasApp], all of which influenced this draft. 884 Appendix D. Document History 886 -09 888 o Changed "http://openid.net/specs/jwt/1.0" to 889 "urn:ietf:params:oauth:token-type:jwt" in preparation for OAuth WG 890 draft. 892 -08 894 o Removed language that required that a JWT must have three parts. 895 Now the number of parts is explicitly dependent upon the 896 representation of the underlying JWS or JWE. 898 o Moved the "alg":"none" definition to the JWS spec. 900 o Registered the "application/jwt" MIME Media Type. 902 o Clarified that the order of the creation and validation steps is 903 not significant in cases where there are no dependencies between 904 the inputs and outputs of the steps. 906 o Corrected the Magic Signatures and Simple Web Token (SWT) 907 references. 909 -07 911 o Defined the "prn" (principal) claim to identify the subject of the 912 JWT. 914 o Defined the "jti" (JWT ID) claim to enable replay protection. 916 o Use the term "JWT Claims Set" rather than "JWT Claims Object" 917 since this is actually a string representing a JSON object and not 918 the JSON object itself. 920 o Moved "MUST" requirements from the Overview to later in the spec. 922 o Respect line length restrictions in examples. 924 o Applied other editorial improvements. 926 -06 928 o Reference and use content from [JWS] and [JWE], rather than 929 repeating it here. 931 o Simplified terminology to better match JWE, where the terms "JWT 932 Header" and "Encoded JWT Header" are now used, for instance, 933 rather than the previous terms "Decoded JWT Header Segment" and 934 "JWT Header Segment". Also changed to "Plaintext JWT" from 935 "Unsigned JWT". 937 o Describe how to perform nested encryption and signing operations. 939 o Changed "integer" to "number", since that is the correct JSON 940 type. 942 o Changed StringAndURI to StringOrURI. 944 -05 946 o Added the "nbf" (not before) claim and clarified the meaning of 947 the "iat" (issued at) claim. 949 -04 951 o Correct typo found by John Bradley: "the JWT Claim Segment is the 952 empty string" -> "the JWT Crypto Segment is the empty string". 954 -03 956 o Added "http://openid.net/specs/jwt/1.0" as a token type identifier 957 URI for JWTs. 959 o Added "iat" (issued at) claim. 961 o Changed RSA SHA-256 from MUST be supported to RECOMMENDED that it 962 be supported. Rationale: Several people have objected to the 963 requirement for implementing RSA SHA-256, some because they will 964 only be using HMACs and symmetric keys, and others because they 965 only want to use ECDSA when using asymmetric keys, either for 966 security or key length reasons, or both. 968 o Defined "alg" value "none" to represent unsigned JWTs. 970 -02 972 o Split signature specification out into separate 973 draft-jones-json-web-signature-00. This split introduced no 974 semantic changes. 976 o The JWT Compact Serialization is now the only token serialization 977 format specified in this draft. The JWT JSON Serialization can 978 continue to be defined in a companion specification. 980 -01 982 o Draft incorporating consensus decisions reached at IIW. 984 -00 986 o Public draft published before November 2010 IIW based upon the 987 JSON token convergence proposal incorporating input from several 988 implementers of related specifications. 990 Authors' Addresses 992 Michael B. Jones 993 Microsoft 995 Email: mbj@microsoft.com 996 URI: http://self-issued.info/ 998 Dirk Balfanz 999 Google 1001 Email: balfanz@google.com 1003 John Bradley 1004 independent 1006 Email: ve7jtb@ve7jtb.com 1007 Yaron Y. Goland 1008 Microsoft 1010 Email: yarong@microsoft.com 1012 John Panzer 1013 Google 1015 Email: jpanzer@google.com 1017 Nat Sakimura 1018 Nomura Research Institute 1020 Email: n-sakimura@nri.co.jp 1022 Paul Tarjan 1023 Facebook 1025 Email: pt@fb.com