Subversion Repositories specifications

Compare Revisions

Rev 537 → Rev 545

1.0/draft-jones-json-web-token.html
145,7 → 145,7
<tr><td class="header">Network Working Group</td><td class="header">M. Jones</td></tr>
<tr><td class="header">Internet-Draft</td><td class="header">Microsoft</td></tr>
<tr><td class="header">Intended status: Standards Track</td><td class="header">D. Balfanz</td></tr>
<tr><td class="header">Expires: May 2, 2012</td><td class="header">Google</td></tr>
<tr><td class="header">Expires: June 15, 2012</td><td class="header">Google</td></tr>
<tr><td class="header">&nbsp;</td><td class="header">J. Bradley</td></tr>
<tr><td class="header">&nbsp;</td><td class="header">independent</td></tr>
<tr><td class="header">&nbsp;</td><td class="header">Y. Goland</td></tr>
156,9 → 156,9
<tr><td class="header">&nbsp;</td><td class="header">Nomura Research Institute</td></tr>
<tr><td class="header">&nbsp;</td><td class="header">P. Tarjan</td></tr>
<tr><td class="header">&nbsp;</td><td class="header">Facebook</td></tr>
<tr><td class="header">&nbsp;</td><td class="header">October 30, 2011</td></tr>
<tr><td class="header">&nbsp;</td><td class="header">December 13, 2011</td></tr>
</table></td></tr></table>
<h1><br />JSON Web Token (JWT)<br />draft-jones-json-web-token-06</h1>
<h1><br />JSON Web Token (JWT)<br />draft-jones-json-web-token-07</h1>
 
<h3>Abstract</h3>
 
199,7 → 199,7
It is inappropriate to use Internet-Drafts as reference material or to cite
them other than as &ldquo;work in progress.&rdquo;</p>
<p>
This Internet-Draft will expire on May 2, 2012.</p>
This Internet-Draft will expire on June 15, 2012.</p>
 
<h3>Copyright Notice</h3>
<p>
282,8 → 282,8
headers and URI query parameters. JWTs encode claims to be
transmitted as a JSON object (as defined in <a class='info' href='#RFC4627'>RFC 4627<span> (</span><span class='info'>Crockford, D., &ldquo;The application/json Media Type for JavaScript Object Notation (JSON),&rdquo; July&nbsp;2006.</span><span>)</span></a> [RFC4627]) that is base64url encoded
and digitally signed and/or encrypted. Signing is
accomplished using JSON Web Signature (JWS) <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, &ldquo;JSON Web Signature (JWS),&rdquo; October&nbsp;2011.</span><span>)</span></a>. Encryption is accomplished using JSON Web Encryption
(JWE) <a class='info' href='#JWE'>[JWE]<span> (</span><span class='info'>Jones, M., Rescorla, E., and J. Hildebrand, &ldquo;JSON Web Encryption (JWE),&rdquo; October&nbsp;2011.</span><span>)</span></a>.
accomplished using JSON Web Signature (JWS) <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, &ldquo;JSON Web Signature (JWS),&rdquo; December&nbsp;2011.</span><span>)</span></a>. Encryption is accomplished using JSON Web Encryption
(JWE) <a class='info' href='#JWE'>[JWE]<span> (</span><span class='info'>Jones, M., Rescorla, E., and J. Hildebrand, &ldquo;JSON Web Encryption (JWE),&rdquo; December&nbsp;2011.</span><span>)</span></a>.
 
</p>
<p>
301,7 → 301,7
<blockquote class="text"><dl>
<dt>JSON Web Token (JWT)</dt>
<dd>
A string consisting of three parts: the JWT Header, the
A string consisting of three parts: the Encoded JWT Header, the
JWT Second Part, and the JWT Third Part, in that order,
with the parts being separated by period ('.') characters,
and each part containing base64url encoded content.
309,12 → 309,22
</dd>
<dt>JWT Header</dt>
<dd>
A string containing a JSON object that
A string representing a JSON object that
describes the cryptographic operations applied to the JWT.
When the JWT is signed, the JWT Header is the JWS Header.
When the JWT is encrypted, the JWT Header is the JWE Header.
 
</dd>
<dt>Header Parameter Names</dt>
<dd>
The names of the members within the JWT Header.
 
</dd>
<dt>Header Parameter Values</dt>
<dd>
The values of the members within the JWT Header.
 
</dd>
<dt>JWT Second Part</dt>
<dd>
When the JWT is signed, the JWT Second Part is the Encoded JWS Payload.
327,21 → 337,26
When the JWT is encrypted, the JWT Third Part is the Encoded JWE Ciphertext.
 
</dd>
<dt>JWT Claims Object</dt>
<dt>JWT Claims Set</dt>
<dd>
A JSON object that represents the claims contained in the JWT.
When the JWT is signed, the bytes of the UTF-8 representation of the JWT Claims Object are base64url encoded to create the Encoded JWS Payload.
When the JWT is encrypted, the bytes of the UTF-8 representation of the JWT Claims Object are used as the JWE Plaintext.
A string representing a JSON object that
contains the claims conveyed by the JWT.
When the JWT is signed, the bytes of the UTF-8 representation of the
JWT Claims Set are base64url encoded to create the Encoded JWS Payload.
When the JWT is encrypted, the bytes of the UTF-8 representation of the
JWT Claims Set are used as the JWE Plaintext.
 
</dd>
<dt>Claim Names</dt>
<dd>
The names of the members of the JWT Claims Object.
The names of the members of the JSON object represented by
the JWT Claims Set.
 
</dd>
<dt>Claim Values</dt>
<dd>
The values of the members of the JWT Claims Object.
The values of the members of the JSON object represented by
the JWT Claims Set.
 
</dd>
<dt>Encoded JWT Header</dt>
358,7 → 373,7
described in <a class='info' href='#RFC4648'>RFC 4648<span> (</span><span class='info'>Josefsson, S., &ldquo;The Base16, Base32, and Base64 Data Encodings,&rdquo; October&nbsp;2006.</span><span>)</span></a> [RFC4648],
Section 5, with the (non URL-safe) '=' padding characters
omitted, as permitted by Section 3.2. (See Appendix C of
<a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, &ldquo;JSON Web Signature (JWS),&rdquo; October&nbsp;2011.</span><span>)</span></a> for notes on implementing base64url
<a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, &ldquo;JSON Web Signature (JWS),&rdquo; December&nbsp;2011.</span><span>)</span></a> for notes on implementing base64url
encoding without padding.)
 
</dd>
373,7 → 388,7
<p>
JWTs represent a set of claims as a JSON object that is
base64url encoded and digitally signed and/or
encrypted. This object is the JWT Claims Object.
encrypted. The JWT Claims Set represents this JSON object.
As per <a class='info' href='#RFC4627'>RFC 4627<span> (</span><span class='info'>Crockford, D., &ldquo;The application/json Media Type for JavaScript Object Notation (JSON),&rdquo; July&nbsp;2006.</span><span>)</span></a> [RFC4627]
Section 2.2, the JSON object consists of zero or more
name/value pairs (or members), where the names are strings and
382,21 → 397,21
 
</p>
<p>
The member names within the JWT Claims Object are
referred to as Claim Names. These names MUST be unique. The
The member names within the JWT Claims Set are
referred to as Claim Names. The
corresponding values are referred to as Claim Values.
 
</p>
<p>
The bytes of the UTF-8 representation of the JWT Claims Object
The bytes of the UTF-8 representation of the JWT Claims Set
are signed in the manner described in JSON Web Signature (JWS)
<a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, &ldquo;JSON Web Signature (JWS),&rdquo; October&nbsp;2011.</span><span>)</span></a> and/or encrypted in the manner described
in JSON Web Encryption (JWE) <a class='info' href='#JWE'>[JWE]<span> (</span><span class='info'>Jones, M., Rescorla, E., and J. Hildebrand, &ldquo;JSON Web Encryption (JWE),&rdquo; October&nbsp;2011.</span><span>)</span></a>.
<a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, &ldquo;JSON Web Signature (JWS),&rdquo; December&nbsp;2011.</span><span>)</span></a> and/or encrypted in the manner described
in JSON Web Encryption (JWE) <a class='info' href='#JWE'>[JWE]<span> (</span><span class='info'>Jones, M., Rescorla, E., and J. Hildebrand, &ldquo;JSON Web Encryption (JWE),&rdquo; December&nbsp;2011.</span><span>)</span></a>.
 
</p>
<p>
The contents of the JWT Header describe the cryptographic
operations applied to the JWT Claims Object.
operations applied to the JWT Claims Set.
If the JWT Header is a JWS Header, the claims are signed.
If the JWT Header is a JWE Header, the claims are encrypted.
 
