idnits 2.17.1 draft-ietf-oauth-json-web-token-08.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 (May 28, 2013) is 3983 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) ** 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 (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track J. Bradley 5 Expires: November 29, 2013 Ping Identity 6 N. Sakimura 7 NRI 8 May 28, 2013 10 JSON Web Token (JWT) 11 draft-ietf-oauth-json-web-token-08 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 November 29, 2013. 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 . . . . . . . . . . . . . . . . . . . 8 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 . . . . . . . . . . . . 9 70 4.1.5. "nbf" (Not Before) Claim . . . . . . . . . . . . . . . 9 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 . . . . . . . . . . . . . . . . . . . . 10 75 4.3. Private Claim Names . . . . . . . . . . . . . . . . . . . 10 76 5. JWT Header . . . . . . . . . . . . . . . . . . . . . . . . . . 11 77 5.1. "typ" (Type) Header Parameter . . . . . . . . . . . . . . 11 78 5.2. "cty" (Content Type) Header Parameter . . . . . . . . . . 11 79 6. Plaintext JWTs . . . . . . . . . . . . . . . . . . . . . . . . 11 80 6.1. Example Plaintext JWT . . . . . . . . . . . . . . . . . . 12 81 7. Rules for Creating and Validating a JWT . . . . . . . . . . . 12 82 7.1. String Comparison Rules . . . . . . . . . . . . . . . . . 14 83 8. Cryptographic Algorithms . . . . . . . . . . . . . . . . . . . 14 84 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 85 9.1. JSON Web Token Claims Registry . . . . . . . . . . . . . . 15 86 9.1.1. Registration Template . . . . . . . . . . . . . . . . 16 87 9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 16 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 . . . . . . . . . . . . . . . . . . . . . . . 17 93 9.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 17 94 9.4. Media Type Registration . . . . . . . . . . . . . . . . . 17 95 9.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 17 96 10. Security Considerations . . . . . . . . . . . . . . . . . . . 18 97 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19 98 11.1. Normative References . . . . . . . . . . . . . . . . . . . 19 99 11.2. Informative References . . . . . . . . . . . . . . . . . . 20 100 Appendix A. Example Encrypted JWT . . . . . . . . . . . . . . . . 20 101 Appendix B. Relationship of JWTs to SAML Assertions . . . . . . . 21 102 Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs) . . 22 103 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 22 104 Appendix E. Document History . . . . . . . . . . . . . . . . . . 23 105 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 25 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 Base64url encoding the octets 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. 283 The set of claims that a JWT must contain to be considered valid is 284 context-dependent and is outside the scope of this specification. 285 Specific applications of JWTs will require implementations to 286 understand and process some claims in particular ways. However, in 287 the absence of such requirements, all claims that are not understood 288 by implementations SHOULD be ignored. 290 There are three classes of JWT Claim Names: Reserved Claim Names, 291 Public Claim Names, and Private Claim Names. 293 4.1. Reserved Claim Names 295 The following Claim Names are reserved. None of the claims defined 296 below are intended to be mandatory to use, but rather, provide a 297 starting point for a set of useful, interoperable claims. All the 298 names are short because a core goal of JWTs is for the representation 299 to be compact. Additional reserved Claim Names can be defined via 300 the IANA JSON Web Token Claims registry Section 9.1. 302 4.1.1. "iss" (Issuer) Claim 304 The "iss" (issuer) claim identifies the principal that issued the 305 JWT. The processing of this claim is generally application specific. 306 The "iss" value is a case sensitive string containing a StringOrURI 307 value. Use of this claim is OPTIONAL. 309 4.1.2. "sub" (Subject) Claim 311 The "sub" (subject) claim identifies the principal that is the 312 subject of the JWT. The Claims in a JWT are normally statements 313 about the subject. The processing of this claim is generally 314 application specific. The "sub" value is a case sensitive string 315 containing a StringOrURI value. Use of this claim is OPTIONAL. 317 4.1.3. "aud" (Audience) Claim 319 The "aud" (audience) claim identifies the audiences that the JWT is 320 intended for. Each principal intended to process the JWT MUST 321 identify itself with a value in audience claim. If the principal 322 processing the claim does not identify itself with a value in the 323 "aud" claim, then the JWT MUST be rejected. In the general case, the 324 "aud" value is an array of case sensitive strings, each containing a 325 StringOrURI value. In the special case when the JWT has one 326 audience, the "aud" value MAY be a single case sensitive string 327 containing a StringOrURI value. The interpretation of audience 328 values is generally application specific. Use of this claim is 329 OPTIONAL. 331 4.1.4. "exp" (Expiration Time) Claim 333 The "exp" (expiration time) claim identifies the expiration time on 334 or after which the JWT MUST NOT be accepted for processing. The 335 processing of the "exp" claim requires that the current date/time 336 MUST be before the expiration date/time listed in the "exp" claim. 337 Implementers MAY provide for some small leeway, usually no more than 338 a few minutes, to account for clock skew. Its value MUST be a number 339 containing an IntDate value. Use of this claim is OPTIONAL. 341 4.1.5. "nbf" (Not Before) Claim 343 The "nbf" (not before) claim identifies the time before which the JWT 344 MUST NOT be accepted for processing. The processing of the "nbf" 345 claim requires that the current date/time MUST be after or equal to 346 the not-before date/time listed in the "nbf" claim. Implementers MAY 347 provide for some small leeway, usually no more than a few minutes, to 348 account for clock skew. Its value MUST be a number containing an 349 IntDate value. Use of this claim is OPTIONAL. 351 4.1.6. "iat" (Issued At) Claim 353 The "iat" (issued at) claim identifies the time at which the JWT was 354 issued. This claim can be used to determine the age of the JWT. Its 355 value MUST be a number containing an IntDate value. Use of this 356 claim is OPTIONAL. 358 4.1.7. "jti" (JWT ID) Claim 360 The "jti" (JWT ID) claim provides a unique identifier for the JWT. 361 The identifier value MUST be assigned in a manner that ensures that 362 there is a negligible probability that the same value will be 363 accidentally assigned to a different data object. The "jti" claim 364 can be used to prevent the JWT from being replayed. The "jti" value 365 is a case sensitive string. Use of this claim is OPTIONAL. 367 4.1.8. "typ" (Type) Claim 369 The "typ" (type) claim is used to declare a type for the contents of 370 this JWT Claims Set. The "typ" value is a case sensitive string. Use 371 of this claim is OPTIONAL. 373 The values used for the "typ" claim come from the same value space as 374 the "typ" header parameter, with the same rules applying. 376 4.2. Public Claim Names 378 Claim Names can be defined at will by those using JWTs. However, in 379 order to prevent collisions, any new Claim Name SHOULD either be 380 registered in the IANA JSON Web Token Claims registry Section 9.1 or 381 be a Public Name: a value that contains a Collision Resistant 382 Namespace. In each case, the definer of the name or value needs to 383 take reasonable precautions to make sure they are in control of the 384 part of the namespace they use to define the Claim Name. 386 4.3. Private Claim Names 388 A producer and consumer of a JWT may agree to use Claim Names that 389 are Private Names: names that are not Reserved Names Section 4.1 or 390 Public Names Section 4.2. Unlike Public Names, Private Names are 391 subject to collision and should be used with caution. 393 5. JWT Header 395 The members of the JSON object represented by the JWT Header describe 396 the cryptographic operations applied to the JWT and optionally, 397 additional properties of the JWT. The member names within the JWT 398 Header are referred to as Header Parameter Names. These names MUST 399 be unique; JWTs with duplicate Header Parameter Names MUST be 400 rejected. The corresponding values are referred to as Header 401 Parameter Values. 403 JWS Header Parameters are defined by [JWS]. JWE Header Parameters 404 are defined by [JWE]. This specification further specifies the use 405 of the following header parameter in both the cases where the JWT is 406 a JWS and where it is a JWE. 408 5.1. "typ" (Type) Header Parameter 410 The "typ" (type) header parameter is used to declare the type of this 411 object. If present, it is RECOMMENDED that its value be either "JWT" 412 or "urn:ietf:params:oauth:token-type:jwt" to indicate that this 413 object is a JWT. The "typ" value is a case sensitive string. Use of 414 this header parameter is OPTIONAL. 416 5.2. "cty" (Content Type) Header Parameter 418 The "cty" (content type) header parameter is used to declare 419 structural information about the JWT. Its value MUST be a string. 421 In the normal case where nested signing or encryption operations are 422 not employed, the use of this header parameter is NOT RECOMMENDED. 423 In the case that nested signing or encryption is employed, the use of 424 this header parameter is REQUIRED; in this case, the value MUST be 425 "JWT", to indicate that a Nested JWT is carried in this JWT. 427 The values used for the "cty" header parameter come from the same 428 value space as the "typ" header parameter, with the same rules 429 applying. 431 6. Plaintext JWTs 433 To support use cases where the JWT content is secured by a means 434 other than a signature and/or encryption contained within the JWT 435 (such as a signature on a data structure containing the JWT), JWTs 436 MAY also be created without a signature or encryption. A plaintext 437 JWT is a JWS using the "none" JWS "alg" header parameter value 438 defined in JSON Web Algorithms (JWA) [JWA]; it is a JWS with the 439 empty string for its JWS Signature value. 441 6.1. Example Plaintext JWT 443 The following example JWT Header declares that the encoded object is 444 a Plaintext JWT: 446 {"alg":"none"} 448 Base64url encoding the octets of the UTF-8 representation of the JWT 449 Header yields this Encoded JWT Header: 451 eyJhbGciOiJub25lIn0 453 The following is an example of a JWT Claims Set: 455 {"iss":"joe", 456 "exp":1300819380, 457 "http://example.com/is_root":true} 459 Base64url encoding the octets of the UTF-8 representation of the JSON 460 Claims Set yields this Encoded JWS Payload (with line breaks for 461 display purposes only): 463 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 464 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 466 The Encoded JWS Signature is the empty string. 468 Concatenating these parts in this order with period ('.') characters 469 between the parts yields this complete JWT (with line breaks for 470 display purposes only): 472 eyJhbGciOiJub25lIn0 473 . 474 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 475 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 476 . 478 7. Rules for Creating and Validating a JWT 480 To create a JWT, one MUST perform these steps. The order of the 481 steps is not significant in cases where there are no dependencies 482 between the inputs and outputs of the steps. 484 1. Create a JWT Claims Set containing the desired claims. Note that 485 white space is explicitly allowed in the representation and no 486 canonicalization is performed before encoding. 488 2. Let the Message be the octets of the UTF-8 representation of the 489 JWT Claims Set. 491 3. Create a JWT Header containing the desired set of header 492 parameters. The JWT MUST conform to either the [JWS] or [JWE] 493 specifications. Note that white space is explicitly allowed in 494 the representation and no canonicalization is performed before 495 encoding. 497 4. Base64url encode the octets of the UTF-8 representation of the 498 JWT Header. Let this be the Encoded JWT Header. 500 5. Depending upon whether the JWT is a JWS or JWE, there are two 501 cases: 503 * If the JWT is a JWS, create a JWS using the JWT Header as the 504 JWS Header and the Message as the JWS Payload; all steps 505 specified in [JWS] for creating a JWS MUST be followed. 507 * Else, if the JWT is a JWE, create a JWE using the JWT Header 508 as the JWE Header and the Message as the JWE Plaintext; all 509 steps specified in [JWE] for creating a JWE MUST be followed. 511 6. If a nested signing or encryption operation will be performed, 512 let the Message be the JWS or JWE, and return to Step 3, using a 513 "cty" (content type) value of "JWT" in the new JWT Header created 514 in that step. 516 7. Otherwise, let the resulting JWT be the JWS or JWE. 518 When validating a JWT the following steps MUST be taken. The order 519 of the steps is not significant in cases where there are no 520 dependencies between the inputs and outputs of the steps. If any of 521 the listed steps fails then the JWT MUST be rejected for processing. 523 1. The JWT MUST contain at least one period ('.') character. 525 2. Let the Encoded JWT Header be the portion of the JWT before the 526 first period ('.') character. 528 3. The Encoded JWT Header MUST be successfully base64url decoded 529 following the restriction given in this specification that no 530 padding characters have been used. 532 4. The resulting JWT Header MUST be completely valid JSON syntax 533 conforming to RFC 4627 [RFC4627]. 535 5. The resulting JWT Header MUST be validated to only include 536 parameters and values whose syntax and semantics are both 537 understood and supported or that are specified as being ignored 538 when not understood. 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 is a JWT that was the subject of nested 557 signing or encryption operations. In this case, return to Step 558 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 7.1. String Comparison Rules 567 Processing a JWT inevitably requires comparing known strings to 568 values in JSON objects. For example, in checking what the algorithm 569 is, the Unicode string encoding "alg" will be checked against the 570 member names in the JWT Header to see if there is a matching Header 571 Parameter Name. 573 Comparisons between JSON strings and other Unicode strings MUST be 574 performed by comparing Unicode code points without normalization as 575 specified in the String Comparison Rules in Section 5.3 of [JWS]. 577 8. Cryptographic Algorithms 579 JWTs use JSON Web Signature (JWS) [JWS] and JSON Web Encryption (JWE) 580 [JWE] to sign and/or encrypt the contents of the JWT. 582 Of the JWA signing algorithms, only HMAC SHA-256 ("HS256") and "none" 583 MUST be implemented by conforming JWT implementations. It is 584 RECOMMENDED that implementations also support RSASSA-PKCS1-V1_5 with 585 the SHA-256 hash algorithm ("RS256") and ECDSA using the P-256 curve 586 and the SHA-256 hash algorithm ("ES256"). Support for other 587 algorithms and key sizes is OPTIONAL. 589 If an implementation provides encryption capabilities, of the JWA 590 encryption algorithms, only RSAES-PKCS1-V1_5 with 2048 bit keys 591 ("RSA1_5"), AES Key Wrap with 128 and 256 bit keys ("A128KW" and 592 "A256KW"), and the composite authenticated encryption algorithm using 593 AES CBC and HMAC SHA-2 ("A128CBC-HS256" and "A256CBC-HS512") MUST be 594 implemented by conforming implementations. It is RECOMMENDED that 595 implementations also support using ECDH-ES to agree upon a key used 596 to wrap the Content Encryption Key ("ECDH-ES+A128KW" and 597 "ECDH-ES+A256KW") and AES in Galois/Counter Mode (GCM) with 128 bit 598 and 256 bit keys ("A128GCM" and "A256GCM"). Support for other 599 algorithms and key sizes is OPTIONAL. 601 9. IANA Considerations 603 9.1. JSON Web Token Claims Registry 605 This specification establishes the IANA JSON Web Token Claims 606 registry for reserved JWT Claim Names. The registry records the 607 reserved Claim Name and a reference to the specification that defines 608 it. This specification registers the Claim Names defined in 609 Section 4.1. 611 Values are registered with a Specification Required [RFC5226] after a 612 two-week review period on the [TBD]@ietf.org mailing list, on the 613 advice of one or more Designated Experts. However, to allow for the 614 allocation of values prior to publication, the Designated Expert(s) 615 may approve registration once they are satisfied that such a 616 specification will be published. 618 Registration requests must be sent to the [TBD]@ietf.org mailing list 619 for review and comment, with an appropriate subject (e.g., "Request 620 for access token type: example"). [[ Note to RFC-EDITOR: The name of 621 the mailing list should be determined in consultation with the IESG 622 and IANA. Suggested name: claims-reg-review. ]] 624 Within the review period, the Designated Expert(s) will either 625 approve or deny the registration request, communicating this decision 626 to the review list and IANA. Denials should include an explanation 627 and, if applicable, suggestions as to how to make the request 628 successful. 630 IANA must only accept registry updates from the Designated Expert(s) 631 and should direct all requests for registration to the review mailing 632 list. 634 9.1.1. Registration Template 636 Claim Name: 637 The name requested (e.g., "example"). This name is case 638 sensitive. Names that match other registered names in a case 639 insensitive manner SHOULD NOT be accepted. 641 Change Controller: 642 For Standards Track RFCs, state "IETF". For others, give the name 643 of the responsible party. Other details (e.g., postal address, 644 email address, home page URI) may also be included. 646 Specification Document(s): 647 Reference to the document(s) that specify the parameter, 648 preferably including URI(s) that can be used to retrieve copies of 649 the document(s). An indication of the relevant sections may also 650 be included but is not required. 652 9.1.2. Initial Registry Contents 654 o Claim Name: "iss" 655 o Change Controller: IETF 656 o Specification Document(s): Section 4.1.1 of [[ this document ]] 658 o Claim Name: "sub" 659 o Change Controller: IETF 660 o Specification Document(s): Section 4.1.2 of [[ this document ]] 662 o Claim Name: "aud" 663 o Change Controller: IETF 664 o Specification Document(s): Section 4.1.3 of [[ this document ]] 666 o Claim Name: "exp" 667 o Change Controller: IETF 668 o Specification Document(s): Section 4.1.4 of [[ this document ]] 670 o Claim Name: "nbf" 671 o Change Controller: IETF 672 o Specification Document(s): Section 4.1.5 of [[ this document ]] 674 o Claim Name: "iat" 675 o Change Controller: IETF 676 o Specification Document(s): Section 4.1.6 of [[ this document ]] 678 o Claim Name: "jti" 679 o Change Controller: IETF 680 o Specification Document(s): Section 4.1.7 of [[ this document ]] 682 o Claim Name: "typ" 683 o Change Controller: IETF 684 o Specification Document(s): Section 4.1.8 of [[ this document ]] 686 9.2. Sub-Namespace Registration of urn:ietf:params:oauth:token-type:jwt 688 9.2.1. Registry Contents 690 This specification registers the value "token-type:jwt" in the IANA 691 urn:ietf:params:oauth registry established in An IETF URN Sub- 692 Namespace for OAuth [RFC6755]. 694 o URN: urn:ietf:params:oauth:token-type:jwt 695 o Common Name: JSON Web Token (JWT) Token Type 696 o Change Controller: IETF 697 o Specification Document(s): [[this document]] 699 9.3. JSON Web Signature and Encryption Type Values Registration 701 9.3.1. Registry Contents 703 This specification registers the "JWT" type value in the IANA JSON 704 Web Signature and Encryption Type Values registry [JWS]: 706 o "typ" Header Parameter Value: "JWT" 707 o Abbreviation for MIME Type: application/jwt 708 o Change Controller: IETF 709 o Specification Document(s): Section 5.1 of [[ this document ]] 711 9.4. Media Type Registration 713 9.4.1. Registry Contents 715 This specification registers the "application/jwt" Media Type 716 [RFC2046] in the MIME Media Type registry [RFC4288] to indicate that 717 the content is a JWT. 719 o Type Name: application 720 o Subtype Name: jwt 721 o Required Parameters: n/a 722 o Optional Parameters: n/a 723 o Encoding considerations: JWT values are encoded as a series of 724 base64url encoded values (some of which may be the empty string) 725 separated by period ('.') characters 726 o Security Considerations: See the Security Considerations section 727 of [[ this document ]] 728 o Interoperability Considerations: n/a 729 o Published Specification: [[ this document ]] 730 o Applications that use this media type: OpenID Connect, Mozilla 731 Persona, Salesforce, Google, numerous others 732 o Additional Information: Magic number(s): n/a, File extension(s): 733 n/a, Macintosh file type code(s): n/a 734 o Person & email address to contact for further information: Michael 735 B. Jones, mbj@microsoft.com 736 o Intended Usage: COMMON 737 o Restrictions on Usage: none 738 o Author: Michael B. Jones, mbj@microsoft.com 739 o Change Controller: IETF 741 10. Security Considerations 743 All of the security issues faced by any cryptographic application 744 must be faced by a JWT/JWS/JWE/JWK agent. Among these issues are 745 protecting the user's private and symmetric keys, preventing various 746 attacks, and helping the user avoid mistakes such as inadvertently 747 encrypting a message for the wrong recipient. The entire list of 748 security considerations is beyond the scope of this document. 750 All the security considerations in the JWS specification also apply 751 to JWT, as do the JWE security considerations when encryption is 752 employed. In particular, the JWS JSON Security Considerations and 753 Unicode Comparison Security Considerations apply equally to the JWT 754 Claims Set in the same manner that they do to the JWS Header. 756 While syntactically, the signing and encryption operations for Nested 757 JWTs may be applied in any order, normally senders should sign the 758 message and then encrypt the result (thus encrypting the signature). 759 This prevents attacks in which the signature is stripped, leaving 760 just an encrypted message, as well as providing privacy for the 761 signer. Furthermore, signatures over encrypted text are not 762 considered valid in many jurisdictions. 764 Note that potential concerns about security issues related to the 765 order of signing and encryption operations are already addressed by 766 the underlying JWS and JWE specifications; in particular, because JWE 767 only supports the use of authenticated encryption algorithms, 768 cryptographic concerns about the potential need to sign after 769 encryption that apply in many contexts do not apply to this 770 specification. 772 11. References 774 11.1. Normative References 776 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 777 draft-ietf-jose-json-web-algorithms (work in progress), 778 May 2013. 780 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 781 Encryption (JWE)", draft-ietf-jose-json-web-encryption 782 (work in progress), May 2013. 784 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 785 Signature (JWS)", draft-ietf-jose-json-web-signature (work 786 in progress), May 2013. 788 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 789 Extensions (MIME) Part Two: Media Types", RFC 2046, 790 November 1996. 792 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 793 Requirement Levels", BCP 14, RFC 2119, March 1997. 795 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 796 Internet: Timestamps", RFC 3339, July 2002. 798 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 799 10646", STD 63, RFC 3629, November 2003. 801 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 802 Resource Identifier (URI): Generic Syntax", STD 66, 803 RFC 3986, January 2005. 805 [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and 806 Registration Procedures", RFC 4288, December 2005. 808 [RFC4627] Crockford, D., "The application/json Media Type for 809 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 811 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 812 Encodings", RFC 4648, October 2006. 814 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 815 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 816 May 2008. 818 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 819 for OAuth", RFC 6755, October 2012. 821 11.2. Informative References 823 [CanvasApp] 824 Facebook, "Canvas Applications", 2010. 826 [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", 827 September 2010. 829 [MagicSignatures] 830 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 831 Signatures", January 2011. 833 [OASIS.saml-core-2.0-os] 834 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 835 "Assertions and Protocol for the OASIS Security Assertion 836 Markup Language (SAML) V2.0", OASIS Standard saml-core- 837 2.0-os, March 2005. 839 [RFC3275] Eastlake, D., Reagle, J., and D. Solo, "(Extensible Markup 840 Language) XML-Signature Syntax and Processing", RFC 3275, 841 March 2002. 843 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 844 Unique IDentifier (UUID) URN Namespace", RFC 4122, 845 July 2005. 847 [SWT] Hardt, D. and Y. Goland, "Simple Web Token (SWT)", 848 Version 0.9.5.1, November 2009. 850 [W3C.CR-xml11-20021015] 851 Cowan, J., "Extensible Markup Language (XML) 1.1", W3C 852 CR CR-xml11-20021015, October 2002. 854 [W3C.REC-xml-c14n-20010315] 855 Boyer, J., "Canonical XML Version 1.0", World Wide Web 856 Consortium Recommendation REC-xml-c14n-20010315, 857 March 2001, 858 . 860 Appendix A. Example Encrypted JWT 862 This example encrypts the same claims as used in Section 3.1 to the 863 recipient using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256. 865 The following example JWE Header (with line breaks for display 866 purposes only) declares that: 868 o the Content Encryption Key is encrypted to the recipient using the 869 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and 871 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 872 algorithm to produce the Ciphertext. 874 {"alg":"RSA1_5","enc":"A128CBC-HS256"} 876 Other than using the octets of the UTF-8 representation of the JSON 877 Claims Set from Section 3.1 as the plaintext value, the computation 878 of this JWT is identical to the computation of the JWE in Appendix 879 A.2 of [JWE], including the keys used. 881 The final result in this example (with line breaks for display 882 purposes only) is: 884 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 885 QR1Owv2ug2WyPBnbQrRARTeEk9kDO2w8qDcjiHnSJflSdv1iNqhWXaKH4MqAkQtM 886 oNfABIPJaZm0HaA415sv3aeuBWnD8J-Ui7Ah6cWafs3ZwwFKDFUUsWHSK-IPKxLG 887 TkND09XyjORj_CHAgOPJ-Sd8ONQRnJvWn_hXV1BNMHzUjPyYwEsRhDhzjAD26ima 888 sOTsgruobpYGoQcXUwFDn7moXPRfDE8-NoQX7N7ZYMmpUDkR-Cx9obNGwJQ3nM52 889 YCitxoQVPzjbl7WBuB7AohdBoZOdZ24WlN1lVIeh8v1K4krB8xgKvRU8kgFrEn_a 890 1rZgN5TiysnmzTROF869lQ. 891 AxY8DCtDaGlsbGljb3RoZQ. 892 MKOle7UQrG6nSxTLX6Mqwt0orbHvAKeWnDYvpIAeZ72deHxz3roJDXQyhxx0wKaM 893 HDjUEOKIwrtkHthpqEanSBNYHZgmNOV7sln1Eu9g3J8. 894 fiK51VwhsxJ-siBMR-YFiA 896 Appendix B. Relationship of JWTs to SAML Assertions 898 SAML 2.0 [OASIS.saml-core-2.0-os] provides a standard for creating 899 security tokens with greater expressivity and more security options 900 than supported by JWTs. However, the cost of this flexibility and 901 expressiveness is both size and complexity. SAML's use of XML 902 [W3C.CR-xml11-20021015] and XML DSIG [RFC3275] contributes to the 903 size of SAML assertions; its use of XML and especially XML 904 Canonicalization [W3C.REC-xml-c14n-20010315] contributes to their 905 complexity. 907 JWTs are intended to provide a simple security token format that is 908 small enough to fit into HTTP headers and query arguments in URIs. 910 It does this by supporting a much simpler token model than SAML and 911 using the JSON [RFC4627] object encoding syntax. It also supports 912 securing tokens using Message Authentication Codes (MACs) and digital 913 signatures using a smaller (and less flexible) format than XML DSIG. 915 Therefore, while JWTs can do some of the things SAML assertions do, 916 JWTs are not intended as a full replacement for SAML assertions, but 917 rather as a token format to be used when ease of implementation or 918 compactness are considerations. 920 SAML Assertions are always statements made by an entity about a 921 subject. JWTs are often used in the same manner, with the entity 922 making the statements being represented by the "iss" (issuer) claim, 923 and the subject being represented by the "sub" (subject) claim. 924 However, with these claims being optional, other uses of the JWT 925 format are also permitted. 927 Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs) 929 Both JWTs and Simple Web Tokens SWT [SWT], at their core, enable sets 930 of claims to be communicated between applications. For SWTs, both 931 the claim names and claim values are strings. For JWTs, while claim 932 names are strings, claim values can be any JSON type. Both token 933 types offer cryptographic protection of their content: SWTs with HMAC 934 SHA-256 and JWTs with a choice of algorithms, including signature, 935 MAC, and encryption algorithms. 937 Appendix D. Acknowledgements 939 The authors acknowledge that the design of JWTs was intentionally 940 influenced by the design and simplicity of Simple Web Tokens [SWT] 941 and ideas for JSON tokens that Dick Hardt discussed within the OpenID 942 community. 944 Solutions for signing JSON content were previously explored by Magic 945 Signatures [MagicSignatures], JSON Simple Sign [JSS], and Canvas 946 Applications [CanvasApp], all of which influenced this draft. 948 This specification is the work of the OAuth Working Group, which 949 includes dozens of active and dedicated participants. In particular, 950 the following individuals contributed ideas, feedback, and wording 951 that influenced this specification: 953 Dirk Balfanz, Richard Barnes, Brian Campbell, Breno de Medeiros, Dick 954 Hardt, Joe Hildebrand, Jeff Hodges, Edmund Jay, Yaron Y. Goland, Ben 955 Laurie, James Manger, Prateek Mishra, Tony Nadalin, Axel Nennker, 956 John Panzer, Emmanuel Raviart, David Recordon, Eric Rescorla, Jim 957 Schaad, Paul Tarjan, Hannes Tschofenig, and Sean Turner. 959 Hannes Tschofenig and Derek Atkins chaired the OAuth working group 960 and Sean Turner and Stephen Farrell served as Security area directors 961 during the creation of this specification. 963 Appendix E. Document History 965 [[ to be removed by the RFC editor before publication as an RFC ]] 967 -08 969 o Tracked a change to how JWEs are computed (which only affected the 970 example encrypted JWT value). 972 -07 974 o Defined that the default action for claims that are not understood 975 is to ignore them unless otherwise specified by applications. 977 o Changed from using the term "byte" to "octet" when referring to 8 978 bit values. 980 o Tracked encryption computation changes in the JWE specification. 982 -06 984 o Changed the name of the "prn" claim to "sub" (subject) both to 985 more closely align with SAML name usage and to use a more 986 intuitive name. 988 o Allow JWTs to have multiple audiences. 990 o Applied editorial improvements suggested by Jeff Hodges, Prateek 991 Mishra, and Hannes Tschofenig. Many of these simplified the 992 terminology used. 994 o Explained why Nested JWTs should be signed and then encrypted. 996 o Clarified statements of the form "This claim is OPTIONAL" to "Use 997 of this claim is OPTIONAL". 999 o Referenced String Comparison Rules in JWS. 1001 o Added seriesInfo information to Internet Draft references. 1003 -05 1005 o Updated values for example AES CBC calculations. 1007 -04 1009 o Promoted Initialization Vector from being a header parameter to 1010 being a top-level JWE element. This saves approximately 16 bytes 1011 in the compact serialization, which is a significant savings for 1012 some use cases. Promoting the Initialization Vector out of the 1013 header also avoids repeating this shared value in the JSON 1014 serialization. 1016 o Applied changes made by the RFC Editor to RFC 6749's registry 1017 language to this specification. 1019 o Reference RFC 6755 -- An IETF URN Sub-Namespace for OAuth. 1021 -03 1023 o Added statement that "StringOrURI values are compared as case- 1024 sensitive strings with no transformations or canonicalizations 1025 applied". 1027 o Indented artwork elements to better distinguish them from the body 1028 text. 1030 -02 1032 o Added an example of an encrypted JWT. 1034 o Added this language to Registration Templates: "This name is case 1035 sensitive. Names that match other registered names in a case 1036 insensitive manner SHOULD NOT be accepted." 1038 o Applied editorial suggestions. 1040 -01 1042 o Added the "cty" (content type) header parameter for declaring type 1043 information about the secured content, as opposed to the "typ" 1044 (type) header parameter, which declares type information about 1045 this object. This significantly simplified nested JWTs. 1047 o Moved description of how to determine whether a header is for a 1048 JWS or a JWE from the JWT spec to the JWE spec. 1050 o Changed registration requirements from RFC Required to 1051 Specification Required with Expert Review. 1053 o Added Registration Template sections for defined registries. 1055 o Added Registry Contents sections to populate registry values. 1057 o Added "Collision Resistant Namespace" to the terminology section. 1059 o Numerous editorial improvements. 1061 -00 1063 o Created the initial IETF draft based upon 1064 draft-jones-json-web-token-10 with no normative changes. 1066 Authors' Addresses 1068 Michael B. Jones 1069 Microsoft 1071 Email: mbj@microsoft.com 1072 URI: http://self-issued.info/ 1074 John Bradley 1075 Ping Identity 1077 Email: ve7jtb@ve7jtb.com 1079 Nat Sakimura 1080 Nomura Research Institute 1082 Email: n-sakimura@nri.co.jp