draft-ietf-oauth-json-web-token-09.txt   draft-ietf-oauth-json-web-token-10.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: January 12, 2014 Ping Identity Expires: January 15, 2014 Ping Identity
N. Sakimura N. Sakimura
NRI NRI
July 11, 2013 July 14, 2013
JSON Web Token (JWT) JSON Web Token (JWT)
draft-ietf-oauth-json-web-token-09 draft-ietf-oauth-json-web-token-10
Abstract Abstract
JSON Web Token (JWT) is a compact URL-safe means of representing JSON Web Token (JWT) is a compact URL-safe means of representing
claims to be transferred between two parties. The claims in a JWT claims to be transferred between two parties. The claims in a JWT
are encoded as a JavaScript Object Notation (JSON) object that is are encoded as a JavaScript Object Notation (JSON) object that is
used as the payload of a JSON Web Signature (JWS) structure or as the used as the payload of a JSON Web Signature (JWS) structure or as the
plaintext of a JSON Web Encryption (JWE) structure, enabling the plaintext of a JSON Web Encryption (JWE) structure, enabling the
claims to be digitally signed or MACed and/or encrypted. claims to be digitally signed or MACed and/or encrypted.
skipping to change at page 1, line 41 skipping to change at page 1, line 41
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 January 12, 2014. This Internet-Draft will expire on January 15, 2014.
Copyright Notice Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the Copyright (c) 2013 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 . . . . . . . . . . . . . . . . 7 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 . . . . . . . . . . . . . . . . . . . 9 4.1. Reserved Claim Names . . . . . . . . . . . . . . . . . . . 8
4.1.1. "iss" (Issuer) Claim . . . . . . . . . . . . . . . . . 9 4.1.1. "iss" (Issuer) Claim . . . . . . . . . . . . . . . . . 8
4.1.2. "sub" (Subject) Claim . . . . . . . . . . . . . . . . 9 4.1.2. "sub" (Subject) Claim . . . . . . . . . . . . . . . . 8
4.1.3. "aud" (Audience) Claim . . . . . . . . . . . . . . . . 9 4.1.3. "aud" (Audience) Claim . . . . . . . . . . . . . . . . 8
4.1.4. "exp" (Expiration Time) Claim . . . . . . . . . . . . 10 4.1.4. "exp" (Expiration Time) Claim . . . . . . . . . . . . 9
4.1.5. "nbf" (Not Before) Claim . . . . . . . . . . . . . . . 10 4.1.5. "nbf" (Not Before) Claim . . . . . . . . . . . . . . . 9
4.1.6. "iat" (Issued At) Claim . . . . . . . . . . . . . . . 10 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 . . . . . . . . . . . . . . . . . . . . 11 4.2. Public Claim Names . . . . . . . . . . . . . . . . . . . . 10
4.3. Private Claim Names . . . . . . . . . . . . . . . . . . . 11 4.3. Private Claim Names . . . . . . . . . . . . . . . . . . . 10
5. JWT Header . . . . . . . . . . . . . . . . . . . . . . . . . . 11 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 . . . . . . . . . . 12 5.2. "cty" (Content Type) Header Parameter . . . . . . . . . . 11
6. Plaintext JWTs . . . . . . . . . . . . . . . . . . . . . . . . 12 5.3. Replicating Claims as Header Parameters . . . . . . . . . 11
6. Plaintext JWTs . . . . . . . . . . . . . . . . . . . . . . . . 11
6.1. Example Plaintext JWT . . . . . . . . . . . . . . . . . . 12 6.1. Example Plaintext JWT . . . . . . . . . . . . . . . . . . 12
7. Rules for Creating and Validating a JWT . . . . . . . . . . . 13 7. Rules for Creating and Validating a JWT . . . . . . . . . . . 12
7.1. String Comparison Rules . . . . . . . . . . . . . . . . . 15 7.1. String Comparison Rules . . . . . . . . . . . . . . . . . 14
8. Cryptographic Algorithms . . . . . . . . . . . . . . . . . . . 15 8. Cryptographic Algorithms . . . . . . . . . . . . . . . . . . . 14
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15
9.1. JSON Web Token Claims Registry . . . . . . . . . . . . . . 16 9.1. JSON Web Token Claims Registry . . . . . . . . . . . . . . 15
9.1.1. Registration Template . . . . . . . . . . . . . . . . 16 9.1.1. Registration Template . . . . . . . . . . . . . . . . 16
9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 17 9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 16
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 . . . . . . . . . . . 17
9.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 17 9.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 17
9.3. JSON Web Signature and Encryption Type Values 9.3. JSON Web Signature and Encryption Type Values
Registration . . . . . . . . . . . . . . . . . . . . . . . 18 Registration . . . . . . . . . . . . . . . . . . . . . . . 17
9.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 18 9.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 17
9.4. Media Type Registration . . . . . . . . . . . . . . . . . 18 9.4. Media Type Registration . . . . . . . . . . . . . . . . . 17
9.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 18 9.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 17
10. Security Considerations . . . . . . . . . . . . . . . . . . . 19 9.5. Registration of JWE Header Parameter Names . . . . . . . . 18
9.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 18
10. Security Considerations . . . . . . . . . . . . . . . . . . . 18
11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19
11.1. Normative References . . . . . . . . . . . . . . . . . . . 19 11.1. Normative References . . . . . . . . . . . . . . . . . . . 19
11.2. Informative References . . . . . . . . . . . . . . . . . . 20 11.2. Informative References . . . . . . . . . . . . . . . . . . 20
Appendix A. Example Encrypted JWT . . . . . . . . . . . . . . . . 21 Appendix A. Example Encrypted JWT . . . . . . . . . . . . . . . . 21
Appendix B. Relationship of JWTs to SAML Assertions . . . . . . . 22 Appendix B. Relationship of JWTs to SAML Assertions . . . . . . . 22
Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs) . . 23 Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs) . . 22
Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 23 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 23
Appendix E. Document History . . . . . . . . . . . . . . . . . . 23 Appendix E. Document History . . . . . . . . . . . . . . . . . . 23
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 26 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 26
1. Introduction 1. Introduction
JSON Web Token (JWT) is a compact claims representation format JSON Web Token (JWT) is a compact claims representation format
intended for space constrained environments such as HTTP intended for space constrained environments such as HTTP
Authorization headers and URI query parameters. JWTs encode claims Authorization headers and URI query parameters. JWTs encode claims
to be transmitted as a JavaScript Object Notation (JSON) [RFC4627] to be transmitted as a JavaScript Object Notation (JSON) [RFC4627]
skipping to change at page 8, line 44 skipping to change at page 7, line 44
. .
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 a JWT Claims Set claims conveyed by the JWT. The Claim Names within a JWT Claims Set
MUST be unique; receipients MUST either reject JWTs with duplicate MUST be unique; recipients MUST either reject JWTs with duplicate
Claim Names or use a JSON parser that returns only the lexically last Claim Names or use a JSON parser that returns only the lexically last
duplicate member name, as specified in Section 15.12 (The JSON duplicate member name, as specified in Section 15.12 (The JSON
Object) of ECMAScript 5.1 [ECMAScript]. Object) of ECMAScript 5.1 [ECMAScript].
The set of claims that a JWT must contain to be considered valid is The set of claims that a JWT must contain to be considered valid is
context-dependent and is outside the scope of this specification. context-dependent and is outside the scope of this specification.
Specific applications of JWTs will require implementations to Specific applications of JWTs will require implementations to
understand and process some claims in particular ways. However, in understand and process some claims in particular ways. However, in
the absence of such requirements, all claims that are not understood the absence of such requirements, all claims that are not understood
by implementations SHOULD be ignored. by implementations SHOULD be ignored.
skipping to change at page 11, line 28 skipping to change at page 10, line 28
are Private Names: names that are not Reserved Names Section 4.1 or are Private Names: names that are not Reserved Names Section 4.1 or
Public Names Section 4.2. Unlike Public Names, Private Names are Public Names Section 4.2. Unlike Public Names, Private Names are
subject to collision and should 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; receipients MUST either reject JWTs with duplicate Header be unique; recipients MUST either reject JWTs with duplicate Header
Parameter Names or use a JSON parser that returns only the lexically Parameter Names or use a JSON parser that returns only the lexically
last duplicate member name, as specified in Section 15.12 (The JSON last duplicate member name, as specified in Section 15.12 (The JSON
Object) of ECMAScript 5.1 [ECMAScript]. The corresponding values are Object) of ECMAScript 5.1 [ECMAScript]. The corresponding values are
referred to as Header Parameter Values. referred to as Header Parameter Values.
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.
skipping to change at page 12, line 20 skipping to change at page 11, line 20
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.
5.3. Replicating Claims as Header Parameters
In some applications using encrypted JWTs, it is useful to have an
unencrypted representation of some Claims. This might be used, for
instance, in application processing rules to determine whether and
how to process the JWT before it is decrypted.
This specification allows Claims present in the JWT Claims Set to be
replicated as Header Parameters in a JWT that is a JWE, as needed by
the application. If such replicated Claims are present, the
application receiving them SHOULD verify that their values are
identical. It is the responsibility of the application to ensure
that only claims that are safe to be transmitted in an unencrypted
manner are replicated as Header Parameter values in the JWT.
This specification reserves the "iss" (issuer) and "aud" (audience)
Header Parameter Names for the purpose of providing unencrypted
replicas of these Claims in encrypted JWTs for applications that need
them. Other specifications MAY similarly reserve other names that
are reserved Claim Names as Header Parameter Names, as needed.
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 JWT other than a signature and/or encryption contained within the JWT
(such as a signature on a data structure containing the JWT), 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 the defined in JSON Web Algorithms (JWA) [JWA]; it is a JWS with the
empty string for its JWS Signature value. empty string for its JWS Signature value.
skipping to change at page 13, line 28 skipping to change at page 12, line 50
. .
7. Rules for Creating and Validating a JWT 7. Rules for Creating and Validating a JWT
To create a JWT, one MUST perform these steps. The order of the To create a JWT, one MUST perform these steps. The order of the
steps is not significant in cases where there are no dependencies steps is not significant in cases where there are no dependencies
between the inputs and outputs of the steps. between the inputs and outputs of the steps.
1. Create a JWT Claims Set containing the desired claims. Note that 1. Create a JWT Claims Set containing the desired claims. Note that
white space is explicitly allowed in the representation and no white space is explicitly allowed in the representation and no
canonicalization is performed before encoding. canonicalization need be performed before encoding.
2. Let the Message be the octets of the UTF-8 representation of the 2. Let the Message be the octets of the UTF-8 representation of the
JWT Claims Set. JWT Claims Set.
3. Create a JWT Header containing the desired set of header 3. Create a JWT Header containing the desired set of header
parameters. The JWT MUST conform to either the [JWS] or [JWE] parameters. The JWT MUST conform to either the [JWS] or [JWE]
specifications. Note that white space is explicitly allowed in specifications. Note that white space is explicitly allowed in
the representation and no canonicalization is performed before the representation and no canonicalization need be performed
encoding. before encoding.
4. Base64url encode the octets of the UTF-8 representation of the 4. Base64url encode the octets of the UTF-8 representation of the
JWT Header. Let this be the Encoded JWT Header. JWT Header. Let this be the Encoded JWT Header.
5. Depending upon whether the JWT is a JWS or JWE, there are two 5. Depending upon whether the JWT is a JWS or JWE, there are two
cases: cases:
* If the JWT is a JWS, create a JWS using the JWT Header as the * If the JWT is a JWS, create a JWS using the JWT Header as the
JWS Header and the Message as the JWS Payload; all steps JWS Header and the Message as the JWS Payload; all steps
specified in [JWS] for creating a JWS MUST be followed. specified in [JWS] for creating a JWS MUST be followed.
skipping to change at page 19, line 5 skipping to change at page 18, line 25
Persona, Salesforce, Google, numerous others Persona, Salesforce, Google, numerous others
o Additional Information: Magic number(s): n/a, File extension(s): o Additional Information: Magic number(s): n/a, File extension(s):
n/a, Macintosh file type code(s): n/a n/a, Macintosh file type code(s): n/a
o Person & email address to contact for further information: Michael o Person & email address to contact for further information: Michael
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
9.5. Registration of JWE Header Parameter Names
This specification registers specific reserved Claim Names defined in
Section 4.1 in the IANA JSON Web Signature and Encryption Header
Parameters registry [JWS] for use by Claims replicated as Header
Parameters, per Section 5.3.
9.5.1. Registry Contents
o Header Parameter Name: "iss"
o Header Parameter Usage Location(s): JWE
o Change Controller: IETF
o Specification Document(s): Section 4.1.1 of [[ this document ]]
o Header Parameter Name: "aud"
o Header Parameter Usage Location(s): JWE
o Change Controller: IETF
o Specification Document(s): Section 4.1.3 of [[ this document ]]
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 and symmetric keys, preventing various protecting the user's private and symmetric keys, preventing various
attacks, and helping the user avoid mistakes such as inadvertently attacks, and helping the user avoid mistakes such as inadvertently
encrypting a message for the wrong recipient. The entire list of encrypting a message for the wrong recipient. The entire list of
security considerations is beyond the scope of this document. security considerations is beyond the scope of this document.
All the security considerations in the JWS specification also apply All the security considerations in the JWS specification also apply
skipping to change at page 23, line 45 skipping to change at page 23, line 40
Schaad, Paul Tarjan, Hannes Tschofenig, and Sean Turner. 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. Document History Appendix E. 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 ]]
-10
o Allowed Claims to be replicated as Header Parameters in encrypted
JWTs as needed by applications that require an unencrypted
representation of specific Claims.
-09 -09
o Clarified that the "typ" header parameter is used in an o Clarified that the "typ" header parameter is used in an
application-specific manner and has no effect upon the JWT application-specific manner and has no effect upon the JWT
processing. processing.
o Stated that receipients MUST either reject JWTs with duplicate o Stated that recipients MUST either reject JWTs with duplicate
Header Parameter Names or with duplicate Claim Names or use a JSON Header Parameter Names or with duplicate Claim Names or use a JSON
parser that returns only the lexically last duplicate member name. parser that returns only the lexically last duplicate member name.
-08 -08
o Tracked a change to how JWEs are computed (which only affected the o Tracked a change to how JWEs are computed (which only affected the
example encrypted JWT value). example encrypted JWT value).
-07 -07
 End of changes. 18 change blocks. 
42 lines changed or deleted 91 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/