One document matched: draft-jones-json-web-token-04.xml
<?xml version="1.0" encoding="US-ASCII"?>
<!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">
<!ENTITY W3C.CR-xml11-20021015 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml4/reference.W3C.CR-xml11-20021015.xml">
<!ENTITY RFC2045 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2045.xml">
<!ENTITY RFC3275 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3275.xml">
<!ENTITY RFC3339 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3339.xml">
<!ENTITY RFC3629 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3629.xml">
<!ENTITY RFC3986 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
<!ENTITY RFC4122 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4122.xml">
<!ENTITY RFC4627 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4627.xml">
<!ENTITY RFC4648 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4648.xml">
<!ENTITY RFC5226 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5226.xml">
]>
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="3"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="std" docName="draft-jones-json-web-token-04"
ipr="trust200902">
<front>
<title>JSON Web Token (JWT)</title>
<author fullname="Michael B. Jones" initials="M.B." surname="Jones">
<organization>Microsoft</organization>
<address>
<email>mbj@microsoft.com</email>
<uri>http://self-issued.info/</uri>
</address>
</author>
<author fullname="Dirk Balfanz" initials="D." surname="Balfanz">
<organization>Google</organization>
<address>
<email>balfanz@google.com</email>
</address>
</author>
<author fullname="John Bradley" initials="J." surname="Bradley">
<organization>independent</organization>
<address>
<email>ve7jtb@ve7jtb.com</email>
</address>
</author>
<author fullname="Yaron Y. Goland" initials="Y.Y." surname="Goland">
<organization>Microsoft</organization>
<address>
<email>yarong@microsoft.com</email>
</address>
</author>
<author fullname="John Panzer" initials="J." surname="Panzer">
<organization>Google</organization>
<address>
<email>jpanzer@google.com</email>
</address>
</author>
<author fullname="Nat Sakimura" initials="N." surname="Sakimura">
<organization>Nomura Research Institute</organization>
<address>
<email>n-sakimura@nri.co.jp</email>
</address>
</author>
<author fullname="Paul Tarjan" initials="P." surname="Tarjan">
<organization>Facebook</organization>
<address>
<email>pt@fb.com</email>
</address>
</author>
<date day="30" month="March" year="2011" />
<area>Applications</area>
<keyword>RFC</keyword>
<keyword>Request for Comments</keyword>
<keyword>I-D</keyword>
<keyword>Internet-Draft</keyword>
<keyword>Assertion</keyword>
<keyword>Claim</keyword>
<keyword>Simple Web Token</keyword>
<keyword>Security Token</keyword>
<keyword>SWT</keyword>
<keyword>JavaScript Object Notation</keyword>
<keyword>JSON</keyword>
<keyword>JSON Web Token</keyword>
<keyword>JWT</keyword>
<keyword>JSON Web Signature</keyword>
<keyword>JWS</keyword>
<keyword>JSON Web Encryption</keyword>
<keyword>JWE</keyword>
<abstract>
<t>
JSON Web Token (JWT) is a means of representing claims to be
transferred between two parties. The claims in a JWT are
encoded as a JSON object that is digitally signed using a JSON
Web Signature (JWS) and optionally encrypted using JSON Web
Encryption (JWE).
</t>
<t>
The suggested pronunciation of JWT is the same as the English
word "jot".
</t>
</abstract>
<note title="Requirements Language">
<t>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described
in <xref target="RFC2119">RFC 2119</xref>.
</t>
</note>
</front>
<middle>
<section title="Introduction">
<t>
JSON Web Token (JWT) is a compact token format intended for
space constrained environments such as HTTP Authorization
headers and URI query parameters. JWTs encode claims to be
transmitted as a JSON object (as defined in <xref
target="RFC4627">RFC 4627</xref>) that is base64url encoded
and digitally signed. Signing is accomplished using a JSON
Web Signature (JWS) <xref target="JWS" />. JWTs may also be
optionally encrypted using JSON Web Encryption (JWE) <xref
target="JWE" />.
</t>
<t>
The suggested pronunciation of JWT is the same as the English
word "jot".
</t>
</section>
<section title="Terminology">
<t>
<list style="hanging">
<t hangText="JSON Web Token (JWT)">
A string consisting of three JWT Token Segments: the JWT
Header Segment, the JWT Claim Segment, and the JWT Crypto
Segment, in that order, with the segments being separated
by period ('.') characters.
</t>
<t hangText="JWT Token Segment">
One of the three parts that make up a JSON Web Token
(JWT). JWT Token Segments are always base64url encoded
values.
</t>
<t hangText="JWT Header Segment">
A JWT Token Segment containing a base64url encoded JSON
object that describes the cryptographic operations applied
to the JWT Header Segment and the JWT Claim Segment. The
JWT Header Segment is the JWS Header Input for creating a
JSON Web Signature (JWS) <xref target="JWS" /> for the JWT.
</t>
<t hangText="JWT Claim Segment">
A JWT Token Segment containing a base64url encoded JSON
object that encodes the claims contained in the JWT. The
JWT Claim Segment is the JWS Payload Input for creating a
JSON Web Signature (JWS) <xref target="JWS" /> for the JWT.
</t>
<t hangText="JWT Crypto Segment">
A JWT Token Segment containing base64url encoded
cryptographic material that secures the contents of the
JWT Header Segment and the JWT Claim Segment. The JWT
Crypto Segment is the JWS Crypto Output for a JSON Web
Signature (JWS) <xref target="JWS" /> created for the JWT.
</t>
<t hangText="Decoded JWT Header Segment">
A JWT Header Segment that has been base64url decoded
back into a JSON object.
</t>
<t hangText="Decoded JWT Claim Segment">
A JWT Claim Segment that has been base64url decoded back
into a JSON object.
</t>
<t hangText="Decoded JWT Crypto Segment">
A JWT Crypto Segment that has been base64url decoded back
into cryptographic material.
</t>
<t hangText="Claim Names">
The names of the members of the JSON object represented
in a JWT Claim Segment.
</t>
<t hangText="Claim Values">
The values of the members of the JSON object represented
in a JWT Claim Segment.
</t>
<t hangText="Base64url Encoding">
For the purposes of this specification, this term always
refers to the he URL- and filename-safe Base64 encoding
described in <xref target="RFC4648">RFC 4648</xref>,
Section 5, with the '=' padding characters omitted, as
permitted by Section 3.2.
</t>
</list>
</t>
</section>
<section title="JSON Web Token (JWT) Overview">
<t>
JWTs represent a set of claims as a JSON object that is
base64url encoded and digitally signed and optionally
encrypted. 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
the values are arbitrary JSON values. These members are the
claims represented by the JWT. The JSON object is base64url
encoded to produce the JWT Claim Segment.
</t>
<t>
The member names within the Decoded JWT Claim Segment are
referred to as Claim Names. These names MUST be unique. The
corresponding values are referred to as Claim Values.
</t>
<t>
The JWT Claim Object is signed in the manner described in JSON
Web Signature (JWS) <xref target="JWS" /> and optionally
encrypted in the manner described in JSON Web Encryption (JWE)
<xref target="JWE" />. The JWT Claim Object is the JWS
Payload Input. The JWT Header Object is the JWS Header Input.
The JWT Crypto Segment is the corresponding JWS Crypto Output.
</t>
<t>
A JWT is represented as the concatenation of the JWT Header
Segment, the JWT Claim Segment, and the JWT Crypto Segment, in
that order, with the segments being separated by period ('.')
characters.
</t>
<section title="Example JWT" anchor="ExampleJWT">
<t>
The following is an example of a JSON object that can be
encoded to produce a JWT Claim Segment:
</t>
<artwork><![CDATA[{"iss":"joe",
"exp":1300819380,
"http://example.com/is_root":true}]]></artwork>
<t>
Base64url encoding the UTF-8 representation of the JSON
object yields this JWT Claim Segment:
</t>
<artwork><![CDATA[eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ]]></artwork>
<t>
The following example JSON header object declares that the
encoded object is a JSON Web Token (JWT) and the JWT Header
Segment and the JWT Claim Segment are signed using the HMAC
SHA-256 algorithm:
</t>
<artwork><![CDATA[{"typ":"JWT",
"alg":"HS256"}]]></artwork>
<t>
Base64url encoding the UTF-8 representation of the JSON
header object yields this JWT Header Segment value:
</t>
<artwork><![CDATA[eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9]]></artwork>
<t>
Signing the UTF-8 representation of the JWT Header Segment
and JWT Claim Segment with the HMAC SHA-256 algorithm and
base64url encoding the result, as per <xref
target="HMACSHA256Example"></xref>, in the manner
specified in <xref target="JWS" />, yields this JWT Crypto
Segment value:
</t>
<artwork><![CDATA[dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk]]></artwork>
<t>
Concatenating these segments in the order
Header.Claims.Signature with period characters between the
segments yields this complete JWT (with line breaks for
display purposes only):
</t>
<artwork><![CDATA[eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
.
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ
.
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk]]></artwork>
<t>
This computation is illustrated in more detail in <xref
target="HMACSHA256Example"></xref>.
</t>
</section>
</section>
<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
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.
</t>
<t>
There are three classes of JWT Claim Names: Reserved Claim
Names, Public Claim Names, and Private Claim Names.
</t>
<section title="Reserved Claim Names" anchor="ReservedClaimName">
<t>
The following claim names are reserved. None of the claims
defined in the table below are intended to be mandatory, but
rather, provide a starting point for a set of useful,
interoperable claims. All the names are short because a
core goal of JWTs is for the tokens to be compact.
</t>
<texttable title="Reserved Claim Definitions" anchor="ClaimTable">
<ttcol align="left">Claim Name</ttcol>
<ttcol align="left">JSON Value Type</ttcol>
<ttcol align="left">Claim Syntax</ttcol>
<ttcol align="left">Claim Semantics</ttcol>
<c>exp</c>
<c>integer</c>
<c>IntDate</c>
<c>
The <spanx style="verb">exp</spanx> (expiration time) claim identifies the
expiration time on or after which the token MUST NOT be
accepted for processing. The processing of the <spanx style="verb">exp</spanx>
claim requires that the current date/time MUST be before
the expiration date/time listed in the <spanx style="verb">exp</spanx>
claim. Implementers MAY provide for some small leeway,
usually no more than a few minutes, to account for clock
skew. This claim is OPTIONAL.
</c>
<c>iat</c>
<c>integer</c>
<c>IntDate</c>
<c>
The <spanx style="verb">iat</spanx> (issued at) claim
identifies the UTC time at which the JWT was issued. The
processing of the <spanx style="verb">iat</spanx> claim
requires that the current date/time MUST be after the
issued date/time listed in the <spanx
style="verb">iat</spanx> claim. Implementers MAY provide
for some small leeway, usually no more than a few minutes,
to account for clock skew. This claim is OPTIONAL.
</c>
<c>iss</c>
<c>string</c>
<c>StringAndURI</c>
<c>
The <spanx style="verb">iss</spanx> (issuer) claim
identifies the principal that issued the JWT. The
processing of this claim is generally application
specific.
The <spanx style="verb">iss</spanx> value is case sensitive.
This claim is OPTIONAL.
</c>
<c>aud</c>
<c>string</c>
<c>StringAndURI</c>
<c>
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
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
application specific.
The <spanx style="verb">aud</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.
The <spanx style="verb">typ</spanx> value is case sensitive.
This claim is OPTIONAL.
</c>
</texttable>
<t>
Additional reserved claim names MAY be defined via the IANA
JSON Web Token Claims registry, as per <xref target="IANA"
/>. The syntax values used above are defined as follows:
</t>
<texttable title="Claim Syntax Definitions" anchor="SyntaxDefinitions">
<ttcol align="left">Syntax Name</ttcol>
<ttcol align="left">Syntax Definition</ttcol>
<c>IntDate</c>
<c>
The number of seconds from 1970-01-01T0:0:0Z as measured
in UTC until the desired date/time. See <xref
target="RFC3339">RFC 3339</xref> for details regarding
date/times in general and UTC in particular.
</c>
<c>String</c>
<c>
Any string value MAY be used.
</c>
<c>StringAndURI</c>
<c>
Any string value MAY be used but a value containing a ":"
character MUST be a URI as defined in <xref
target="RFC3986">RFC 3986</xref>.
</c>
</texttable>
</section>
<section title="Public Claim Names" anchor="PublicClaimName">
<t>
Claim names can be defined at will by those using
JWTs. However, in order to prevent collisions, any new claim
name SHOULD either be defined in the IANA JSON Web Token
Claims registry or be defined as a URI that contains a
collision resistant namespace. Examples of collision
resistant namespaces include:
<list style="symbols">
<t>
Domain Names,
</t>
<t>
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
target="RFC4122">RFC 4122</xref>.
</t>
</list>
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.</t>
</section>
<section title="Private Claim Names" anchor="PrivateClaimName">
<t>
A producer and consumer of a JWT may agree to any claim
name that is not a Reserved Name <xref
target="ReservedClaimName"></xref> or a Public Name <xref
target="PublicClaimName"></xref>. Unlike Public Names,
these private names are subject to collision and should be
used with caution.
</t>
</section>
</section>
<section title="JWT Header">
<t>
The members of the JSON object represented by the Decoded JWT
Header Segment describe the cryptographic operations applied
to the JWT Header Segment and the JWT Claim Segment and
optionally, additional properties of the JWT. The JWT Header
Segment is used as the JWS Header Input for signing. The
format of the header and the cryptographic operations applied
MUST be as specified in JSON Web Signature (JWS) <xref
target="JWS" /> and JSON Web Encryption (JWE) <xref
target="JWE" />.
</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" />.
This specification further specifies the use of the following
header parameters when the JWS Header Input is a JWT Header
Segment.
</t>
<texttable title="Reserved Header Parameter Usage" anchor="HeaderParameterTable">
<ttcol align="left">Header Parameter Name</ttcol>
<ttcol align="left">JSON Value Type</ttcol>
<ttcol align="left">Header Parameter Syntax</ttcol>
<ttcol align="left">Header Parameter Semantics</ttcol>
<c>typ</c>
<c>string</c>
<c>String</c>
<c>
The <spanx style="verb">typ</spanx> (type) header parameter
MAY be used to declare that this data structure is a JWT.
If a <spanx style="verb">typ</spanx> parameter is present,
it is RECOMMENDED that its value be either "JWT" or
"http://openid.net/specs/jwt/1.0". Use of this header
parameter is OPTIONAL.
</c>
</texttable>
</section>
<section title="Rules for Creating and Validating a JWT">
<t>
To create a JWT, one MUST follow these steps:
<list style="numbers">
<t>
Create a JSON object containing the desired claims. Note
that white space is explicitly allowed in the
representation and no canonicalization is performed before
encoding.
</t>
<t>
Translate this JSON object's Unicode code points into
UTF-8, as defined in <xref target="RFC3629">RFC
3629</xref>. This is the Decoded JWT Claim Segment.
</t>
<t>
Base64url encode the Decoded JWT Claim Segment. This
encoding becomes the JWT Claim Segment.
</t>
<t>
Create a JSON object containing a set of desired header
parameters that conform to the <xref target="JWS" /> and
<xref target="JWE" /> specifications. Note that white
space is explicitly allowed in the representation and no
canonicalization is performed before encoding.
</t>
<t>
Translate this JSON object's Unicode code points into
UTF-8, as defined in <xref target="RFC3629">RFC
3629</xref>. This is the Decoded JWT Header Segment.
</t>
<t>
Base64url encode the UTF-8 representation of this JSON
object as defined in this specification (without
padding). This encoding becomes a JWT Header Segment.
</t>
<t>
Unless the <spanx style="verb">alg</spanx> value is <spanx
style="verb">none</spanx>, sign and optionally encrypt
the JWT Header Segment and JWT Claim Segment values in the
manner described in the <xref target="JWS" /> and <xref
target="JWE" /> specifications; the JWT Header Segment is
used as the JWS Header Input and the JWT Claim Segment is
used as the JWS Payload Input; the resulting JWS Crypto
Output is used as the JWT Claim Segment. Otherwise, if
the <spanx style="verb">alg</spanx> value is <spanx
style="verb">none</spanx>, the JWT Crypto Segment is the
empty string.
</t>
<t>
Concatenate the JWT Header Segment, the JWT Claim
Segment, and the JWT Crypto Segment in that order,
separating each by period characters, to create the JWT.
</t>
</list>
</t>
<t>
When validating a JWT the following steps MUST be taken. If
any of the listed steps fails then the token MUST be rejected
for processing.
</t>
<t>
<list style="numbers">
<t>
The JWT MUST contain two period characters.
</t>
<t>
The JWT MUST be split on the two period characters
resulting in three segment strings. The first segment
is the JWT Header Segment; the second is the JWT Claim
Segment; the third is the JWT Crypto Segment.
</t>
<t>
The JWT Claim Segment MUST be successfully base64url
decoded following the restriction given in this specification that
no padding characters have been used.
</t>
<t>
The Decoded JWT Claim Segment MUST be completely valid
JSON syntax conforming to <xref target="RFC4627">RFC
4627</xref>.
</t>
<t>
When used in a security-related context, the Decoded JWT
Claim Segment MUST be validated to only include claims
whose syntax and semantics are both understood and
supported.
</t>
<t>
The JWT Header Segment MUST be successfully base64url
decoded following the restriction given in this specification that
no padding characters have been used.
</t>
<t>
The Decoded JWT Header Segment MUST be completely valid
JSON syntax conforming to <xref target="RFC4627">RFC
4627</xref>.
</t>
<t>
The JWT Crypto Segment MUST be successfully base64url
decoded following the restriction given in this specification that
no padding characters have been used.
</t>
<t>
The JWT Header Segment MUST be validated to only include
parameters and values whose syntax and semantics are both
understood and supported.
</t>
<t>
Unless the <spanx style="verb">alg</spanx> value is <spanx
style="verb">none</spanx>, the JWT Crypto Segment MUST
be successfully validated against the JWT Header Segment
and JWT Claim Segment in the manner defined by the <xref
target="JWS" /> and <xref target="JWE" /> specifications;
otherwise the JWT Crypto Segment MUST be the empty string.
</t>
</list>
</t>
<t>
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 Decoded JWT Header
Segment 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>.
</t>
<t>
Comparisons between JSON strings and other Unicode strings
MUST be performed as specified below:
</t>
<t>
<list style="numbers">
<t>
Remove any JSON applied escaping to produce an array of
Unicode code points.
</t>
<t>
<xref target="USA15">Unicode Normalization</xref> MUST NOT
be applied at any point to either the JSON string or to
the string it is to be compared against.
</t>
<t>
Comparisons between the two strings MUST be performed as a
Unicode code point to code point equality comparison.
</t>
</list>
</t>
</section>
<section title="Base64url encoding as used by JWTs" anchor="base64urllogic">
<t>
JWTs make use of the base64url encoding as defined in <xref
target="RFC4648">RFC 4648</xref>. As allowed by Section 3.2 of
the RFC, this specification mandates that base64url encoding
when used with JWTs MUST NOT use padding. The reason for this
restriction is that the padding character ('=') is not URL
safe.
</t>
<t>
For notes on implementing base64url encoding without padding,
see <xref target="base64urlnotes"></xref>.
</t>
</section>
<section title="Signing JWTs with Cryptographic Algorithms" anchor="Signing">
<t>
JWTs use JSON Web Signatures (JWSs) <xref target="JWS" /> and
JSON Web Encryption (JWE) <xref target="JWE" /> to sign and
optionally encrypt the contents of the JWT Header Segment and
the JWT Claim Segment to produce the JWT Crypto Segment Value.
</t>
<t>
Of the JWS signing algorithms, only HMAC SHA-256 MUST be
implemented by conforming JWT implementations. It is
RECOMMENDED that implementations also support the RSA SHA-256
and ECDSA P-256 SHA-256 algorithms. Support for other
algorithms is OPTIONAL.
</t>
</section>
<section title="Unsigned JWTs" anchor="Unsigned">
<t>
To support use cases where the JWT content is secured by a
means other than a signature contained within the token (such
as signature on a data structure containing the token), JWTs
MAY also be created without a signature. Unsigned JWTs MUST
use the <spanx style="verb">alg</spanx> value <spanx
style="verb">none</spanx> and use the empty string as the
JWT Crypto Segment value.
</t>
</section>
<section title="IANA Considerations" anchor="IANA">
<t>
This specification calls for:
<list style="symbols">
<t>
A new IANA registry entitled "JSON Web Token Claims" for
reserved claim names is defined in <xref
target="ReservedClaimName"></xref>. Inclusion in the
registry is RFC Required in the <xref target="RFC5226">RFC
5226</xref> sense for reserved JWT claim names that are
intended to be interoperable between implementations. The
registry will just record the reserved claim name and a
pointer to the RFC that defines it. This specification
defines inclusion of the claim names defined in <xref
target="ClaimTable"></xref>.
</t>
</list>
</t>
</section>
<section title="Security Considerations" anchor="Security">
<t>
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 are
unescaped. Need to also put in text about: Importance of
keeping secrets secret. Rotating keys. Strengths and
weaknesses of the different algorithms.
</t>
<t>
TBD: Need to put in text about why strict JSON validation is
necessary. Basically, that if malformed JSON is received then
the intent of the sender is impossible to reliably
discern. While in non-security contexts it's o.k. to be
generous in what one accepts, in security contexts this can
lead to serious security holes. For example, malformed JSON
might indicate that someone has managed to find a security
hole in the issuer's code and is leveraging it to get the
issuer to issue "bad" tokens whose content the attacker can
control.
</t>
<t>
TBD: Write about need to secure token content if a signature
is not contained in the JWT itself.
</t>
<section title="Unicode Comparison Security Issues">
<t>
Claim names in JWTs are Unicode strings. For security
reasons, the representations of these names must be compared
verbatim after performing any escape processing (as per
<xref target="RFC4627">RFC 4627</xref>, Section 2.5).
</t>
<t>
This means, for instance, that these JSON strings must
compare as being equal ("JWT", "\u004aWT"), whereas these
must all compare as being not equal to the first set or to
each other ("jwt", "Jwt", "JW\u0074").
</t>
<t>
JSON strings MAY contain characters outside the Unicode
Basic Multilingual Plane. For instance, the G clef
character (U+1D11E) may be represented in a JSON string as
"\uD834\uDD1E". Ideally, JWT implementations SHOULD ensure
that characters outside the Basic Multilingual Plane are
preserved and compared correctly; alternatively, if this is
not possible due to these characters exercising limitations
present in the underlying JSON implementation, then input
containing them MUST be rejected.
</t>
</section>
</section>
<section title="Open Issues and Things To Be Done (TBD)" anchor="TBD">
<t>
The following items remain to be done in this draft (and related drafts):
</t>
<list style="symbols">
<t>
Consider whether we really want to allow private claim names
and that are not registered with IANA and are not in
collision-resistant namespaces. Eventually this could
result in interop nightmares where you need to have
different code to talk to different endpoints that "knows"
about each endpoints' private parameters.
</t>
<t>
Clarify the optional ability to provide type information
for JWTs and/or their segments. Specifically, clarify the
intended use of the <spanx style="verb">typ</spanx> Header Parameter and the <spanx style="verb">typ</spanx>
claim, whether they convey 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.
</t>
<t>
Finish the Security Considerations section.
</t>
<t>
Sort out what to do with the IANA registries if this is
first standardized as an OpenID specification.
</t>
<t>
Write a companion specification that contains the former
JWT JSON Serialization.
</t>
</list>
</section>
</middle>
<back>
<references title="Normative References">
&RFC2045;
&rfc2119;
&RFC3339;
&RFC3629;
&RFC3986;
&RFC4627;
&RFC4648;
&RFC5226;
<reference anchor="USA15">
<front>
<title>Unicode Normalization Forms</title>
<author fullname="Mark Davis" initials="M." surname="Davis">
<address>
<email>markdavis@google.com</email>
</address>
</author>
<author fullname="Ken Whistler" initials="K." surname="Whistler">
<address>
<email>ken@unicode.org</email>
</address>
</author>
<author fullname="Martin Dürst" initials="M."
surname="Dürst"></author>
<date day="03" month="09" year="2009" />
</front>
<seriesInfo name="Unicode Standard Annex" value="15" />
</reference>
<reference anchor="JWS">
<front>
<title>JSON Web Signature (JWS)</title>
<author fullname="Michael B. Jones" initials="M.B." surname="Jones">
<organization>Microsoft</organization>
<address>
<email>mbj@microsoft.com</email>
<uri>http://self-issued.info/</uri>
</address>
</author>
<author fullname="Dirk Balfanz" initials="D." surname="Balfanz">
<organization>Google</organization>
<address>
<email>balfanz@google.com</email>
</address>
</author>
<author fullname="John Bradley" initials="J." surname="Bradley">
<organization>independent</organization>
<address>
<email>ve7jtb@ve7jtb.com</email>
</address>
</author>
<author fullname="Yaron Y. Goland" initials="Y.Y." surname="Goland">
<organization>Microsoft</organization>
<address>
<email>yarong@microsoft.com</email>
</address>
</author>
<author fullname="John Panzer" initials="J." surname="Panzer">
<organization>Google</organization>
<address>
<email>jpanzer@google.com</email>
</address>
</author>
<author fullname="Nat Sakimura" initials="N." surname="Sakimura">
<organization>Nomura Research Institute</organization>
<address>
<email>n-sakimura@nri.co.jp</email>
</address>
</author>
<author fullname="Paul Tarjan" initials="P." surname="Tarjan">
<organization>Facebook</organization>
<address>
<email>pt@fb.com</email>
</address>
</author>
<date day="28" month="March" year="2011" />
</front>
<format target="http://self-issued.info/docs/draft-jones-json-web-signature.html" type="HTML" />
</reference>
</references>
<references title="Informative References">
&OASIS.saml-core-2.0-os;
&W3C.CR-xml11-20021015;
&RFC3275;
&RFC4122;
<reference anchor="SWT">
<front>
<title>Simple Web Token (SWT)</title>
<author fullname="Dick Hardt" initials="D." surname="Hardt"></author>
<author fullname="Yaron Y. Goland" initials="Y.Y." surname="Goland"></author>
<date month="November" year="2009" />
</front>
<format target="http://oauth-wrap-wg.googlegroups.com/web/SWT-v0.9.5.1.pdf?gda=Sn4MsEMAAABFB7PFAFiVedPtjcqT8uuIImHXUksNUKMXLyrSumAs_dF2tzlQ33RhT1wW8BFYO1QytiJ-HdGYYcPi_09pl8N7FWLveOaWjzbYnpnkpmxcWg" type="PDF" />
<seriesInfo name="Version" value="0.9.5.1" />
</reference>
<reference anchor="MagicSignatures">
<front>
<title>Magic Signatures</title>
<author fullname="John Panzer (editor)" initials="J." surname="Panzer (editor)"></author>
<author fullname="Ben Laurie" initials="B." surname="Laurie"></author>
<author fullname="Dirk Balfanz" initials="D." surname="Balfanz"></author>
<date month="August" year="2010" />
</front>
<format target="http://salmon-protocol.googlecode.com/svn/trunk/draft-panzer-magicsig-experimental-00.html" type="HTML" />
</reference>
<reference anchor="JSS">
<front>
<title>JSON Simple Sign</title>
<author fullname="John Bradley" initials="J." surname="Bradley">
<organization>independent</organization>
</author>
<author fullname="Nat Sakimura (editor)" initials="N. " surname="Sakimura (editor)">
<organization>Nomura Research Institute</organization>
</author>
<date month="September" year="2010" />
</front>
<format target="http://jsonenc.info/jss/1.0/" type="HTML" />
</reference>
<reference anchor="CanvasApp">
<front>
<title>Canvas Applications</title>
<author fullname="Facebook" surname="Facebook"></author>
<date year="2010" />
</front>
<format target="http://developers.facebook.com/docs/authentication/canvas" type="HTML" />
</reference>
<reference anchor="JWE">
<front>
<title>JSON Web Encryption (JWE)</title>
<author fullname="Michael B. Jones" initials="M.B." surname="Jones">
<organization>Microsoft</organization>
<address>
<email>mbj@microsoft.com</email>
<uri>http://self-issued.info/</uri>
</address>
</author>
<author fullname="John Bradley" initials="J." surname="Bradley">
<organization>independent</organization>
<address>
<email>ve7jtb@ve7jtb.com</email>
</address>
</author>
<author fullname="Nat Sakimura" initials="N." surname="Sakimura">
<organization>Nomura Research Institute</organization>
<address>
<email>n-sakimura@nri.co.jp</email>
</address>
</author>
<date day="28" month="March" year="2011" />
</front>
<format target="http://self-issued.info/docs/draft-jones-json-web-encryption.html" type="HTML" />
</reference>
</references>
<section title="JWT Examples" anchor="JWTExamples">
<t>
This section provides several examples of JWTs. The
cryptographic operations for these examples are detailed in
the JSON Web Signature (JWS) <xref target="JWS" />
specification.
</t>
<section title="JWT using HMAC SHA-256" anchor="HMACSHA256Example">
<t>
The Decoded JWT Claim Segment used in this example is:
</t>
<artwork><![CDATA[{"iss":"joe",
"exp":1300819380,
"http://example.com/is_root":true}]]></artwork>
<t>
Note that white space is explicitly allowed in Decoded JWT
Claim Segments and no canonicalization is performed before
encoding. The following byte array contains the UTF-8
characters for the Decoded JWT Claim Segment:
</t>
<t>
[123, 34, 105, 115, 115, 34, 58, 34, 106, 111, 101, 34, 44, 13, 10, 32, 34, 101, 120, 112, 34, 58, 49, 51, 48, 48, 56, 49, 57, 51, 56, 48, 44, 13, 10, 32, 34, 104, 116, 116, 112, 58, 47, 47, 101, 120, 97, 109, 112, 108, 101, 46, 99, 111, 109, 47, 105, 115, 95, 114, 111, 111, 116, 34, 58, 116, 114, 117, 101, 125]
</t>
<t>
Base64url encoding the above yields the JWT Claim Segment value:
</t>
<artwork><![CDATA[eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ]]></artwork>
<t>
The following example JSON header object declares that the
data structure is a JSON Web Token (JWT) and the JWT Header
Segment and JWT Crypto Segment are signed using the HMAC
SHA-256 algorithm:
</t>
<artwork><![CDATA[{"typ":"JWT",
"alg":"HS256"}]]></artwork>
<t>
The following byte array contains the UTF-8 characters for
the Decoded JWT Header Segment:
</t>
<t>
[123, 34, 116, 121, 112, 34, 58, 34, 74, 87, 84, 34, 44, 13, 10, 32, 34, 97, 108, 103, 34, 58, 34, 72, 83, 50, 53, 54, 34, 125]
</t>
<t>
Base64url encoding this UTF-8 representation yields this
JWT Header Segment value:
</t>
<artwork><![CDATA[eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9]]></artwork>
<t>
This example uses the key represented by the following
byte array:
</t>
<t>
[3, 35, 53, 75, 43, 15, 165, 188, 131, 126, 6, 101, 119, 123, 166, 143, 90, 179, 40, 230, 240, 84, 201, 40, 169, 15, 132, 178, 210, 80, 46, 191, 211, 251, 90, 146, 210, 6, 71, 239, 150, 138, 180, 195, 119, 98, 61, 34, 61, 46, 33, 114, 5, 46, 79, 8, 192, 205, 154, 245, 103, 208, 128, 163]
</t>
<t>
Signing the JWT Header Segment and JWT Claim Segment with
this key in the manner specified by <xref target="JWS" />
yields this JWT Crypto Segment value:
</t>
<artwork><![CDATA[dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk]]></artwork>
<t>
Combining these segments in the order
Header.Claims.Signature with period characters between
the segments yields this complete JWT (with line breaks
for display purposes only):
</t>
<artwork><![CDATA[eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
.
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ
.
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk]]></artwork>
</section>
<section title="JWT using RSA SHA-256" anchor="RSASHA256Example">
<t>
The Decoded JWT Claim Segment used in this example is the
same as in the previous example:
</t>
<artwork><![CDATA[{"iss":"joe",
"exp":1300819380,
"http://example.com/is_root":true}]]></artwork>
<t>
Since the JWT Claim Segment will therefore be the same,
its computation is not repeated here. However, the
Decoded JWT Header Segment is different in two ways:
First, because a different algorithm is being used, the
<spanx style="verb">alg</spanx> value is different. Second, for illustration
purposes only, the optional "typ" parameter is not used.
(This difference is not related to the signature algorithm
employed.) The Decoded JWT Header Segment used is:
</t>
<artwork><![CDATA[{"alg":"RS256"}]]></artwork>
<t>
The following byte array contains the UTF-8 characters for
the Decoded JWT Header Segment:
</t>
<t>
[123, 34, 97, 108, 103, 34, 58, 34, 82, 83, 50, 53, 54, 34, 125]
</t>
<t>
Base64url encoding this UTF-8 representation yields this
JWT Header Segment value:
</t>
<artwork><![CDATA[eyJhbGciOiJSUzI1NiJ9]]></artwork>
<t>
The RSA key consists of a public part (n, e), and a
private exponent d. The values of the RSA key used in
this example, presented as the byte arrays representing
big endian integers are:
</t>
<texttable>
<ttcol align="left">Parameter Name</ttcol>
<ttcol align="left">Value</ttcol>
<c>n</c>
<c>
[161, 248, 22, 10, 226, 227, 201, 180, 101, 206, 141, 45, 101, 98, 99, 54, 43, 146, 125, 190, 41, 225, 240, 36, 119, 252, 22, 37, 204, 144, 161, 54, 227, 139, 217, 52, 151, 197, 182, 234, 99, 221, 119, 17, 230, 124, 116, 41, 249, 86, 176, 251, 138, 143, 8, 154, 220, 75, 105, 137, 60, 193, 51, 63, 83, 237, 208, 25, 184, 119, 132, 37, 47, 236, 145, 79, 228, 133, 119, 105, 89, 75, 234, 66, 128, 211, 44, 15, 85, 191, 98, 148, 79, 19, 3, 150, 188, 110, 155, 223, 110, 189, 210, 189, 163, 103, 142, 236, 160, 198, 104, 247, 1, 179, 141, 191, 251, 56, 200, 52, 44, 226, 254, 109, 39, 250, 222, 74, 90, 72, 116, 151, 157, 212, 185, 207, 154, 222, 196, 199, 91, 5, 133, 44, 44, 15, 94, 248, 165, 193, 117, 3, 146, 249, 68, 232, 237, 100, 193, 16, 198, 182, 71, 96, 154, 164, 120, 58, 235, 156, 108, 154, 215, 85, 49, 48, 80, 99, 139, 131, 102, 92, 111, 111, 122, 130, 163, 150, 112, 42, 31, 100, 27, 130, 211, 235, 242, 57, 34, 25, 73, 31, 182, 134, 135, 44, 87, 22, 245, 10, 248, 53, 141, 154, 139, 157, 23, 195, 64, 114, 143, 127, 135, 216, 154, 24, 216, 252, 171, 103, 173, 132, 89, 12, 46, 207, 117, 147, 57, 54, 60, 7, 3, 77, 111, 96, 111, 158, 33, 224, 84, 86, 202, 229, 233, 161]
</c>
<c>e</c>
<c>
[1, 0, 1]
</c>
<c>d</c>
<c>
[18, 174, 113, 164, 105, 205, 10, 43, 195, 126, 82, 108, 69, 0, 87, 31, 29, 97, 117, 29, 100, 233, 73, 112, 123, 98, 89, 15, 157, 11, 165, 124, 150, 60, 64, 30, 63, 207, 47, 44, 211, 189, 236, 136, 229, 3, 191, 198, 67, 155, 11, 40, 200, 47, 125, 55, 151, 103, 31, 82, 19, 238, 216, 193, 90, 37, 216, 213, 206, 160, 2, 94, 227, 171, 46, 139, 127, 121, 33, 111, 198, 59, 234, 86, 39, 83, 180, 6, 68, 198, 161, 81, 39, 217, 178, 149, 69, 64, 160, 187, 225, 163, 5, 86, 152, 45, 78, 159, 222, 95, 100, 37, 241, 77, 75, 113, 52, 65, 181, 93, 199, 59, 155, 74, 237, 204, 146, 172, 227, 146, 126, 55, 245, 125, 12, 253, 94, 117, 129, 250, 81, 44, 143, 73, 97, 169, 235, 11, 128, 248, 168, 7, 70, 114, 138, 85, 255, 70, 71, 31, 52, 37, 6, 59, 157, 83, 100, 47, 94, 222, 30, 132, 214, 19, 8, 26, 250, 92, 34, 208, 81, 40, 91, 214, 59, 148, 59, 86, 93, 137, 138, 5, 104, 84, 19, 229, 60, 60, 108, 101, 37, 255, 31, 227, 78, 61, 220, 112, 240, 213, 100, 80, 253, 164, 139, 161, 46, 16, 78, 157, 235, 159, 184, 24, 129, 225, 196, 189, 242, 93, 146, 71, 244, 80, 200, 101, 146, 121, 104, 231, 115, 52, 244, 65, 79, 117, 167, 80, 225, 57, 84, 110, 58, 138, 115, 157]
</c>
</texttable>
<t>
Signing the JWT Header Segment and JWT Claim Segment with
this key in the manner specified by <xref target="JWS" />
yields this JWT Crypto Segment value:
</t>
<artwork><![CDATA[cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZmh7AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjbKBYNX4BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHlb1L07Qe7K0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZESc6BfI7noOPqvhJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AXLIhWkWywlVmtVrBp0igcN_IoypGlUPQGe77Rw]]></artwork>
<t>
Combining these segments in the order
Header.Claims.Signature with period characters between
the segments yields this complete JWT (with line breaks
for display purposes only):
</t>
<artwork><![CDATA[eyJhbGciOiJSUzI1NiJ9
.
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ
.
cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZmh7AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjbKBYNX4BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHlb1L07Qe7K0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZESc6BfI7noOPqvhJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AXLIhWkWywlVmtVrBp0igcN_IoypGlUPQGe77Rw]]></artwork>
</section>
<section title="JWT using ECDSA P-256 SHA-256" anchor="ECDSASHA256Example">
<t>
The Decoded JWT Claim Segment used in this example is the
same as in the previous examples:
</t>
<artwork><![CDATA[{"iss":"joe",
"exp":1300819380,
"http://example.com/is_root":true}]]></artwork>
<t>
Since the JWT Claim Segment will therefore be the same,
its computation is not repeated here. However, the
Decoded JWT Header Segment is differs from the previous
example because a different algorithm is being used. The
Decoded JWT Header Segment used is:
</t>
<artwork><![CDATA[{"alg":"ES256"}]]></artwork>
<t>
The following byte array contains the UTF-8 characters for
the Decoded JWT Header Segment:
</t>
<t>
[123, 34, 97, 108, 103, 34, 58, 34, 69, 83, 50, 53, 54, 34, 125]
</t>
<t>
Base64url encoding this UTF-8 representation yields this
JWT Header Segment value:
</t>
<artwork><![CDATA[eyJhbGciOiJFUzI1NiJ9]]></artwork>
<t>
The ECDSA key consists of a public part, the EC point (x,
y), and a private part d. The values of the ECDSA key
used in this example, presented as the byte arrays
representing big endian integers are:
</t>
<texttable>
<ttcol align="left">Parameter Name</ttcol>
<ttcol align="left">Value</ttcol>
<c>x</c>
<c>
[127, 205, 206, 39, 112, 246, 196, 93, 65, 131, 203, 238, 111, 219, 75, 123, 88, 7, 51, 53, 123, 233, 239, 19, 186, 207, 110, 60, 123, 209, 84, 69]
</c>
<c>y</c>
<c>
[199, 241, 68, 205, 27, 189, 155, 126, 135, 44, 223, 237, 185, 238, 185, 244, 179, 105, 93, 110, 169, 11, 36, 173, 138, 70, 35, 40, 133, 136, 229, 173]
</c>
<c>d</c>
<c>
[142, 155, 16, 158, 113, 144, 152, 191, 152, 4, 135, 223, 31, 93, 119, 233, 203, 41, 96, 110, 190, 210, 38, 59, 95, 87, 194, 19, 223, 132, 244, 178]
</c>
</texttable>
<t>
Signing the JWT Header Segment and JWT Claim Segment with
this key in the manner specified by <xref target="JWS" />
yields this JWT Crypto Segment value:
</t>
<artwork><![CDATA[DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8ISlSApmWQxfKTUJqPP3-Kg6NU1Q]]></artwork>
<t>
Combining these segments in the order
Header.Claims.Signature with period characters between
the segments yields this complete JWT (with line breaks
for display purposes only):
</t>
<artwork><![CDATA[eyJhbGciOiJFUzI1NiJ9
.
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ
.
DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8ISlSApmWQxfKTUJqPP3-Kg6NU1Q]]></artwork>
</section>
</section>
<section title="Notes on implementing base64url encoding without padding" anchor="base64urlnotes">
<t>
This appendix describes how to implement base64url encoding
and decoding functions without padding based upon standard
base64 encoding and decoding functions that do use padding.
</t>
<t>
To be concrete, example C# code implementing these functions
is shown below. Similar code could be used in other
languages.
</t>
<artwork><![CDATA[static string base64urlencode(byte [] arg)
{
string s = Convert.ToBase64String(arg); // Standard base64 encoder
s = s.Split('=')[0]; // Remove any trailing '='s
s = s.Replace('+', '-'); // 62nd char of encoding
s = s.Replace('/', '_'); // 63rd char of encoding
return s;
}
static byte [] base64urldecode(string arg)
{
string s = arg;
s = s.Replace('-', '+'); // 62nd char of encoding
s = s.Replace('_', '/'); // 63rd char of encoding
switch (s.Length % 4) // Pad with trailing '='s
{
case 0: break; // No pad chars in this case
case 2: s += "=="; break; // Two pad chars
case 3: s += "="; break; // One pad char
default: throw new System.Exception(
"Illegal base64url string!");
}
return Convert.FromBase64String(s); // Standard base64 decoder
}]]></artwork>
<t>
As per the example code above, the number of '=' padding
characters that needs to be added to the end of a base64url
encoded string without padding to turn it into one with
padding is a deterministic function of the length of the
encoded string. Specifically,
if the length mod 4 is 0, no padding is added;
if the length mod 4 is 2, two '=' padding characters are added;
if the length mod 4 is 3, one '=' padding character is added;
if the length mod 4 is 1, the input is malformed.
</t>
<t>
An example correspondence between unencoded and encoded values
follows. The byte sequence below encodes into the string
below, which when decoded, reproduces the byte sequence.
</t>
<artwork>3 236 255 224 193</artwork>
<artwork>A-z_4ME</artwork>
</section>
<section title="Relationship of JWTs to SAML Tokens">
<t>
<xref target="OASIS.saml-core-2.0-os">SAML 2.0</xref> provides
a standard for creating tokens with much greater expressivity
and more security options than supported by JWTs. However, the
cost of this flexibility and expressiveness is both size and
complexity. In addition, SAML's use of <xref
target="W3C.CR-xml11-20021015">XML</xref> and <xref
target="RFC3275">XML DSIG</xref> only contributes to the size
of SAML tokens.
</t>
<t>
JWTs are intended to provide a simple token format that is
small enough to fit into HTTP headers and query arguments in
URIs. It does this by supporting a much simpler token model
than SAML and using the <xref target="RFC4627">JSON</xref>
object encoding syntax. It also supports securing tokens using
Hash-based Message Authentication Codes (HMACs) and digital
signatures using a smaller (and less flexible) format than XML
DSIG.
</t>
<t>
Therefore, while JWTs can do some of the things SAML tokens
do, JWTs are not intended as a full replacement for SAML
tokens, but rather as a compromise token format to be used
when space is at a premium.
</t>
</section>
<section title="Relationship of JWTs to Simple Web Tokens (SWTs)">
<t>
Both JWTs and Simple Web Tokens <xref target="SWT">SWT</xref>,
at their core, enable sets of claims to be communicated
between applications. For SWTs, both the claim names and
claim values are strings. For JWTs, while claim names are
strings, claim values can be any JSON type. Both token types
offer cryptographic protection of their content: SWTs with
HMAC SHA-256 and JWTs with a choice of algorithms, including
HMAC SHA-256, RSA SHA-256, and ECDSA P-256 SHA-256.
</t>
</section>
<section title="Acknowledgements" anchor="Acknowledgements">
<t>
The authors acknowledge that the design of JWTs was
intentionally influenced by the design and simplicity of <xref
target="SWT">Simple Web Tokens</xref> and ideas for JSON
tokens that Dick Hardt discussed within the OpenID community.
</t>
<t>
Solutions for signing JSON content were previously explored by
<xref target="MagicSignatures">Magic Signatures</xref>, <xref
target="JSS">JSON Simple Sign</xref>, and <xref
target="CanvasApp">Canvas Applications</xref>, all of which
influenced this draft.
</t>
</section>
<section title='Document History'>
<t>
-04
<list style='symbols'>
<t>
Correct typo found by John Bradley: "the JWT Claim Segment
is the empty string" -> "the JWT Crypto Segment is the
empty string".
</t>
</list>
</t>
<t>
-03
<list style="symbols">
<t>
Added "http://openid.net/specs/jwt/1.0" as a token type
identifier URI for JWTs.
</t>
<t>
Added <spanx style="verb">iat</spanx> (issued at) claim.
</t>
<t>
Changed RSA SHA-256 from MUST be supported to RECOMMENDED
that it be supported. Rationale: Several people have
objected to the requirement for implementing RSA SHA-256,
some because they will only be using HMACs and symmetric
keys, and others because they only want to use ECDSA when
using asymmetric keys, either for security or key length
reasons, or both.
</t>
<t>
Defined <spanx style="verb">alg</spanx> value <spanx
style="verb">none</spanx> to represent unsigned JWTs.
</t>
</list>
</t>
<t>
-02
<list style='symbols'>
<t>
Split signature specification out into separate
draft-jones-json-web-signature-00. This split introduced
no semantic changes.
</t>
<t>
The JWT Compact Serialization is now the only token
serialization format specified in this draft. The JWT
JSON Serialization can continue to be defined in a
companion specification.
</t>
</list>
</t>
<t>
-01
<list style='symbols'>
<t>
Draft incorporating consensus decisions reached at IIW.
</t>
</list>
</t>
<t>
-00
<list style='symbols'>
<t>
Public draft published before November 2010 IIW based upon
the JSON token convergence proposal incorporating input
from several implementers of related specifications.
</t>
</list>
</t>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 16:55:07 |