draft-ietf-oauth-json-web-token-01.txt   draft-ietf-oauth-json-web-token-02.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 7, 2013 Ping Identity Expires: January 17, 2013 Ping Identity
N. Sakimura N. Sakimura
NRI NRI
July 6, 2012 July 16, 2012
JSON Web Token (JWT) JSON Web Token (JWT)
draft-ietf-oauth-json-web-token-01 draft-ietf-oauth-json-web-token-02
Abstract Abstract
JSON Web Token (JWT) is a means of representing claims to be JSON Web Token (JWT) is a means of representing claims to be
transferred between two parties. The claims in a JWT are encoded as transferred between two parties. The claims in a JWT are encoded as
a JavaScript Object Notation (JSON) object that is digitally signed a JavaScript Object Notation (JSON) object that is digitally signed
or MACed using JSON Web Signature (JWS) and/or encrypted using JSON or MACed using JSON Web Signature (JWS) and/or encrypted using JSON
Web Encryption (JWE). Web Encryption (JWE).
The suggested pronunciation of JWT is the same as the English word The suggested pronunciation of JWT is the same as the English word
skipping to change at page 1, line 40 skipping to change at page 1, line 40
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 7, 2013. This Internet-Draft will expire on January 17, 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 . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. JSON Web Token (JWT) Overview . . . . . . . . . . . . . . . . 5 3. JSON Web Token (JWT) Overview . . . . . . . . . . . . . . . . 6
3.1. Example JWT . . . . . . . . . . . . . . . . . . . . . . . 6 3.1. Example JWT . . . . . . . . . . . . . . . . . . . . . . . 7
4. JWT Claims . . . . . . . . . . . . . . . . . . . . . . . . . . 7 4. JWT Claims . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4.1. Reserved Claim Names . . . . . . . . . . . . . . . . . . . 7 4.1. Reserved Claim Names . . . . . . . . . . . . . . . . . . . 8
4.1.1. "exp" (Expiration Time) Claim . . . . . . . . . . . . 7 4.1.1. "exp" (Expiration Time) Claim . . . . . . . . . . . . 8
4.1.2. "nbf" (Not Before) Claim . . . . . . . . . . . . . . . 7 4.1.2. "nbf" (Not Before) Claim . . . . . . . . . . . . . . . 8
4.1.3. "iat" (Issued At) Claim . . . . . . . . . . . . . . . 8 4.1.3. "iat" (Issued At) Claim . . . . . . . . . . . . . . . 9
4.1.4. "iss" (Issuer) Claim . . . . . . . . . . . . . . . . . 8 4.1.4. "iss" (Issuer) Claim . . . . . . . . . . . . . . . . . 9
4.1.5. "aud" (Audience) Claim . . . . . . . . . . . . . . . . 8 4.1.5. "aud" (Audience) Claim . . . . . . . . . . . . . . . . 9
4.1.6. "prn" (Principal) Claim . . . . . . . . . . . . . . . 8 4.1.6. "prn" (Principal) Claim . . . . . . . . . . . . . . . 9
4.1.7. "jti" (JWT ID) Claim . . . . . . . . . . . . . . . . . 8 4.1.7. "jti" (JWT ID) Claim . . . . . . . . . . . . . . . . . 9
4.1.8. "typ" (Type) Claim . . . . . . . . . . . . . . . . . . 9 4.1.8. "typ" (Type) Claim . . . . . . . . . . . . . . . . . . 10
4.2. Public Claim Names . . . . . . . . . . . . . . . . . . . . 9 4.2. Public Claim Names . . . . . . . . . . . . . . . . . . . . 10
4.3. Private Claim Names . . . . . . . . . . . . . . . . . . . 9 4.3. Private Claim Names . . . . . . . . . . . . . . . . . . . 10
5. JWT Header . . . . . . . . . . . . . . . . . . . . . . . . . . 9 5. JWT Header . . . . . . . . . . . . . . . . . . . . . . . . . . 10
5.1. "typ" (Type) Header Parameter . . . . . . . . . . . . . . 9 5.1. "typ" (Type) Header Parameter . . . . . . . . . . . . . . 10
5.2. "cty" (Content Type) Header Parameter . . . . . . . . . . 10 5.2. "cty" (Content Type) Header Parameter . . . . . . . . . . 11
6. Plaintext JWTs . . . . . . . . . . . . . . . . . . . . . . . . 10 6. Plaintext JWTs . . . . . . . . . . . . . . . . . . . . . . . . 11
6.1. Example Plaintext JWT . . . . . . . . . . . . . . . . . . 10 6.1. Example Plaintext JWT . . . . . . . . . . . . . . . . . . 11
7. Rules for Creating and Validating a JWT . . . . . . . . . . . 11 7. Rules for Creating and Validating a JWT . . . . . . . . . . . 12
8. Cryptographic Algorithms . . . . . . . . . . . . . . . . . . . 13 8. Cryptographic Algorithms . . . . . . . . . . . . . . . . . . . 14
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15
9.1. JSON Web Token Claims Registry . . . . . . . . . . . . . . 14 9.1. JSON Web Token Claims Registry . . . . . . . . . . . . . . 15
9.1.1. Registration Template . . . . . . . . . . . . . . . . 14 9.1.1. Registration Template . . . . . . . . . . . . . . . . 15
9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 15 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 . . . . . . . . . . . 16 urn:ietf:params:oauth:token-type:jwt . . . . . . . . . . . 17
9.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 16 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 . . . . . . . . . . . . . . . . . . . . . . . 16 Registration . . . . . . . . . . . . . . . . . . . . . . . 17
9.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 16 9.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 17
9.4. Media Type Registration . . . . . . . . . . . . . . . . . 16 9.4. Media Type Registration . . . . . . . . . . . . . . . . . 17
9.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 16 9.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 17
10. Security Considerations . . . . . . . . . . . . . . . . . . . 17 10. Security Considerations . . . . . . . . . . . . . . . . . . . 18
11. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 18 11. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 19
12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19
12.1. Normative References . . . . . . . . . . . . . . . . . . . 18 12.1. Normative References . . . . . . . . . . . . . . . . . . . 19
12.2. Informative References . . . . . . . . . . . . . . . . . . 19 12.2. Informative References . . . . . . . . . . . . . . . . . . 20
Appendix A. Relationship of JWTs to SAML Tokens . . . . . . . . . 19 Appendix A. Example Encrypted JWT . . . . . . . . . . . . . . . . 21
Appendix B. Relationship of JWTs to Simple Web Tokens (SWTs) . . 20 Appendix B. Relationship of JWTs to SAML Tokens . . . . . . . . . 22
Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 20 Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs) . . 22
Appendix D. Document History . . . . . . . . . . . . . . . . . . 20 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 22
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 21 Appendix E. Document History . . . . . . . . . . . . . . . . . . 23
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 23
1. Introduction 1. Introduction
JSON Web Token (JWT) is a compact token format intended for space JSON Web Token (JWT) is a compact token format intended for space
constrained environments such as HTTP Authorization headers and URI constrained environments such as HTTP Authorization headers and URI
query parameters. JWTs encode claims to be transmitted as a query parameters. JWTs encode claims to be transmitted as a
JavaScript Object Notation (JSON) [RFC4627] object that is base64url JavaScript Object Notation (JSON) [RFC4627] object that is base64url
encoded and digitally signed or MACed and/or encrypted. Signing and encoded and digitally signed or MACed and/or encrypted. Signing and
MACing is performed using JSON Web Signature (JWS) [JWS]. Encryption MACing is performed using JSON Web Signature (JWS) [JWS]. Encryption
is performed using JSON Web Encryption (JWE) [JWE]. is performed using JSON Web Encryption (JWE) [JWE].
skipping to change at page 4, line 27 skipping to change at page 5, line 27
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 consisting of multiple parts, the JSON Web Token (JWT) A string representing a set of claims as a JSON
first being the Encoded JWT Header, plus additional parts object that is digitally signed or MACed and/or encrypted. The
depending upon the contents of the header, with the parts being string consists of multiple parts, the first being the Encoded JWT
separated by period ('.') characters, and each part containing Header, plus additional parts depending upon the contents of the
base64url encoded content. 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
described in RFC 4648 [RFC4648], Section 5, with the (non URL-
safe) '=' padding characters omitted, as permitted by Section 3.2.
(See Appendix C of [JWS] for notes on implementing base64url
encoding without padding.)
JWT Header A string representing a JSON object that describes the JWT Header A string representing a JSON object that describes the
cryptographic operations applied to the JWT. When the JWT is cryptographic operations applied to the JWT. When the JWT is
digitally signed or MACed, the JWT Header is a JWS Header. When digitally signed or MACed, the JWT Header is a JWS Header. When
the JWT is encrypted, the JWT Header is a JWE Header. the JWT is encrypted, the JWT Header is a JWE Header.
Header Parameter Name The name of a member of the JSON object Header Parameter Name The name of a member of the JSON object
representing a JWT Header. representing a JWT Header.
Header Parameter Value The value of a member of the JSON object Header Parameter Value The value of a member of the JSON object
skipping to change at page 5, line 14 skipping to change at page 6, line 21
Claim Name The name of a member of the JSON object representing a Claim Name The name of a member of the JSON object representing a
JWT Claims Set. JWT Claims Set.
Claim Value The value of a member of the JSON object representing a Claim Value The value of a member of the JSON object representing a
JWT Claims Set. JWT Claims Set.
Encoded JWT Header Base64url encoding of the bytes of the UTF-8 Encoded JWT Header Base64url encoding of the bytes of the UTF-8
[RFC3629] representation of the JWT Header. [RFC3629] representation of the JWT Header.
Base64url Encoding For the purposes of this specification, this term
always refers to the URL- and filename-safe Base64 encoding
described in RFC 4648 [RFC4648], Section 5, with the (non URL-
safe) '=' padding characters omitted, as permitted by Section 3.2.
(See Appendix C of [JWS] for notes on implementing base64url
encoding without padding.)
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
delegated namespace, the definer of a name needs to take delegated namespace, the definer of a name needs to take
skipping to change at page 7, line 13 skipping to change at page 8, line 13
display purposes only): display purposes only):
eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
. .
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
. .
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
This computation is illustrated in more detail in [JWS], Appendix This computation is illustrated in more detail in [JWS], Appendix
A.1. A.1. 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 this object MUST
be unique; JWTs with duplicate Claim Names MUST be rejected. Note be unique; JWTs with duplicate Claim Names MUST be rejected. Note
however, that the set of claims that a JWT must contain to be 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
skipping to change at page 8, line 21 skipping to change at page 9, line 21
The "iat" (issued at) claim identifies the time at which the JWT was The "iat" (issued at) claim identifies the time at which the JWT was
issued. This claim can be used to determine the age of the token. issued. This claim can be used to determine the age of the token.
Its value MUST be a number containing an IntDate value. This claim Its value MUST be a number containing an IntDate value. This claim
is OPTIONAL. is OPTIONAL.
4.1.4. "iss" (Issuer) Claim 4.1.4. "iss" (Issuer) Claim
The "iss" (issuer) claim identifies the principal that issued the The "iss" (issuer) claim identifies the principal that issued the
JWT. The processing of this claim is generally application specific. JWT. The processing of this claim is generally application specific.
The "iss" value is case sensitive. Its value MUST be a string The "iss" value is a case sensitive string containing a StringOrURI
containing a StringOrURI value. This claim is OPTIONAL. value. This claim is OPTIONAL.
4.1.5. "aud" (Audience) Claim 4.1.5. "aud" (Audience) Claim
The "aud" (audience) claim identifies the audience that the JWT is The "aud" (audience) claim identifies the audience that the JWT is
intended for. The principal intended to process the JWT MUST be intended for. The principal intended to process the JWT MUST be
identified with the value of the audience claim. If the principal identified with the value of the audience claim. If the principal
processing the claim does not identify itself with the identifier in processing the claim does not identify itself with the identifier in
the "aud" claim value then the JWT MUST be rejected. The the "aud" claim value then the JWT MUST be rejected. The
interpretation of the audience value is generally application interpretation of the audience value is generally application
specific. The "aud" value is case sensitive. Its value MUST be a specific. The "aud" value is a case sensitive string containing a
string containing a StringOrURI value. This claim is OPTIONAL. StringOrURI value. This claim is OPTIONAL.
4.1.6. "prn" (Principal) Claim 4.1.6. "prn" (Principal) Claim
The "prn" (principal) claim identifies the subject of the JWT. The The "prn" (principal) claim identifies the subject of the JWT. The
processing of this claim is generally application specific. The processing of this claim is generally application specific. The
"prn" value is case sensitive. Its value MUST be a string containing "prn" value is a case sensitive string containing a StringOrURI
a StringOrURI value. This claim is OPTIONAL. value. This 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 case sensitive. Its value MUST be a string. This claim is is a case sensitive string. This claim is OPTIONAL.
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 case sensitive. Its value this JWT Claims Set. The "typ" value is a case sensitive string.
MUST be a string. This claim is OPTIONAL. 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 URI that contains a Collision Resistant Namespace.
skipping to change at page 9, line 51 skipping to change at page 10, line 51
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 case sensitive. Its value MUST object is a JWT. The "typ" value is a case sensitive string. This
be a string. This header parameter is OPTIONAL. 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
skipping to change at page 14, line 41 skipping to change at page 15, line 41
and, if applicable, suggestions as to how to make the request and, if applicable, suggestions as to how to make the request
successful. successful.
IANA must only accept registry updates from the Designated Expert(s), IANA must only accept registry updates from the Designated Expert(s),
and should direct all requests for registration to the review mailing and should direct all requests for registration to the review mailing
list. list.
9.1.1. Registration Template 9.1.1. Registration Template
Claim Name: Claim Name:
The name requested (e.g., "example"). The name requested (e.g., "example"). This name is case
sensitive. Names that match other registered names in a case
insensitive manner SHOULD NOT be accepted.
Change Controller: Change Controller:
For standards-track RFCs, state "IETF". For others, give the name For standards-track RFCs, state "IETF". For others, give the name
of the responsible party. Other details (e.g., postal address, of the responsible party. Other details (e.g., postal address,
e-mail address, home page URI) may also be included. e-mail address, home page URI) may also be included.
Specification Document(s): Specification Document(s):
Reference to the document that specifies the parameter, preferably Reference to the document that specifies the parameter, preferably
including a URI that can be used to retrieve a copy of the including a URI that can be used to retrieve a copy of the
document. An indication of the relevant sections may also be document. An indication of the relevant sections may also be
skipping to change at page 18, line 11 skipping to change at page 19, line 15
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. Open Issues 11. 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 Provide an example of an encrypted JWT. o Track changes to the underlying JOSE specifications.
12. References 12. References
12.1. Normative References 12.1. Normative References
[I-D.ietf-oauth-urn-sub-ns] [I-D.ietf-oauth-urn-sub-ns]
Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace
for OAuth", draft-ietf-oauth-urn-sub-ns-05 (work in for OAuth", draft-ietf-oauth-urn-sub-ns-05 (work in
progress), June 2012. progress), June 2012.
skipping to change at page 19, line 48 skipping to change at page 21, line 5
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.
Appendix A. Relationship of JWTs to SAML Tokens Appendix A. Example Encrypted JWT
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
an integrated integrity check, so a separate integrity check
calculation is performed using HMAC SHA-256, with separate encryption
and integrity keys being derived from a master key using the Concat
KDF with the SHA-256 digest function.
The following example JWE Header (with line breaks for display
purposes only) declares that:
o the Content Master Key is encrypted to the recipient using the
RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key,
o the Plaintext is encrypted using the AES CBC algorithm with a 128
bit key to produce the Ciphertext,
o the JWE Integrity Value safeguarding the integrity of the
Ciphertext and the parameters used to create it was computed with
the HMAC SHA-256 algorithm, and
o the 128 bit Initialization Vector (IV) with the base64url encoding
"AxY8DCtDaGlsbGljb3RoZQ" was used.
{"alg":"RSA1_5","enc":"A128CBC","int":"HS256","iv":"AxY8DCtDaGls
bGljb3RoZQ"}
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
of this JWT is identical to the computation of the JWE in Appendix
A.2 of [JWE], including the keys used.
The final result in this example (with line breaks for display
purposes only) is:
eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDIiwiaW50IjoiSFMyNTYiLCJp
diI6IkF4WThEQ3REYUdsc2JHbGpiM1JvWlEifQ.
VjBkk22MjrFUMUl8ItbS8CjKjku4HQz4RiHD0eVG4dir-7XbDkPr1q6YtnN1X-av
1EKmEnsrbhSxTvqtY4oEbWKLoEQ7zVm_0BW-rnwxdwrj4QJrhXGnqIL6bC4waZVJ
qYhVQIahVWSQsCRcS1oYXA-2GhT6rk91y118DUkhGDsvdK2_hQsNGE6BQVN1i-Xw
Uoz5sM6_0PRQ1FsYnJATMjVZfa4otHiooZ_KcOlSWIDxhMDqfPOu60--1ej0eZBy
O7Ar_IZvzPAWqJ9agGFQIVGRZviXhN0WeErq9fVTcgeSUPsmurRSTYhTrNFLojqP
qqk8pI61kn8GmZxA80-RUQ.
7kLQQst655TUxmDzysjRLXnD-nfLK5EQK7ODAUkwxc0aRb9NOgu0EMJgOR6Vz8eN
baf8six_OP6BRyUTYrCkH73-inD6Rc-7vc9eC5fcfSM.
COyXNSm-CdfAL22WIKcoyCgQwb85aLW3ttDkzNj_1Wg
Appendix B. Relationship of JWTs to SAML Tokens
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 tokens with much greater expressivity and more security options than
supported by JWTs. However, the cost of this flexibility and 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. In addition, SAML's use
of XML [W3C.CR-xml11-20021015] and XML DSIG [RFC3275] only of XML [W3C.CR-xml11-20021015] and XML DSIG [RFC3275] only
contributes to the size of SAML tokens. contributes to the size of SAML tokens.
JWTs are intended to provide a simple token format that is small 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 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 this by supporting a much simpler token model than SAML and using the
JSON [RFC4627] object encoding syntax. It also supports securing JSON [RFC4627] object encoding syntax. It also supports securing
tokens using Message Authentication Codes (MACs) and digital 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 tokens do, JWTs
are not intended as a full replacement for SAML tokens, but rather as 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. a compromise token format to be used when space is at a premium.
Appendix B. 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 HMAC SHA-256,
RSA SHA-256, and ECDSA P-256 SHA-256. RSA SHA-256, and ECDSA P-256 SHA-256.
Appendix C. 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. Dirk
Balfanz, Yaron Y. Goland, John Panzer, and Paul Tarjan all made Balfanz, Yaron Y. Goland, John Panzer, and Paul Tarjan all made
significant contributions to the design of this specification. significant contributions to the design of this specification.
Appendix D. 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 ]]
-02
o Added an example of an encrypted JWT.
o Added this language to Registration Templates: "This name is case
sensitive. Names that match other registered names in a case
insensitive manner SHOULD NOT be accepted."
o Applied editorial suggestions.
-01 -01
o Added the "cty" (content type) header parameter for declaring type o Added the "cty" (content type) header parameter for declaring type
information about the secured content, as opposed to the "typ" information about the secured content, as opposed to the "typ"
(type) header parameter, which declares type information about (type) header parameter, which declares type information about
this object. This significantly simplified nested JWTs. this object. This significantly simplified nested JWTs.
o Moved description of how to determine whether a header is for a o Moved description of how to determine whether a header is for a
JWS or a JWE from the JWT spec to the JWE spec. JWS or a JWE from the JWT spec to the JWE spec.
o Changed registration requirements from RFC Required to o Changed registration requirements from RFC Required to
Specification Required with Expert Review. Specification Required with Expert Review.
 End of changes. 24 change blocks. 
79 lines changed or deleted 140 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/