430,21 → 445,23
 
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9</pre></div>
<p>
The following is an example of a JWT Claims Object:
The following is an example of a JWT Claims Set:
 
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>{"iss":"joe",
"exp":1300819380,
"http://example.com/is_root":true}</pre></div>
<p>
Base64url encoding the bytes of the UTF-8 representation of
the JSON Claims Object yields this Encoded JWS Payload,
which is used as the JWT Second Part:
the JSON Claims Set yields this Encoded JWS Payload,
which is used as the JWT Second Part
(with line breaks for display purposes only):
 
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ</pre></div>
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly
9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ</pre></div>
<p>
Signing the Encoded JWS Header and Encoded JWS Payload with
the HMAC SHA-256 algorithm and base64url encoding the
signature in the manner specified in <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, &ldquo;JSON Web Signature (JWS),&rdquo; October&nbsp;2011.</span><span>)</span></a>,
signature in the manner specified in <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, &ldquo;JSON Web Signature (JWS),&rdquo; December&nbsp;2011.</span><span>)</span></a>,
yields this Encoded JWS Signature, which is used as the JWT
Third Part:
 
457,11 → 474,12
 
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
.
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
.
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk</pre></div>
<p>
This computation is illustrated in more detail in <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, &ldquo;JSON Web Signature (JWS),&rdquo; October&nbsp;2011.</span><span>)</span></a>, Appendix A.1.
This computation is illustrated in more detail in <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, &ldquo;JSON Web Signature (JWS),&rdquo; December&nbsp;2011.</span><span>)</span></a>, Appendix A.1.
 
</p>
<a name="anchor4"></a><br /><hr />
470,8 → 488,10
JWT Claims</h3>
 
<p>
A JWT contains a set of claims represented as a base64url
encoded JSON object. Note however, that the set of claims a
The JWT Claims Set represents a JSON object whose members
are the claims conveyed by the JWT.
The Claim Names within this object MUST be unique.
Note however, that the set of claims that a
JWT must contain to be considered valid is context-dependent
and is outside the scope of this specification. When used in
a security-related context, implementations MUST understand
564,23 → 584,51
The <tt>aud</tt> (audience) claim
identifies the audience that the JWT is intended for. The
principal intended to process the JWT MUST be identified
by the value of the audience claim. If the principal
with the value of the audience claim. If the principal
processing the claim does not identify itself with the
identifier in the <tt>aud</tt> claim
value then the JWT MUST be rejected. The interpretation
of the contents of the audience value is generally
of the audience value is generally
application specific.
The <tt>aud</tt> value is case sensitive.
This claim is OPTIONAL.
</td>
</tr>
<tr>
<td align="left">prn</td>
<td align="left">string</td>
<td align="left">StringOrURI</td>
<td align="left">
The <tt>prn</tt> (principal) claim
identifies the subject of the JWT. The processing of this
claim is generally application specific.
The <tt>prn</tt> value is case sensitive.
This claim is OPTIONAL.
</td>
</tr>
<tr>
<td align="left">jti</td>
<td align="left">string</td>
<td align="left">String</td>
<td align="left">
The <tt>jti</tt> (JWT ID) claim
provides a unique identifier for the JWT. The identifier
value MUST be assigned in a manner that ensures that there
is a negligible probability that the same value will be
accidentally assigned to a different data object. The
<tt>jti</tt> claim can be used to
prevent the JWT from being replayed.
The <tt>jti</tt> value is case sensitive.
This claim is OPTIONAL.
</td>
</tr>
<tr>
<td align="left">typ</td>
<td align="left">string</td>
<td align="left">String</td>
<td align="left">
The <tt>typ</tt> (type) claim is used
to declare a type for the contents of this JWT Claims Object.
to declare a type for the contents of this JWT Claims Set.
The <tt>typ</tt> value is case sensitive.
This claim is OPTIONAL.
</td>
643,8 → 691,8
 
</li>
<li>
Object Identifiers (OIDs) as defined in the ITU-T X 660
and X 670 Recommendation series or
Object Identifiers (OIDs) as defined in the ITU-T X.660
and X.670 Recommendation series, or
 
</li>
<li>
653,7 → 701,7
</li>
</ul><p>
 
In each case, the definer of the name or value MUST take
In each case, the definer of the name or value needs to take
reasonable precautions to make sure they are in control of
the part of the namespace they use to define the claim
name.
679,9 → 727,18
The members of the JSON object represented by the JWT Header
describe the cryptographic operations applied to the JWT and
optionally, additional properties of the JWT.
The member names within the JWT Header are
referred to as Header Parameter Names. These names MUST be
unique. The corresponding values are referred to as Header
Parameter Values.
 
</p>
<p>
Implementations MUST understand the entire contents of the
header; otherwise, the JWT MUST be rejected for processing.
 
</p>
<p>
There are two ways of distinguishing whether the JWT is a JWS
or JWE. The first is by examining the <tt>alg</tt> (algorithm) header value. If the
value represents a signature algorithm, the JWT is a JWS; if
693,13 → 750,8
 
</p>
<p>
Implementations MUST understand the entire contents of the
header; otherwise, the JWT MUST be rejected for processing.
 
</p>
<p>
JWS Header Parameters are defined by <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, &ldquo;JSON Web Signature (JWS),&rdquo; October&nbsp;2011.</span><span>)</span></a>.
JWE Header Parameters are defined by <a class='info' href='#JWE'>[JWE]<span> (</span><span class='info'>Jones, M., Rescorla, E., and J. Hildebrand, &ldquo;JSON Web Encryption (JWE),&rdquo; October&nbsp;2011.</span><span>)</span></a>.
JWS Header Parameters are defined by <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, &ldquo;JSON Web Signature (JWS),&rdquo; December&nbsp;2011.</span><span>)</span></a>.
JWE Header Parameters are defined by <a class='info' href='#JWE'>[JWE]<span> (</span><span class='info'>Jones, M., Rescorla, E., and J. Hildebrand, &ldquo;JSON Web Encryption (JWE),&rdquo; December&nbsp;2011.</span><span>)</span></a>.
This specification further specifies the use of the following
header parameters in both the cases where the JWT is a JWS and
where it is a JWE.
745,7 → 797,7
signature or encryption. Plaintext JWTs MUST use the <tt>alg</tt> value <tt>none</tt>, and are formatted identically to a
signed JWT with an empty signature. This means that the
base64url encoding of the bytes representing the UTF-8
encoding of the JWT Claims Object is the JWT Second Part, and
encoding of the JWT Claims Set is the JWT Second Part, and
the empty string is the JWT Third Part.
 
</p>
765,17 → 817,19
 
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>eyJhbGciOiJub25lIn0</pre></div>
<p>
The following is an example of a JWT Claims Object:
The following is an example of a JWT Claims Set:
 
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>{"iss":"joe",
"exp":1300819380,
"http://example.com/is_root":true}</pre></div>
<p>
Base64url encoding the bytes of the UTF-8 representation of
the JSON Claims Object yields this Encoded JWS Payload,
which is used as the JWT Second Part:
the JSON Claims Set yields this Encoded JWS Payload,
which is used as the JWT Second Part
(with line breaks for display purposes only):
 
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ</pre></div>
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ</pre></div>
<p>
The JWT Third Part is the empty string.
 
788,7 → 842,8
 
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>eyJhbGciOiJub25lIn0
.
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
.
</pre></div>
<a name="anchor6"></a><br /><hr />
797,12 → 852,12
Rules for Creating and Validating a JWT</h3>
 
<p>
To create a JWT, one MUST follow these steps:
To create a JWT, one MUST perform these steps:
 
</p>
<ol class="text">
<li>
Create a JWT Claims Object containing the desired claims.
Create a JWT Claims Set containing the desired claims.
Note that white space is explicitly allowed in the
representation and no canonicalization is performed before
encoding.
810,13 → 865,13
</li>
<li>
Let the Message be the bytes of the UTF-8 representation
of the JWT Claims Object.
of the JWT Claims Set.
 
</li>
<li>
Create a JWT Header containing the desired set of header
parameters. If the JWT is to be signed or encrypted, they
MUST conform to either the <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, &ldquo;JSON Web Signature (JWS),&rdquo; October&nbsp;2011.</span><span>)</span></a> or <a class='info' href='#JWE'>[JWE]<span> (</span><span class='info'>Jones, M., Rescorla, E., and J. Hildebrand, &ldquo;JSON Web Encryption (JWE),&rdquo; October&nbsp;2011.</span><span>)</span></a> specifications, respectively. Else, if
MUST conform to either the <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, &ldquo;JSON Web Signature (JWS),&rdquo; December&nbsp;2011.</span><span>)</span></a> or <a class='info' href='#JWE'>[JWE]<span> (</span><span class='info'>Jones, M., Rescorla, E., and J. Hildebrand, &ldquo;JSON Web Encryption (JWE),&rdquo; December&nbsp;2011.</span><span>)</span></a> specifications, respectively. Else, if
the JWT is to be plaintext, the <tt>alg</tt> value <tt>none</tt> MUST be used. Note that white
space is explicitly allowed in the representation and no
canonicalization is performed before encoding.
835,7 → 890,7
<li>
If the JWT is to be signed, create a JWS using the JWT
Header as the JWS Header and the Message as the JWS
Payload; all steps specified in <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, &ldquo;JSON Web Signature (JWS),&rdquo; October&nbsp;2011.</span><span>)</span></a>
Payload; all steps specified in <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, &ldquo;JSON Web Signature (JWS),&rdquo; December&nbsp;2011.</span><span>)</span></a>
for creating a JWS MUST be followed.
Let the JWT Second Part be the Encoded JWS Payload and
let the JWT Third Part be the Encoded JWS Signature.
844,7 → 899,7
<li>
If the JWT is to be encrypted, create a JWE using the
JWT Header as the JWE Header and the Message as the
JWE Plaintext; all steps specified in <a class='info' href='#JWE'>[JWE]<span> (</span><span class='info'>Jones, M., Rescorla, E., and J. Hildebrand, &ldquo;JSON Web Encryption (JWE),&rdquo; October&nbsp;2011.</span><span>)</span></a> for creating a JWE MUST be followed.
JWE Plaintext; all steps specified in <a class='info' href='#JWE'>[JWE]<span> (</span><span class='info'>Jones, M., Rescorla, E., and J. Hildebrand, &ldquo;JSON Web Encryption (JWE),&rdquo; December&nbsp;2011.</span><span>)</span></a> for creating a JWE MUST be followed.
Let the JWT Second Part be the Encoded JWE Encrypted
Key and let the JWT Third Part be the Encoded JWS
Ciphertext.
930,13 → 985,13
 
