idnits 2.17.1 draft-ietf-oauth-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 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 (July 11, 2013) is 3936 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'ECMAScript' ** 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 Summary: 4 errors (**), 0 flaws (~~), 2 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: January 12, 2014 Ping Identity 6 N. Sakimura 7 NRI 8 July 11, 2013 10 JSON Web Token (JWT) 11 draft-ietf-oauth-json-web-token-09 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 January 12, 2014. 42 Copyright Notice 44 Copyright (c) 2013 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 . . . . . . . . . . . . . . . . . . . . . . . . . 5 60 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5 61 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 62 3. JSON Web Token (JWT) Overview . . . . . . . . . . . . . . . . 7 63 3.1. Example JWT . . . . . . . . . . . . . . . . . . . . . . . 7 64 4. JWT Claims . . . . . . . . . . . . . . . . . . . . . . . . . . 8 65 4.1. Reserved Claim Names . . . . . . . . . . . . . . . . . . . 9 66 4.1.1. "iss" (Issuer) Claim . . . . . . . . . . . . . . . . . 9 67 4.1.2. "sub" (Subject) Claim . . . . . . . . . . . . . . . . 9 68 4.1.3. "aud" (Audience) Claim . . . . . . . . . . . . . . . . 9 69 4.1.4. "exp" (Expiration Time) Claim . . . . . . . . . . . . 10 70 4.1.5. "nbf" (Not Before) Claim . . . . . . . . . . . . . . . 10 71 4.1.6. "iat" (Issued At) Claim . . . . . . . . . . . . . . . 10 72 4.1.7. "jti" (JWT ID) Claim . . . . . . . . . . . . . . . . . 10 73 4.1.8. "typ" (Type) Claim . . . . . . . . . . . . . . . . . . 10 74 4.2. Public Claim Names . . . . . . . . . . . . . . . . . . . . 11 75 4.3. Private Claim Names . . . . . . . . . . . . . . . . . . . 11 76 5. JWT Header . . . . . . . . . . . . . . . . . . . . . . . . . . 11 77 5.1. "typ" (Type) Header Parameter . . . . . . . . . . . . . . 11 78 5.2. "cty" (Content Type) Header Parameter . . . . . . . . . . 12 79 6. Plaintext JWTs . . . . . . . . . . . . . . . . . . . . . . . . 12 80 6.1. Example Plaintext JWT . . . . . . . . . . . . . . . . . . 12 81 7. Rules for Creating and Validating a JWT . . . . . . . . . . . 13 82 7.1. String Comparison Rules . . . . . . . . . . . . . . . . . 15 83 8. Cryptographic Algorithms . . . . . . . . . . . . . . . . . . . 15 84 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 85 9.1. JSON Web Token Claims Registry . . . . . . . . . . . . . . 16 86 9.1.1. Registration Template . . . . . . . . . . . . . . . . 16 87 9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 17 88 9.2. Sub-Namespace Registration of 89 urn:ietf:params:oauth:token-type:jwt . . . . . . . . . . . 17 90 9.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 17 91 9.3. JSON Web Signature and Encryption Type Values 92 Registration . . . . . . . . . . . . . . . . . . . . . . . 18 93 9.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 18 94 9.4. Media Type Registration . . . . . . . . . . . . . . . . . 18 95 9.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 18 96 10. Security Considerations . . . . . . . . . . . . . . . . . . . 19 97 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19 98 11.1. Normative References . . . . . . . . . . . . . . . . . . . 19 99 11.2. Informative References . . . . . . . . . . . . . . . . . . 20 100 Appendix A. Example Encrypted JWT . . . . . . . . . . . . . . . . 21 101 Appendix B. Relationship of JWTs to SAML Assertions . . . . . . . 22 102 Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs) . . 23 103 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 23 104 Appendix E. Document History . . . . . . . . . . . . . . . . . . 23 105 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 26 107 1. Introduction 109 JSON Web Token (JWT) is a compact claims representation format 110 intended for space constrained environments such as HTTP 111 Authorization headers and URI query parameters. JWTs encode claims 112 to be transmitted as a JavaScript Object Notation (JSON) [RFC4627] 113 object that is used as the payload of a JSON Web Signature (JWS) 114 [JWS] structure or as the plaintext of a JSON Web Encryption (JWE) 115 [JWE] structure, enabling the claims to be digitally signed or MACed 116 and/or encrypted. JWTs are always represented using the JWS Compact 117 Serialization or the JWE Compact Serialization. 119 The suggested pronunciation of JWT is the same as the English word 120 "jot". 122 1.1. Notational Conventions 124 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 125 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 126 document are to be interpreted as described in Key words for use in 127 RFCs to Indicate Requirement Levels [RFC2119]. 129 2. Terminology 131 JSON Web Token (JWT) A string representing a set of claims as a JSON 132 object that is encoded in a JWS or JWE, enabling the claims to be 133 digitally signed or MACed and/or encrypted. 135 Base64url Encoding The URL- and filename-safe Base64 encoding 136 described in RFC 4648 [RFC4648], Section 5, with the (non URL- 137 safe) '=' padding characters omitted, as permitted by Section 3.2. 138 (See Appendix C of [JWS] for notes on implementing base64url 139 encoding without padding.) 141 JSON Text Object A UTF-8 [RFC3629] encoded text string representing 142 a JSON object; the syntax of JSON objects is defined in Section 143 2.2 of [RFC4627]. 145 JWT Header A JSON Text Object that describes the cryptographic 146 operations applied to the JWT. When the JWT is digitally signed 147 or MACed, the JWT Header is a JWS Header. When the JWT is 148 encrypted, the JWT Header is a JWE Header. 150 Header Parameter Name The name of a member of the JWT Header. 152 Header Parameter Value The value of a member of the JWT Header. 154 JWT Claims Set A JSON Text Object that contains the Claims conveyed 155 by the JWT. 157 Claim A piece of information asserted about a subject. A Claim is 158 represented as a name/value pair consisting of a Claim Name and a 159 Claim Value. 161 Claim Name The name portion of a Claim representation. A Claim Name 162 is always a string. 164 Claim Value The value portion of a Claim representation. A Claim 165 Value can be any JSON value. 167 Encoded JWT Header Base64url encoding of the JWT Header. 169 Nested JWT A JWT in which nested signing and/or encryption are 170 employed. In nested JWTs, a JWT is used as the payload or 171 plaintext value of an enclosing JWS or JWE structure, 172 respectively. 174 Plaintext JWT A JWT whose Claims are not integrity protected or 175 encrypted. 177 Collision Resistant Namespace A namespace that allows names to be 178 allocated in a manner such that they are highly unlikely to 179 collide with other names. For instance, collision resistance can 180 be achieved through administrative delegation of portions of the 181 namespace or through use of collision-resistant name allocation 182 functions. Examples of Collision Resistant Namespaces include: 183 Domain Names, Object Identifiers (OIDs) as defined in the ITU-T 184 X.660 and X.670 Recommendation series, and Universally Unique 185 IDentifiers (UUIDs) [RFC4122]. When using an administratively 186 delegated namespace, the definer of a name needs to take 187 reasonable precautions to ensure they are in control of the 188 portion of the namespace they use to define the name. 190 StringOrURI A JSON string value, with the additional requirement 191 that while arbitrary string values MAY be used, any value 192 containing a ":" character MUST be a URI [RFC3986]. StringOrURI 193 values are compared as case-sensitive strings with no 194 transformations or canonicalizations applied. 196 IntDate A JSON numeric value representing the number of seconds from 197 1970-01-01T0:0:0Z UTC until the specified UTC date/time. See RFC 198 3339 [RFC3339] for details regarding date/times in general and UTC 199 in particular. 201 3. JSON Web Token (JWT) Overview 203 JWTs represent a set of claims as a JSON object that is encoded in a 204 JWS and/or JWE structure. This JSON object is the JWT Claims Set. As 205 per RFC 4627 [RFC4627] Section 2.2, the JSON object consists of zero 206 or more name/value pairs (or members), where the names are strings 207 and the values are arbitrary JSON values. These members are the 208 claims represented by the JWT. 210 The member names within the JWT Claims Set are referred to as Claim 211 Names. The corresponding values are referred to as Claim Values. 213 The contents of the JWT Header describe the cryptographic operations 214 applied to the JWT Claims Set. If the JWT Header is a JWS Header, the 215 JWT is represented as a JWS, and the claims are digitally signed or 216 MACed, with the JWT Claims Set being the JWS Payload. If the JWT 217 Header is a JWE Header, the JWT is represented as a JWE, and the 218 claims are encrypted, with the JWT Claims Set being the input 219 Plaintext. A JWT may be enclosed in another JWE or JWS structure to 220 create a Nested JWT, enabling nested signing and encryption to be 221 performed. 223 A JWT is represented as a sequence of URL-safe parts separated by 224 period ('.') characters. Each part contains a base64url encoded 225 value. The number of parts in the JWT is dependent upon the 226 representation of the resulting JWS or JWE object using the JWS 227 Compact Serialization or the JWE Compact Serialization. 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 octets 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 The following octet sequence, which is the UTF-8 representation of 251 the JWT Claims Set above, is the JWS Payload: 253 [123, 34, 105, 115, 115, 34, 58, 34, 106, 111, 101, 34, 44, 13, 10, 254 32, 34, 101, 120, 112, 34, 58, 49, 51, 48, 48, 56, 49, 57, 51, 56, 255 48, 44, 13, 10, 32, 34, 104, 116, 116, 112, 58, 47, 47, 101, 120, 97, 256 109, 112, 108, 101, 46, 99, 111, 109, 47, 105, 115, 95, 114, 111, 257 111, 116, 34, 58, 116, 114, 117, 101, 125] 259 Base64url encoding the JWS Payload yields this Encoded JWS Payload 260 (with line breaks for display purposes only): 262 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly 263 9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ 265 Signing the Encoded JWS Header and Encoded JWS Payload with the HMAC 266 SHA-256 algorithm and base64url encoding the signature in the manner 267 specified in [JWS], yields this Encoded JWS Signature: 269 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 271 Concatenating these parts in this order with period ('.') characters 272 between the parts yields this complete JWT (with line breaks for 273 display purposes only): 275 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 276 . 277 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 278 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 279 . 280 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 282 This computation is illustrated in more detail in Appendix A.1 of 283 [JWS]. See Appendix A for an example of an encrypted JWT. 285 4. JWT Claims 287 The JWT Claims Set represents a JSON object whose members are the 288 claims conveyed by the JWT. The Claim Names within a JWT Claims Set 289 MUST be unique; receipients MUST either reject JWTs with duplicate 290 Claim Names or use a JSON parser that returns only the lexically last 291 duplicate member name, as specified in Section 15.12 (The JSON 292 Object) of ECMAScript 5.1 [ECMAScript]. 294 The set of claims that a JWT must contain to be considered valid is 295 context-dependent and is outside the scope of this specification. 296 Specific applications of JWTs will require implementations to 297 understand and process some claims in particular ways. However, in 298 the absence of such requirements, all claims that are not understood 299 by implementations SHOULD be ignored. 301 There are three classes of JWT Claim Names: Reserved Claim Names, 302 Public Claim Names, and Private Claim Names. 304 4.1. Reserved Claim Names 306 The following Claim Names are reserved. None of the claims defined 307 below are intended to be mandatory to use, but rather, provide a 308 starting point for a set of useful, interoperable claims. All the 309 names are short because a core goal of JWTs is for the representation 310 to be compact. Additional reserved Claim Names can be defined via 311 the IANA JSON Web Token Claims registry Section 9.1. 313 4.1.1. "iss" (Issuer) Claim 315 The "iss" (issuer) claim identifies the principal that issued the 316 JWT. The processing of this claim is generally application specific. 317 The "iss" value is a case sensitive string containing a StringOrURI 318 value. Use of this claim is OPTIONAL. 320 4.1.2. "sub" (Subject) Claim 322 The "sub" (subject) claim identifies the principal that is the 323 subject of the JWT. The Claims in a JWT are normally statements 324 about the subject. The processing of this claim is generally 325 application specific. The "sub" value is a case sensitive string 326 containing a StringOrURI value. Use of this claim is OPTIONAL. 328 4.1.3. "aud" (Audience) Claim 330 The "aud" (audience) claim identifies the audiences that the JWT is 331 intended for. Each principal intended to process the JWT MUST 332 identify itself with a value in audience claim. If the principal 333 processing the claim does not identify itself with a value in the 334 "aud" claim, then the JWT MUST be rejected. In the general case, the 335 "aud" value is an array of case sensitive strings, each containing a 336 StringOrURI value. In the special case when the JWT has one 337 audience, the "aud" value MAY be a single case sensitive string 338 containing a StringOrURI value. The interpretation of audience 339 values is generally application specific. Use of this claim is 340 OPTIONAL. 342 4.1.4. "exp" (Expiration Time) Claim 344 The "exp" (expiration time) claim identifies the expiration time on 345 or after which the JWT MUST NOT be accepted for processing. The 346 processing of the "exp" claim requires that the current date/time 347 MUST be before the expiration date/time listed in the "exp" claim. 348 Implementers MAY provide for some small leeway, usually no more than 349 a few minutes, to account for clock skew. Its value MUST be a number 350 containing an IntDate value. Use of this claim is OPTIONAL. 352 4.1.5. "nbf" (Not Before) Claim 354 The "nbf" (not before) claim identifies the time before which the JWT 355 MUST NOT be accepted for processing. The processing of the "nbf" 356 claim requires that the current date/time MUST be after or equal to 357 the not-before date/time listed in the "nbf" claim. Implementers MAY 358 provide for some small leeway, usually no more than a few minutes, to 359 account for clock skew. Its value MUST be a number containing an 360 IntDate value. Use of this claim is OPTIONAL. 362 4.1.6. "iat" (Issued At) Claim 364 The "iat" (issued at) claim identifies the time at which the JWT was 365 issued. This claim can be used to determine the age of the JWT. Its 366 value MUST be a number containing an IntDate value. Use of this 367 claim is OPTIONAL. 369 4.1.7. "jti" (JWT ID) Claim 371 The "jti" (JWT ID) claim provides a unique identifier for the JWT. 372 The identifier value MUST be assigned in a manner that ensures that 373 there is a negligible probability that the same value will be 374 accidentally assigned to a different data object. The "jti" claim 375 can be used to prevent the JWT from being replayed. The "jti" value 376 is a case sensitive string. Use of this claim is OPTIONAL. 378 4.1.8. "typ" (Type) Claim 380 The "typ" (type) claim MAY be used to declare a type for the contents 381 of this JWT Claims Set in an application-specific manner in contexts 382 where this is useful to the application. The "typ" value is a case 383 sensitive string. Use of this claim is OPTIONAL. 385 The values used for the "typ" claim come from the same value space as 386 the "typ" header parameter, with the same rules applying. 388 4.2. Public Claim Names 390 Claim Names can be defined at will by those using JWTs. However, in 391 order to prevent collisions, any new Claim Name SHOULD either be 392 registered in the IANA JSON Web Token Claims registry Section 9.1 or 393 be a Public Name: a value that contains a Collision Resistant 394 Namespace. In each case, the definer of the name or value needs to 395 take reasonable precautions to make sure they are in control of the 396 part of the namespace they use to define the Claim Name. 398 4.3. Private Claim Names 400 A producer and consumer of a JWT MAY agree to use Claim Names that 401 are Private Names: names that are not Reserved Names Section 4.1 or 402 Public Names Section 4.2. Unlike Public Names, Private Names are 403 subject to collision and should be used with caution. 405 5. JWT Header 407 The members of the JSON object represented by the JWT Header describe 408 the cryptographic operations applied to the JWT and optionally, 409 additional properties of the JWT. The member names within the JWT 410 Header are referred to as Header Parameter Names. These names MUST 411 be unique; receipients MUST either reject JWTs with duplicate Header 412 Parameter Names or use a JSON parser that returns only the lexically 413 last duplicate member name, as specified in Section 15.12 (The JSON 414 Object) of ECMAScript 5.1 [ECMAScript]. The corresponding values are 415 referred to as Header Parameter Values. 417 JWS Header Parameters are defined by [JWS]. JWE Header Parameters 418 are defined by [JWE]. This specification further specifies the use 419 of the following header parameter in both the cases where the JWT is 420 a JWS and where it is a JWE. 422 5.1. "typ" (Type) Header Parameter 424 The "typ" (type) header parameter MAY be used to declare the type of 425 this JWT in an application-specific manner in contexts where this is 426 useful to the application. This parameter has no effect upon the JWT 427 processing. If present, it is RECOMMENDED that its value be either 428 "JWT" or "urn:ietf:params:oauth:token-type:jwt" to indicate that this 429 object is a JWT. The "typ" value is a case sensitive string. Use of 430 this header parameter is OPTIONAL. 432 5.2. "cty" (Content Type) Header Parameter 434 The "cty" (content type) header parameter is used to declare 435 structural information about the JWT. Its value MUST be a string. 437 In the normal case where nested signing or encryption operations are 438 not employed, the use of this header parameter is NOT RECOMMENDED. 439 In the case that nested signing or encryption is employed, the use of 440 this header parameter is REQUIRED; in this case, the value MUST be 441 "JWT", to indicate that a Nested JWT is carried in this JWT. 443 The values used for the "cty" header parameter come from the same 444 value space as the "typ" header parameter, with the same rules 445 applying. 447 6. Plaintext JWTs 449 To support use cases where the JWT content is secured by a means 450 other than a signature and/or encryption contained within the JWT 451 (such as a signature on a data structure containing the JWT), JWTs 452 MAY also be created without a signature or encryption. A plaintext 453 JWT is a JWS using the "none" JWS "alg" header parameter value 454 defined in JSON Web Algorithms (JWA) [JWA]; it is a JWS with the 455 empty string for its JWS Signature value. 457 6.1. Example Plaintext JWT 459 The following example JWT Header declares that the encoded object is 460 a Plaintext JWT: 462 {"alg":"none"} 464 Base64url encoding the octets of the UTF-8 representation of the JWT 465 Header yields this Encoded JWT Header: 467 eyJhbGciOiJub25lIn0 469 The following is an example of a JWT Claims Set: 471 {"iss":"joe", 472 "exp":1300819380, 473 "http://example.com/is_root":true} 475 Base64url encoding the octets of the UTF-8 representation of the JWT 476 Claims Set yields this Encoded JWS Payload (with line breaks for 477 display purposes only): 479 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 480 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 482 The Encoded JWS Signature is the empty string. 484 Concatenating these parts in this order with period ('.') characters 485 between the parts yields this complete JWT (with line breaks for 486 display purposes only): 488 eyJhbGciOiJub25lIn0 489 . 490 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 491 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 492 . 494 7. Rules for Creating and Validating a JWT 496 To create a JWT, one MUST perform these steps. The order of the 497 steps is not significant in cases where there are no dependencies 498 between the inputs and outputs of the steps. 500 1. Create a JWT Claims Set containing the desired claims. Note that 501 white space is explicitly allowed in the representation and no 502 canonicalization is performed before encoding. 504 2. Let the Message be the octets of the UTF-8 representation of the 505 JWT Claims Set. 507 3. Create a JWT Header containing the desired set of header 508 parameters. The JWT MUST conform to either the [JWS] or [JWE] 509 specifications. Note that white space is explicitly allowed in 510 the representation and no canonicalization is performed before 511 encoding. 513 4. Base64url encode the octets of the UTF-8 representation of the 514 JWT Header. Let this be the Encoded JWT Header. 516 5. Depending upon whether the JWT is a JWS or JWE, there are two 517 cases: 519 * If the JWT is a JWS, create a JWS using the JWT Header as the 520 JWS Header and the Message as the JWS Payload; all steps 521 specified in [JWS] for creating a JWS MUST be followed. 523 * Else, if the JWT is a JWE, create a JWE using the JWT Header 524 as the JWE Header and the Message as the JWE Plaintext; all 525 steps specified in [JWE] for creating a JWE MUST be followed. 527 6. If a nested signing or encryption operation will be performed, 528 let the Message be the JWS or JWE, and return to Step 3, using a 529 "cty" (content type) value of "JWT" in the new JWT Header created 530 in that step. 532 7. Otherwise, let the resulting JWT be the JWS or JWE. 534 When validating a JWT the following steps MUST be taken. The order 535 of the steps is not significant in cases where there are no 536 dependencies between the inputs and outputs of the steps. If any of 537 the listed steps fails then the JWT MUST be rejected for processing. 539 1. The JWT MUST contain at least one period ('.') character. 541 2. Let the Encoded JWT Header be the portion of the JWT before the 542 first period ('.') character. 544 3. The Encoded JWT Header MUST be successfully base64url decoded 545 following the restriction given in this specification that no 546 padding characters have been used. 548 4. The resulting JWT Header MUST be completely valid JSON syntax 549 conforming to RFC 4627 [RFC4627]. 551 5. The resulting JWT Header MUST be validated to only include 552 parameters and values whose syntax and semantics are both 553 understood and supported or that are specified as being ignored 554 when not understood. 556 6. Determine whether the JWT is a JWS or a JWE by examining the 557 "alg" (algorithm) header value and optionally, the "enc" 558 (encryption method) header value, if present. 560 7. Depending upon whether the JWT is a JWS or JWE, there are two 561 cases: 563 * If the JWT is a JWS, all steps specified in [JWS] for 564 validating a JWS MUST be followed. Let the Message be the 565 result of base64url decoding the JWS Payload. 567 * Else, if the JWT is a JWE, all steps specified in [JWE] for 568 validating a JWE MUST be followed. Let the Message be the 569 JWE Plaintext. 571 8. If the JWT Header contains a "cty" (content type) value of 572 "JWT", then the Message is a JWT that was the subject of nested 573 signing or encryption operations. In this case, return to Step 574 1, using the Message as the JWT. 576 9. Otherwise, let the JWT Claims Set be the Message. 578 10. The JWT Claims Set MUST be completely valid JSON syntax 579 conforming to RFC 4627 [RFC4627]. 581 7.1. String Comparison Rules 583 Processing a JWT inevitably requires comparing known strings to 584 values in JSON objects. For example, in checking what the algorithm 585 is, the Unicode string encoding "alg" will be checked against the 586 member names in the JWT Header to see if there is a matching Header 587 Parameter Name. 589 Comparisons between JSON strings and other Unicode strings MUST be 590 performed by comparing Unicode code points without normalization as 591 specified in the String Comparison Rules in Section 5.3 of [JWS]. 593 8. Cryptographic Algorithms 595 JWTs use JSON Web Signature (JWS) [JWS] and JSON Web Encryption (JWE) 596 [JWE] to sign and/or encrypt the contents of the JWT. 598 Of the JWA signing algorithms, only HMAC SHA-256 ("HS256") and "none" 599 MUST be implemented by conforming JWT implementations. It is 600 RECOMMENDED that implementations also support RSASSA-PKCS1-V1_5 with 601 the SHA-256 hash algorithm ("RS256") and ECDSA using the P-256 curve 602 and the SHA-256 hash algorithm ("ES256"). Support for other 603 algorithms and key sizes is OPTIONAL. 605 If an implementation provides encryption capabilities, of the JWA 606 encryption algorithms, only RSAES-PKCS1-V1_5 with 2048 bit keys 607 ("RSA1_5"), AES Key Wrap with 128 and 256 bit keys ("A128KW" and 608 "A256KW"), and the composite authenticated encryption algorithm using 609 AES CBC and HMAC SHA-2 ("A128CBC-HS256" and "A256CBC-HS512") MUST be 610 implemented by conforming implementations. It is RECOMMENDED that 611 implementations also support using ECDH-ES to agree upon a key used 612 to wrap the Content Encryption Key ("ECDH-ES+A128KW" and 613 "ECDH-ES+A256KW") and AES in Galois/Counter Mode (GCM) with 128 bit 614 and 256 bit keys ("A128GCM" and "A256GCM"). Support for other 615 algorithms and key sizes is OPTIONAL. 617 9. IANA Considerations 618 9.1. JSON Web Token Claims Registry 620 This specification establishes the IANA JSON Web Token Claims 621 registry for reserved JWT Claim Names. The registry records the 622 reserved Claim Name and a reference to the specification that defines 623 it. This specification registers the Claim Names defined in 624 Section 4.1. 626 Values are registered with a Specification Required [RFC5226] after a 627 two-week review period on the [TBD]@ietf.org mailing list, on the 628 advice of one or more Designated Experts. However, to allow for the 629 allocation of values prior to publication, the Designated Expert(s) 630 may approve registration once they are satisfied that such a 631 specification will be published. 633 Registration requests must be sent to the [TBD]@ietf.org mailing list 634 for review and comment, with an appropriate subject (e.g., "Request 635 for access token type: example"). [[ Note to RFC-EDITOR: The name of 636 the mailing list should be determined in consultation with the IESG 637 and IANA. Suggested name: claims-reg-review. ]] 639 Within the review period, the Designated Expert(s) will either 640 approve or deny the registration request, communicating this decision 641 to the review list and IANA. Denials should include an explanation 642 and, if applicable, suggestions as to how to make the request 643 successful. 645 IANA must only accept registry updates from the Designated Expert(s) 646 and should direct all requests for registration to the review mailing 647 list. 649 9.1.1. Registration Template 651 Claim Name: 652 The name requested (e.g., "example"). This name is case 653 sensitive. Names that match other registered names in a case 654 insensitive manner SHOULD NOT be accepted. 656 Change Controller: 657 For Standards Track RFCs, state "IETF". For others, give the name 658 of the responsible party. Other details (e.g., postal address, 659 email address, home page URI) may also be included. 661 Specification Document(s): 662 Reference to the document(s) that specify the parameter, 663 preferably including URI(s) that can be used to retrieve copies of 664 the document(s). An indication of the relevant sections may also 665 be included but is not required. 667 9.1.2. Initial Registry Contents 669 o Claim Name: "iss" 670 o Change Controller: IETF 671 o Specification Document(s): Section 4.1.1 of [[ this document ]] 673 o Claim Name: "sub" 674 o Change Controller: IETF 675 o Specification Document(s): Section 4.1.2 of [[ this document ]] 677 o Claim Name: "aud" 678 o Change Controller: IETF 679 o Specification Document(s): Section 4.1.3 of [[ this document ]] 681 o Claim Name: "exp" 682 o Change Controller: IETF 683 o Specification Document(s): Section 4.1.4 of [[ this document ]] 685 o Claim Name: "nbf" 686 o Change Controller: IETF 687 o Specification Document(s): Section 4.1.5 of [[ this document ]] 689 o Claim Name: "iat" 690 o Change Controller: IETF 691 o Specification Document(s): Section 4.1.6 of [[ this document ]] 693 o Claim Name: "jti" 694 o Change Controller: IETF 695 o Specification Document(s): Section 4.1.7 of [[ this document ]] 697 o Claim Name: "typ" 698 o Change Controller: IETF 699 o Specification Document(s): Section 4.1.8 of [[ this document ]] 701 9.2. Sub-Namespace Registration of urn:ietf:params:oauth:token-type:jwt 703 9.2.1. Registry Contents 705 This specification registers the value "token-type:jwt" in the IANA 706 urn:ietf:params:oauth registry established in An IETF URN Sub- 707 Namespace for OAuth [RFC6755], which can be used to indicate that the 708 content is a JWT. 710 o URN: urn:ietf:params:oauth:token-type:jwt 711 o Common Name: JSON Web Token (JWT) Token Type 712 o Change Controller: IETF 713 o Specification Document(s): [[this document]] 715 9.3. JSON Web Signature and Encryption Type Values Registration 717 9.3.1. Registry Contents 719 This specification registers the "JWT" type value in the IANA JSON 720 Web Signature and Encryption Type Values registry [JWS], which can be 721 used to indicate that the content is a JWT. 723 o "typ" Header Parameter Value: "JWT" 724 o Abbreviation for MIME Type: application/jwt 725 o Change Controller: IETF 726 o Specification Document(s): Section 5.1 of [[ this document ]] 728 9.4. Media Type Registration 730 9.4.1. Registry Contents 732 This specification registers the "application/jwt" Media Type 733 [RFC2046] in the MIME Media Type registry [RFC4288], which can be 734 used to indicate that the content is a JWT. 736 o Type Name: application 737 o Subtype Name: jwt 738 o Required Parameters: n/a 739 o Optional Parameters: n/a 740 o Encoding considerations: JWT values are encoded as a series of 741 base64url encoded values (some of which may be the empty string) 742 separated by period ('.') characters 743 o Security Considerations: See the Security Considerations section 744 of [[ this document ]] 745 o Interoperability Considerations: n/a 746 o Published Specification: [[ this document ]] 747 o Applications that use this media type: OpenID Connect, Mozilla 748 Persona, Salesforce, Google, numerous others 749 o Additional Information: Magic number(s): n/a, File extension(s): 750 n/a, Macintosh file type code(s): n/a 751 o Person & email address to contact for further information: Michael 752 B. Jones, mbj@microsoft.com 753 o Intended Usage: COMMON 754 o Restrictions on Usage: none 755 o Author: Michael B. Jones, mbj@microsoft.com 756 o Change Controller: IETF 758 10. Security Considerations 760 All of the security issues faced by any cryptographic application 761 must be faced by a JWT/JWS/JWE/JWK agent. Among these issues are 762 protecting the user's private and symmetric keys, preventing various 763 attacks, and helping the user avoid mistakes such as inadvertently 764 encrypting a message for the wrong recipient. The entire list of 765 security considerations is beyond the scope of this document. 767 All the security considerations in the JWS specification also apply 768 to JWT, as do the JWE security considerations when encryption is 769 employed. In particular, the JWS JSON Security Considerations and 770 Unicode Comparison Security Considerations apply equally to the JWT 771 Claims Set in the same manner that they do to the JWS Header. 773 While syntactically, the signing and encryption operations for Nested 774 JWTs may be applied in any order, normally senders should sign the 775 message and then encrypt the result (thus encrypting the signature). 776 This prevents attacks in which the signature is stripped, leaving 777 just an encrypted message, as well as providing privacy for the 778 signer. Furthermore, signatures over encrypted text are not 779 considered valid in many jurisdictions. 781 Note that potential concerns about security issues related to the 782 order of signing and encryption operations are already addressed by 783 the underlying JWS and JWE specifications; in particular, because JWE 784 only supports the use of authenticated encryption algorithms, 785 cryptographic concerns about the potential need to sign after 786 encryption that apply in many contexts do not apply to this 787 specification. 789 11. References 791 11.1. Normative References 793 [ECMAScript] 794 Ecma International, "ECMAScript Language Specification, 795 5.1 Edition", ECMA 262, June 2011. 797 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 798 draft-ietf-jose-json-web-algorithms (work in progress), 799 July 2013. 801 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 802 Encryption (JWE)", draft-ietf-jose-json-web-encryption 803 (work in progress), July 2013. 805 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 806 Signature (JWS)", draft-ietf-jose-json-web-signature (work 807 in progress), July 2013. 809 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 810 Extensions (MIME) Part Two: Media Types", RFC 2046, 811 November 1996. 813 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 814 Requirement Levels", BCP 14, RFC 2119, March 1997. 816 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 817 Internet: Timestamps", RFC 3339, July 2002. 819 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 820 10646", STD 63, RFC 3629, November 2003. 822 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 823 Resource Identifier (URI): Generic Syntax", STD 66, 824 RFC 3986, January 2005. 826 [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and 827 Registration Procedures", RFC 4288, December 2005. 829 [RFC4627] Crockford, D., "The application/json Media Type for 830 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 832 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 833 Encodings", RFC 4648, October 2006. 835 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 836 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 837 May 2008. 839 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 840 for OAuth", RFC 6755, October 2012. 842 11.2. Informative References 844 [CanvasApp] 845 Facebook, "Canvas Applications", 2010. 847 [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", 848 September 2010. 850 [MagicSignatures] 851 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 852 Signatures", January 2011. 854 [OASIS.saml-core-2.0-os] 855 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 856 "Assertions and Protocol for the OASIS Security Assertion 857 Markup Language (SAML) V2.0", OASIS Standard saml-core- 858 2.0-os, March 2005. 860 [RFC3275] Eastlake, D., Reagle, J., and D. Solo, "(Extensible Markup 861 Language) XML-Signature Syntax and Processing", RFC 3275, 862 March 2002. 864 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 865 Unique IDentifier (UUID) URN Namespace", RFC 4122, 866 July 2005. 868 [SWT] Hardt, D. and Y. Goland, "Simple Web Token (SWT)", 869 Version 0.9.5.1, November 2009. 871 [W3C.CR-xml11-20021015] 872 Cowan, J., "Extensible Markup Language (XML) 1.1", W3C 873 CR CR-xml11-20021015, October 2002. 875 [W3C.REC-xml-c14n-20010315] 876 Boyer, J., "Canonical XML Version 1.0", World Wide Web 877 Consortium Recommendation REC-xml-c14n-20010315, 878 March 2001, 879 . 881 Appendix A. Example Encrypted JWT 883 This example encrypts the same claims as used in Section 3.1 to the 884 recipient using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256. 886 The following example JWE Header (with line breaks for display 887 purposes only) declares that: 889 o the Content Encryption Key is encrypted to the recipient using the 890 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and 892 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 893 algorithm to produce the Ciphertext. 895 {"alg":"RSA1_5","enc":"A128CBC-HS256"} 897 Other than using the octets of the UTF-8 representation of the JWT 898 Claims Set from Section 3.1 as the plaintext value, the computation 899 of this JWT is identical to the computation of the JWE in Appendix 900 A.2 of [JWE], including the keys used. 902 The final result in this example (with line breaks for display 903 purposes only) is: 905 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 906 QR1Owv2ug2WyPBnbQrRARTeEk9kDO2w8qDcjiHnSJflSdv1iNqhWXaKH4MqAkQtM 907 oNfABIPJaZm0HaA415sv3aeuBWnD8J-Ui7Ah6cWafs3ZwwFKDFUUsWHSK-IPKxLG 908 TkND09XyjORj_CHAgOPJ-Sd8ONQRnJvWn_hXV1BNMHzUjPyYwEsRhDhzjAD26ima 909 sOTsgruobpYGoQcXUwFDn7moXPRfDE8-NoQX7N7ZYMmpUDkR-Cx9obNGwJQ3nM52 910 YCitxoQVPzjbl7WBuB7AohdBoZOdZ24WlN1lVIeh8v1K4krB8xgKvRU8kgFrEn_a 911 1rZgN5TiysnmzTROF869lQ. 912 AxY8DCtDaGlsbGljb3RoZQ. 913 MKOle7UQrG6nSxTLX6Mqwt0orbHvAKeWnDYvpIAeZ72deHxz3roJDXQyhxx0wKaM 914 HDjUEOKIwrtkHthpqEanSBNYHZgmNOV7sln1Eu9g3J8. 915 fiK51VwhsxJ-siBMR-YFiA 917 Appendix B. Relationship of JWTs to SAML Assertions 919 SAML 2.0 [OASIS.saml-core-2.0-os] provides a standard for creating 920 security tokens with greater expressivity and more security options 921 than supported by JWTs. However, the cost of this flexibility and 922 expressiveness is both size and complexity. SAML's use of XML 923 [W3C.CR-xml11-20021015] and XML DSIG [RFC3275] contributes to the 924 size of SAML assertions; its use of XML and especially XML 925 Canonicalization [W3C.REC-xml-c14n-20010315] contributes to their 926 complexity. 928 JWTs are intended to provide a simple security token format that is 929 small enough to fit into HTTP headers and query arguments in URIs. 930 It does this by supporting a much simpler token model than SAML and 931 using the JSON [RFC4627] object encoding syntax. It also supports 932 securing tokens using Message Authentication Codes (MACs) and digital 933 signatures using a smaller (and less flexible) format than XML DSIG. 935 Therefore, while JWTs can do some of the things SAML assertions do, 936 JWTs are not intended as a full replacement for SAML assertions, but 937 rather as a token format to be used when ease of implementation or 938 compactness are considerations. 940 SAML Assertions are always statements made by an entity about a 941 subject. JWTs are often used in the same manner, with the entity 942 making the statements being represented by the "iss" (issuer) claim, 943 and the subject being represented by the "sub" (subject) claim. 944 However, with these claims being optional, other uses of the JWT 945 format are also permitted. 947 Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs) 949 Both JWTs and Simple Web Tokens SWT [SWT], at their core, enable sets 950 of claims to be communicated between applications. For SWTs, both 951 the claim names and claim values are strings. For JWTs, while claim 952 names are strings, claim values can be any JSON type. Both token 953 types offer cryptographic protection of their content: SWTs with HMAC 954 SHA-256 and JWTs with a choice of algorithms, including signature, 955 MAC, and encryption algorithms. 957 Appendix D. Acknowledgements 959 The authors acknowledge that the design of JWTs was intentionally 960 influenced by the design and simplicity of Simple Web Tokens [SWT] 961 and ideas for JSON tokens that Dick Hardt discussed within the OpenID 962 community. 964 Solutions for signing JSON content were previously explored by Magic 965 Signatures [MagicSignatures], JSON Simple Sign [JSS], and Canvas 966 Applications [CanvasApp], all of which influenced this draft. 968 This specification is the work of the OAuth Working Group, which 969 includes dozens of active and dedicated participants. In particular, 970 the following individuals contributed ideas, feedback, and wording 971 that influenced this specification: 973 Dirk Balfanz, Richard Barnes, Brian Campbell, Breno de Medeiros, Dick 974 Hardt, Joe Hildebrand, Jeff Hodges, Edmund Jay, Yaron Y. Goland, Ben 975 Laurie, James Manger, Prateek Mishra, Tony Nadalin, Axel Nennker, 976 John Panzer, Emmanuel Raviart, David Recordon, Eric Rescorla, Jim 977 Schaad, Paul Tarjan, Hannes Tschofenig, and Sean Turner. 979 Hannes Tschofenig and Derek Atkins chaired the OAuth working group 980 and Sean Turner and Stephen Farrell served as Security area directors 981 during the creation of this specification. 983 Appendix E. Document History 985 [[ to be removed by the RFC editor before publication as an RFC ]] 987 -09 989 o Clarified that the "typ" header parameter is used in an 990 application-specific manner and has no effect upon the JWT 991 processing. 993 o Stated that receipients MUST either reject JWTs with duplicate 994 Header Parameter Names or with duplicate Claim Names or use a JSON 995 parser that returns only the lexically last duplicate member name. 997 -08 999 o Tracked a change to how JWEs are computed (which only affected the 1000 example encrypted JWT value). 1002 -07 1004 o Defined that the default action for claims that are not understood 1005 is to ignore them unless otherwise specified by applications. 1007 o Changed from using the term "byte" to "octet" when referring to 8 1008 bit values. 1010 o Tracked encryption computation changes in the JWE specification. 1012 -06 1014 o Changed the name of the "prn" claim to "sub" (subject) both to 1015 more closely align with SAML name usage and to use a more 1016 intuitive name. 1018 o Allow JWTs to have multiple audiences. 1020 o Applied editorial improvements suggested by Jeff Hodges, Prateek 1021 Mishra, and Hannes Tschofenig. Many of these simplified the 1022 terminology used. 1024 o Explained why Nested JWTs should be signed and then encrypted. 1026 o Clarified statements of the form "This claim is OPTIONAL" to "Use 1027 of this claim is OPTIONAL". 1029 o Referenced String Comparison Rules in JWS. 1031 o Added seriesInfo information to Internet Draft references. 1033 -05 1035 o Updated values for example AES CBC calculations. 1037 -04 1039 o Promoted Initialization Vector from being a header parameter to 1040 being a top-level JWE element. This saves approximately 16 bytes 1041 in the compact serialization, which is a significant savings for 1042 some use cases. Promoting the Initialization Vector out of the 1043 header also avoids repeating this shared value in the JSON 1044 serialization. 1046 o Applied changes made by the RFC Editor to RFC 6749's registry 1047 language to this specification. 1049 o Reference RFC 6755 -- An IETF URN Sub-Namespace for OAuth. 1051 -03 1053 o Added statement that "StringOrURI values are compared as case- 1054 sensitive strings with no transformations or canonicalizations 1055 applied". 1057 o Indented artwork elements to better distinguish them from the body 1058 text. 1060 -02 1062 o Added an example of an encrypted JWT. 1064 o Added this language to Registration Templates: "This name is case 1065 sensitive. Names that match other registered names in a case 1066 insensitive manner SHOULD NOT be accepted." 1068 o Applied editorial suggestions. 1070 -01 1072 o Added the "cty" (content type) header parameter for declaring type 1073 information about the secured content, as opposed to the "typ" 1074 (type) header parameter, which declares type information about 1075 this object. This significantly simplified nested JWTs. 1077 o Moved description of how to determine whether a header is for a 1078 JWS or a JWE from the JWT spec to the JWE spec. 1080 o Changed registration requirements from RFC Required to 1081 Specification Required with Expert Review. 1083 o Added Registration Template sections for defined registries. 1085 o Added Registry Contents sections to populate registry values. 1087 o Added "Collision Resistant Namespace" to the terminology section. 1089 o Numerous editorial improvements. 1091 -00 1093 o Created the initial IETF draft based upon 1094 draft-jones-json-web-token-10 with no normative changes. 1096 Authors' Addresses 1098 Michael B. Jones 1099 Microsoft 1101 Email: mbj@microsoft.com 1102 URI: http://self-issued.info/ 1104 John Bradley 1105 Ping Identity 1107 Email: ve7jtb@ve7jtb.com 1109 Nat Sakimura 1110 Nomura Research Institute 1112 Email: n-sakimura@nri.co.jp