draft-ietf-oauth-json-web-token-05.txt   draft-ietf-oauth-json-web-token-06.txt 
OAuth Working Group M. Jones OAuth Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track J. Bradley Intended status: Standards Track J. Bradley
Expires: May 10, 2013 Ping Identity Expires: June 30, 2013 Ping Identity
N. Sakimura N. Sakimura
NRI NRI
November 6, 2012 December 27, 2012
JSON Web Token (JWT) JSON Web Token (JWT)
draft-ietf-oauth-json-web-token-05 draft-ietf-oauth-json-web-token-06
Abstract Abstract
JSON Web Token (JWT) is a means of representing claims to be JSON Web Token (JWT) is a compact URL-safe means of representing
transferred between two parties. The claims in a JWT are encoded as claims to be transferred between two parties. The claims in a JWT
a JavaScript Object Notation (JSON) object that is digitally signed are encoded as a JavaScript Object Notation (JSON) object that is
or MACed using JSON Web Signature (JWS) and/or encrypted using JSON used as the payload of a JSON Web Signature (JWS) structure or as the
Web Encryption (JWE). plaintext of a JSON Web Encryption (JWE) structure, enabling the
claims to be digitally signed or MACed and/or encrypted.
The suggested pronunciation of JWT is the same as the English word The suggested pronunciation of JWT is the same as the English word
"jot". "jot".
Status of this Memo Status of this Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on May 10, 2013. This Internet-Draft will expire on June 30, 2013.
Copyright Notice Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the Copyright (c) 2012 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. JSON Web Token (JWT) Overview . . . . . . . . . . . . . . . . 6 3. JSON Web Token (JWT) Overview . . . . . . . . . . . . . . . . 6
3.1. Example JWT . . . . . . . . . . . . . . . . . . . . . . . 7 3.1. Example JWT . . . . . . . . . . . . . . . . . . . . . . . 6
4. JWT Claims . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4. JWT Claims . . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.1. Reserved Claim Names . . . . . . . . . . . . . . . . . . . 8 4.1. Reserved Claim Names . . . . . . . . . . . . . . . . . . . 7
4.1.1. "exp" (Expiration Time) Claim . . . . . . . . . . . . 8 4.1.1. "iss" (Issuer) Claim . . . . . . . . . . . . . . . . . 8
4.1.2. "nbf" (Not Before) Claim . . . . . . . . . . . . . . . 9 4.1.2. "sub" (Subject) Claim . . . . . . . . . . . . . . . . 8
4.1.3. "iat" (Issued At) Claim . . . . . . . . . . . . . . . 9 4.1.3. "aud" (Audience) Claim . . . . . . . . . . . . . . . . 8
4.1.4. "iss" (Issuer) Claim . . . . . . . . . . . . . . . . . 9 4.1.4. "exp" (Expiration Time) Claim . . . . . . . . . . . . 8
4.1.5. "aud" (Audience) Claim . . . . . . . . . . . . . . . . 9 4.1.5. "nbf" (Not Before) Claim . . . . . . . . . . . . . . . 8
4.1.6. "prn" (Principal) Claim . . . . . . . . . . . . . . . 9 4.1.6. "iat" (Issued At) Claim . . . . . . . . . . . . . . . 9
4.1.7. "jti" (JWT ID) Claim . . . . . . . . . . . . . . . . . 10 4.1.7. "jti" (JWT ID) Claim . . . . . . . . . . . . . . . . . 9
4.1.8. "typ" (Type) Claim . . . . . . . . . . . . . . . . . . 10 4.1.8. "typ" (Type) Claim . . . . . . . . . . . . . . . . . . 9
4.2. Public Claim Names . . . . . . . . . . . . . . . . . . . . 10 4.2. Public Claim Names . . . . . . . . . . . . . . . . . . . . 9
4.3. Private Claim Names . . . . . . . . . . . . . . . . . . . 10 4.3. Private Claim Names . . . . . . . . . . . . . . . . . . . 9
5. JWT Header . . . . . . . . . . . . . . . . . . . . . . . . . . 10 5. JWT Header . . . . . . . . . . . . . . . . . . . . . . . . . . 10
5.1. "typ" (Type) Header Parameter . . . . . . . . . . . . . . 11 5.1. "typ" (Type) Header Parameter . . . . . . . . . . . . . . 10
5.2. "cty" (Content Type) Header Parameter . . . . . . . . . . 11 5.2. "cty" (Content Type) Header Parameter . . . . . . . . . . 10
6. Plaintext JWTs . . . . . . . . . . . . . . . . . . . . . . . . 11 6. Plaintext JWTs . . . . . . . . . . . . . . . . . . . . . . . . 10
6.1. Example Plaintext JWT . . . . . . . . . . . . . . . . . . 11 6.1. Example Plaintext JWT . . . . . . . . . . . . . . . . . . 11
7. Rules for Creating and Validating a JWT . . . . . . . . . . . 12 7. Rules for Creating and Validating a JWT . . . . . . . . . . . 11
7.1. String Comparison Rules . . . . . . . . . . . . . . . . . 13
8. Cryptographic Algorithms . . . . . . . . . . . . . . . . . . . 14 8. Cryptographic Algorithms . . . . . . . . . . . . . . . . . . . 14
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14
9.1. JSON Web Token Claims Registry . . . . . . . . . . . . . . 15 9.1. JSON Web Token Claims Registry . . . . . . . . . . . . . . 14
9.1.1. Registration Template . . . . . . . . . . . . . . . . 16 9.1.1. Registration Template . . . . . . . . . . . . . . . . 15
9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 16 9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 15
9.2. Sub-Namespace Registration of 9.2. Sub-Namespace Registration of
urn:ietf:params:oauth:token-type:jwt . . . . . . . . . . . 17 urn:ietf:params:oauth:token-type:jwt . . . . . . . . . . . 16
9.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 17 9.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 16
9.3. JSON Web Signature and Encryption Type Values 9.3. JSON Web Signature and Encryption Type Values
Registration . . . . . . . . . . . . . . . . . . . . . . . 17 Registration . . . . . . . . . . . . . . . . . . . . . . . 16
9.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 17 9.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 16
9.4. Media Type Registration . . . . . . . . . . . . . . . . . 17 9.4. Media Type Registration . . . . . . . . . . . . . . . . . 16
9.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 17 9.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 16
10. Security Considerations . . . . . . . . . . . . . . . . . . . 18
10. Security Considerations . . . . . . . . . . . . . . . . . . . 17
11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18
11.1. Normative References . . . . . . . . . . . . . . . . . . . 18 11.1. Normative References . . . . . . . . . . . . . . . . . . . 18
11.2. Informative References . . . . . . . . . . . . . . . . . . 19 11.2. Informative References . . . . . . . . . . . . . . . . . . 19
Appendix A. Example Encrypted JWT . . . . . . . . . . . . . . . . 20 Appendix A. Example Encrypted JWT . . . . . . . . . . . . . . . . 19
Appendix B. Relationship of JWTs to SAML Tokens . . . . . . . . . 21 Appendix B. Relationship of JWTs to SAML Assertions . . . . . . . 20
Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs) . . 21 Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs) . . 21
Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 21 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 21
Appendix E. Open Issues . . . . . . . . . . . . . . . . . . . . . 22 Appendix E. Open Issues . . . . . . . . . . . . . . . . . . . . . 22
Appendix F. Document History . . . . . . . . . . . . . . . . . . 22 Appendix F. Document History . . . . . . . . . . . . . . . . . . 22
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 23 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 24
1. Introduction 1. Introduction
JSON Web Token (JWT) is a compact token format intended for space JSON Web Token (JWT) is a compact claims representation format
constrained environments such as HTTP Authorization headers and URI intended for space constrained environments such as HTTP
query parameters. JWTs encode claims to be transmitted as a Authorization headers and URI query parameters. JWTs encode claims
JavaScript Object Notation (JSON) [RFC4627] object that is base64url to be transmitted as a JavaScript Object Notation (JSON) [RFC4627]
encoded and digitally signed or MACed and/or encrypted. Signing and object that is used as the payload of a JSON Web Signature (JWS)
MACing is performed using JSON Web Signature (JWS) [JWS]. Encryption [JWS] structure or as the plaintext of a JSON Web Encryption (JWE)
is performed using JSON Web Encryption (JWE) [JWE]. [JWE] structure, enabling the claims to be digitally signed or MACed
and/or encrypted.
The suggested pronunciation of JWT is the same as the English word The suggested pronunciation of JWT is the same as the English word
"jot". "jot".
1.1. Notational Conventions 1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in Key words for use in document are to be interpreted as described in Key words for use in
RFCs to Indicate Requirement Levels [RFC2119]. RFCs to Indicate Requirement Levels [RFC2119].
2. Terminology 2. Terminology
JSON Web Token (JWT) A string representing a set of claims as a JSON JSON Web Token (JWT) A string representing a set of claims as a JSON
object that is digitally signed or MACed and/or encrypted. The object that is encoded in a JWS or JWE, enabling the claims to be
string consists of multiple parts, the first being the Encoded JWT digitally signed or MACed and/or encrypted.
Header, plus additional parts depending upon the contents of the
header, with the parts being separated by period ('.') characters,
and each part containing base64url encoded content.
Base64url Encoding The URL- and filename-safe Base64 encoding Base64url Encoding The URL- and filename-safe Base64 encoding
described in RFC 4648 [RFC4648], Section 5, with the (non URL- described in RFC 4648 [RFC4648], Section 5, with the (non URL-
safe) '=' padding characters omitted, as permitted by Section 3.2. safe) '=' padding characters omitted, as permitted by Section 3.2.
(See Appendix C of [JWS] for notes on implementing base64url (See Appendix C of [JWS] for notes on implementing base64url
encoding without padding.) encoding without padding.)
JWT Header A string representing a JSON object that describes the JSON Text Object A UTF-8 encoded text string representing a JSON
cryptographic operations applied to the JWT. When the JWT is object; the syntax of JSON objects is defined in Section 2.2 of
digitally signed or MACed, the JWT Header is a JWS Header. When [RFC4627].
the JWT is encrypted, the JWT Header is a JWE Header.
Header Parameter Name The name of a member of the JSON object JWT Header A JSON Text Object that describes the cryptographic
representing a JWT Header. operations applied to the JWT. When the JWT is digitally signed
or MACed, the JWT Header is a JWS Header. When the JWT is
encrypted, the JWT Header is a JWE Header.
Header Parameter Value The value of a member of the JSON object Header Parameter Name The name of a member of the JWT Header.
representing a JWT Header.
JWT Claims Set A string representing a JSON object that contains the Header Parameter Value The value of a member of the JWT Header.
claims conveyed by the JWT. When the JWT is digitally signed or
MACed, 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 Name The name of a member of the JSON object representing a JWT Claims Set A JSON Text Object that contains the Claims conveyed
JWT Claims Set. by the JWT, where each claim is represented as a name/value pair
of a Claim Name and a Claim Value.
Claim Value The value of a member of the JSON object representing a Claim A piece of information asserted about a subject. Here, Claims
JWT Claims Set. are represented name/value pairs, consisting of a Claim Name and a
Claim Value.
Encoded JWT Header Base64url encoding of the bytes of the UTF-8 Claim Name The name portion of a Claim representation. A Claim Name
[RFC3629] representation of the JWT Header. is always a string.
Claim Value The value portion of a Claim representation. A Claim
Value can be any JSON value.
Encoded JWT Header Base64url encoding of the JWT Header.
Nested JWT A JWT in which nested signing or encryption are employed.
In nested JWTs, a JWT is used as the payload or plaintext value of
an enclosing JWS or JWE structure, respectively.
Plaintext JWT A JWT whose Claims are not integrity protected or
encrypted.
Collision Resistant Namespace A namespace that allows names to be Collision Resistant Namespace A namespace that allows names to be
allocated in a manner such that they are highly unlikely to allocated in a manner such that they are highly unlikely to
collide with other names. For instance, collision resistance can collide with other names. For instance, collision resistance can
be achieved through administrative delegation of portions of the be achieved through administrative delegation of portions of the
namespace or through use of collision-resistant name allocation namespace or through use of collision-resistant name allocation
functions. Examples of Collision Resistant Namespaces include: functions. Examples of Collision Resistant Namespaces include:
Domain Names, Object Identifiers (OIDs) as defined in the ITU-T Domain Names, Object Identifiers (OIDs) as defined in the ITU-T
X.660 and X.670 Recommendation series, and Universally Unique X.660 and X.670 Recommendation series, and Universally Unique
IDentifiers (UUIDs) [RFC4122]. When using an administratively IDentifiers (UUIDs) [RFC4122]. When using an administratively
skipping to change at page 6, line 47 skipping to change at page 6, line 7
values are compared as case-sensitive strings with no values are compared as case-sensitive strings with no
transformations or canonicalizations applied. transformations or canonicalizations applied.
IntDate A JSON numeric value representing the number of seconds from IntDate A JSON numeric value representing the number of seconds from
1970-01-01T0:0:0Z UTC until the specified UTC date/time. See RFC 1970-01-01T0:0:0Z UTC until the specified UTC date/time. See RFC
3339 [RFC3339] for details regarding date/times in general and UTC 3339 [RFC3339] for details regarding date/times in general and UTC
in particular. in particular.
3. JSON Web Token (JWT) Overview 3. JSON Web Token (JWT) Overview
JWTs represent a set of claims as a JSON object that is base64url JWTs represent a set of claims as a JSON object that is encoded in a
encoded and digitally signed or MACed and/or encrypted. The JWT JWS and/or JWE structure. This JSON object is the JWT Claims Set. As
Claims Set represents this JSON object. As per RFC 4627 [RFC4627] per RFC 4627 [RFC4627] Section 2.2, the JSON object consists of zero
Section 2.2, the JSON object consists of zero or more name/value or more name/value pairs (or members), where the names are strings
pairs (or members), where the names are strings and the values are and the values are arbitrary JSON values. These members are the
arbitrary JSON values. These members are the claims represented by claims represented by the JWT.
the JWT.
The member names within the JWT Claims Set are referred to as Claim The member names within the JWT Claims Set are referred to as Claim
Names. The corresponding values are referred to as Claim Values. Names. The corresponding values are referred to as Claim Values.
The bytes of the UTF-8 representation of the JWT Claims Set are
digitally signed or MACed 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 The contents of the JWT Header describe the cryptographic operations
applied to the JWT Claims Set. If the JWT Header is a JWS Header, the applied to the JWT Claims Set. If the JWT Header is a JWS Header, the
claims are digitally signed or MACed. If the JWT Header is a JWE JWT is represented as a JWS, and the claims are digitally signed or
Header, the claims are encrypted. MACed, with the JWT Claims Set being the JWS Payload. If the JWT
Header is a JWE Header, the JWT is represented as a JWE, and the
claims are encrypted, with the JWT Claims Set being the input
Plaintext. A JWT may be enclosed in another JWE or JWS structure to
create a Nested JWT, enabling nested signing and encryption to be
performed.
A JWT is represented as a JWS or JWE. The number of parts is A JWT is represented as a sequence of URL-safe parts separated by
dependent upon the representation of the resulting JWS or JWE. period ('.') characters. Each part contains a base64url encoded
value. The number of parts in the JWT is dependent upon the
representation of the resulting JWS or JWE.
3.1. Example JWT 3.1. Example JWT
The following example JWT Header declares that the encoded object is The following example JWT Header declares that the encoded object is
a JSON Web Token (JWT) and the JWT is MACed using the HMAC SHA-256 a JSON Web Token (JWT) and the JWT is MACed using the HMAC SHA-256
algorithm: algorithm:
{"typ":"JWT", {"typ":"JWT",
"alg":"HS256"} "alg":"HS256"}
skipping to change at page 8, line 26 skipping to change at page 7, line 35
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
. .
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
This computation is illustrated in more detail in Appendix A.1 of This computation is illustrated in more detail in Appendix A.1 of
[JWS]. See Appendix A for an example of an encrypted JWT. [JWS]. See Appendix A for an example of an encrypted JWT.
4. JWT Claims 4. JWT Claims
The JWT Claims Set represents a JSON object whose members are the The JWT Claims Set represents a JSON object whose members are the
claims conveyed by the JWT. The Claim Names within this object MUST claims conveyed by the JWT. The Claim Names within a JWT Claims Set
be unique; JWTs with duplicate Claim Names MUST be rejected. Note MUST be unique; JWTs with duplicate Claim Names MUST be rejected.
however, that the set of claims that a JWT must contain to be 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 considered valid is context-dependent and is outside the scope of
this specification. When used in a security-related context, this specification. When used in a security-related context,
implementations MUST understand and support all of the claims implementations MUST understand and support all of the claims
present; otherwise, the JWT MUST be rejected for processing. present; otherwise, the JWT MUST be rejected for processing.
There are three classes of JWT Claim Names: Reserved Claim Names, There are three classes of JWT Claim Names: Reserved Claim Names,
Public Claim Names, and Private Claim Names. Public Claim Names, and Private Claim Names.
4.1. Reserved Claim Names 4.1. Reserved Claim Names
The following claim names are reserved. None of the claims defined The following Claim Names are reserved. None of the claims defined
below are intended to be mandatory, but rather, provide a starting below are intended to be mandatory to use, but rather, provide a
point for a set of useful, interoperable claims. All the names are starting point for a set of useful, interoperable claims. All the
short because a core goal of JWTs is for the tokens to be compact. names are short because a core goal of JWTs is for the representation
Additional reserved claim names MAY be defined via the IANA JSON Web to be compact. Additional reserved Claim Names MAY be defined via
Token Claims registry Section 9.1. the IANA JSON Web Token Claims registry Section 9.1.
4.1.1. "exp" (Expiration Time) Claim 4.1.1. "iss" (Issuer) Claim
The "exp" (expiration time) claim identifies the expiration time on The "iss" (issuer) claim identifies the principal that issued the
or after which the token MUST NOT be accepted for processing. The JWT. The processing of this claim is generally application specific.
processing of the "exp" claim requires that the current date/time The "iss" value is a case sensitive string containing a StringOrURI
MUST be before the expiration date/time listed in the "exp" claim. value. Use of this claim is OPTIONAL.
Implementers MAY provide for some small leeway, usually no more than
a few minutes, to account for clock skew. Its value MUST be a number
containing an IntDate value. This claim is OPTIONAL.
4.1.2. "nbf" (Not Before) Claim 4.1.2. "sub" (Subject) Claim
The "nbf" (not before) claim identifies the time before which the The "sub" (subject) claim identifies the principal that is the
token MUST NOT be accepted for processing. The processing of the subject of the JWT. The Claims in a JWT are normally statements
"nbf" claim requires that the current date/time MUST be after or about the subject. The processing of this claim is generally
equal to the not-before date/time listed in the "nbf" claim. application specific. The "sub" value is a case sensitive string
Implementers MAY provide for some small leeway, usually no more than containing a StringOrURI value. Use of this claim is OPTIONAL.
a few minutes, to account for clock skew. Its value MUST be a number
containing an IntDate value. This claim is OPTIONAL.
4.1.3. "iat" (Issued At) Claim 4.1.3. "aud" (Audience) Claim
The "iat" (issued at) claim identifies the time at which the JWT was The "aud" (audience) claim identifies the audiences that the JWT is
issued. This claim can be used to determine the age of the token. intended for. Each principal intended to process the JWT MUST
Its value MUST be a number containing an IntDate value. This claim identify itself with a value in audience claim. If the principal
is OPTIONAL. processing the claim does not identify itself with a value in the
"aud" claim, then the JWT MUST be rejected. In the general case, the
"aud" value is an array of case sensitive strings, each containing a
StringOrURI value. In the special case when the JWT has one
audience, the "aud" value MAY be a single case sensitive string
containing a StringOrURI value. The interpretation of audience
values is generally application specific. Use of this claim is
OPTIONAL.
4.1.4. "iss" (Issuer) Claim 4.1.4. "exp" (Expiration Time) Claim
The "iss" (issuer) claim identifies the principal that issued the The "exp" (expiration time) claim identifies the expiration time on
JWT. The processing of this claim is generally application specific. or after which the JWT MUST NOT be accepted for processing. The
The "iss" value is a case sensitive string containing a StringOrURI processing of the "exp" claim requires that the current date/time
value. This claim is OPTIONAL. MUST be before the expiration date/time listed in the "exp" claim.
Implementers MAY provide for some small leeway, usually no more than
a few minutes, to account for clock skew. Its value MUST be a number
containing an IntDate value. Use of this claim is OPTIONAL.
4.1.5. "aud" (Audience) Claim 4.1.5. "nbf" (Not Before) Claim
The "aud" (audience) claim identifies the audience that the JWT is The "nbf" (not before) claim identifies the time before which the JWT
intended for. The principal intended to process the JWT MUST be MUST NOT be accepted for processing. The processing of the "nbf"
identified with the value of the audience claim. If the principal claim requires that the current date/time MUST be after or equal to
processing the claim does not identify itself with the identifier in the not-before date/time listed in the "nbf" claim. Implementers MAY
the "aud" claim value then the JWT MUST be rejected. The provide for some small leeway, usually no more than a few minutes, to
interpretation of the audience value is generally application account for clock skew. Its value MUST be a number containing an
specific. The "aud" value is a case sensitive string containing a IntDate value. Use of this claim is OPTIONAL.
StringOrURI value. This claim is OPTIONAL.
4.1.6. "prn" (Principal) Claim 4.1.6. "iat" (Issued At) Claim
The "prn" (principal) claim identifies the subject of the JWT. The The "iat" (issued at) claim identifies the time at which the JWT was
processing of this claim is generally application specific. The issued. This claim can be used to determine the age of the JWT. Its
"prn" value is a case sensitive string containing a StringOrURI value MUST be a number containing an IntDate value. Use of this
value. This claim is OPTIONAL. claim is OPTIONAL.
4.1.7. "jti" (JWT ID) Claim 4.1.7. "jti" (JWT ID) Claim
The "jti" (JWT ID) claim provides a unique identifier for the JWT. The "jti" (JWT ID) claim provides a unique identifier for the JWT.
The identifier value MUST be assigned in a manner that ensures that The identifier value MUST be assigned in a manner that ensures that
there is a negligible probability that the same value will be there is a negligible probability that the same value will be
accidentally assigned to a different data object. The "jti" claim accidentally assigned to a different data object. The "jti" claim
can be used to prevent the JWT from being replayed. The "jti" value can be used to prevent the JWT from being replayed. The "jti" value
is a case sensitive string. This claim is OPTIONAL. is a case sensitive string. Use of this claim is OPTIONAL.
4.1.8. "typ" (Type) Claim 4.1.8. "typ" (Type) Claim
The "typ" (type) claim is used to declare a type for the contents of The "typ" (type) claim is used to declare a type for the contents of
this JWT Claims Set. The "typ" value is a case sensitive string. this JWT Claims Set. The "typ" value is a case sensitive string. Use
This claim is OPTIONAL. of this claim is OPTIONAL.
The values used for the "typ" claim come from the same value space as The values used for the "typ" claim come from the same value space as
the "typ" header parameter, with the same rules applying. the "typ" header parameter, with the same rules applying.
4.2. Public Claim Names 4.2. Public Claim Names
Claim names can be defined at will by those using JWTs. However, in Claim Names can be defined at will by those using JWTs. However, in
order to prevent collisions, any new claim name SHOULD either be order to prevent collisions, any new Claim Name SHOULD either be
registered in the IANA JSON Web Token Claims registry Section 9.1 or registered in the IANA JSON Web Token Claims registry Section 9.1 or
be a URI that contains a Collision Resistant Namespace. be a Public Name: a value that contains a Collision Resistant
Namespace. 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.
4.3. Private Claim Names 4.3. Private Claim Names
A producer and consumer of a JWT may agree to any claim name that is A producer and consumer of a JWT may agree to use Claim Names that
not a Reserved Name Section 4.1 or a Public Name Section 4.2. Unlike are Private Names: names that are not Reserved Names Section 4.1 or
Public Names, these private names are subject to collision and should Public Names Section 4.2. Unlike Public Names, Private Names are
be used with caution. subject to collision and should be used with caution.
5. JWT Header 5. JWT Header
The members of the JSON object represented by the JWT Header describe The members of the JSON object represented by the JWT Header describe
the cryptographic operations applied to the JWT and optionally, the cryptographic operations applied to the JWT and optionally,
additional properties of the JWT. The member names within the JWT additional properties of the JWT. The member names within the JWT
Header are referred to as Header Parameter Names. These names MUST Header are referred to as Header Parameter Names. These names MUST
be unique; JWTs with duplicate Header Parameter Names MUST be be unique; JWTs with duplicate Header Parameter Names MUST be
rejected. The corresponding values are referred to as Header rejected. The corresponding values are referred to as Header
Parameter Values. Parameter Values.
skipping to change at page 11, line 12 skipping to change at page 10, line 28
JWS Header Parameters are defined by [JWS]. JWE Header Parameters JWS Header Parameters are defined by [JWS]. JWE Header Parameters
are defined by [JWE]. This specification further specifies the use are defined by [JWE]. This specification further specifies the use
of the following header parameter in both the cases where the JWT is of the following header parameter in both the cases where the JWT is
a JWS and where it is a JWE. a JWS and where it is a JWE.
5.1. "typ" (Type) Header Parameter 5.1. "typ" (Type) Header Parameter
The "typ" (type) header parameter is used to declare the type of this The "typ" (type) header parameter is used to declare the type of this
object. If present, it is RECOMMENDED that its value be either "JWT" object. If present, it is RECOMMENDED that its value be either "JWT"
or "urn:ietf:params:oauth:token-type:jwt" to indicate that this or "urn:ietf:params:oauth:token-type:jwt" to indicate that this
object is a JWT. The "typ" value is a case sensitive string. This object is a JWT. The "typ" value is a case sensitive string. Use of
header parameter is OPTIONAL. this header parameter is OPTIONAL.
5.2. "cty" (Content Type) Header Parameter 5.2. "cty" (Content Type) Header Parameter
The "cty" (content type) header parameter is used to declare The "cty" (content type) header parameter is used to declare
structural information about the JWT. Its value MUST be a string. structural information about the JWT. Its value MUST be a string.
In the normal case where nested signing or encryption operations are In the normal case where nested signing or encryption operations are
not employed, the use of this header parameter is NOT RECOMMENDED. not employed, the use of this header parameter is NOT RECOMMENDED.
In the case that nested signing or encryption is employed, the use of In the case that nested signing or encryption is employed, the use of
this header parameter is REQUIRED; in this case, the value MUST be this header parameter is REQUIRED; in this case, the value MUST be
"JWT", to indicate that a nested JWT is carried in this JWT. "JWT", to indicate that a Nested JWT is carried in this JWT.
The values used for the "cty" header parameter come from the same The values used for the "cty" header parameter come from the same
value space as the "typ" header parameter, with the same rules value space as the "typ" header parameter, with the same rules
applying. applying.
6. Plaintext JWTs 6. Plaintext JWTs
To support use cases where the JWT content is secured by a means To support use cases where the JWT content is secured by a means
other than a signature and/or encryption contained within the token other than a signature and/or encryption contained within the JWT
(such as a signature on a data structure containing the token), JWTs (such as a signature on a data structure containing the JWT), JWTs
MAY also be created without a signature or encryption. A plaintext MAY also be created without a signature or encryption. A plaintext
JWT is a JWS using the "none" JWS "alg" header parameter value JWT is a JWS using the "none" JWS "alg" header parameter value
defined in JSON Web Algorithms (JWA) [JWA]; it is a JWS with an empty defined in JSON Web Algorithms (JWA) [JWA]; it is a JWS with the
JWS Signature value. empty string for its JWS Signature value.
6.1. Example Plaintext JWT 6.1. Example Plaintext JWT
The following example JWT Header declares that the encoded object is The following example JWT Header declares that the encoded object is
a Plaintext JWT: a Plaintext JWT:
{"alg":"none"} {"alg":"none"}
Base64url encoding the bytes of the UTF-8 representation of the JWT Base64url encoding the bytes of the UTF-8 representation of the JWT
Header yields this Encoded JWT Header: Header yields this Encoded JWT Header:
skipping to change at page 13, line 26 skipping to change at page 12, line 42
6. If a nested signing or encryption operation will be performed, 6. If a nested signing or encryption operation will be performed,
let the Message be the JWS or JWE, and return to Step 3, using a let the Message be the JWS or JWE, and return to Step 3, using a
"cty" (content type) value of "JWT" in the new JWT Header created "cty" (content type) value of "JWT" in the new JWT Header created
in that step. in that step.
7. Otherwise, let the resulting JWT be the JWS or JWE. 7. Otherwise, let the resulting JWT be the JWS or JWE.
When validating a JWT the following steps MUST be taken. The order When validating a JWT the following steps MUST be taken. The order
of the steps is not significant in cases where there are no of the steps is not significant in cases where there are no
dependencies between the inputs and outputs of the steps. If any of dependencies between the inputs and outputs of the steps. If any of
the listed steps fails then the token MUST be rejected for the listed steps fails then the JWT MUST be rejected for processing.
processing.
1. The JWT MUST contain at least one period ('.') character. 1. The JWT MUST contain at least one period ('.') character.
2. Let the Encoded JWT Header be the portion of the JWT before the 2. Let the Encoded JWT Header be the portion of the JWT before the
first period ('.') character. first period ('.') character.
3. The Encoded JWT Header MUST be successfully base64url decoded 3. The Encoded JWT Header MUST be successfully base64url decoded
following the restriction given in this specification that no following the restriction given in this specification that no
padding characters have been used. padding characters have been used.
skipping to change at page 14, line 27 skipping to change at page 13, line 41
9. Otherwise, let the JWT Claims Set be the Message. 9. Otherwise, let the JWT Claims Set be the Message.
10. The JWT Claims Set MUST be completely valid JSON syntax 10. The JWT Claims Set MUST be completely valid JSON syntax
conforming to RFC 4627 [RFC4627]. conforming to RFC 4627 [RFC4627].
11. When used in a security-related context, the JWT Claims Set MUST 11. When used in a security-related context, the JWT Claims Set MUST
be validated to only include claims whose syntax and semantics be validated to only include claims whose syntax and semantics
are both understood and supported. are both understood and supported.
7.1. String Comparison Rules
Processing a JWT inevitably requires comparing known strings to Processing a JWT inevitably requires comparing known strings to
values in the token. For example, in checking what the algorithm is, values in JSON objects. For example, in checking what the algorithm
the Unicode string encoding "alg" will be checked against the member is, the Unicode string encoding "alg" will be checked against the
names in the JWT Header to see if there is a matching header member names in the JWT Header to see if there is a matching Header
parameter name. A similar process occurs when determining if the Parameter Name.
value of the "alg" header parameter represents a supported algorithm.
Comparisons between JSON strings and other Unicode strings MUST be Comparisons between JSON strings and other Unicode strings MUST be
performed as specified below: performed by comparing Unicode code points without normalization as
specified in the String Comparison Rules in Section 5.3 of [JWS].
1. Remove any JSON applied escaping to produce an array of Unicode
code points.
2. Unicode Normalization [USA15] MUST NOT be applied at any point to
either the JSON string or to the string it is to be compared
against.
3. Comparisons between the two strings MUST be performed as a
Unicode code point to code point equality comparison.
8. Cryptographic Algorithms 8. Cryptographic Algorithms
JWTs use JSON Web Signature (JWS) [JWS] and JSON Web Encryption (JWE) JWTs use JSON Web Signature (JWS) [JWS] and JSON Web Encryption (JWE)
[JWE] to sign and/or encrypt the contents of the JWT. [JWE] to sign and/or encrypt the contents of the JWT.
Of the JWS signing algorithms, only HMAC SHA-256 and "none" MUST be Of the JWS signing algorithms, only HMAC SHA-256 and "none" MUST be
implemented by conforming JWT implementations. It is RECOMMENDED implemented by conforming JWT implementations. It is RECOMMENDED
that implementations also support the RSA SHA-256 and ECDSA P-256 that implementations also support the RSA SHA-256 and ECDSA P-256
SHA-256 algorithms. Support for other algorithms and key sizes is SHA-256 algorithms. Support for other algorithms and key sizes is
skipping to change at page 16, line 25 skipping to change at page 15, line 29
email address, home page URI) may also be included. email address, home page URI) may also be included.
Specification Document(s): Specification Document(s):
Reference to the document(s) that specify the parameter, Reference to the document(s) that specify the parameter,
preferably including URI(s) that can be used to retrieve copies of preferably including URI(s) that can be used to retrieve copies of
the document(s). An indication of the relevant sections may also the document(s). An indication of the relevant sections may also
be included but is not required. be included but is not required.
9.1.2. Initial Registry Contents 9.1.2. Initial Registry Contents
o Claim Name: "exp" o Claim Name: "iss"
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.1 of [[ this document ]] o Specification Document(s): Section 4.1.1 of [[ this document ]]
o Claim Name: "nbf" o Claim Name: "sub"
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.2 of [[ this document ]] o Specification Document(s): Section 4.1.2 of [[ this document ]]
o Claim Name: "iat" o Claim Name: "aud"
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.3 of [[ this document ]] o Specification Document(s): Section 4.1.3 of [[ this document ]]
o Claim Name: "iss" o Claim Name: "exp"
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.4 of [[ this document ]] o Specification Document(s): Section 4.1.4 of [[ this document ]]
o Claim Name: "aud" o Claim Name: "nbf"
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.5 of [[ this document ]] o Specification Document(s): Section 4.1.5 of [[ this document ]]
o Claim Name: "prn" o Claim Name: "iat"
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.6 of [[ this document ]] o Specification Document(s): Section 4.1.6 of [[ this document ]]
o Claim Name: "jti" o Claim Name: "jti"
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.7 of [[ this document ]] o Specification Document(s): Section 4.1.7 of [[ this document ]]
o Claim Name: "typ" o Claim Name: "typ"
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.8 of [[ this document ]] o Specification Document(s): Section 4.1.8 of [[ this document ]]
skipping to change at page 18, line 24 skipping to change at page 17, line 27
B. Jones, mbj@microsoft.com B. Jones, mbj@microsoft.com
o Intended Usage: COMMON o Intended Usage: COMMON
o Restrictions on Usage: none o Restrictions on Usage: none
o Author: Michael B. Jones, mbj@microsoft.com o Author: Michael B. Jones, mbj@microsoft.com
o Change Controller: IETF o Change Controller: IETF
10. Security Considerations 10. Security Considerations
All of the security issues faced by any cryptographic application All of the security issues faced by any cryptographic application
must be faced by a JWT/JWS/JWE/JWK agent. Among these issues are must be faced by a JWT/JWS/JWE/JWK agent. Among these issues are
protecting the user's private key, preventing various attacks, and protecting the user's private and symmetric keys, preventing various
helping the user avoid mistakes such as inadvertently encrypting a attacks, and helping the user avoid mistakes such as inadvertently
message for the wrong recipient. The entire list of security encrypting a message for the wrong recipient. The entire list of
considerations is beyond the scope of this document, but some security considerations is beyond the scope of this document.
significant concerns are listed here.
All the security considerations in the JWS specification also apply All the security considerations in the JWS specification also apply
to JWT, as do the JWE security considerations when encryption is to JWT, as do the JWE security considerations when encryption is
employed. In particular, the JWS JSON Security Considerations and employed. In particular, the JWS JSON Security Considerations and
Unicode Comparison Security Considerations apply equally to the JWT Unicode Comparison Security Considerations apply equally to the JWT
Claims Set in the same manner that they do to the JWS Header. Claims Set in the same manner that they do to the JWS Header.
11. References While syntactically, the signing and encryption operations for Nested
JWTs may be applied in any order, normally senders should sign the
message and then encrypt the result (thus encrypting the signature).
This prevents attacks in which the signature is stripped, leaving
just an encrypted message, as well as providing privacy for the
signer. Furthermore, signatures over encrypted text are not
considered valid in many jurisdictions.
11. References
11.1. Normative References 11.1. Normative References
[JWA] Jones, M., "JSON Web Algorithms (JWA)", November 2012. [JWA] Jones, M., "JSON Web Algorithms (JWA)",
draft-ietf-jose-json-web-algorithms (work in progress),
December 2012.
[JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web
Encryption (JWE)", November 2012. Encryption (JWE)", draft-ietf-jose-json-web-encryption
(work in progress), December 2012.
[JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", November 2012. Signature (JWS)", draft-ietf-jose-json-web-signature (work
in progress), December 2012.
[RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part Two: Media Types", RFC 2046, Extensions (MIME) Part Two: Media Types", RFC 2046,
November 1996. November 1996.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the
Internet: Timestamps", RFC 3339, July 2002. Internet: Timestamps", RFC 3339, July 2002.
skipping to change at page 20, line 21 skipping to change at page 19, line 39
Unique IDentifier (UUID) URN Namespace", RFC 4122, Unique IDentifier (UUID) URN Namespace", RFC 4122,
July 2005. July 2005.
[SWT] Hardt, D. and Y. Goland, "Simple Web Token (SWT)", [SWT] Hardt, D. and Y. Goland, "Simple Web Token (SWT)",
Version 0.9.5.1, November 2009. Version 0.9.5.1, November 2009.
[W3C.CR-xml11-20021015] [W3C.CR-xml11-20021015]
Cowan, J., "Extensible Markup Language (XML) 1.1", W3C Cowan, J., "Extensible Markup Language (XML) 1.1", W3C
CR CR-xml11-20021015, October 2002. CR CR-xml11-20021015, October 2002.
[W3C.REC-xml-c14n-20010315]
Boyer, J., "Canonical XML Version 1.0", World Wide Web
Consortium Recommendation REC-xml-c14n-20010315,
March 2001,
<http://www.w3.org/TR/2001/REC-xml-c14n-20010315>.
Appendix A. Example Encrypted JWT Appendix A. Example Encrypted JWT
This example encrypts the same claims as used in Section 3.1 to the This example encrypts the same claims as used in Section 3.1 to the
recipient using RSAES-PKCS1-V1_5 and AES CBC. AES CBC does not have recipient using RSAES-PKCS1-V1_5 and AES CBC. AES CBC does not have
an integrated integrity check, so a separate integrity check an integrated integrity check, so a separate integrity check
calculation is performed using HMAC SHA-256, with separate encryption calculation is performed using HMAC SHA-256, with separate encryption
and integrity keys being derived from a master key using the Concat and integrity keys being derived from a master key using the Concat
KDF with the SHA-256 digest function. KDF with the SHA-256 digest function.
The following example JWE Header (with line breaks for display The following example JWE Header (with line breaks for display
purposes only) declares that: purposes only) declares that:
o the Content Master Key is encrypted to the recipient using the o the Content Master Key is encrypted to the recipient using the
RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and
o the Plaintext is encrypted using the AES CBC algorithm with a 128 o the Plaintext is encrypted using the AES CBC algorithm with a 128
bit key to produce the Ciphertext, with the integrity of the bit key to produce the Ciphertext, with the integrity of the
Ciphertext and the parameters used to create it being secured Ciphertext and the parameters used to create it being secured
using the HMAC SHA-256 algorithm. using the HMAC SHA-256 algorithm.
{"alg":"RSA1_5","enc":"A128CBC+HS256"} {"alg":"RSA1_5","enc":"A128CBC+HS256"}
Other than using the bytes of the UTF-8 representation of the JSON Other than using the bytes of the UTF-8 representation of the JSON
Claims Set from Section 3.1 as the plaintext value, the computation Claims Set from Section 3.1 as the plaintext value, the computation
of this JWT is identical to the computation of the JWE in Appendix of this JWT is identical to the computation of the JWE in Appendix
A.2 of [JWE], including the keys used. A.2 of [JWE], including the keys used.
The final result in this example (with line breaks for display The final result in this example (with line breaks for display
purposes only) is: purposes only) is:
eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDK0hTMjU2In0. eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDK0hTMjU2In0.
pwaFh7yJPivLjjPkzC-GeAyHuy7AinGcS51AZ7TXnwkC80Ow1aW47kcT_UV54ubo pwaFh7yJPivLjjPkzC-GeAyHuy7AinGcS51AZ7TXnwkC80Ow1aW47kcT_UV54ubo
nONbeArwOVuR7shveXnwPmucwrk_3OCcHrCbE1HR-Jfme2mF_WR3zUMcwqmU0RlH nONbeArwOVuR7shveXnwPmucwrk_3OCcHrCbE1HR-Jfme2mF_WR3zUMcwqmU0RlH
kwx9txo_sKRasjlXc8RYP-evLCmT1XRXKjtY5l44Gnh0A84hGvVfMxMfCWXh38hi kwx9txo_sKRasjlXc8RYP-evLCmT1XRXKjtY5l44Gnh0A84hGvVfMxMfCWXh38hi
2h8JMjQHGQ3mivVui5lbf-zzb3qXXxNO1ZYoWgs5tP1-T54QYc9Bi9wodFPWNPKB 2h8JMjQHGQ3mivVui5lbf-zzb3qXXxNO1ZYoWgs5tP1-T54QYc9Bi9wodFPWNPKB
kY-BgewG-Vmc59JqFeprk1O08qhKQeOGCWc0WPC_n_LIpGWH6spRm7KGuYdgDMkQ kY-BgewG-Vmc59JqFeprk1O08qhKQeOGCWc0WPC_n_LIpGWH6spRm7KGuYdgDMkQ
bd4uuB0uPPLx_euVCdrVrA. bd4uuB0uPPLx_euVCdrVrA.
AxY8DCtDaGlsbGljb3RoZQ. AxY8DCtDaGlsbGljb3RoZQ.
7MI2lRCaoyYx1HclVXkr8DhmDoikTmOp3IdEmm4qgBThFkqFqOs3ivXLJTku4M0f 7MI2lRCaoyYx1HclVXkr8DhmDoikTmOp3IdEmm4qgBThFkqFqOs3ivXLJTku4M0f
laMAbGG_X6K8_B-0E-7ak-Olm_-_V03oBUUGTAc-F0A. laMAbGG_X6K8_B-0E-7ak-Olm_-_V03oBUUGTAc-F0A.
OwWNxnC-BMEie-GkFHzVWiNiaV3zUHf6fCOGTwbRckU OwWNxnC-BMEie-GkFHzVWiNiaV3zUHf6fCOGTwbRckU
Appendix B. Relationship of JWTs to SAML Tokens Appendix B. Relationship of JWTs to SAML Assertions
SAML 2.0 [OASIS.saml-core-2.0-os] provides a standard for creating SAML 2.0 [OASIS.saml-core-2.0-os] provides a standard for creating
tokens with much greater expressivity and more security options than security tokens with greater expressivity and more security options
supported by JWTs. However, the cost of this flexibility and than supported by JWTs. However, the cost of this flexibility and
expressiveness is both size and complexity. In addition, SAML's use expressiveness is both size and complexity. SAML's use of XML
of XML [W3C.CR-xml11-20021015] and XML DSIG [RFC3275] only [W3C.CR-xml11-20021015] and XML DSIG [RFC3275] contributes to the
contributes to the size of SAML tokens. size of SAML assertions; its use of XML and especially XML
Canonicalization [W3C.REC-xml-c14n-20010315] contributes to their
complexity.
JWTs are intended to provide a simple token format that is small JWTs are intended to provide a simple security token format that is
enough to fit into HTTP headers and query arguments in URIs. It does small enough to fit into HTTP headers and query arguments in URIs.
this by supporting a much simpler token model than SAML and using the It does this by supporting a much simpler token model than SAML and
JSON [RFC4627] object encoding syntax. It also supports securing using the JSON [RFC4627] object encoding syntax. It also supports
tokens using Message Authentication Codes (MACs) and digital securing tokens using Message Authentication Codes (MACs) and digital
signatures using a smaller (and less flexible) format than XML DSIG. signatures using a smaller (and less flexible) format than XML DSIG.
Therefore, while JWTs can do some of the things SAML tokens do, JWTs Therefore, while JWTs can do some of the things SAML assertions do,
are not intended as a full replacement for SAML tokens, but rather as JWTs are not intended as a full replacement for SAML assertions, but
a compromise token format to be used when space is at a premium. rather as a token format to be used when ease of implementation or
compactness are considerations.
SAML Assertions are always statements made by an entity about a
subject. JWTs are often used in the same manner, with the entity
making the statements being represented by the "iss" (issuer) claim,
and the subject being represented by the "sub" (subject) claim.
However, with these claims being optional, other uses of the JWT
format are also permitted.
Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs) Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs)
Both JWTs and Simple Web Tokens SWT [SWT], at their core, enable sets Both JWTs and Simple Web Tokens SWT [SWT], at their core, enable sets
of claims to be communicated between applications. For SWTs, both of claims to be communicated between applications. For SWTs, both
the claim names and claim values are strings. For JWTs, while claim the claim names and claim values are strings. For JWTs, while claim
names are strings, claim values can be any JSON type. Both token names are strings, claim values can be any JSON type. Both token
types offer cryptographic protection of their content: SWTs with HMAC types offer cryptographic protection of their content: SWTs with HMAC
SHA-256 and JWTs with a choice of algorithms, including HMAC SHA-256, SHA-256 and JWTs with a choice of algorithms, including signature,
RSA SHA-256, and ECDSA P-256 SHA-256. MAC, and encryption algorithms.
Appendix D. Acknowledgements Appendix D. Acknowledgements
The authors acknowledge that the design of JWTs was intentionally The authors acknowledge that the design of JWTs was intentionally
influenced by the design and simplicity of Simple Web Tokens [SWT] influenced by the design and simplicity of Simple Web Tokens [SWT]
and ideas for JSON tokens that Dick Hardt discussed within the OpenID and ideas for JSON tokens that Dick Hardt discussed within the OpenID
community. community.
Solutions for signing JSON content were previously explored by Magic Solutions for signing JSON content were previously explored by Magic
Signatures [MagicSignatures], JSON Simple Sign [JSS], and Canvas Signatures [MagicSignatures], JSON Simple Sign [JSS], and Canvas
Applications [CanvasApp], all of which influenced this draft. Dirk Applications [CanvasApp], all of which influenced this draft.
Balfanz, Yaron Y. Goland, John Panzer, and Paul Tarjan all made
significant contributions to the design of this specification. This specification is the work of the OAuth Working Group, which
includes dozens of active and dedicated participants. In particular,
the following individuals contributed ideas, feedback, and wording
that influenced this specification:
Dirk Balfanz, Richard Barnes, Brian Campbell, Breno de Medeiros, Dick
Hardt, Joe Hildebrand, Jeff Hodges, Edmund Jay, Yaron Y. Goland, Ben
Laurie, James Manger, Prateek Mishra, Tony Nadalin, Axel Nennker,
John Panzer, Emmanuel Raviart, David Recordon, Eric Rescorla, Jim
Schaad, Paul Tarjan, Hannes Tschofenig, and Sean Turner.
Hannes Tschofenig and Derek Atkins chaired the OAuth working group Hannes Tschofenig and Derek Atkins chaired the OAuth working group
and Sean Turner and Stephen Farrell served as Security area directors and Sean Turner and Stephen Farrell served as Security area directors
during the creation of this specification. during the creation of this specification.
Appendix E. Open Issues Appendix E. Open Issues
[[ to be removed by the RFC editor before publication as an RFC ]] [[ to be removed by the RFC editor before publication as an RFC ]]
The following items remain to be considered or done in this draft: The following items remain to be considered or done in this draft:
o Track changes to the underlying JOSE specifications. o Track changes to the underlying JOSE specifications.
o Should all claims continue to be required to be understood by
implementations using them when used in a security-related context
or should a means of declaring that specific claims may be safely
ignored if not understood should be defined? This is related to
the similar JOSE issue about whether all header fields must
continue to be understood.
Appendix F. Document History Appendix F. Document History
[[ to be removed by the RFC editor before publication as an RFC ]] [[ to be removed by the RFC editor before publication as an RFC ]]
-06
o Changed the name of the "prn" claim to "sub" (subject) both to
more closely align with SAML name usage and to use a more
intuitive name.
o Allow JWTs to have multiple audiences.
o Applied editorial improvements suggested by Jeff Hodges, Prateek
Mishra, and Hannes Tschofenig. Many of these simplified the
terminology used.
o Explained why Nested JWTs should be signed and then encrypted.
o Clarified statements of the form "This claim is OPTIONAL" to "Use
of this claim is OPTIONAL".
o Referenced String Comparison Rules in JWS.
o Added seriesInfo information to Internet Draft references.
-05 -05
o Updated values for example AES CBC calculations. o Updated values for example AES CBC calculations.
-04 -04
o Promoted Initialization Vector from being a header parameter to o Promoted Initialization Vector from being a header parameter to
being a top-level JWE element. This saves approximately 16 bytes being a top-level JWE element. This saves approximately 16 bytes
in the compact serialization, which is a significant savings for in the compact serialization, which is a significant savings for
some use cases. Promoting the Initialization Vector out of the some use cases. Promoting the Initialization Vector out of the
 End of changes. 77 change blocks. 
221 lines changed or deleted 293 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/