<ul class="text">
<li>
If the JWT is signed, all steps specified in <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, &ldquo;JSON Web Signature (JWS),&rdquo; October&nbsp;2011.</span><span>)</span></a> for validating a JWS MUST be followed.
If the JWT is signed, all steps specified in <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, &ldquo;JSON Web Signature (JWS),&rdquo; December&nbsp;2011.</span><span>)</span></a> for validating a JWS MUST be followed.
Let the Message be the result of base64url decoding
the JWS Payload.
 
</li>
<li>
If the JWT is encrypted, all steps specified in <a class='info' href='#JWE'>[JWE]<span> (</span><span class='info'>Jones, M., Rescorla, E., and J. Hildebrand, &ldquo;JSON Web Encryption (JWE),&rdquo; October&nbsp;2011.</span><span>)</span></a> for validating a JWE MUST be followed.
If the JWT is encrypted, all steps specified in <a class='info' href='#JWE'>[JWE]<span> (</span><span class='info'>Jones, M., Rescorla, E., and J. Hildebrand, &ldquo;JSON Web Encryption (JWE),&rdquo; December&nbsp;2011.</span><span>)</span></a> for validating a JWE MUST be followed.
Let the Message be the JWE Plaintext.
 
</li>
957,18 → 1012,18
 
</li>
<li>
Otherwise, let the JWT Claims object be the Message.
Otherwise, let the JWT Claims Set be the Message.
 
</li>
<li>
The JWT Claims Object MUST be completely valid
The JWT Claims Set MUST be completely valid
JSON syntax conforming to <a class='info' href='#RFC4627'>RFC
4627<span> (</span><span class='info'>Crockford, D., &ldquo;The application/json Media Type for JavaScript Object Notation (JSON),&rdquo; July&nbsp;2006.</span><span>)</span></a> [RFC4627].
 
</li>
<li>
When used in a security-related context, the JWT
Claims Object MUST be validated to only include claims
When used in a security-related context, the
JWT Claims Set MUST be validated to only include claims
whose syntax and semantics are both understood and
supported.
 
980,19 → 1035,17
Processing a JWT inevitably requires comparing known strings
to values in the token. For example, in checking what the
algorithm is, the Unicode string encoding <tt>alg</tt> will be
checked against the member names in the JWT Header to see if there is a matching header parameter
checked against the member names in the JWT Header
to see if there is a matching header parameter
name. A similar process occurs when determining if the value
of the <tt>alg</tt> header parameter represents a supported
algorithm. Comparing Unicode strings, however, has significant
security implications, as per <a class='info' href='#Security'>Section&nbsp;10<span> (</span><span class='info'>Security Considerations</span><span>)</span></a>.
algorithm.
 
</p>
<p>
Comparisons between JSON strings and other Unicode strings
MUST be performed as specified below:
 
</p>
<p>
 
</p>
<ol class="text">
<li>
1020,8 → 1073,8
Cryptographic Algorithms</h3>
 
<p>
JWTs use JSON Web Signature (JWS) <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, &ldquo;JSON Web Signature (JWS),&rdquo; October&nbsp;2011.</span><span>)</span></a> and
JSON Web Encryption (JWE) <a class='info' href='#JWE'>[JWE]<span> (</span><span class='info'>Jones, M., Rescorla, E., and J. Hildebrand, &ldquo;JSON Web Encryption (JWE),&rdquo; October&nbsp;2011.</span><span>)</span></a> to sign and/or
JWTs use JSON Web Signature (JWS) <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, &ldquo;JSON Web Signature (JWS),&rdquo; December&nbsp;2011.</span><span>)</span></a> and
JSON Web Encryption (JWE) <a class='info' href='#JWE'>[JWE]<span> (</span><span class='info'>Jones, M., Rescorla, E., and J. Hildebrand, &ldquo;JSON Web Encryption (JWE),&rdquo; December&nbsp;2011.</span><span>)</span></a> to sign and/or
encrypt the contents of the JWT.
 
</p>
1158,7 → 1211,7
Claim Name in addition to the Header Parameter,
whether it conveys syntax or semantics, and indeed,
whether this is the right approach. Also clarify the
relationship between these type values and <a class='info' href='#RFC2045'>MIME<span> (</span><span class='info'>Freed, N. and N. Borenstein, &ldquo;Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies,&rdquo; November&nbsp;1996.</span><span>)</span></a> [RFC2045] types.
relationship between these type values and <a class='info' href='#RFC2045'>MIME<span> (</span><span class='info'>Freed, N. and N. Borenstein, &ldquo;Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies,&rdquo; November&nbsp;1996.</span><span>)</span></a> [RFC2045] types (if any).
 
</li>
<li>
1201,7 → 1254,7
<h3>12.1.&nbsp;Normative References</h3>
<table width="99%" border="0">
<tr><td class="author-text" valign="top"><a name="JWS">[JWS]</a></td>
<td class="author-text"><a href="mailto:mbj@microsoft.com">Jones, M.</a>, <a href="mailto:balfanz@google.com">Balfanz, D.</a>, <a href="mailto:ve7jtb@ve7jtb.com">Bradley, J.</a>, <a href="mailto:yarong@microsoft.com">Goland, Y.</a>, <a href="mailto:jpanzer@google.com">Panzer, J.</a>, <a href="mailto:n-sakimura@nri.co.jp">Sakimura, N.</a>, and <a href="mailto:pt@fb.com">P. Tarjan</a>, &ldquo;<a href="http://self-issued.info/docs/draft-jones-json-web-signature.html">JSON Web Signature (JWS)</a>,&rdquo; October&nbsp;2011.</td></tr>
<td class="author-text"><a href="mailto:mbj@microsoft.com">Jones, M.</a>, <a href="mailto:balfanz@google.com">Balfanz, D.</a>, <a href="mailto:ve7jtb@ve7jtb.com">Bradley, J.</a>, <a href="mailto:yarong@microsoft.com">Goland, Y.</a>, <a href="mailto:jpanzer@google.com">Panzer, J.</a>, <a href="mailto:n-sakimura@nri.co.jp">Sakimura, N.</a>, and <a href="mailto:pt@fb.com">P. Tarjan</a>, &ldquo;<a href="http://tools.ietf.org/html/draft-jones-json-web-signature">JSON Web Signature (JWS)</a>,&rdquo; December&nbsp;2011.</td></tr>
<tr><td class="author-text" valign="top"><a name="RFC2045">[RFC2045]</a></td>
<td class="author-text"><a href="mailto:ned@innosoft.com">Freed, N.</a> and <a href="mailto:nsb@nsb.fv.com">N. Borenstein</a>, &ldquo;<a href="http://tools.ietf.org/html/rfc2045">Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies</a>,&rdquo; RFC&nbsp;2045, November&nbsp;1996 (<a href="http://www.rfc-editor.org/rfc/rfc2045.txt">TXT</a>).</td></tr>
<tr><td class="author-text" valign="top"><a name="RFC2119">[RFC2119]</a></td>
1231,7 → 1284,7
<tr><td class="author-text" valign="top"><a name="JSS">[JSS]</a></td>
<td class="author-text">Bradley, J. and N. Sakimura (editor), &ldquo;<a href="http://jsonenc.info/jss/1.0/">JSON Simple Sign</a>,&rdquo; September&nbsp;2010.</td></tr>
<tr><td class="author-text" valign="top"><a name="JWE">[JWE]</a></td>
<td class="author-text"><a href="mailto:mbj@microsoft.com">Jones, M.</a>, <a href="mailto:ekr@rtfm.com">Rescorla, E.</a>, and <a href="mailto:jhildebr@cisco.com">J. Hildebrand</a>, &ldquo;<a href="http://self-issued.info/docs/draft-jones-json-web-encryption.html">JSON Web Encryption (JWE)</a>,&rdquo; October&nbsp;2011.</td></tr>
<td class="author-text"><a href="mailto:mbj@microsoft.com">Jones, M.</a>, <a href="mailto:ekr@rtfm.com">Rescorla, E.</a>, and <a href="mailto:jhildebr@cisco.com">J. Hildebrand</a>, &ldquo;<a href="http://tools.ietf.org/html/draft-jones-json-web-encryption">JSON Web Encryption (JWE)</a>,&rdquo; December&nbsp;2011.</td></tr>
<tr><td class="author-text" valign="top"><a name="MagicSignatures">[MagicSignatures]</a></td>
<td class="author-text">Panzer (editor), J., Laurie, B., and D. Balfanz, &ldquo;<a href="http://salmon-protocol.googlecode.com/svn/trunk/draft-panzer-magicsig-experimental-00.html">Magic Signatures</a>,&rdquo; August&nbsp;2010.</td></tr>
<tr><td class="author-text" valign="top"><a name="OASIS.saml-core-2.0-os">[OASIS.saml-core-2.0-os]</a></td>
1318,12 → 1371,48
Document History</h3>
 
