idnits 2.17.1 draft-ietf-oauth-json-web-token-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (May 22, 2012) is 4356 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 OAuth Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track J. Bradley 5 Expires: November 23, 2012 Ping Identity 6 N. Sakimura 7 NRI 8 May 22, 2012 10 JSON Web Token (JWT) 11 draft-ietf-oauth-json-web-token-00 13 Abstract 15 JSON Web Token (JWT) is a means of representing claims to be 16 transferred between two parties. The claims in a JWT are encoded as 17 a JSON object that is digitally signed or MACed using JSON Web 18 Signature (JWS) and/or encrypted using JSON Web Encryption (JWE). 20 The suggested pronunciation of JWT is the same as the English word 21 "jot". 23 Requirements Language 25 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 26 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 27 document are to be interpreted as described in RFC 2119 [RFC2119]. 29 Status of this Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at http://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on November 23, 2012. 46 Copyright Notice 48 Copyright (c) 2012 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 65 3. JSON Web Token (JWT) Overview . . . . . . . . . . . . . . . . 5 66 3.1. Example JWT . . . . . . . . . . . . . . . . . . . . . . . 6 67 4. JWT Claims . . . . . . . . . . . . . . . . . . . . . . . . . . 6 68 4.1. Reserved Claim Names . . . . . . . . . . . . . . . . . . . 7 69 4.1.1. "exp" (Expiration Time) Claim . . . . . . . . . . . . 7 70 4.1.2. "nbf" (Not Before) Claim . . . . . . . . . . . . . . . 7 71 4.1.3. "iat" (Issued At) Claim . . . . . . . . . . . . . . . 7 72 4.1.4. "iss" (Issuer) Claim . . . . . . . . . . . . . . . . . 8 73 4.1.5. "aud" (Audience) Claim . . . . . . . . . . . . . . . . 8 74 4.1.6. "prn" (Principal) Claim . . . . . . . . . . . . . . . 8 75 4.1.7. "jti" (JWT ID) Claim . . . . . . . . . . . . . . . . . 8 76 4.1.8. "typ" (Type) Claim . . . . . . . . . . . . . . . . . . 8 77 4.2. Public Claim Names . . . . . . . . . . . . . . . . . . . . 8 78 4.3. Private Claim Names . . . . . . . . . . . . . . . . . . . 9 79 5. JWT Header . . . . . . . . . . . . . . . . . . . . . . . . . . 9 80 5.1. "typ" (Type) Header Parameter . . . . . . . . . . . . . . 10 81 6. Plaintext JWTs . . . . . . . . . . . . . . . . . . . . . . . . 10 82 6.1. Example Plaintext JWT . . . . . . . . . . . . . . . . . . 10 83 7. Rules for Creating and Validating a JWT . . . . . . . . . . . 11 84 8. Cryptographic Algorithms . . . . . . . . . . . . . . . . . . . 13 85 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 86 9.1. JSON Web Token Claims Registry . . . . . . . . . . . . . . 14 87 9.2. Sub-Namespace Registration of 88 urn:ietf:params:oauth:token-type:jwt . . . . . . . . . . . 14 89 9.3. Registration of application/jwt MIME Media Type . . . . . 14 90 9.4. Registration of "JWT" Type Value . . . . . . . . . . . . . 15 91 10. Security Considerations . . . . . . . . . . . . . . . . . . . 16 92 11. Open Issues and Things To Be Done (TBD) . . . . . . . . . . . 16 93 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16 94 12.1. Normative References . . . . . . . . . . . . . . . . . . . 16 95 12.2. Informative References . . . . . . . . . . . . . . . . . . 17 96 Appendix A. Relationship of JWTs to SAML Tokens . . . . . . . . . 18 97 Appendix B. Relationship of JWTs to Simple Web Tokens (SWTs) . . 18 98 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 18 99 Appendix D. Document History . . . . . . . . . . . . . . . . . . 19 100 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 19 102 1. Introduction 104 JSON Web Token (JWT) is a compact token format intended for space 105 constrained environments such as HTTP Authorization headers and URI 106 query parameters. JWTs encode claims to be transmitted as a JSON 107 object (as defined in RFC 4627 [RFC4627]) that is base64url encoded 108 and digitally signed or MACed and/or encrypted. Signing and MACing 109 is performed using JSON Web Signature (JWS) [JWS]. Encryption is 110 performed using JSON Web Encryption (JWE) [JWE]. 112 The suggested pronunciation of JWT is the same as the English word 113 "jot". 115 2. Terminology 117 JSON Web Token (JWT) A string consisting of multiple parts, the 118 first being the Encoded JWT Header, plus additional parts 119 depending upon the contents of the header, with the parts being 120 separated by period ('.') characters, and each part containing 121 base64url encoded content. 123 JWT Header A string representing a JSON object that describes the 124 cryptographic operations applied to the JWT. When the JWT is 125 digitally signed or MACed, the JWT Header is a JWS Header. When 126 the JWT is encrypted, the JWT Header is a JWE Header. 128 Header Parameter Names The names of the members within the JWT 129 Header. 131 Header Parameter Values The values of the members within the JWT 132 Header. 134 JWT Claims Set A string representing a JSON object that contains the 135 claims conveyed by the JWT. When the JWT is digitally signed or 136 MACed, the bytes of the UTF-8 representation of the JWT Claims Set 137 are base64url encoded to create the Encoded JWS Payload. When the 138 JWT is encrypted, the bytes of the UTF-8 representation of the JWT 139 Claims Set are used as the JWE Plaintext. 141 Claim Names The names of the members of the JSON object represented 142 by the JWT Claims Set. 144 Claim Values The values of the members of the JSON object 145 represented by the JWT Claims Set. 147 Encoded JWT Header Base64url encoding of the bytes of the UTF-8 RFC 148 3629 [RFC3629] representation of the JWT Header. 150 Base64url Encoding For the purposes of this specification, this term 151 always refers to the URL- and filename-safe Base64 encoding 152 described in RFC 4648 [RFC4648], Section 5, with the (non URL- 153 safe) '=' padding characters omitted, as permitted by Section 3.2. 154 (See Appendix C of [JWS] for notes on implementing base64url 155 encoding without padding.) 157 StringOrURI A JSON string value, with the additional requirement 158 that while arbitrary string values MAY be used, any value 159 containing a ":" character MUST be a URI as defined in RFC 3986 160 [RFC3986]. 162 IntDate A JSON numeric value representing the number of seconds from 163 1970-01-01T0:0:0Z UTC until the specified UTC date/time. See RFC 164 3339 [RFC3339] for details regarding date/times in general and UTC 165 in particular. 167 3. JSON Web Token (JWT) Overview 169 JWTs represent a set of claims as a JSON object that is base64url 170 encoded and digitally signed or MACed and/or encrypted. The JWT 171 Claims Set represents this JSON object. As per RFC 4627 [RFC4627] 172 Section 2.2, the JSON object consists of zero or more name/value 173 pairs (or members), where the names are strings and the values are 174 arbitrary JSON values. These members are the claims represented by 175 the JWT. 177 The member names within the JWT Claims Set are referred to as Claim 178 Names. The corresponding values are referred to as Claim Values. 180 The bytes of the UTF-8 representation of the JWT Claims Set are 181 digitally signed or MACed in the manner described in JSON Web 182 Signature (JWS) [JWS] and/or encrypted in the manner described in 183 JSON Web Encryption (JWE) [JWE]. 185 The contents of the JWT Header describe the cryptographic operations 186 applied to the JWT Claims Set. If the JWT Header is a JWS Header, the 187 claims are digitally signed or MACed. If the JWT Header is a JWE 188 Header, the claims are encrypted. 190 A JWT is represented as a JWS or JWE. The number of parts is 191 dependent upon the representation of the resulting JWS or JWE. 193 3.1. Example JWT 195 The following example JWT Header declares that the encoded object is 196 a JSON Web Token (JWT) and the JWT is MACed using the HMAC SHA-256 197 algorithm: 198 {"typ":"JWT", 199 "alg":"HS256"} 201 Base64url encoding the bytes of the UTF-8 representation of the JWT 202 Header yields this Encoded JWS Header value, which is used as the 203 Encoded JWT Header: 204 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 206 The following is an example of a JWT Claims Set: 207 {"iss":"joe", 208 "exp":1300819380, 209 "http://example.com/is_root":true} 211 Base64url encoding the bytes of the UTF-8 representation of the JSON 212 Claims Set yields this Encoded JWS Payload (with line breaks for 213 display purposes only): 214 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly 215 9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ 217 Signing the Encoded JWS Header and Encoded JWS Payload with the HMAC 218 SHA-256 algorithm and base64url encoding the signature in the manner 219 specified in [JWS], yields this Encoded JWS Signature: 220 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 222 Concatenating these parts in this order with period characters 223 between the parts yields this complete JWT (with line breaks for 224 display purposes only): 225 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 226 . 227 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 228 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 229 . 230 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 232 This computation is illustrated in more detail in [JWS], Appendix 233 A.1. 235 4. JWT Claims 237 The JWT Claims Set represents a JSON object whose members are the 238 claims conveyed by the JWT. The Claim Names within this object MUST 239 be unique; JWTs with duplicate Claim Names MUST be rejected. Note 240 however, that the set of claims that a JWT must contain to be 241 considered valid is context-dependent and is outside the scope of 242 this specification. When used in a security-related context, 243 implementations MUST understand and support all of the claims 244 present; otherwise, the JWT MUST be rejected for processing. 246 There are three classes of JWT Claim Names: Reserved Claim Names, 247 Public Claim Names, and Private Claim Names. 249 4.1. Reserved Claim Names 251 The following claim names are reserved. None of the claims defined 252 below are intended to be mandatory, but rather, provide a starting 253 point for a set of useful, interoperable claims. All the names are 254 short because a core goal of JWTs is for the tokens to be compact. 255 Additional reserved claim names MAY be defined via the IANA JSON Web 256 Token Claims registry Section 9.1. 258 4.1.1. "exp" (Expiration Time) Claim 260 The "exp" (expiration time) claim identifies the expiration time on 261 or after which the token MUST NOT be accepted for processing. The 262 processing of the "exp" claim requires that the current date/time 263 MUST be before the expiration date/time listed in the "exp" claim. 264 Implementers MAY provide for some small leeway, usually no more than 265 a few minutes, to account for clock skew. Its value MUST be a number 266 containing an IntDate value. This claim is OPTIONAL. 268 4.1.2. "nbf" (Not Before) Claim 270 The "nbf" (not before) claim identifies the time before which the 271 token MUST NOT be accepted for processing. The processing of the 272 "nbf" claim requires that the current date/time MUST be after or 273 equal to the not-before date/time listed in the "nbf" claim. 274 Implementers MAY provide for some small leeway, usually no more than 275 a few minutes, to account for clock skew. Its value MUST be a number 276 containing an IntDate value. This claim is OPTIONAL. 278 4.1.3. "iat" (Issued At) Claim 280 The "iat" (issued at) claim identifies the time at which the JWT was 281 issued. This claim can be used to determine the age of the token. 282 Its value MUST be a number containing an IntDate value. This claim 283 is OPTIONAL. 285 4.1.4. "iss" (Issuer) Claim 287 The "iss" (issuer) claim identifies the principal that issued the 288 JWT. The processing of this claim is generally application specific. 289 The "iss" value is case sensitive. Its value MUST be a string 290 containing a StringOrURI value. This claim is OPTIONAL. 292 4.1.5. "aud" (Audience) Claim 294 The "aud" (audience) claim identifies the audience that the JWT is 295 intended for. The principal intended to process the JWT MUST be 296 identified with the value of the audience claim. If the principal 297 processing the claim does not identify itself with the identifier in 298 the "aud" claim value then the JWT MUST be rejected. The 299 interpretation of the audience value is generally application 300 specific. The "aud" value is case sensitive. Its value MUST be a 301 string containing a StringOrURI value. This claim is OPTIONAL. 303 4.1.6. "prn" (Principal) Claim 305 The "prn" (principal) claim identifies the subject of the JWT. The 306 processing of this claim is generally application specific. The 307 "prn" value is case sensitive. Its value MUST be a string containing 308 a StringOrURI value. This claim is OPTIONAL. 310 4.1.7. "jti" (JWT ID) Claim 312 The "jti" (JWT ID) claim provides a unique identifier for the JWT. 313 The identifier value MUST be assigned in a manner that ensures that 314 there is a negligible probability that the same value will be 315 accidentally assigned to a different data object. The "jti" claim 316 can be used to prevent the JWT from being replayed. The "jti" value 317 is case sensitive. Its value MUST be a string. This claim is 318 OPTIONAL. 320 4.1.8. "typ" (Type) Claim 322 The "typ" (type) claim is used to declare a type for the contents of 323 this JWT Claims Set. The "typ" value is case sensitive. Its value 324 MUST be a string. This claim is OPTIONAL. 326 The values used for the "typ" claim SHOULD come from the same value 327 space as the "typ" header parameter, with the same rules applying. 329 4.2. Public Claim Names 331 Claim names can be defined at will by those using JWTs. However, in 332 order to prevent collisions, any new claim name SHOULD either be 333 defined in the IANA JSON Web Token Claims registry Section 9.1 or be 334 a URI that contains a collision resistant namespace. Examples of 335 collision resistant namespaces include: 337 o Domain Names, 339 o Object Identifiers (OIDs) as defined in the ITU-T X.660 and X.670 340 Recommendation series, or 342 o Universally Unique IDentifier (UUID) as defined in RFC 4122 343 [RFC4122]. 345 In each case, the definer of the name or value needs to take 346 reasonable precautions to make sure they are in control of the part 347 of the namespace they use to define the claim name. 349 4.3. Private Claim Names 351 A producer and consumer of a JWT may agree to any claim name that is 352 not a Reserved Name Section 4.1 or a Public Name Section 4.2. Unlike 353 Public Names, these private names are subject to collision and should 354 be used with caution. 356 5. JWT Header 358 The members of the JSON object represented by the JWT Header describe 359 the cryptographic operations applied to the JWT and optionally, 360 additional properties of the JWT. The member names within the JWT 361 Header are referred to as Header Parameter Names. These names MUST 362 be unique; JWTs with duplicate Header Parameter Names MUST be 363 rejected. The corresponding values are referred to as Header 364 Parameter Values. 366 Implementations MUST understand the entire contents of the header; 367 otherwise, the JWT MUST be rejected for processing. 369 There are two ways of distinguishing whether the JWT is a JWS or JWE. 370 The first is by examining the "alg" (algorithm) header value. If the 371 value represents a signature algorithm, the JWT is a JWS; if it 372 represents an encryption algorithm, the JWT is a JWE. A second 373 method is determining whether an "enc" (encryption method) member 374 exists. If the "enc" member exists, the JWT is a JWE; otherwise, the 375 JWT is a JWS. Both methods will yield the same result. 377 JWS Header Parameters are defined by [JWS]. JWE Header Parameters 378 are defined by [JWE]. This specification further specifies the use 379 of the following header parameters in both the cases where the JWT is 380 a JWS and where it is a JWE. 382 5.1. "typ" (Type) Header Parameter 384 The "typ" (type) header parameter is used to declare structural 385 information about the JWT. In the normal case where nested signing 386 or encryption operations are not employed, the use of this header 387 parameter is OPTIONAL, and if present, it is RECOMMENDED that its 388 value be either "JWT" or "urn:ietf:params:oauth:token-type:jwt". In 389 the case that nested signing or encryption steps are employed, the 390 use of this header parameter is REQUIRED; in this case, the value 391 MUST either be "JWS", to indicate that a nested digitally signed or 392 MACed JWT is carried in this JWT or "JWE", to indicate that a nested 393 encrypted JWT is carried in this JWT. 395 6. Plaintext JWTs 397 To support use cases where the JWT content is secured by a means 398 other than a signature and/or encryption contained within the token 399 (such as a signature on a data structure containing the token), JWTs 400 MAY also be created without a signature or encryption. A plaintext 401 JWT is a JWS using the "none" JWS "alg" header parameter value 402 defined in JSON Web Algorithms (JWA) [JWA]; it is a JWS with an empty 403 JWS Signature value. 405 6.1. Example Plaintext JWT 407 The following example JWT Header declares that the encoded object is 408 a Plaintext JWT: 409 {"alg":"none"} 411 Base64url encoding the bytes of the UTF-8 representation of the JWT 412 Header yields this Encoded JWT Header: 413 eyJhbGciOiJub25lIn0 415 The following is an example of a JWT Claims Set: 416 {"iss":"joe", 417 "exp":1300819380, 418 "http://example.com/is_root":true} 420 Base64url encoding the bytes of the UTF-8 representation of the JSON 421 Claims Set yields this Encoded JWS Payload (with line breaks for 422 display purposes only): 423 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 424 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 426 The Encoded JWS Signature is the empty string. 428 Concatenating these parts in this order with period characters 429 between the parts yields this complete JWT (with line breaks for 430 display purposes only): 431 eyJhbGciOiJub25lIn0 432 . 433 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 434 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 435 . 437 7. Rules for Creating and Validating a JWT 439 To create a JWT, one MUST perform these steps. The order of the 440 steps is not significant in cases where there are no dependencies 441 between the inputs and outputs of the steps. 443 1. Create a JWT Claims Set containing the desired claims. Note that 444 white space is explicitly allowed in the representation and no 445 canonicalization is performed before encoding. 447 2. Let the Message be the bytes of the UTF-8 representation of the 448 JWT Claims Set. 450 3. Create a JWT Header containing the desired set of header 451 parameters. The JWT MUST conform to either the [JWS] or [JWE] 452 specifications. Note that white space is explicitly allowed in 453 the representation and no canonicalization is performed before 454 encoding. 456 4. Base64url encode the bytes of the UTF-8 representation of the JWT 457 Header. Let this be the Encoded JWT Header. 459 5. Depending upon whether the JWT is a JWS or JWE, there are two 460 cases: 462 * If the JWT is a JWS, create a JWS using the JWT Header as the 463 JWS Header and the Message as the JWS Payload; all steps 464 specified in [JWS] for creating a JWS MUST be followed. 466 * Else, if the JWT is a JWE, create a JWE using the JWT Header 467 as the JWE Header and the Message as the JWE Plaintext; all 468 steps specified in [JWE] for creating a JWE MUST be followed. 470 6. If a nested signing or encryption operation will be performed, 471 let the Message be the JWS or JWE, and return to Step 3, using a 472 "typ" value of either "JWS" or "JWE" respectively in the new JWT 473 Header created in that step. 475 7. Otherwise, let the resulting JWT be the JWS or JWE. 477 When validating a JWT the following steps MUST be taken. The order 478 of the steps is not significant in cases where there are no 479 dependencies between the inputs and outputs of the steps. If any of 480 the listed steps fails then the token MUST be rejected for 481 processing. 483 1. The JWT MUST contain at least one period character. 485 2. Let the Encoded JWT Header be the portion of the JWT before the 486 first period character. 488 3. The Encoded JWT Header MUST be successfully base64url decoded 489 following the restriction given in this specification that no 490 padding characters have been used. 492 4. The resulting JWT Header MUST be completely valid JSON syntax 493 conforming to RFC 4627 [RFC4627]. 495 5. The resulting JWT Header MUST be validated to only include 496 parameters and values whose syntax and semantics are both 497 understood and supported. 499 6. Determine whether the JWT is a JWS or a JWE by examining the 500 "alg" (algorithm) header value and optionally, the "enc" 501 (encryption method) header value, if present. 503 7. Depending upon whether the JWT is a JWS or JWE, there are two 504 cases: 506 * If the JWT is a JWS, all steps specified in [JWS] for 507 validating a JWS MUST be followed. Let the Message be the 508 result of base64url decoding the JWS Payload. 510 * Else, if the JWT is a JWE, all steps specified in [JWE] for 511 validating a JWE MUST be followed. Let the Message be the 512 JWE Plaintext. 514 8. If the JWT Header contains a "typ" value of either "JWS" or 515 "JWE", then the Message contains a JWT that was the subject of 516 nested signing or encryption operations, respectively. In this 517 case, return to Step 1, using the Message as the JWT. 519 9. Otherwise, let the JWT Claims Set be the Message. 521 10. The JWT Claims Set MUST be completely valid JSON syntax 522 conforming to RFC 4627 [RFC4627]. 524 11. When used in a security-related context, the JWT Claims Set MUST 525 be validated to only include claims whose syntax and semantics 526 are both understood and supported. 528 Processing a JWT inevitably requires comparing known strings to 529 values in the token. For example, in checking what the algorithm is, 530 the Unicode string encoding "alg" will be checked against the member 531 names in the JWT Header to see if there is a matching header 532 parameter name. A similar process occurs when determining if the 533 value of the "alg" header parameter represents a supported algorithm. 535 Comparisons between JSON strings and other Unicode strings MUST be 536 performed as specified below: 538 1. Remove any JSON applied escaping to produce an array of Unicode 539 code points. 541 2. Unicode Normalization [USA15] MUST NOT be applied at any point to 542 either the JSON string or to the string it is to be compared 543 against. 545 3. Comparisons between the two strings MUST be performed as a 546 Unicode code point to code point equality comparison. 548 8. Cryptographic Algorithms 550 JWTs use JSON Web Signature (JWS) [JWS] and JSON Web Encryption (JWE) 551 [JWE] to sign and/or encrypt the contents of the JWT. 553 Of the JWS signing algorithms, only HMAC SHA-256 and "none" MUST be 554 implemented by conforming JWT implementations. It is RECOMMENDED 555 that implementations also support the RSA SHA-256 and ECDSA P-256 556 SHA-256 algorithms. Support for other algorithms and key sizes is 557 OPTIONAL. 559 If an implementation provides encryption capabilities, of the JWE 560 encryption algorithms, only RSA-PKCS1-1.5 with 2048 bit keys, AES- 561 128-KW, AES-256-KW, AES-128-CBC, and AES-256-CBC MUST be implemented 562 by conforming implementations. It is RECOMMENDED that 563 implementations also support ECDH-ES with 256 bit keys, AES-128-GCM, 564 and AES-256-GCM. Support for other algorithms and key sizes is 565 OPTIONAL. 567 9. IANA Considerations 568 9.1. JSON Web Token Claims Registry 570 This specification establishes the IANA JSON Web Token Claims 571 registry for reserved JWT claim names. Inclusion in the registry is 572 RFC Required in the RFC 5226 [RFC5226] sense. The registry records 573 the reserved claim name and a reference to the RFC that defines it. 574 This specification registers the claim names defined in Section 4.1. 576 9.2. Sub-Namespace Registration of urn:ietf:params:oauth:token-type:jwt 578 This specification registers the value "token-type:jwt" in the 579 registry urn:ietf:params:oauth established in An IETF URN Sub- 580 Namespace for OAuth [I-D.ietf-oauth-urn-sub-ns]. 582 o URN: urn:ietf:params:oauth:token-type:jwt 584 o Common Name: JSON Web Token (JWT) Token Type 586 o Change controller: IETF 588 o Description: [[this document]] 590 9.3. Registration of application/jwt MIME Media Type 592 This specification registers the "application/jwt" MIME Media Type 593 RFC 2045 [RFC2045]. 595 Type name: 596 application 598 Subtype name: 599 jwt 601 Required parameters: 602 n/a 604 Optional parameters: 605 n/a 607 Encoding considerations: 608 n/a 610 Security considerations: 611 See the Security Considerations section of this document 613 Interoperability considerations: 614 n/a 616 Published specification: 617 [[ this document ]] 619 Applications that use this media type: 620 OpenID Connect, Mozilla Browser ID, Salesforce, Google, numerous 621 others 623 Additional information: 624 Magic number(s): n/a 625 File extension(s): n/a 626 Macintosh file type code(s): n/a 628 Person & email address to contact for further information: 629 Michael B. Jones 630 mbj@microsoft.com 632 Intended usage: 633 COMMON 635 Restrictions on usage: 636 none 638 Author: 639 Michael B. Jones 640 mbj@microsoft.com 642 Change controller: 643 IETF 645 9.4. Registration of "JWT" Type Value 647 This specification registers the following "typ" header parameter 648 value in the JSON Web Signature and Encryption "typ" Values registry 649 established by the JSON Web Algorithms (JWA) [JWA] specification: 651 "typ" header parameter value: 652 "JWT" 654 Abbreviation for MIME type: 655 application/jwt 657 Change controller: 658 IETF 660 Description: 661 [[ this document ]] 663 10. Security Considerations 665 All the security considerations in the JWS specification also apply 666 to JWT, as do the JWE security considerations when encryption is 667 employed. In particular, the JWS JSON Security Considerations and 668 Unicode Comparison Security Considerations apply equally to the JWT 669 Claims Set in the same manner that they do to the JWS Header. 671 11. Open Issues and Things To Be Done (TBD) 673 The following items remain to be done in this draft: 675 o Provide an example of an encrypted JWT. 677 12. References 679 12.1. Normative References 681 [I-D.ietf-oauth-urn-sub-ns] 682 Tschofenig, H., "An IETF URN Sub-Namespace for OAuth", 683 draft-ietf-oauth-urn-sub-ns-02 (work in progress), 684 January 2012. 686 [JWA] Jones, M., "JSON Web Algorithms (JWA)", May 2012. 688 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 689 Encryption (JWE)", May 2012. 691 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 692 Signature (JWS)", May 2012. 694 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 695 Extensions (MIME) Part One: Format of Internet Message 696 Bodies", RFC 2045, November 1996. 698 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 699 Requirement Levels", BCP 14, RFC 2119, March 1997. 701 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 702 Internet: Timestamps", RFC 3339, July 2002. 704 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 705 10646", STD 63, RFC 3629, November 2003. 707 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 708 Resource Identifier (URI): Generic Syntax", STD 66, 709 RFC 3986, January 2005. 711 [RFC4627] Crockford, D., "The application/json Media Type for 712 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 714 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 715 Encodings", RFC 4648, October 2006. 717 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 718 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 719 May 2008. 721 [USA15] Davis, M., Whistler, K., and M. Duerst, "Unicode 722 Normalization Forms", Unicode Standard Annex 15, 09 2009. 724 12.2. Informative References 726 [CanvasApp] 727 Facebook, "Canvas Applications", 2010. 729 [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", 730 September 2010. 732 [MagicSignatures] 733 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 734 Signatures", January 2011. 736 [OASIS.saml-core-2.0-os] 737 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 738 "Assertions and Protocol for the OASIS Security Assertion 739 Markup Language (SAML) V2.0", OASIS Standard saml-core- 740 2.0-os, March 2005. 742 [RFC3275] Eastlake, D., Reagle, J., and D. Solo, "(Extensible Markup 743 Language) XML-Signature Syntax and Processing", RFC 3275, 744 March 2002. 746 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 747 Unique IDentifier (UUID) URN Namespace", RFC 4122, 748 July 2005. 750 [SWT] Hardt, D. and Y. Goland, "Simple Web Token (SWT)", 751 Version 0.9.5.1, November 2009. 753 [W3C.CR-xml11-20021015] 754 Cowan, J., "Extensible Markup Language (XML) 1.1", W3C 755 CR CR-xml11-20021015, October 2002. 757 Appendix A. Relationship of JWTs to SAML Tokens 759 SAML 2.0 [OASIS.saml-core-2.0-os] provides a standard for creating 760 tokens with much greater expressivity and more security options than 761 supported by JWTs. However, the cost of this flexibility and 762 expressiveness is both size and complexity. In addition, SAML's use 763 of XML [W3C.CR-xml11-20021015] and XML DSIG [RFC3275] only 764 contributes to the size of SAML tokens. 766 JWTs are intended to provide a simple token format that is small 767 enough to fit into HTTP headers and query arguments in URIs. It does 768 this by supporting a much simpler token model than SAML and using the 769 JSON [RFC4627] object encoding syntax. It also supports securing 770 tokens using Message Authentication Codes (MACs) and digital 771 signatures using a smaller (and less flexible) format than XML DSIG. 773 Therefore, while JWTs can do some of the things SAML tokens do, JWTs 774 are not intended as a full replacement for SAML tokens, but rather as 775 a compromise token format to be used when space is at a premium. 777 Appendix B. Relationship of JWTs to Simple Web Tokens (SWTs) 779 Both JWTs and Simple Web Tokens SWT [SWT], at their core, enable sets 780 of claims to be communicated between applications. For SWTs, both 781 the claim names and claim values are strings. For JWTs, while claim 782 names are strings, claim values can be any JSON type. Both token 783 types offer cryptographic protection of their content: SWTs with HMAC 784 SHA-256 and JWTs with a choice of algorithms, including HMAC SHA-256, 785 RSA SHA-256, and ECDSA P-256 SHA-256. 787 Appendix C. Acknowledgements 789 The authors acknowledge that the design of JWTs was intentionally 790 influenced by the design and simplicity of Simple Web Tokens [SWT] 791 and ideas for JSON tokens that Dick Hardt discussed within the OpenID 792 community. 794 Solutions for signing JSON content were previously explored by Magic 795 Signatures [MagicSignatures], JSON Simple Sign [JSS], and Canvas 796 Applications [CanvasApp], all of which influenced this draft. Dirk 797 Balfanz, Yaron Y. Goland, John Panzer, and Paul Tarjan all made 798 significant contributions to the design of this specification. 800 Appendix D. Document History 802 [[ to be removed by the RFC editor before publication as an RFC ]] 804 -00 806 o Created the initial IETF draft based upon 807 draft-jones-json-web-token-10 with no normative changes. 809 Authors' Addresses 811 Michael B. Jones 812 Microsoft 814 Email: mbj@microsoft.com 815 URI: http://self-issued.info/ 817 John Bradley 818 Ping Identity 820 Email: ve7jtb@ve7jtb.com 822 Nat Sakimura 823 Nomura Research Institute 825 Email: n-sakimura@nri.co.jp