idnits 2.17.1 draft-ietf-oauth-json-web-token-06.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 seems to use 'NOT RECOMMENDED' as an RFC 2119 keyword, but does not include the phrase in its RFC 2119 key words list. -- The document date (December 27, 2012) is 4138 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC3629' is defined on line 788, but no explicit reference was found in the text == Unused Reference: 'USA15' is defined on line 811, but no explicit reference was found in the text ** Obsolete normative reference: RFC 4288 (Obsoleted by RFC 6838) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Downref: Normative reference to an Informational RFC: RFC 6755 -- Possible downref: Non-RFC (?) normative reference: ref. 'USA15' Summary: 4 errors (**), 0 flaws (~~), 4 warnings (==), 2 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: June 30, 2013 Ping Identity 6 N. Sakimura 7 NRI 8 December 27, 2012 10 JSON Web Token (JWT) 11 draft-ietf-oauth-json-web-token-06 13 Abstract 15 JSON Web Token (JWT) is a compact URL-safe means of representing 16 claims to be transferred between two parties. The claims in a JWT 17 are encoded as a JavaScript Object Notation (JSON) object that is 18 used as the payload of a JSON Web Signature (JWS) structure or as the 19 plaintext of a JSON Web Encryption (JWE) structure, enabling the 20 claims to be digitally signed or MACed and/or encrypted. 22 The suggested pronunciation of JWT is the same as the English word 23 "jot". 25 Status of this Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at http://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on June 30, 2013. 42 Copyright Notice 44 Copyright (c) 2012 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4 61 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 62 3. JSON Web Token (JWT) Overview . . . . . . . . . . . . . . . . 6 63 3.1. Example JWT . . . . . . . . . . . . . . . . . . . . . . . 6 64 4. JWT Claims . . . . . . . . . . . . . . . . . . . . . . . . . . 7 65 4.1. Reserved Claim Names . . . . . . . . . . . . . . . . . . . 7 66 4.1.1. "iss" (Issuer) Claim . . . . . . . . . . . . . . . . . 8 67 4.1.2. "sub" (Subject) Claim . . . . . . . . . . . . . . . . 8 68 4.1.3. "aud" (Audience) Claim . . . . . . . . . . . . . . . . 8 69 4.1.4. "exp" (Expiration Time) Claim . . . . . . . . . . . . 8 70 4.1.5. "nbf" (Not Before) Claim . . . . . . . . . . . . . . . 8 71 4.1.6. "iat" (Issued At) Claim . . . . . . . . . . . . . . . 9 72 4.1.7. "jti" (JWT ID) Claim . . . . . . . . . . . . . . . . . 9 73 4.1.8. "typ" (Type) Claim . . . . . . . . . . . . . . . . . . 9 74 4.2. Public Claim Names . . . . . . . . . . . . . . . . . . . . 9 75 4.3. Private Claim Names . . . . . . . . . . . . . . . . . . . 9 76 5. JWT Header . . . . . . . . . . . . . . . . . . . . . . . . . . 10 77 5.1. "typ" (Type) Header Parameter . . . . . . . . . . . . . . 10 78 5.2. "cty" (Content Type) Header Parameter . . . . . . . . . . 10 79 6. Plaintext JWTs . . . . . . . . . . . . . . . . . . . . . . . . 10 80 6.1. Example Plaintext JWT . . . . . . . . . . . . . . . . . . 11 81 7. Rules for Creating and Validating a JWT . . . . . . . . . . . 11 82 7.1. String Comparison Rules . . . . . . . . . . . . . . . . . 13 83 8. Cryptographic Algorithms . . . . . . . . . . . . . . . . . . . 14 84 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 85 9.1. JSON Web Token Claims Registry . . . . . . . . . . . . . . 14 86 9.1.1. Registration Template . . . . . . . . . . . . . . . . 15 87 9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 15 88 9.2. Sub-Namespace Registration of 89 urn:ietf:params:oauth:token-type:jwt . . . . . . . . . . . 16 90 9.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 16 91 9.3. JSON Web Signature and Encryption Type Values 92 Registration . . . . . . . . . . . . . . . . . . . . . . . 16 93 9.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 16 94 9.4. Media Type Registration . . . . . . . . . . . . . . . . . 16 95 9.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 16 97 10. Security Considerations . . . . . . . . . . . . . . . . . . . 17 98 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 99 11.1. Normative References . . . . . . . . . . . . . . . . . . . 18 100 11.2. Informative References . . . . . . . . . . . . . . . . . . 19 101 Appendix A. Example Encrypted JWT . . . . . . . . . . . . . . . . 19 102 Appendix B. Relationship of JWTs to SAML Assertions . . . . . . . 20 103 Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs) . . 21 104 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 21 105 Appendix E. Open Issues . . . . . . . . . . . . . . . . . . . . . 22 106 Appendix F. Document History . . . . . . . . . . . . . . . . . . 22 107 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 24 109 1. Introduction 111 JSON Web Token (JWT) is a compact claims representation format 112 intended for space constrained environments such as HTTP 113 Authorization headers and URI query parameters. JWTs encode claims 114 to be transmitted as a JavaScript Object Notation (JSON) [RFC4627] 115 object that is used as the payload of a JSON Web Signature (JWS) 116 [JWS] structure or as the plaintext of a JSON Web Encryption (JWE) 117 [JWE] structure, enabling the claims to be digitally signed or MACed 118 and/or encrypted. 120 The suggested pronunciation of JWT is the same as the English word 121 "jot". 123 1.1. Notational Conventions 125 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 126 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 127 document are to be interpreted as described in Key words for use in 128 RFCs to Indicate Requirement Levels [RFC2119]. 130 2. Terminology 132 JSON Web Token (JWT) A string representing a set of claims as a JSON 133 object that is encoded in a JWS or JWE, enabling the claims to be 134 digitally signed or MACed and/or encrypted. 136 Base64url Encoding The URL- and filename-safe Base64 encoding 137 described in RFC 4648 [RFC4648], Section 5, with the (non URL- 138 safe) '=' padding characters omitted, as permitted by Section 3.2. 139 (See Appendix C of [JWS] for notes on implementing base64url 140 encoding without padding.) 142 JSON Text Object A UTF-8 encoded text string representing a JSON 143 object; the syntax of JSON objects is defined in Section 2.2 of 144 [RFC4627]. 146 JWT Header A JSON Text Object that describes the cryptographic 147 operations applied to the JWT. When the JWT is digitally signed 148 or MACed, the JWT Header is a JWS Header. When the JWT is 149 encrypted, the JWT Header is a JWE Header. 151 Header Parameter Name The name of a member of the JWT Header. 153 Header Parameter Value The value of a member of the JWT Header. 155 JWT Claims Set A JSON Text Object that contains the Claims conveyed 156 by the JWT, where each claim is represented as a name/value pair 157 of a Claim Name and a Claim Value. 159 Claim A piece of information asserted about a subject. Here, Claims 160 are represented name/value pairs, consisting of a Claim Name and a 161 Claim Value. 163 Claim Name The name portion of a Claim representation. A Claim Name 164 is always a string. 166 Claim Value The value portion of a Claim representation. A Claim 167 Value can be any JSON value. 169 Encoded JWT Header Base64url encoding of the JWT Header. 171 Nested JWT A JWT in which nested signing or encryption are employed. 172 In nested JWTs, a JWT is used as the payload or plaintext value of 173 an enclosing JWS or JWE structure, respectively. 175 Plaintext JWT A JWT whose Claims are not integrity protected or 176 encrypted. 178 Collision Resistant Namespace A namespace that allows names to be 179 allocated in a manner such that they are highly unlikely to 180 collide with other names. For instance, collision resistance can 181 be achieved through administrative delegation of portions of the 182 namespace or through use of collision-resistant name allocation 183 functions. Examples of Collision Resistant Namespaces include: 184 Domain Names, Object Identifiers (OIDs) as defined in the ITU-T 185 X.660 and X.670 Recommendation series, and Universally Unique 186 IDentifiers (UUIDs) [RFC4122]. When using an administratively 187 delegated namespace, the definer of a name needs to take 188 reasonable precautions to ensure they are in control of the 189 portion of the namespace they use to define the name. 191 StringOrURI A JSON string value, with the additional requirement 192 that while arbitrary string values MAY be used, any value 193 containing a ":" character MUST be a URI [RFC3986]. StringOrURI 194 values are compared as case-sensitive strings with no 195 transformations or canonicalizations applied. 197 IntDate A JSON numeric value representing the number of seconds from 198 1970-01-01T0:0:0Z UTC until the specified UTC date/time. See RFC 199 3339 [RFC3339] for details regarding date/times in general and UTC 200 in particular. 202 3. JSON Web Token (JWT) Overview 204 JWTs represent a set of claims as a JSON object that is encoded in a 205 JWS and/or JWE structure. This JSON object is the JWT Claims Set. As 206 per RFC 4627 [RFC4627] Section 2.2, the JSON object consists of zero 207 or more name/value pairs (or members), where the names are strings 208 and the values are arbitrary JSON values. These members are the 209 claims represented by the JWT. 211 The member names within the JWT Claims Set are referred to as Claim 212 Names. The corresponding values are referred to as Claim Values. 214 The contents of the JWT Header describe the cryptographic operations 215 applied to the JWT Claims Set. If the JWT Header is a JWS Header, the 216 JWT is represented as a JWS, and the claims are digitally signed or 217 MACed, with the JWT Claims Set being the JWS Payload. If the JWT 218 Header is a JWE Header, the JWT is represented as a JWE, and the 219 claims are encrypted, with the JWT Claims Set being the input 220 Plaintext. A JWT may be enclosed in another JWE or JWS structure to 221 create a Nested JWT, enabling nested signing and encryption to be 222 performed. 224 A JWT is represented as a sequence of URL-safe parts separated by 225 period ('.') characters. Each part contains a base64url encoded 226 value. The number of parts in the JWT is dependent upon the 227 representation of the resulting JWS or JWE. 229 3.1. Example JWT 231 The following example JWT Header declares that the encoded object is 232 a JSON Web Token (JWT) and the JWT is MACed using the HMAC SHA-256 233 algorithm: 235 {"typ":"JWT", 236 "alg":"HS256"} 238 Base64url encoding the bytes of the UTF-8 representation of the JWT 239 Header yields this Encoded JWS Header value, which is used as the 240 Encoded JWT Header: 242 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 244 The following is an example of a JWT Claims Set: 246 {"iss":"joe", 247 "exp":1300819380, 248 "http://example.com/is_root":true} 250 Base64url encoding the bytes of the UTF-8 representation of the JSON 251 Claims Set yields this Encoded JWS Payload (with line breaks for 252 display purposes only): 254 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly 255 9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ 257 Signing the Encoded JWS Header and Encoded JWS Payload with the HMAC 258 SHA-256 algorithm and base64url encoding the signature in the manner 259 specified in [JWS], yields this Encoded JWS Signature: 261 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 263 Concatenating these parts in this order with period ('.') characters 264 between the parts yields this complete JWT (with line breaks for 265 display purposes only): 267 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 268 . 269 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 270 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 271 . 272 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 274 This computation is illustrated in more detail in Appendix A.1 of 275 [JWS]. See Appendix A for an example of an encrypted JWT. 277 4. JWT Claims 279 The JWT Claims Set represents a JSON object whose members are the 280 claims conveyed by the JWT. The Claim Names within a JWT Claims Set 281 MUST be unique; JWTs with duplicate Claim Names MUST be rejected. 282 Note however, that the set of claims that a JWT must contain to be 283 considered valid is context-dependent and is outside the scope of 284 this specification. When used in a security-related context, 285 implementations MUST understand and support all of the claims 286 present; otherwise, the JWT MUST be rejected for processing. 288 There are three classes of JWT Claim Names: Reserved Claim Names, 289 Public Claim Names, and Private Claim Names. 291 4.1. Reserved Claim Names 293 The following Claim Names are reserved. None of the claims defined 294 below are intended to be mandatory to use, but rather, provide a 295 starting point for a set of useful, interoperable claims. All the 296 names are short because a core goal of JWTs is for the representation 297 to be compact. Additional reserved Claim Names MAY be defined via 298 the IANA JSON Web Token Claims registry Section 9.1. 300 4.1.1. "iss" (Issuer) Claim 302 The "iss" (issuer) claim identifies the principal that issued the 303 JWT. The processing of this claim is generally application specific. 304 The "iss" value is a case sensitive string containing a StringOrURI 305 value. Use of this claim is OPTIONAL. 307 4.1.2. "sub" (Subject) Claim 309 The "sub" (subject) claim identifies the principal that is the 310 subject of the JWT. The Claims in a JWT are normally statements 311 about the subject. The processing of this claim is generally 312 application specific. The "sub" value is a case sensitive string 313 containing a StringOrURI value. Use of this claim is OPTIONAL. 315 4.1.3. "aud" (Audience) Claim 317 The "aud" (audience) claim identifies the audiences that the JWT is 318 intended for. Each principal intended to process the JWT MUST 319 identify itself with a value in audience claim. If the principal 320 processing the claim does not identify itself with a value in the 321 "aud" claim, then the JWT MUST be rejected. In the general case, the 322 "aud" value is an array of case sensitive strings, each containing a 323 StringOrURI value. In the special case when the JWT has one 324 audience, the "aud" value MAY be a single case sensitive string 325 containing a StringOrURI value. The interpretation of audience 326 values is generally application specific. Use of this claim is 327 OPTIONAL. 329 4.1.4. "exp" (Expiration Time) Claim 331 The "exp" (expiration time) claim identifies the expiration time on 332 or after which the JWT MUST NOT be accepted for processing. The 333 processing of the "exp" claim requires that the current date/time 334 MUST be before the expiration date/time listed in the "exp" claim. 335 Implementers MAY provide for some small leeway, usually no more than 336 a few minutes, to account for clock skew. Its value MUST be a number 337 containing an IntDate value. Use of this claim is OPTIONAL. 339 4.1.5. "nbf" (Not Before) Claim 341 The "nbf" (not before) claim identifies the time before which the JWT 342 MUST NOT be accepted for processing. The processing of the "nbf" 343 claim requires that the current date/time MUST be after or equal to 344 the not-before date/time listed in the "nbf" claim. Implementers MAY 345 provide for some small leeway, usually no more than a few minutes, to 346 account for clock skew. Its value MUST be a number containing an 347 IntDate value. Use of this claim is OPTIONAL. 349 4.1.6. "iat" (Issued At) Claim 351 The "iat" (issued at) claim identifies the time at which the JWT was 352 issued. This claim can be used to determine the age of the JWT. Its 353 value MUST be a number containing an IntDate value. Use of this 354 claim is OPTIONAL. 356 4.1.7. "jti" (JWT ID) Claim 358 The "jti" (JWT ID) claim provides a unique identifier for the JWT. 359 The identifier value MUST be assigned in a manner that ensures that 360 there is a negligible probability that the same value will be 361 accidentally assigned to a different data object. The "jti" claim 362 can be used to prevent the JWT from being replayed. The "jti" value 363 is a case sensitive string. Use of this claim is OPTIONAL. 365 4.1.8. "typ" (Type) Claim 367 The "typ" (type) claim is used to declare a type for the contents of 368 this JWT Claims Set. The "typ" value is a case sensitive string. Use 369 of this claim is OPTIONAL. 371 The values used for the "typ" claim come from the same value space as 372 the "typ" header parameter, with the same rules applying. 374 4.2. Public Claim Names 376 Claim Names can be defined at will by those using JWTs. However, in 377 order to prevent collisions, any new Claim Name SHOULD either be 378 registered in the IANA JSON Web Token Claims registry Section 9.1 or 379 be a Public Name: a value that contains a Collision Resistant 380 Namespace. In each case, the definer of the name or value needs to 381 take reasonable precautions to make sure they are in control of the 382 part of the namespace they use to define the Claim Name. 384 4.3. Private Claim Names 386 A producer and consumer of a JWT may agree to use Claim Names that 387 are Private Names: names that are not Reserved Names Section 4.1 or 388 Public Names Section 4.2. Unlike Public Names, Private Names are 389 subject to collision and should be used with caution. 391 5. JWT Header 393 The members of the JSON object represented by the JWT Header describe 394 the cryptographic operations applied to the JWT and optionally, 395 additional properties of the JWT. The member names within the JWT 396 Header are referred to as Header Parameter Names. These names MUST 397 be unique; JWTs with duplicate Header Parameter Names MUST be 398 rejected. The corresponding values are referred to as Header 399 Parameter Values. 401 Implementations MUST understand the entire contents of the header; 402 otherwise, the JWT MUST be rejected for processing. 404 JWS Header Parameters are defined by [JWS]. JWE Header Parameters 405 are defined by [JWE]. This specification further specifies the use 406 of the following header parameter in both the cases where the JWT is 407 a JWS and where it is a JWE. 409 5.1. "typ" (Type) Header Parameter 411 The "typ" (type) header parameter is used to declare the type of this 412 object. If present, it is RECOMMENDED that its value be either "JWT" 413 or "urn:ietf:params:oauth:token-type:jwt" to indicate that this 414 object is a JWT. The "typ" value is a case sensitive string. Use of 415 this header parameter is OPTIONAL. 417 5.2. "cty" (Content Type) Header Parameter 419 The "cty" (content type) header parameter is used to declare 420 structural information about the JWT. Its value MUST be a string. 422 In the normal case where nested signing or encryption operations are 423 not employed, the use of this header parameter is NOT RECOMMENDED. 424 In the case that nested signing or encryption is employed, the use of 425 this header parameter is REQUIRED; in this case, the value MUST be 426 "JWT", to indicate that a Nested JWT is carried in this JWT. 428 The values used for the "cty" header parameter come from the same 429 value space as the "typ" header parameter, with the same rules 430 applying. 432 6. Plaintext JWTs 434 To support use cases where the JWT content is secured by a means 435 other than a signature and/or encryption contained within the JWT 436 (such as a signature on a data structure containing the JWT), JWTs 437 MAY also be created without a signature or encryption. A plaintext 438 JWT is a JWS using the "none" JWS "alg" header parameter value 439 defined in JSON Web Algorithms (JWA) [JWA]; it is a JWS with the 440 empty string for its JWS Signature value. 442 6.1. Example Plaintext JWT 444 The following example JWT Header declares that the encoded object is 445 a Plaintext JWT: 447 {"alg":"none"} 449 Base64url encoding the bytes of the UTF-8 representation of the JWT 450 Header yields this Encoded JWT Header: 452 eyJhbGciOiJub25lIn0 454 The following is an example of a JWT Claims Set: 456 {"iss":"joe", 457 "exp":1300819380, 458 "http://example.com/is_root":true} 460 Base64url encoding the bytes of the UTF-8 representation of the JSON 461 Claims Set yields this Encoded JWS Payload (with line breaks for 462 display purposes only): 464 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 465 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 467 The Encoded JWS Signature is the empty string. 469 Concatenating these parts in this order with period ('.') characters 470 between the parts yields this complete JWT (with line breaks for 471 display purposes only): 473 eyJhbGciOiJub25lIn0 474 . 475 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 476 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 477 . 479 7. Rules for Creating and Validating a JWT 481 To create a JWT, one MUST perform these steps. The order of the 482 steps is not significant in cases where there are no dependencies 483 between the inputs and outputs of the steps. 485 1. Create a JWT Claims Set containing the desired claims. Note that 486 white space is explicitly allowed in the representation and no 487 canonicalization is performed before encoding. 489 2. Let the Message be the bytes of the UTF-8 representation of the 490 JWT Claims Set. 492 3. Create a JWT Header containing the desired set of header 493 parameters. The JWT MUST conform to either the [JWS] or [JWE] 494 specifications. Note that white space is explicitly allowed in 495 the representation and no canonicalization is performed before 496 encoding. 498 4. Base64url encode the bytes of the UTF-8 representation of the JWT 499 Header. Let this be the Encoded JWT Header. 501 5. Depending upon whether the JWT is a JWS or JWE, there are two 502 cases: 504 * If the JWT is a JWS, create a JWS using the JWT Header as the 505 JWS Header and the Message as the JWS Payload; all steps 506 specified in [JWS] for creating a JWS MUST be followed. 508 * Else, if the JWT is a JWE, create a JWE using the JWT Header 509 as the JWE Header and the Message as the JWE Plaintext; all 510 steps specified in [JWE] for creating a JWE MUST be followed. 512 6. If a nested signing or encryption operation will be performed, 513 let the Message be the JWS or JWE, and return to Step 3, using a 514 "cty" (content type) value of "JWT" in the new JWT Header created 515 in that step. 517 7. Otherwise, let the resulting JWT be the JWS or JWE. 519 When validating a JWT the following steps MUST be taken. The order 520 of the steps is not significant in cases where there are no 521 dependencies between the inputs and outputs of the steps. If any of 522 the listed steps fails then the JWT MUST be rejected for processing. 524 1. The JWT MUST contain at least one period ('.') character. 526 2. Let the Encoded JWT Header be the portion of the JWT before the 527 first period ('.') character. 529 3. The Encoded JWT Header MUST be successfully base64url decoded 530 following the restriction given in this specification that no 531 padding characters have been used. 533 4. The resulting JWT Header MUST be completely valid JSON syntax 534 conforming to RFC 4627 [RFC4627]. 536 5. The resulting JWT Header MUST be validated to only include 537 parameters and values whose syntax and semantics are both 538 understood and supported. 540 6. Determine whether the JWT is a JWS or a JWE by examining the 541 "alg" (algorithm) header value and optionally, the "enc" 542 (encryption method) header value, if present. 544 7. Depending upon whether the JWT is a JWS or JWE, there are two 545 cases: 547 * If the JWT is a JWS, all steps specified in [JWS] for 548 validating a JWS MUST be followed. Let the Message be the 549 result of base64url decoding the JWS Payload. 551 * Else, if the JWT is a JWE, all steps specified in [JWE] for 552 validating a JWE MUST be followed. Let the Message be the 553 JWE Plaintext. 555 8. If the JWT Header contains a "cty" (content type) value of 556 "JWT", then the Message contains a JWT that was the subject of 557 nested signing or encryption operations. In this case, return 558 to Step 1, using the Message as the JWT. 560 9. Otherwise, let the JWT Claims Set be the Message. 562 10. The JWT Claims Set MUST be completely valid JSON syntax 563 conforming to RFC 4627 [RFC4627]. 565 11. When used in a security-related context, the JWT Claims Set MUST 566 be validated to only include claims whose syntax and semantics 567 are both understood and supported. 569 7.1. String Comparison Rules 571 Processing a JWT inevitably requires comparing known strings to 572 values in JSON objects. For example, in checking what the algorithm 573 is, the Unicode string encoding "alg" will be checked against the 574 member names in the JWT Header to see if there is a matching Header 575 Parameter Name. 577 Comparisons between JSON strings and other Unicode strings MUST be 578 performed by comparing Unicode code points without normalization as 579 specified in the String Comparison Rules in Section 5.3 of [JWS]. 581 8. Cryptographic Algorithms 583 JWTs use JSON Web Signature (JWS) [JWS] and JSON Web Encryption (JWE) 584 [JWE] to sign and/or encrypt the contents of the JWT. 586 Of the JWS signing algorithms, only HMAC SHA-256 and "none" MUST be 587 implemented by conforming JWT implementations. It is RECOMMENDED 588 that implementations also support the RSA SHA-256 and ECDSA P-256 589 SHA-256 algorithms. Support for other algorithms and key sizes is 590 OPTIONAL. 592 If an implementation provides encryption capabilities, of the JWE 593 encryption algorithms, only RSA-PKCS1-1.5 with 2048 bit keys, AES- 594 128-KW, AES-256-KW, AES-128-CBC, and AES-256-CBC MUST be implemented 595 by conforming implementations. It is RECOMMENDED that 596 implementations also support ECDH-ES with 256 bit keys, AES-128-GCM, 597 and AES-256-GCM. Support for other algorithms and key sizes is 598 OPTIONAL. 600 9. IANA Considerations 602 9.1. JSON Web Token Claims Registry 604 This specification establishes the IANA JSON Web Token Claims 605 registry for reserved JWT Claim Names. The registry records the 606 reserved Claim Name and a reference to the specification that defines 607 it. This specification registers the Claim Names defined in 608 Section 4.1. 610 Values are registered with a Specification Required [RFC5226] after a 611 two-week review period on the [TBD]@ietf.org mailing list, on the 612 advice of one or more Designated Experts. However, to allow for the 613 allocation of values prior to publication, the Designated Expert(s) 614 may approve registration once they are satisfied that such a 615 specification will be published. 617 Registration requests must be sent to the [TBD]@ietf.org mailing list 618 for review and comment, with an appropriate subject (e.g., "Request 619 for access token type: example"). [[ Note to RFC-EDITOR: The name of 620 the mailing list should be determined in consultation with the IESG 621 and IANA. Suggested name: claims-reg-review. ]] 623 Within the review period, the Designated Expert(s) will either 624 approve or deny the registration request, communicating this decision 625 to the review list and IANA. Denials should include an explanation 626 and, if applicable, suggestions as to how to make the request 627 successful. 629 IANA must only accept registry updates from the Designated Expert(s) 630 and should direct all requests for registration to the review mailing 631 list. 633 9.1.1. Registration Template 635 Claim Name: 636 The name requested (e.g., "example"). This name is case 637 sensitive. Names that match other registered names in a case 638 insensitive manner SHOULD NOT be accepted. 640 Change Controller: 641 For Standards Track RFCs, state "IETF". For others, give the name 642 of the responsible party. Other details (e.g., postal address, 643 email address, home page URI) may also be included. 645 Specification Document(s): 646 Reference to the document(s) that specify the parameter, 647 preferably including URI(s) that can be used to retrieve copies of 648 the document(s). An indication of the relevant sections may also 649 be included but is not required. 651 9.1.2. Initial Registry Contents 653 o Claim Name: "iss" 654 o Change Controller: IETF 655 o Specification Document(s): Section 4.1.1 of [[ this document ]] 657 o Claim Name: "sub" 658 o Change Controller: IETF 659 o Specification Document(s): Section 4.1.2 of [[ this document ]] 661 o Claim Name: "aud" 662 o Change Controller: IETF 663 o Specification Document(s): Section 4.1.3 of [[ this document ]] 665 o Claim Name: "exp" 666 o Change Controller: IETF 667 o Specification Document(s): Section 4.1.4 of [[ this document ]] 669 o Claim Name: "nbf" 670 o Change Controller: IETF 671 o Specification Document(s): Section 4.1.5 of [[ this document ]] 673 o Claim Name: "iat" 674 o Change Controller: IETF 675 o Specification Document(s): Section 4.1.6 of [[ this document ]] 677 o Claim Name: "jti" 678 o Change Controller: IETF 679 o Specification Document(s): Section 4.1.7 of [[ this document ]] 681 o Claim Name: "typ" 682 o Change Controller: IETF 683 o Specification Document(s): Section 4.1.8 of [[ this document ]] 685 9.2. Sub-Namespace Registration of urn:ietf:params:oauth:token-type:jwt 687 9.2.1. Registry Contents 689 This specification registers the value "token-type:jwt" in the IANA 690 urn:ietf:params:oauth registry established in An IETF URN Sub- 691 Namespace for OAuth [RFC6755]. 693 o URN: urn:ietf:params:oauth:token-type:jwt 694 o Common Name: JSON Web Token (JWT) Token Type 695 o Change Controller: IETF 696 o Specification Document(s): [[this document]] 698 9.3. JSON Web Signature and Encryption Type Values Registration 700 9.3.1. Registry Contents 702 This specification registers the "JWT" type value in the IANA JSON 703 Web Signature and Encryption Type Values registry [JWS]: 705 o "typ" Header Parameter Value: "JWT" 706 o Abbreviation for MIME Type: application/jwt 707 o Change Controller: IETF 708 o Specification Document(s): Section 5.1 of [[ this document ]] 710 9.4. Media Type Registration 712 9.4.1. Registry Contents 714 This specification registers the "application/jwt" Media Type 715 [RFC2046] in the MIME Media Type registry [RFC4288] to indicate that 716 the content is a JWT. 718 o Type Name: application 719 o Subtype Name: jwt 720 o Required Parameters: n/a 721 o Optional Parameters: n/a 722 o Encoding considerations: JWT values are encoded as a series of 723 base64url encoded values (some of which may be the empty string) 724 separated by period ('.') characters 725 o Security Considerations: See the Security Considerations section 726 of this document 727 o Interoperability Considerations: n/a 728 o Published Specification: [[ this document ]] 729 o Applications that use this media type: OpenID Connect, Mozilla 730 Browser ID, Salesforce, Google, numerous others 731 o Additional Information: Magic number(s): n/a, File extension(s): 732 n/a, Macintosh file type code(s): n/a 733 o Person & email address to contact for further information: Michael 734 B. Jones, mbj@microsoft.com 735 o Intended Usage: COMMON 736 o Restrictions on Usage: none 737 o Author: Michael B. Jones, mbj@microsoft.com 738 o Change Controller: IETF 740 10. Security Considerations 742 All of the security issues faced by any cryptographic application 743 must be faced by a JWT/JWS/JWE/JWK agent. Among these issues are 744 protecting the user's private and symmetric keys, preventing various 745 attacks, and helping the user avoid mistakes such as inadvertently 746 encrypting a message for the wrong recipient. The entire list of 747 security considerations is beyond the scope of this document. 749 All the security considerations in the JWS specification also apply 750 to JWT, as do the JWE security considerations when encryption is 751 employed. In particular, the JWS JSON Security Considerations and 752 Unicode Comparison Security Considerations apply equally to the JWT 753 Claims Set in the same manner that they do to the JWS Header. 755 While syntactically, the signing and encryption operations for Nested 756 JWTs may be applied in any order, normally senders should sign the 757 message and then encrypt the result (thus encrypting the signature). 758 This prevents attacks in which the signature is stripped, leaving 759 just an encrypted message, as well as providing privacy for the 760 signer. Furthermore, signatures over encrypted text are not 761 considered valid in many jurisdictions. 763 11. References 764 11.1. Normative References 766 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 767 draft-ietf-jose-json-web-algorithms (work in progress), 768 December 2012. 770 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 771 Encryption (JWE)", draft-ietf-jose-json-web-encryption 772 (work in progress), December 2012. 774 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 775 Signature (JWS)", draft-ietf-jose-json-web-signature (work 776 in progress), December 2012. 778 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 779 Extensions (MIME) Part Two: Media Types", RFC 2046, 780 November 1996. 782 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 783 Requirement Levels", BCP 14, RFC 2119, March 1997. 785 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 786 Internet: Timestamps", RFC 3339, July 2002. 788 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 789 10646", STD 63, RFC 3629, November 2003. 791 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 792 Resource Identifier (URI): Generic Syntax", STD 66, 793 RFC 3986, January 2005. 795 [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and 796 Registration Procedures", BCP 13, RFC 4288, December 2005. 798 [RFC4627] Crockford, D., "The application/json Media Type for 799 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 801 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 802 Encodings", RFC 4648, October 2006. 804 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 805 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 806 May 2008. 808 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 809 for OAuth", RFC 6755, October 2012. 811 [USA15] Davis, M., Whistler, K., and M. Duerst, "Unicode 812 Normalization Forms", Unicode Standard Annex 15, 09 2009. 814 11.2. Informative References 816 [CanvasApp] 817 Facebook, "Canvas Applications", 2010. 819 [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", 820 September 2010. 822 [MagicSignatures] 823 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 824 Signatures", January 2011. 826 [OASIS.saml-core-2.0-os] 827 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 828 "Assertions and Protocol for the OASIS Security Assertion 829 Markup Language (SAML) V2.0", OASIS Standard saml-core- 830 2.0-os, March 2005. 832 [RFC3275] Eastlake, D., Reagle, J., and D. Solo, "(Extensible Markup 833 Language) XML-Signature Syntax and Processing", RFC 3275, 834 March 2002. 836 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 837 Unique IDentifier (UUID) URN Namespace", RFC 4122, 838 July 2005. 840 [SWT] Hardt, D. and Y. Goland, "Simple Web Token (SWT)", 841 Version 0.9.5.1, November 2009. 843 [W3C.CR-xml11-20021015] 844 Cowan, J., "Extensible Markup Language (XML) 1.1", W3C 845 CR CR-xml11-20021015, October 2002. 847 [W3C.REC-xml-c14n-20010315] 848 Boyer, J., "Canonical XML Version 1.0", World Wide Web 849 Consortium Recommendation REC-xml-c14n-20010315, 850 March 2001, 851 . 853 Appendix A. Example Encrypted JWT 855 This example encrypts the same claims as used in Section 3.1 to the 856 recipient using RSAES-PKCS1-V1_5 and AES CBC. AES CBC does not have 857 an integrated integrity check, so a separate integrity check 858 calculation is performed using HMAC SHA-256, with separate encryption 859 and integrity keys being derived from a master key using the Concat 860 KDF with the SHA-256 digest function. 862 The following example JWE Header (with line breaks for display 863 purposes only) declares that: 865 o the Content Master Key is encrypted to the recipient using the 866 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and 868 o the Plaintext is encrypted using the AES CBC algorithm with a 128 869 bit key to produce the Ciphertext, with the integrity of the 870 Ciphertext and the parameters used to create it being secured 871 using the HMAC SHA-256 algorithm. 873 {"alg":"RSA1_5","enc":"A128CBC+HS256"} 875 Other than using the bytes of the UTF-8 representation of the JSON 876 Claims Set from Section 3.1 as the plaintext value, the computation 877 of this JWT is identical to the computation of the JWE in Appendix 878 A.2 of [JWE], including the keys used. 880 The final result in this example (with line breaks for display 881 purposes only) is: 883 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDK0hTMjU2In0. 884 pwaFh7yJPivLjjPkzC-GeAyHuy7AinGcS51AZ7TXnwkC80Ow1aW47kcT_UV54ubo 885 nONbeArwOVuR7shveXnwPmucwrk_3OCcHrCbE1HR-Jfme2mF_WR3zUMcwqmU0RlH 886 kwx9txo_sKRasjlXc8RYP-evLCmT1XRXKjtY5l44Gnh0A84hGvVfMxMfCWXh38hi 887 2h8JMjQHGQ3mivVui5lbf-zzb3qXXxNO1ZYoWgs5tP1-T54QYc9Bi9wodFPWNPKB 888 kY-BgewG-Vmc59JqFeprk1O08qhKQeOGCWc0WPC_n_LIpGWH6spRm7KGuYdgDMkQ 889 bd4uuB0uPPLx_euVCdrVrA. 890 AxY8DCtDaGlsbGljb3RoZQ. 891 7MI2lRCaoyYx1HclVXkr8DhmDoikTmOp3IdEmm4qgBThFkqFqOs3ivXLJTku4M0f 892 laMAbGG_X6K8_B-0E-7ak-Olm_-_V03oBUUGTAc-F0A. 893 OwWNxnC-BMEie-GkFHzVWiNiaV3zUHf6fCOGTwbRckU 895 Appendix B. Relationship of JWTs to SAML Assertions 897 SAML 2.0 [OASIS.saml-core-2.0-os] provides a standard for creating 898 security tokens with greater expressivity and more security options 899 than supported by JWTs. However, the cost of this flexibility and 900 expressiveness is both size and complexity. SAML's use of XML 901 [W3C.CR-xml11-20021015] and XML DSIG [RFC3275] contributes to the 902 size of SAML assertions; its use of XML and especially XML 903 Canonicalization [W3C.REC-xml-c14n-20010315] contributes to their 904 complexity. 906 JWTs are intended to provide a simple security token format that is 907 small enough to fit into HTTP headers and query arguments in URIs. 908 It does this by supporting a much simpler token model than SAML and 909 using the JSON [RFC4627] object encoding syntax. It also supports 910 securing tokens using Message Authentication Codes (MACs) and digital 911 signatures using a smaller (and less flexible) format than XML DSIG. 913 Therefore, while JWTs can do some of the things SAML assertions do, 914 JWTs are not intended as a full replacement for SAML assertions, but 915 rather as a token format to be used when ease of implementation or 916 compactness are considerations. 918 SAML Assertions are always statements made by an entity about a 919 subject. JWTs are often used in the same manner, with the entity 920 making the statements being represented by the "iss" (issuer) claim, 921 and the subject being represented by the "sub" (subject) claim. 922 However, with these claims being optional, other uses of the JWT 923 format are also permitted. 925 Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs) 927 Both JWTs and Simple Web Tokens SWT [SWT], at their core, enable sets 928 of claims to be communicated between applications. For SWTs, both 929 the claim names and claim values are strings. For JWTs, while claim 930 names are strings, claim values can be any JSON type. Both token 931 types offer cryptographic protection of their content: SWTs with HMAC 932 SHA-256 and JWTs with a choice of algorithms, including signature, 933 MAC, and encryption algorithms. 935 Appendix D. Acknowledgements 937 The authors acknowledge that the design of JWTs was intentionally 938 influenced by the design and simplicity of Simple Web Tokens [SWT] 939 and ideas for JSON tokens that Dick Hardt discussed within the OpenID 940 community. 942 Solutions for signing JSON content were previously explored by Magic 943 Signatures [MagicSignatures], JSON Simple Sign [JSS], and Canvas 944 Applications [CanvasApp], all of which influenced this draft. 946 This specification is the work of the OAuth Working Group, which 947 includes dozens of active and dedicated participants. In particular, 948 the following individuals contributed ideas, feedback, and wording 949 that influenced this specification: 951 Dirk Balfanz, Richard Barnes, Brian Campbell, Breno de Medeiros, Dick 952 Hardt, Joe Hildebrand, Jeff Hodges, Edmund Jay, Yaron Y. Goland, Ben 953 Laurie, James Manger, Prateek Mishra, Tony Nadalin, Axel Nennker, 954 John Panzer, Emmanuel Raviart, David Recordon, Eric Rescorla, Jim 955 Schaad, Paul Tarjan, Hannes Tschofenig, and Sean Turner. 957 Hannes Tschofenig and Derek Atkins chaired the OAuth working group 958 and Sean Turner and Stephen Farrell served as Security area directors 959 during the creation of this specification. 961 Appendix E. Open Issues 963 [[ to be removed by the RFC editor before publication as an RFC ]] 965 The following items remain to be considered or done in this draft: 967 o Track changes to the underlying JOSE specifications. 969 o Should all claims continue to be required to be understood by 970 implementations using them when used in a security-related context 971 or should a means of declaring that specific claims may be safely 972 ignored if not understood should be defined? This is related to 973 the similar JOSE issue about whether all header fields must 974 continue to be understood. 976 Appendix F. Document History 978 [[ to be removed by the RFC editor before publication as an RFC ]] 980 -06 982 o Changed the name of the "prn" claim to "sub" (subject) both to 983 more closely align with SAML name usage and to use a more 984 intuitive name. 986 o Allow JWTs to have multiple audiences. 988 o Applied editorial improvements suggested by Jeff Hodges, Prateek 989 Mishra, and Hannes Tschofenig. Many of these simplified the 990 terminology used. 992 o Explained why Nested JWTs should be signed and then encrypted. 994 o Clarified statements of the form "This claim is OPTIONAL" to "Use 995 of this claim is OPTIONAL". 997 o Referenced String Comparison Rules in JWS. 999 o Added seriesInfo information to Internet Draft references. 1001 -05 1003 o Updated values for example AES CBC calculations. 1005 -04 1007 o Promoted Initialization Vector from being a header parameter to 1008 being a top-level JWE element. This saves approximately 16 bytes 1009 in the compact serialization, which is a significant savings for 1010 some use cases. Promoting the Initialization Vector out of the 1011 header also avoids repeating this shared value in the JSON 1012 serialization. 1014 o Applied changes made by the RFC Editor to RFC 6749's registry 1015 language to this specification. 1017 o Reference RFC 6755 -- An IETF URN Sub-Namespace for OAuth. 1019 -03 1021 o Added statement that "StringOrURI values are compared as case- 1022 sensitive strings with no transformations or canonicalizations 1023 applied". 1025 o Indented artwork elements to better distinguish them from the body 1026 text. 1028 -02 1030 o Added an example of an encrypted JWT. 1032 o Added this language to Registration Templates: "This name is case 1033 sensitive. Names that match other registered names in a case 1034 insensitive manner SHOULD NOT be accepted." 1036 o Applied editorial suggestions. 1038 -01 1040 o Added the "cty" (content type) header parameter for declaring type 1041 information about the secured content, as opposed to the "typ" 1042 (type) header parameter, which declares type information about 1043 this object. This significantly simplified nested JWTs. 1045 o Moved description of how to determine whether a header is for a 1046 JWS or a JWE from the JWT spec to the JWE spec. 1048 o Changed registration requirements from RFC Required to 1049 Specification Required with Expert Review. 1051 o Added Registration Template sections for defined registries. 1053 o Added Registry Contents sections to populate registry values. 1055 o Added "Collision Resistant Namespace" to the terminology section. 1057 o Numerous editorial improvements. 1059 -00 1061 o Created the initial IETF draft based upon 1062 draft-jones-json-web-token-10 with no normative changes. 1064 Authors' Addresses 1066 Michael B. Jones 1067 Microsoft 1069 Email: mbj@microsoft.com 1070 URI: http://self-issued.info/ 1072 John Bradley 1073 Ping Identity 1075 Email: ve7jtb@ve7jtb.com 1077 Nat Sakimura 1078 Nomura Research Institute 1080 Email: n-sakimura@nri.co.jp