<p>
-07
</p>
<ul class="text">
<li>
Defined the <tt>prn</tt> (principal)
claim to identify the subject of the JWT.
 
</li>
<li>
Defined the <tt>jti</tt> (JWT ID)
claim to enable replay protection.
 
</li>
<li>
Use the term "JWT Claims Set" rather than "JWT Claims Object"
since this is actually a string representing a JSON object
and not the JSON object itself.
 
</li>
<li>
Moved "MUST" requirements from the Overview to later in
the spec.
 
</li>
<li>
Respect line length restrictions in examples.
 
</li>
<li>
Applied other editorial improvements.
 
</li>
</ul><p>
 
</p>
<p>
-06
</p>
<ul class="text">
<li>
Reference and use content from <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, &ldquo;JSON Web Signature (JWS),&rdquo; October&nbsp;2011.</span><span>)</span></a> and
<a class='info' href='#JWE'>[JWE]<span> (</span><span class='info'>Jones, M., Rescorla, E., and J. Hildebrand, &ldquo;JSON Web Encryption (JWE),&rdquo; October&nbsp;2011.</span><span>)</span></a>, rather than repeating it here.
Reference and use content from <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, &ldquo;JSON Web Signature (JWS),&rdquo; December&nbsp;2011.</span><span>)</span></a> and
<a class='info' href='#JWE'>[JWE]<span> (</span><span class='info'>Jones, M., Rescorla, E., and J. Hildebrand, &ldquo;JSON Web Encryption (JWE),&rdquo; December&nbsp;2011.</span><span>)</span></a>, rather than repeating it here.
 
</li>
<li>
1.0/draft-jones-json-web-token.pdf Cannot display: file marked as a binary type. svn:mime-type = application/octet-stream
1.0/draft-jones-json-web-token.txt
4,7 → 4,7
Network Working Group M. Jones
Internet-Draft Microsoft
Intended status: Standards Track D. Balfanz
Expires: May 2, 2012 Google
Expires: June 15, 2012 Google
J. Bradley
independent
Y. Goland
15,11 → 15,11
Nomura Research Institute
P. Tarjan
Facebook
October 30, 2011
December 13, 2011
 
 
JSON Web Token (JWT)
draft-jones-json-web-token-06
draft-jones-json-web-token-07
 
Abstract
 
52,15 → 52,15
 
 
 
Jones, et al. Expires May 2, 2012 [Page 1]
Jones, et al. Expires June 15, 2012 [Page 1]
Internet-Draft JSON Web Token (JWT) October 2011
Internet-Draft JSON Web Token (JWT) December 2011
 
 
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
 
This Internet-Draft will expire on May 2, 2012.
This Internet-Draft will expire on June 15, 2012.
 
Copyright Notice
 
108,9 → 108,9
 
 
 
Jones, et al. Expires May 2, 2012 [Page 2]
Jones, et al. Expires June 15, 2012 [Page 2]
Internet-Draft JSON Web Token (JWT) October 2011
Internet-Draft JSON Web Token (JWT) December 2011
 
 
Table of Contents
118,28 → 118,28
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. JSON Web Token (JWT) Overview . . . . . . . . . . . . . . . . 5
3.1. Example JWT . . . . . . . . . . . . . . . . . . . . . . . 5
3.1. Example JWT . . . . . . . . . . . . . . . . . . . . . . . 6
4. JWT Claims . . . . . . . . . . . . . . . . . . . . . . . . . . 6
4.1. Reserved Claim Names . . . . . . . . . . . . . . . . . . . 7
4.2. Public Claim Names . . . . . . . . . . . . . . . . . . . . 9
4.3. Private Claim Names . . . . . . . . . . . . . . . . . . . 9
5. JWT Header . . . . . . . . . . . . . . . . . . . . . . . . . . 9
6. Plaintext JWTs . . . . . . . . . . . . . . . . . . . . . . . . 10
4.3. Private Claim Names . . . . . . . . . . . . . . . . . . . 10
5. JWT Header . . . . . . . . . . . . . . . . . . . . . . . . . . 10
6. Plaintext JWTs . . . . . . . . . . . . . . . . . . . . . . . . 11
6.1. Example Plaintext JWT . . . . . . . . . . . . . . . . . . 11
7. Rules for Creating and Validating a JWT . . . . . . . . . . . 11
8. Cryptographic Algorithms . . . . . . . . . . . . . . . . . . . 14
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14
7. Rules for Creating and Validating a JWT . . . . . . . . . . . 12
8. Cryptographic Algorithms . . . . . . . . . . . . . . . . . . . 15
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15
10. Security Considerations . . . . . . . . . . . . . . . . . . . 15
10.1. Unicode Comparison Security Issues . . . . . . . . . . . . 15
10.1. Unicode Comparison Security Issues . . . . . . . . . . . . 16
11. Open Issues and Things To Be Done (TBD) . . . . . . . . . . . 16
12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16
12.1. Normative References . . . . . . . . . . . . . . . . . . . 16
12.2. Informative References . . . . . . . . . . . . . . . . . . 17
Appendix A. Relationship of JWTs to SAML Tokens . . . . . . . . . 18
Appendix B. Relationship of JWTs to Simple Web Tokens (SWTs) . . 18
Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 18
Appendix D. Document History . . . . . . . . . . . . . . . . . . 19
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 20
12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 17
12.1. Normative References . . . . . . . . . . . . . . . . . . . 17
12.2. Informative References . . . . . . . . . . . . . . . . . . 18
Appendix A. Relationship of JWTs to SAML Tokens . . . . . . . . . 19
Appendix B. Relationship of JWTs to Simple Web Tokens (SWTs) . . 19
Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 19
Appendix D. Document History . . . . . . . . . . . . . . . . . . 20
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 21
 
 
 
164,9 → 164,9
 
 
 
Jones, et al. Expires May 2, 2012 [Page 3]
Jones, et al. Expires June 15, 2012 [Page 3]
Internet-Draft JSON Web Token (JWT) October 2011
Internet-Draft JSON Web Token (JWT) December 2011
 
 
1. Introduction
185,16 → 185,22
 
2. Terminology
 
JSON Web Token (JWT) A string consisting of three parts: the JWT
Header, the JWT Second Part, and the JWT Third Part, in that
JSON Web Token (JWT) A string consisting of three parts: the Encoded
JWT Header, the JWT Second Part, and the JWT Third Part, in that
order, with the parts being separated by period ('.') characters,
and each part containing base64url encoded content.
 
JWT Header A string containing a JSON object that describes the
JWT Header A string representing a JSON object that describes the
cryptographic operations applied to the JWT. When the JWT is
signed, the JWT Header is the JWS Header. When the JWT is
encrypted, the JWT Header is the JWE Header.
 
Header Parameter Names The names of the members within the JWT
Header.
 
Header Parameter Values The values of the members within the JWT
Header.
 
JWT Second Part When the JWT is signed, the JWT Second Part is the
Encoded JWS Payload. When the JWT is encrypted, the JWT Second
Part is the Encoded JWE Encrypted Key.
203,28 → 209,28
Encoded JWS Signature. When the JWT is encrypted, the JWT Third
Part is the Encoded JWE Ciphertext.
 
JWT Claims Object A JSON object that represents the claims contained
in the JWT. When the JWT is signed, the bytes of the UTF-8
representation of the JWT Claims Object are base64url encoded to
create the Encoded JWS Payload. When the JWT is encrypted, the
bytes of the UTF-8 representation of the JWT Claims Object are
used as the JWE Plaintext.
JWT Claims Set A string representing a JSON object that contains the
claims conveyed by the JWT. When the JWT is signed, the bytes of
the UTF-8 representation of the JWT Claims Set are base64url
encoded to create the Encoded JWS Payload. When the JWT is
encrypted, the bytes of the UTF-8 representation of the JWT Claims
Set are used as the JWE Plaintext.
 
Claim Names The names of the members of the JWT Claims Object.
 
Claim Values The values of the members of the JWT Claims Object.
 
 
 
Jones, et al. Expires June 15, 2012 [Page 4]
Internet-Draft JSON Web Token (JWT) December 2011
 
 
Claim Names The names of the members of the JSON object represented
by the JWT Claims Set.
 
Claim Values The values of the members of the JSON object
represented by the JWT Claims Set.
 
Jones, et al. Expires May 2, 2012 [Page 4]
Internet-Draft JSON Web Token (JWT) October 2011
 
 
Encoded JWT Header Base64url encoding of the bytes of the UTF-8 RFC
3629 [RFC3629] representation of the JWT Header.
 
239,25 → 245,24
3. JSON Web Token (JWT) Overview
 
JWTs represent a set of claims as a JSON object that is base64url
encoded and digitally signed and/or encrypted. This object is the
JWT Claims Object. As per RFC 4627 [RFC4627] Section 2.2, the JSON
object consists of zero or more name/value pairs (or members), where
the names are strings and the values are arbitrary JSON values.
These members are the claims represented by the JWT.
encoded and digitally signed and/or encrypted. The JWT Claims Set
represents this JSON object. As per RFC 4627 [RFC4627] Section 2.2,
the JSON object consists of zero or more name/value pairs (or
members), where the names are strings and the values are arbitrary
JSON values. These members are the claims represented by the JWT.
 
The member names within the JWT Claims Object are referred to as
Claim Names. These names MUST be unique. The corresponding values
are referred to as Claim Values.
The member names within the JWT Claims Set are referred to as Claim
Names. The corresponding values are referred to as Claim Values.
 
The bytes of the UTF-8 representation of the JWT Claims Object are
The bytes of the UTF-8 representation of the JWT Claims Set are
signed in the manner described in JSON Web Signature (JWS) [JWS]
and/or encrypted in the manner described in JSON Web Encryption (JWE)
[JWE].
 
The contents of the JWT Header describe the cryptographic operations
applied to the JWT Claims Object. If the JWT Header is a JWS Header,
the claims are signed. If the JWT Header is a JWE Header, the claims
are encrypted.
applied to the JWT Claims Set. If the JWT Header is a JWS Header, the
claims are signed. If the JWT Header is a JWE Header, the claims are
encrypted.
 
A JWT is represented as the concatenation of the Encoded JWT Header,
the JWT Second Part, and the JWT Third Part, in that order, with the
266,6 → 271,16
the JWT. When encrypted, the three parts of the JWT are the three
parts of a JWE used to represent the JWT.
 
 
 
 
 
 
Jones, et al. Expires June 15, 2012 [Page 5]
Internet-Draft JSON Web Token (JWT) December 2011
 
 
3.1. Example JWT
 
The following example JWT Header declares that the encoded object is
274,27 → 289,21
{"typ":"JWT",
"alg":"HS256"}
 
 
 
Jones, et al. Expires May 2, 2012 [Page 5]
Internet-Draft JSON Web Token (JWT) October 2011
 
 
Base64url encoding the bytes of the UTF-8 representation of the JWT
Header yields this Encoded JWS Header value, which is used as the
Encoded JWT Header:
eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
 
The following is an example of a JWT Claims Object:
The following is an example of a JWT Claims Set:
{"iss":"joe",
"exp":1300819380,
"http://example.com/is_root":true}
 
Base64url encoding the bytes of the UTF-8 representation of the JSON
Claims Object yields this Encoded JWS Payload, which is used as the
JWT Second Part:
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ
Claims Set yields this Encoded JWS Payload, which is used as the JWT
Second Part (with line breaks for display purposes only):
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly
9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ
 
Signing the Encoded JWS Header and Encoded JWS Payload with the HMAC
SHA-256 algorithm and base64url encoding the signature in the manner
305,11 → 314,12
Concatenating these parts in the order Header.Second.Third with
period characters between the parts yields this complete JWT (with
line breaks for display purposes only):
eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
.
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ
.
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
.
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
.
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
 
This computation is illustrated in more detail in [JWS], Appendix
A.1.
317,26 → 327,25
 
4. JWT Claims
 
A JWT contains a set of claims represented as a base64url encoded
JSON object. Note however, that the set of claims a JWT must contain
to be considered valid is context-dependent and is outside the scope
of this specification. When used in a security-related context,
implementations MUST understand and support all of the claims
present; otherwise, the JWT MUST be rejected for processing.
The JWT Claims Set represents a JSON object whose members are the
claims conveyed by the JWT. The Claim Names within this object MUST
 
There are three classes of JWT Claim Names: Reserved Claim Names,
Public Claim Names, and Private Claim Names.
 
 
Jones, et al. Expires June 15, 2012 [Page 6]
Internet-Draft JSON Web Token (JWT) December 2011
 
 
be unique. Note however, that the set of claims that a JWT must
contain to be considered valid is context-dependent and is outside
the scope of this specification. When used in a security-related
context, implementations MUST understand and support all of the
claims present; otherwise, the JWT MUST be rejected for processing.
 
There are three classes of JWT Claim Names: Reserved Claim Names,
Public Claim Names, and Private Claim Names.
 
Jones, et al. Expires May 2, 2012 [Page 6]
Internet-Draft JSON Web Token (JWT) October 2011
 
 
4.1. Reserved Claim Names
 
The following claim names are reserved. None of the claims defined
376,23 → 385,19
| | | | a few minutes, to account for |
| | | | clock skew. This claim is |
| | | | OPTIONAL. |
| iat | number | IntDate | The "iat" (issued at) claim |
| | | | identifies the time at which the |
| | | | JWT was issued. This claim can be |
| | | | used to determine the age of the |
| | | | token. This claim is OPTIONAL. |
 
 
 
 
 
 
 
Jones, et al. Expires May 2, 2012 [Page 7]
Jones, et al. Expires June 15, 2012 [Page 7]
Internet-Draft JSON Web Token (JWT) October 2011
Internet-Draft JSON Web Token (JWT) December 2011
 
 
| iat | number | IntDate | The "iat" (issued at) claim |
| | | | identifies the time at which the |
| | | | JWT was issued. This claim can be |
| | | | used to determine the age of the |
| | | | token. This claim is OPTIONAL. |
| iss | string | StringOrURI | The "iss" (issuer) claim |
| | | | identifies the principal that |
| | | | issued the JWT. The processing of |
404,20 → 409,49
| | | | identifies the audience that the |
| | | | JWT is intended for. The |
| | | | principal intended to process the |
| | | | JWT MUST be identified by the |
| | | | JWT MUST be identified with the |
| | | | value of the audience claim. If |
| | | | the principal processing the claim |
| | | | does not identify itself with the |
| | | | identifier in the "aud" claim |
| | | | value then the JWT MUST be |
| | | | rejected. The interpretation of |
| | | | the contents of the audience value |
| | | | is generally application specific. |
| | | | The "aud" value is case sensitive. |
| | | | the audience value is generally |
| | | | application specific. The "aud" |
| | | | value is case sensitive. This |
| | | | claim is OPTIONAL. |
| prn | string | StringOrURI | The "prn" (principal) claim |
| | | | identifies the subject of the JWT. |
| | | | The processing of this claim is |
| | | | generally application specific. |
| | | | The "prn" value is case sensitive. |
| | | | This claim is OPTIONAL. |
| jti | string | String | The "jti" (JWT ID) claim provides |
| | | | a unique identifier for the JWT. |
| | | | The identifier value MUST be |
| | | | assigned in a manner that ensures |
| | | | that there is a negligible |
| | | | probability that the same value |
| | | | will be accidentally assigned to a |
| | | | different data object. The "jti" |
| | | | claim can be used to prevent the |
| | | | JWT from being replayed. The |
| | | | "jti" value is case sensitive. |
| | | | This claim is OPTIONAL. |
 
 
 
 
 
 
Jones, et al. Expires June 15, 2012 [Page 8]
Internet-Draft JSON Web Token (JWT) December 2011
 
 
| typ | string | String | The "typ" (type) claim is used to |
| | | | declare a type for the contents of |
| | | | this JWT Claims Object. The "typ" |
| | | | this JWT Claims Set. The "typ" |
| | | | value is case sensitive. This |
| | | | claim is OPTIONAL. |
+-------+--------+-------------+------------------------------------+
441,14 → 475,6
| | 3986 [RFC3986]. |
+-------------+-----------------------------------------------------+
 
 
 
 
Jones, et al. Expires May 2, 2012 [Page 8]
Internet-Draft JSON Web Token (JWT) October 2011
 
 
Table 2: Claim Syntax Definitions
 
4.2. Public Claim Names
461,16 → 487,24
 
o Domain Names,
 
o Object Identifiers (OIDs) as defined in the ITU-T X 660 and X 670
Recommendation series or
o Object Identifiers (OIDs) as defined in the ITU-T X.660 and X.670
Recommendation series, or
 
o Universally Unique IDentifier (UUID) as defined in RFC 4122
[RFC4122].
 
In each case, the definer of the name or value MUST take reasonable
precautions to make sure they are in control of the part of the
namespace they use to define the claim name.
In each case, the definer of the name or value needs to take
reasonable precautions to make sure they are in control of the part
of the namespace they use to define the claim name.
 
 
 
 
Jones, et al. Expires June 15, 2012 [Page 9]
Internet-Draft JSON Web Token (JWT) December 2011
 
 
4.3. Private Claim Names
 
A producer and consumer of a JWT may agree to any claim name that is
483,8 → 517,14
 
The members of the JSON object represented by the JWT Header describe
the cryptographic operations applied to the JWT and optionally,
additional properties of the JWT.
additional properties of the JWT. The member names within the JWT
Header are referred to as Header Parameter Names. These names MUST
be unique. The corresponding values are referred to as Header
Parameter Values.
 
Implementations MUST understand the entire contents of the header;
otherwise, the JWT MUST be rejected for processing.
 
There are two ways of distinguishing whether the JWT is a JWS or JWE.
The first is by examining the "alg" (algorithm) header value. If the
value represents a signature algorithm, the JWT is a JWS; if it
493,22 → 533,34
exists. If the "enc" member exists, the JWT is a JWE; otherwise, the
JWT is a JWS. Both methods will yield the same result.
 
Implementations MUST understand the entire contents of the header;
otherwise, the JWT MUST be rejected for processing.
 
JWS Header Parameters are defined by [JWS]. JWE Header Parameters
are defined by [JWE]. This specification further specifies the use
of the following header parameters in both the cases where the JWT is
a JWS and where it is a JWE.
 
 
 
Jones, et al. Expires May 2, 2012 [Page 9]
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
Jones, et al. Expires June 15, 2012 [Page 10]
Internet-Draft JSON Web Token (JWT) October 2011
Internet-Draft JSON Web Token (JWT) December 2011
 
 
are defined by [JWE]. This specification further specifies the use
of the following header parameters in both the cases where the JWT is
a JWS and where it is a JWE.
 
+----------+--------+-----------+-----------------------------------+
| Header | JSON | Header | Header Parameter Semantics |
| Paramete | Value | Parameter | |
548,60 → 600,60
JWTs MUST use the "alg" value "none", and are formatted identically
to a signed JWT with an empty signature. This means that the
base64url encoding of the bytes representing the UTF-8 encoding of
the JWT Claims Object is the JWT Second Part, and the empty string is
the JWT Claims Set is the JWT Second Part, and the empty string is
the JWT Third Part.
 
6.1. Example Plaintext JWT
 
The following example JWT Header declares that the encoded object is
a Plaintext JWT:
{"alg":"none"}
 
 
 
 
Jones, et al. Expires May 2, 2012 [Page 10]
Jones, et al. Expires June 15, 2012 [Page 11]
Internet-Draft JSON Web Token (JWT) October 2011
Internet-Draft JSON Web Token (JWT) December 2011
 
 
6.1. Example Plaintext JWT
 
The following example JWT Header declares that the encoded object is
a Plaintext JWT:
{"alg":"none"}
 
Base64url encoding the bytes of the UTF-8 representation of the JWT
Header yields this Encoded JWT Header:
eyJhbGciOiJub25lIn0
 
The following is an example of a JWT Claims Object:
The following is an example of a JWT Claims Set:
{"iss":"joe",
"exp":1300819380,
"http://example.com/is_root":true}
 
Base64url encoding the bytes of the UTF-8 representation of the JSON
Claims Object yields this Encoded JWS Payload, which is used as the
JWT Second Part:
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ
Claims Set yields this Encoded JWS Payload, which is used as the JWT
Second Part (with line breaks for display purposes only):
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
 
The JWT Third Part is the empty string.
 
Concatenating these parts in the order Header.Second.Third with
period characters between the parts yields this complete JWT (with
line breaks for display purposes only):
eyJhbGciOiJub25lIn0
.
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ
.
eyJhbGciOiJub25lIn0
.
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
.
 
 
7. Rules for Creating and Validating a JWT
 
To create a JWT, one MUST follow these steps:
To create a JWT, one MUST perform these steps:
 
1. Create a JWT Claims Object containing the desired claims. Note
that white space is explicitly allowed in the representation and
no canonicalization is performed before encoding.
1. Create a JWT Claims Set containing the desired claims. Note that
white space is explicitly allowed in the representation and no
canonicalization is performed before encoding.
 
2. Let the Message be the bytes of the UTF-8 representation of the
JWT Claims Object.
JWT Claims Set.
 
3. Create a JWT Header containing the desired set of header
parameters. If the JWT is to be signed or encrypted, they MUST
609,19 → 661,18
respectively. Else, if the JWT is to be plaintext, the "alg"
value "none" MUST be used. Note that white space is explicitly
allowed in the representation and no canonicalization is
performed before encoding.
 
4. Base64url encode the bytes of the UTF-8 representation of the JWT
Header. Let this be the Encoded JWT Header.
 
 
Jones, et al. Expires May 2, 2012 [Page 11]
 
Jones, et al. Expires June 15, 2012 [Page 12]
Internet-Draft JSON Web Token (JWT) October 2011
Internet-Draft JSON Web Token (JWT) December 2011
 
 
performed before encoding.
 
4. Base64url encode the bytes of the UTF-8 representation of the JWT
Header. Let this be the Encoded JWT Header.
 
5. Depending upon whether the JWT is to be signed, encrypted, or
plaintext, there are three cases:
 
665,18 → 716,18
 
3. The Encoded JWT Header MUST be successfully base64url decoded
following the restriction given in this specification that no
padding characters have been used.
 
4. The JWT Header MUST be completely valid JSON syntax conforming
to RFC 4627 [RFC4627].
 
 
Jones, et al. Expires May 2, 2012 [Page 12]
Internet-Draft JSON Web Token (JWT) October 2011
 
 
padding characters have been used.
Jones, et al. Expires June 15, 2012 [Page 13]
Internet-Draft JSON Web Token (JWT) December 2011
 
4. The JWT Header MUST be completely valid JSON syntax conforming
to RFC 4627 [RFC4627].
 
5. The JWT Header MUST be validated to only include parameters and
values whose syntax and semantics are both understood and
706,14 → 757,14
nested signing or encryption operations, respectively. In this
case, return to Step 1, using the Message as the JWT.
 
9. Otherwise, let the JWT Claims object be the Message.
9. Otherwise, let the JWT Claims Set be the Message.
 
10. The JWT Claims Object MUST be completely valid JSON syntax
10. The JWT Claims Set MUST be completely valid JSON syntax
conforming to RFC 4627 [RFC4627].
 
11. When used in a security-related context, the JWT Claims Object
MUST be validated to only include claims whose syntax and
semantics are both understood and supported.
11. When used in a security-related context, the JWT Claims Set MUST
be validated to only include claims whose syntax and semantics
are both understood and supported.
 
Processing a JWT inevitably requires comparing known strings to
values in the token. For example, in checking what the algorithm is,
722,19 → 773,18
parameter name. A similar process occurs when determining if the
value of the "alg" header parameter represents a supported algorithm.
 
Comparisons between JSON strings and other Unicode strings MUST be
performed as specified below:
 
 
Jones, et al. Expires May 2, 2012 [Page 13]
Internet-Draft JSON Web Token (JWT) October 2011
 
 
Comparing Unicode strings, however, has significant security
implications, as per Section 10.
 
Comparisons between JSON strings and other Unicode strings MUST be
performed as specified below:
Jones, et al. Expires June 15, 2012 [Page 14]
Internet-Draft JSON Web Token (JWT) December 2011
 
 
1. Remove any JSON applied escaping to produce an array of Unicode
code points.
 
777,20 → 827,20
defines inclusion of the claim names defined in Table 1.
 
 
10. Security Considerations
 
TBD: Lots of work to do here. We need to remember to look into any
issues relating to security and JSON parsing. One wonders just how
secure most JSON parsing libraries are. Were they ever hardened for
security scenarios? If not, what kind of holes does that open up?
 
 
Jones, et al. Expires May 2, 2012 [Page 14]
 
Jones, et al. Expires June 15, 2012 [Page 15]
Internet-Draft JSON Web Token (JWT) October 2011
Internet-Draft JSON Web Token (JWT) December 2011
 
 
10. Security Considerations
 
TBD: Lots of work to do here. We need to remember to look into any
issues relating to security and JSON parsing. One wonders just how
secure most JSON parsing libraries are. Were they ever hardened for
security scenarios? If not, what kind of holes does that open up?
Also, we need to walk through the JSON standard and see what kind of
issues we have especially around comparison of names. For instance,
comparisons of claim names and other parameters must occur after they
834,17 → 884,19
then input containing them MUST be rejected.
 
 
11. Open Issues and Things To Be Done (TBD)
 
The following items remain to be done in this draft:
 
Jones, et al. Expires May 2, 2012 [Page 15]
Internet-Draft JSON Web Token (JWT) October 2011
 
 
11. Open Issues and Things To Be Done (TBD)
 
The following items remain to be done in this draft:
 
Jones, et al. Expires June 15, 2012 [Page 16]
Internet-Draft JSON Web Token (JWT) December 2011
 
 
o Provide an example of an encrypted JWT.
 
o Clarify the optional ability to provide type information for JWTs
852,7 → 904,7
specify the "typ" Claim Name in addition to the Header Parameter,
whether it conveys syntax or semantics, and indeed, whether this
is the right approach. Also clarify the relationship between
these type values and MIME [RFC2045] types.
these type values and MIME [RFC2045] types (if any).
 
o Think about how to best describe the concept currently described
as "the bytes of the UTF-8 representation of". Possible terms to
878,7 → 930,7
 
[JWS] Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer,
J., Sakimura, N., and P. Tarjan, "JSON Web Signature
(JWS)", October 2011.
(JWS)", December 2011.
 
[RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part One: Format of Internet Message
890,16 → 942,17
[RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the
Internet: Timestamps", RFC 3339, July 2002.
 
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003.
 
 
Jones, et al. Expires May 2, 2012 [Page 16]
 
 
Jones, et al. Expires June 15, 2012 [Page 17]
Internet-Draft JSON Web Token (JWT) October 2011
Internet-Draft JSON Web Token (JWT) December 2011
 
 
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003.
 
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005.
926,7 → 979,7
September 2010.
 
[JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web
Encryption (JWE)", October 2011.
Encryption (JWE)", December 2011.
 
[MagicSignatures]
Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic
946,16 → 999,16
Unique IDentifier (UUID) URN Namespace", RFC 4122,
July 2005.
 
[SWT] Hardt, D. and Y. Goland, "Simple Web Token (SWT)",
Version 0.9.5.1, November 2009.
 
 
Jones, et al. Expires May 2, 2012 [Page 17]
 
Jones, et al. Expires June 15, 2012 [Page 18]
Internet-Draft JSON Web Token (JWT) October 2011
Internet-Draft JSON Web Token (JWT) December 2011
 
 
[SWT] Hardt, D. and Y. Goland, "Simple Web Token (SWT)",
Version 0.9.5.1, November 2009.
 
[W3C.CR-xml11-20021015]
Cowan, J., "Extensible Markup Language (XML) 1.1", W3C
CR CR-xml11-20021015, October 2002.
1001,21 → 1054,36
and ideas for JSON tokens that Dick Hardt discussed within the OpenID
community.
 
Solutions for signing JSON content were previously explored by Magic
Signatures [MagicSignatures], JSON Simple Sign [JSS], and Canvas
Applications [CanvasApp], all of which influenced this draft.
 
 
 
Jones, et al. Expires May 2, 2012 [Page 18]
Jones, et al. Expires June 15, 2012 [Page 19]
Internet-Draft JSON Web Token (JWT) October 2011
Internet-Draft JSON Web Token (JWT) December 2011
 
 
Solutions for signing JSON content were previously explored by Magic
Signatures [MagicSignatures], JSON Simple Sign [JSS], and Canvas
Applications [CanvasApp], all of which influenced this draft.
Appendix D. Document History
 
-07
 
Appendix D. Document History
o Defined the "prn" (principal) claim to identify the subject of the
JWT.
 
o Defined the "jti" (JWT ID) claim to enable replay protection.
 
o Use the term "JWT Claims Set" rather than "JWT Claims Object"
since this is actually a string representing a JSON object and not
the JSON object itself.
 
o Moved "MUST" requirements from the Overview to later in the spec.
 
o Respect line length restrictions in examples.
 
o Applied other editorial improvements.
 
-06
 
o Reference and use content from [JWS] and [JWE], rather than
1046,6 → 1114,13
 
-03
 
 
 
Jones, et al. Expires June 15, 2012 [Page 20]
Internet-Draft JSON Web Token (JWT) December 2011
 
 
o Added "http://openid.net/specs/jwt/1.0" as a token type identifier
URI for JWTs.
 
1058,13 → 1133,6
only want to use ECDSA when using asymmetric keys, either for
security or key length reasons, or both.
 
 
 
Jones, et al. Expires May 2, 2012 [Page 19]
Internet-Draft JSON Web Token (JWT) October 2011
 
 
o Defined "alg" value "none" to represent unsigned JWTs.
 
-02
1097,28 → 1165,28
URI: http://self-issued.info/
 
 
Dirk Balfanz
Google
 
Email: balfanz@google.com
 
 
John Bradley
independent
 
Email: ve7jtb@ve7jtb.com
 
 
 
Jones, et al. Expires June 15, 2012 [Page 21]
Internet-Draft JSON Web Token (JWT) December 2011
 
 
Dirk Balfanz
Google
 
Email: balfanz@google.com
 
 
John Bradley
independent
 
Jones, et al. Expires May 2, 2012 [Page 20]
Internet-Draft JSON Web Token (JWT) October 2011
Email: ve7jtb@ve7jtb.com
 
 
Yaron Y. Goland
1160,17 → 1228,5
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
Jones, et al. Expires May 2, 2012 [Page 21]
Jones, et al. Expires June 15, 2012 [Page 22]
1.0/draft-jones-json-web-token.xml
1,4 → 1,5
<?xml version="1.0" encoding="US-ASCII"?>
<?xml-stylesheet type='text/xsl' href='http://xml.resource.org/authoring/rfc2629.xslt' ?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC2119 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY OASIS.saml-core-2.0-os PUBLIC "" "http://xml.resource.org/public/rfc/bibxml2/reference.OASIS.saml-core-2.0-os.xml">
15,7 → 16,7
]>
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="3"?>
<?rfc tocdepth="4"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
23,7 → 24,7
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="std" docName="draft-jones-json-web-token-06"
<rfc category="std" docName="draft-jones-json-web-token-07"
ipr="trust200902">
<front>
<title>JSON Web Token (JWT)</title>
78,9 → 79,9
</address>
</author>
 
<date day="30" month="October" year="2011" />
<date day="13" month="December" year="2011" />
 
<area>Applications</area>
<area>Security</area>
 
<keyword>RFC</keyword>
<keyword>Request for Comments</keyword>
148,40 → 149,51
<list style="hanging">
 
<t hangText="JSON Web Token (JWT)">
A string consisting of three parts: the JWT Header, the
A string consisting of three parts: the Encoded JWT Header, the
JWT Second Part, and the JWT Third Part, in that order,
with the parts being separated by period ('.') characters,
and each part containing base64url encoded content.
</t>
 
<t hangText="JWT Header">
A string containing a JSON object that
A string representing a JSON object that
describes the cryptographic operations applied to the JWT.
When the JWT is signed, the JWT Header is the JWS Header.
When the JWT is encrypted, the JWT Header is the JWE Header.
</t>
 
<t hangText="Header Parameter Names">
The names of the members within the JWT Header.
</t>
<t hangText="Header Parameter Values">
The values of the members within the JWT Header.
</t>
 
<t hangText="JWT Second Part">
When the JWT is signed, the JWT Second Part is the Encoded JWS Payload.
When the JWT is encrypted, the JWT Second Part is the Encoded JWE Encrypted Key.
</t>
 
<t hangText="JWT Third Part">
When the JWT is signed, the JWT Third Part is the Encoded JWS Signature.
When the JWT is encrypted, the JWT Third Part is the Encoded JWE Ciphertext.
</t>
 
<t hangText="JWT Claims Object">
A JSON object that represents the claims contained in the JWT.
When the JWT is signed, the bytes of the UTF-8 representation of the JWT Claims Object are base64url encoded to create the Encoded JWS Payload.
When the JWT is encrypted, the bytes of the UTF-8 representation of the JWT Claims Object are used as the JWE Plaintext.
<t hangText="JWT Claims Set">
A string representing a JSON object that
contains the claims conveyed by the JWT.
When the JWT is signed, the bytes of the UTF-8 representation of the
JWT Claims Set are base64url encoded to create the Encoded JWS Payload.
When the JWT is encrypted, the bytes of the UTF-8 representation of the
JWT Claims Set are used as the JWE Plaintext.
</t>
 
<t hangText="Claim Names">
The names of the members of the JWT Claims Object.
The names of the members of the JSON object represented by
the JWT Claims Set.
</t>
<t hangText="Claim Values">
The values of the members of the JWT Claims Object.
The values of the members of the JSON object represented by
the JWT Claims Set.
</t>
 
<t hangText="Encoded JWT Header">
208,7 → 220,7
<t>
JWTs represent a set of claims as a JSON object that is
base64url encoded and digitally signed and/or
encrypted. This object is the JWT Claims Object.
encrypted. The JWT Claims Set represents this JSON object.
As per <xref target="RFC4627">RFC 4627</xref>
Section 2.2, the JSON object consists of zero or more
name/value pairs (or members), where the names are strings and
216,19 → 228,19
claims represented by the JWT.
</t>
<t>
The member names within the JWT Claims Object are
referred to as Claim Names. These names MUST be unique. The
The member names within the JWT Claims Set are
referred to as Claim Names. The
corresponding values are referred to as Claim Values.
</t>
<t>
The bytes of the UTF-8 representation of the JWT Claims Object
The bytes of the UTF-8 representation of the JWT Claims Set
are signed in the manner described in JSON Web Signature (JWS)
<xref target="JWS" /> and/or encrypted in the manner described
in JSON Web Encryption (JWE) <xref target="JWE" />.
</t>
<t>
The contents of the JWT Header describe the cryptographic
operations applied to the JWT Claims Object.
operations applied to the JWT Claims Set.
If the JWT Header is a JWS Header, the claims are signed.
If the JWT Header is a JWE Header, the claims are encrypted.
</t>
262,7 → 274,7
<figure><artwork><![CDATA[eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9]]></artwork></figure>
 
<t>
The following is an example of a JWT Claims Object:
The following is an example of a JWT Claims Set:
</t>
 
<figure><artwork><![CDATA[{"iss":"joe",
271,11 → 283,13
 
<t>
Base64url encoding the bytes of the UTF-8 representation of
the JSON Claims Object yields this Encoded JWS Payload,
which is used as the JWT Second Part:
the JSON Claims Set yields this Encoded JWS Payload,
which is used as the JWT Second Part
(with line breaks for display purposes only):
</t>
 
<figure><artwork><![CDATA[eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ]]></artwork></figure>
<figure><artwork><![CDATA[eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly
9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ]]></artwork></figure>
 
<t>
Signing the Encoded JWS Header and Encoded JWS Payload with
296,7 → 310,8
 
<figure><artwork><![CDATA[eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
.
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
.
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk]]></artwork></figure>
 
312,8 → 327,10
<section title="JWT Claims">
 
<t>
A JWT contains a set of claims represented as a base64url
encoded JSON object. Note however, that the set of claims a
The JWT Claims Set represents a JSON object whose members
are the claims conveyed by the JWT.
The Claim Names within this object MUST be unique.
Note however, that the set of claims that a
JWT must contain to be considered valid is context-dependent
and is outside the scope of this specification. When used in
a security-related context, implementations MUST understand
401,22 → 418,48
The <spanx style="verb">aud</spanx> (audience) claim
identifies the audience that the JWT is intended for. The
principal intended to process the JWT MUST be identified
by the value of the audience claim. If the principal
with the value of the audience claim. If the principal
processing the claim does not identify itself with the
identifier in the <spanx style="verb">aud</spanx> claim
value then the JWT MUST be rejected. The interpretation
of the contents of the audience value is generally
of the audience value is generally
application specific.
The <spanx style="verb">aud</spanx> value is case sensitive.
This claim is OPTIONAL.
</c>
 
<c>prn</c>
<c>string</c>
<c>StringOrURI</c>
<c>
The <spanx style="verb">prn</spanx> (principal) claim
identifies the subject of the JWT. The processing of this
claim is generally application specific.
The <spanx style="verb">prn</spanx> value is case sensitive.
This claim is OPTIONAL.
</c>
 
<c>jti</c>
<c>string</c>
<c>String</c>
<c>
The <spanx style="verb">jti</spanx> (JWT ID) claim
provides a unique identifier for the JWT. The identifier
value MUST be assigned in a manner that ensures that there
is a negligible probability that the same value will be
accidentally assigned to a different data object. The
<spanx style="verb">jti</spanx> claim can be used to
prevent the JWT from being replayed.
The <spanx style="verb">jti</spanx> value is case sensitive.
This claim is OPTIONAL.
</c>
 
<c>typ</c>
<c>string</c>
<c>String</c>
<c>
The <spanx style="verb">typ</spanx> (type) claim is used
to declare a type for the contents of this JWT Claims Object.
to declare a type for the contents of this JWT Claims Set.
The <spanx style="verb">typ</spanx> value is case sensitive.
This claim is OPTIONAL.
</c>
472,8 → 515,8
Domain Names,
</t>
<t>
Object Identifiers (OIDs) as defined in the ITU-T X 660
and X 670 Recommendation series or
Object Identifiers (OIDs) as defined in the ITU-T X.660
and X.670 Recommendation series, or
</t>
<t>
Universally Unique IDentifier (UUID) as defined in <xref
481,7 → 524,7
</t>
</list>
 
In each case, the definer of the name or value MUST take
In each case, the definer of the name or value needs to take
reasonable precautions to make sure they are in control of
the part of the namespace they use to define the claim
name.</t>
507,8 → 550,16
The members of the JSON object represented by the JWT Header
describe the cryptographic operations applied to the JWT and
optionally, additional properties of the JWT.
The member names within the JWT Header are
referred to as Header Parameter Names. These names MUST be
unique. The corresponding values are referred to as Header
Parameter Values.
</t>
<t>
Implementations MUST understand the entire contents of the
header; otherwise, the JWT MUST be rejected for processing.
</t>
<t>
There are two ways of distinguishing whether the JWT is a JWS
or JWE. The first is by examining the <spanx
style="verb">alg</spanx> (algorithm) header value. If the
521,10 → 572,6
yield the same result.
</t>
<t>
Implementations MUST understand the entire contents of the
header; otherwise, the JWT MUST be rejected for processing.
</t>
<t>
JWS Header Parameters are defined by <xref target="JWS" />.
JWE Header Parameters are defined by <xref target="JWE" />.
This specification further specifies the use of the following
573,7 → 620,7
style="verb">none</spanx>, and are formatted identically to a
signed JWT with an empty signature. This means that the
base64url encoding of the bytes representing the UTF-8
encoding of the JWT Claims Object is the JWT Second Part, and
encoding of the JWT Claims Set is the JWT Second Part, and
the empty string is the JWT Third Part.
</t>
 
594,7 → 641,7
<figure><artwork><![CDATA[eyJhbGciOiJub25lIn0]]></artwork></figure>
 
<t>
The following is an example of a JWT Claims Object:
The following is an example of a JWT Claims Set:
</t>
 
<figure><artwork><![CDATA[{"iss":"joe",
603,11 → 650,13
 
<t>
Base64url encoding the bytes of the UTF-8 representation of
the JSON Claims Object yields this Encoded JWS Payload,
which is used as the JWT Second Part:
the JSON Claims Set yields this Encoded JWS Payload,
which is used as the JWT Second Part
(with line breaks for display purposes only):
</t>
 
<figure><artwork><![CDATA[eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ]]></artwork></figure>
<figure><artwork><![CDATA[eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ]]></artwork></figure>
 
<t>
The JWT Third Part is the empty string.
622,7 → 671,8
 
<figure><artwork><![CDATA[eyJhbGciOiJub25lIn0
.
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
.
]]></artwork></figure>
</section>
632,19 → 682,19
<section title="Rules for Creating and Validating a JWT">
 
<t>
To create a JWT, one MUST follow these steps:
To create a JWT, one MUST perform these steps:
 
<list style="numbers">
 
<t>
Create a JWT Claims Object containing the desired claims.
Create a JWT Claims Set containing the desired claims.
Note that white space is explicitly allowed in the
representation and no canonicalization is performed before
encoding.
</t>
<t>
Let the Message be the bytes of the UTF-8 representation
of the JWT Claims Object.
of the JWT Claims Set.
</t>
<t>
Create a JWT Header containing the desired set of header
773,16 → 823,16
this case, return to Step 1, using the Message as the JWT.
</t>
<t>
Otherwise, let the JWT Claims object be the Message.
Otherwise, let the JWT Claims Set be the Message.
</t>
<t>
The JWT Claims Object MUST be completely valid
The JWT Claims Set MUST be completely valid
JSON syntax conforming to <xref target="RFC4627">RFC
4627</xref>.
</t>
<t>
When used in a security-related context, the JWT
Claims Object MUST be validated to only include claims
When used in a security-related context, the
JWT Claims Set MUST be validated to only include claims
whose syntax and semantics are both understood and
supported.
</t>
793,18 → 843,16
Processing a JWT inevitably requires comparing known strings
to values in the token. For example, in checking what the
algorithm is, the Unicode string encoding <spanx style="verb">alg</spanx> will be
checked against the member names in the JWT Header to see if there is a matching header parameter
checked against the member names in the JWT Header
to see if there is a matching header parameter
name. A similar process occurs when determining if the value
of the <spanx style="verb">alg</spanx> header parameter represents a supported
algorithm. Comparing Unicode strings, however, has significant
security implications, as per <xref target="Security"></xref>.
algorithm.
</t>
<t>
Comparisons between JSON strings and other Unicode strings
MUST be performed as specified below:
</t>
 
<t>
<list style="numbers">
 
<t>
954,7 → 1002,7
whether it conveys syntax or semantics, and indeed,
whether this is the right approach. Also clarify the
relationship between these type values and <xref
target="RFC2045">MIME</xref> types.
target="RFC2045">MIME</xref> types (if any).
</t>
<t>
Think about how to best describe the concept currently
1075,9 → 1123,9
</address>
</author>
 
<date day="30" month="October" year="2011" />
<date day="13" month="December" year="2011" />
</front>
<format target="http://self-issued.info/docs/draft-jones-json-web-signature.html" type="HTML" />
<format target="http://tools.ietf.org/html/draft-jones-json-web-signature" type="HTML" />
</reference>
</references>
 
1170,9 → 1218,9
</address>
</author>
 
<date day="30" month="October" year="2011" />
<date day="13" month="December" year="2011" />
</front>
<format target="http://self-issued.info/docs/draft-jones-json-web-encryption.html" type="HTML" />
<format target="http://tools.ietf.org/html/draft-jones-json-web-encryption" type="HTML" />
</reference>
 
</references>
1241,6 → 1289,34
 
<section title='Document History'>
<t>
-07
<list style='symbols'>
<t>
Defined the <spanx style="verb">prn</spanx> (principal)
claim to identify the subject of the JWT.
</t>
<t>
Defined the <spanx style="verb">jti</spanx> (JWT ID)
claim to enable replay protection.
</t>
<t>
Use the term "JWT Claims Set" rather than "JWT Claims Object"
since this is actually a string representing a JSON object
and not the JSON object itself.
</t>
<t>
Moved "MUST" requirements from the Overview to later in
the spec.
</t>
<t>
Respect line length restrictions in examples.
</t>
<t>
Applied other editorial improvements.
</t>
</list>
</t>
<t>
-06
<list style='symbols'>
<t>