draft-ietf-oauth-json-web-token-25.txt   draft-ietf-oauth-json-web-token-26.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 5, 2015 Ping Identity Expires: March 27, 2015 Ping Identity
N. Sakimura N. Sakimura
NRI NRI
July 4, 2014 September 23, 2014
JSON Web Token (JWT) JSON Web Token (JWT)
draft-ietf-oauth-json-web-token-25 draft-ietf-oauth-json-web-token-26
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.
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
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 5, 2015. This Internet-Draft will expire on March 27, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2014 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
skipping to change at page 2, line 21 skipping to change at page 2, line 21
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. JSON Web Token (JWT) Overview . . . . . . . . . . . . . . . . 6 3. JSON Web Token (JWT) Overview . . . . . . . . . . . . . . . . 6
3.1. Example JWT . . . . . . . . . . . . . . . . . . . . . . . 6 3.1. Example JWT . . . . . . . . . . . . . . . . . . . . . . . 6
4. JWT Claims . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4. JWT Claims . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4.1. Registered Claim Names . . . . . . . . . . . . . . . . . . 8 4.1. Registered Claim Names . . . . . . . . . . . . . . . . . . 8
4.1.1. "iss" (Issuer) Claim . . . . . . . . . . . . . . . . . 8 4.1.1. "iss" (Issuer) Claim . . . . . . . . . . . . . . . . . 9
4.1.2. "sub" (Subject) Claim . . . . . . . . . . . . . . . . 9 4.1.2. "sub" (Subject) Claim . . . . . . . . . . . . . . . . 9
4.1.3. "aud" (Audience) Claim . . . . . . . . . . . . . . . . 9 4.1.3. "aud" (Audience) Claim . . . . . . . . . . . . . . . . 9
4.1.4. "exp" (Expiration Time) Claim . . . . . . . . . . . . 9 4.1.4. "exp" (Expiration Time) Claim . . . . . . . . . . . . 9
4.1.5. "nbf" (Not Before) Claim . . . . . . . . . . . . . . . 9 4.1.5. "nbf" (Not Before) Claim . . . . . . . . . . . . . . . 9
4.1.6. "iat" (Issued At) Claim . . . . . . . . . . . . . . . 9 4.1.6. "iat" (Issued At) Claim . . . . . . . . . . . . . . . 10
4.1.7. "jti" (JWT ID) Claim . . . . . . . . . . . . . . . . . 10 4.1.7. "jti" (JWT ID) Claim . . . . . . . . . . . . . . . . . 10
4.2. Public Claim Names . . . . . . . . . . . . . . . . . . . . 10 4.2. Public Claim Names . . . . . . . . . . . . . . . . . . . . 10
4.3. Private Claim Names . . . . . . . . . . . . . . . . . . . 10 4.3. Private Claim Names . . . . . . . . . . . . . . . . . . . 10
5. JOSE Header . . . . . . . . . . . . . . . . . . . . . . . . . 10 5. JOSE Header . . . . . . . . . . . . . . . . . . . . . . . . . 10
5.1. "typ" (Type) Header Parameter . . . . . . . . . . . . . . 10 5.1. "typ" (Type) Header Parameter . . . . . . . . . . . . . . 11
5.2. "cty" (Content Type) Header Parameter . . . . . . . . . . 11 5.2. "cty" (Content Type) Header Parameter . . . . . . . . . . 11
5.3. Replicating Claims as Header Parameters . . . . . . . . . 11 5.3. Replicating Claims as Header Parameters . . . . . . . . . 11
6. Plaintext JWTs . . . . . . . . . . . . . . . . . . . . . . . . 12 6. Unsecured JWTs . . . . . . . . . . . . . . . . . . . . . . . . 12
6.1. Example Plaintext JWT . . . . . . . . . . . . . . . . . . 12 6.1. Example Unsecured JWT . . . . . . . . . . . . . . . . . . 12
7. Rules for Creating and Validating a JWT . . . . . . . . . . . 13 7. Rules for Creating and Validating a JWT . . . . . . . . . . . 13
7.1. String Comparison Rules . . . . . . . . . . . . . . . . . 14 7.1. String Comparison Rules . . . . . . . . . . . . . . . . . 15
8. Implementation Requirements . . . . . . . . . . . . . . . . . 15 8. Implementation Requirements . . . . . . . . . . . . . . . . . 15
9. URI for Declaring that Content is a JWT . . . . . . . . . . . 15 9. URI for Declaring that Content is a JWT . . . . . . . . . . . 16
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16
10.1. JSON Web Token Claims Registry . . . . . . . . . . . . . . 16 10.1. JSON Web Token Claims Registry . . . . . . . . . . . . . . 16
10.1.1. Registration Template . . . . . . . . . . . . . . . . 17 10.1.1. Registration Template . . . . . . . . . . . . . . . . 17
10.1.2. Initial Registry Contents . . . . . . . . . . . . . . 17 10.1.2. Initial Registry Contents . . . . . . . . . . . . . . 17
10.2. Sub-Namespace Registration of 10.2. Sub-Namespace Registration of
urn:ietf:params:oauth:token-type:jwt . . . . . . . . . . . 18 urn:ietf:params:oauth:token-type:jwt . . . . . . . . . . . 18
10.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 18 10.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 18
10.3. Media Type Registration . . . . . . . . . . . . . . . . . 18 10.3. Media Type Registration . . . . . . . . . . . . . . . . . 18
10.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 18 10.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 18
10.4. Header Parameter Names Registration . . . . . . . . . . . 19 10.4. Header Parameter Names Registration . . . . . . . . . . . 19
10.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 19 10.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 19
11. Security Considerations . . . . . . . . . . . . . . . . . . . 19 11. Security Considerations . . . . . . . . . . . . . . . . . . . 20
11.1. Trust Decisions . . . . . . . . . . . . . . . . . . . . . 20 11.1. Trust Decisions . . . . . . . . . . . . . . . . . . . . . 20
11.2. Signing and Encryption Order . . . . . . . . . . . . . . . 20 11.2. Signing and Encryption Order . . . . . . . . . . . . . . . 20
12. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 20 12. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 20
13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21
13.1. Normative References . . . . . . . . . . . . . . . . . . . 21 13.1. Normative References . . . . . . . . . . . . . . . . . . . 21
13.2. Informative References . . . . . . . . . . . . . . . . . . 21 13.2. Informative References . . . . . . . . . . . . . . . . . . 22
Appendix A. JWT Examples . . . . . . . . . . . . . . . . . . . . 22 Appendix A. JWT Examples . . . . . . . . . . . . . . . . . . . . 23
A.1. Example Encrypted JWT . . . . . . . . . . . . . . . . . . 23 A.1. Example Encrypted JWT . . . . . . . . . . . . . . . . . . 23
A.2. Example Nested JWT . . . . . . . . . . . . . . . . . . . . 23 A.2. Example Nested JWT . . . . . . . . . . . . . . . . . . . . 24
Appendix B. Relationship of JWTs to SAML Assertions . . . . . . . 25 Appendix B. Relationship of JWTs to SAML Assertions . . . . . . . 25
Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs) . . 26 Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs) . . 26
Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 26 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 26
Appendix E. Document History . . . . . . . . . . . . . . . . . . 26 Appendix E. Document History . . . . . . . . . . . . . . . . . . 27
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 32 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 32
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) [RFC7159] to be transmitted as a JavaScript Object Notation (JSON) [RFC7159]
object that is used as the payload of a JSON Web Signature (JWS) object that is used as the payload of a JSON Web Signature (JWS)
[JWS] structure or as the plaintext of a JSON Web Encryption (JWE) [JWS] structure or as the plaintext of a JSON Web Encryption (JWE)
skipping to change at page 4, line 35 skipping to change at page 4, line 35
words for use in RFCs to Indicate Requirement Levels [RFC2119]. If words for use in RFCs to Indicate Requirement Levels [RFC2119]. If
these words are used without being spelled in uppercase then they are these words are used without being spelled in uppercase then they are
to be interpreted with their normal natural language meanings. to be interpreted with their normal natural language meanings.
2. Terminology 2. Terminology
These terms defined by the JSON Web Signature (JWS) [JWS] These terms defined by the JSON Web Signature (JWS) [JWS]
specification are incorporated into this specification: "JSON Web specification are incorporated into this specification: "JSON Web
Signature (JWS)", "Base64url Encoding", "Header Parameter", "JOSE Signature (JWS)", "Base64url Encoding", "Header Parameter", "JOSE
Header", "JWS Compact Serialization", "JWS Payload", "JWS Signature", Header", "JWS Compact Serialization", "JWS Payload", "JWS Signature",
and "Plaintext JWS". and "Unsecured JWS".
These terms defined by the JSON Web Encryption (JWE) [JWE] These terms defined by the JSON Web Encryption (JWE) [JWE]
specification are incorporated into this specification: "JSON Web specification are incorporated into this specification: "JSON Web
Encryption (JWE)", "Content Encryption Key (CEK)", "JWE Compact Encryption (JWE)", "Content Encryption Key (CEK)", "JWE Compact
Serialization", "JWE Encrypted Key", "JWE Initialization Vector", Serialization", "JWE Encrypted Key", "JWE Initialization Vector",
"JWE Plaintext". "JWE Plaintext".
These terms are defined by this specification: These terms are defined by this specification:
JSON Web Token (JWT) JSON Web Token (JWT)
skipping to change at page 5, line 29 skipping to change at page 5, line 29
any JSON value. any JSON value.
Encoded JOSE Header Encoded JOSE Header
Base64url encoding of the JOSE Header. Base64url encoding of the JOSE Header.
Nested JWT Nested JWT
A JWT in which nested signing and/or encryption are employed. In A JWT in which nested signing and/or encryption are employed. In
nested JWTs, a JWT is used as the payload or plaintext value of an nested JWTs, a JWT is used as the payload or plaintext value of an
enclosing JWS or JWE structure, respectively. enclosing JWS or JWE structure, respectively.
Plaintext JWT Unsecured JWT
A JWT whose Claims are not integrity protected or encrypted. A JWT whose Claims are not integrity protected or encrypted.
Collision-Resistant Name Collision-Resistant Name
A name in a namespace that enables names to be allocated in a A name in a namespace that enables names to be allocated in a
manner such that they are highly unlikely to collide with other manner such that they are highly unlikely to collide with other
names. Examples of collision-resistant namespaces include: Domain names. Examples of collision-resistant namespaces include: Domain
Names, Object Identifiers (OIDs) as defined in the ITU-T X.660 and Names, Object Identifiers (OIDs) as defined in the ITU-T X.660 and
X.670 Recommendation series, and Universally Unique IDentifiers X.670 Recommendation series, and Universally Unique IDentifiers
(UUIDs) [RFC4122]. When using an administratively delegated (UUIDs) [RFC4122]. When using an administratively delegated
namespace, the definer of a name needs to take reasonable namespace, the definer of a name needs to take reasonable
precautions to ensure they are in control of the portion of the precautions to ensure they are in control of the portion of the
namespace they use to define the name. namespace they use to define the name.
StringOrURI StringOrURI
A JSON string value, with the additional requirement that while A JSON string value, with the additional requirement that while
arbitrary string values MAY be used, any value containing a ":" arbitrary string values MAY be used, any value containing a ":"
character MUST be a URI [RFC3986]. StringOrURI values are character MUST be a URI [RFC3986]. StringOrURI values are
compared as case-sensitive strings with no transformations or compared as case-sensitive strings with no transformations or
canonicalizations applied. canonicalizations applied.
IntDate NumericDate
A JSON numeric value representing the number of seconds from 1970- A JSON numeric value representing the number of seconds from 1970-
01-01T0:0:0Z UTC until the specified UTC date/time. See RFC 3339 01-01T00:00:00Z UTC until the specified UTC date/time, ignoring
leap seconds. This is equivalent to the IEEE Std 1003.1, 2013
Edition [POSIX.1] definition "Seconds Since the Epoch", in which
each day is accounted for by exactly 86400 seconds, other than
that non-integer values can be represented. See RFC 3339
[RFC3339] for details regarding date/times in general and UTC in [RFC3339] for details regarding date/times in general and UTC in
particular. 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 encoded in a JWTs represent a set of claims as a JSON object that is encoded in a
JWS and/or JWE structure. This JSON object is the JWT Claims Set. As JWS and/or JWE structure. This JSON object is the JWT Claims Set. As
per Section 4 of RFC 7159 [RFC7159], the JSON object consists of zero per Section 4 of RFC 7159 [RFC7159], the JSON object consists of zero
or more name/value pairs (or members), where the names are strings or more name/value pairs (or members), where the names are strings
and the values are arbitrary JSON values. These members are the and the values are arbitrary JSON values. These members are the
claims represented by the JWT. claims represented by the JWT. This JSON object MAY contain white
space and/or line breaks.
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 contents of the JOSE Header describe the cryptographic operations The contents of the JOSE Header describe the cryptographic operations
applied to the JWT Claims Set. If the JOSE Header is for a JWS applied to the JWT Claims Set. If the JOSE Header is for a JWS
object, the JWT is represented as a JWS, and the claims are digitally object, the JWT is represented as a JWS, and the claims are digitally
signed or MACed, with the JWT Claims Set being the JWS Payload. If signed or MACed, with the JWT Claims Set being the JWS Payload. If
the JOSE Header is for a JWE object, the JWT is represented as a JWE, the JOSE Header is for a JWE object, the JWT is represented as a JWE,
and the claims are encrypted, with the JWT Claims Set being the JWE and the claims are encrypted, with the JWT Claims Set being the JWE
skipping to change at page 9, line 37 skipping to change at page 9, line 44
Use of this claim is OPTIONAL. Use of this claim is OPTIONAL.
4.1.4. "exp" (Expiration Time) Claim 4.1.4. "exp" (Expiration Time) Claim
The "exp" (expiration time) claim identifies the expiration time on The "exp" (expiration time) claim identifies the expiration time on
or after which the JWT MUST NOT be accepted for processing. The or after which the JWT MUST NOT be accepted for processing. The
processing of the "exp" claim requires that the current date/time processing of the "exp" claim requires that the current date/time
MUST be before the expiration date/time listed in the "exp" claim. MUST be before the expiration date/time listed in the "exp" claim.
Implementers MAY provide for some small leeway, usually no more than 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 a few minutes, to account for clock skew. Its value MUST be a number
containing an IntDate value. Use of this claim is OPTIONAL. containing a NumericDate value. Use of this claim is OPTIONAL.
4.1.5. "nbf" (Not Before) Claim 4.1.5. "nbf" (Not Before) Claim
The "nbf" (not before) claim identifies the time before which the JWT The "nbf" (not before) claim identifies the time before which the JWT
MUST NOT be accepted for processing. The processing of the "nbf" MUST NOT be accepted for processing. The processing of the "nbf"
claim requires that the current date/time MUST be after or equal to claim requires that the current date/time MUST be after or equal to
the not-before date/time listed in the "nbf" claim. Implementers MAY the not-before date/time listed in the "nbf" claim. Implementers MAY
provide for some small leeway, usually no more than a few minutes, to 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 account for clock skew. Its value MUST be a number containing a
IntDate value. Use of this claim is OPTIONAL. NumericDate value. Use of this claim is OPTIONAL.
4.1.6. "iat" (Issued At) Claim 4.1.6. "iat" (Issued At) Claim
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 JWT. Its issued. This claim can be used to determine the age of the JWT. Its
value MUST be a number containing an IntDate value. Use of this value MUST be a number containing a NumericDate value. Use of 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. Use of this claim is OPTIONAL. is a case-sensitive string. Use of this claim is OPTIONAL.
skipping to change at page 11, line 23 skipping to change at page 11, line 30
it is RECOMMENDED that "JWT" always be spelled using uppercase it is RECOMMENDED that "JWT" always be spelled using uppercase
characters for compatibility with legacy implementations. Use of characters for compatibility with legacy implementations. Use of
this 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 defined by [JWS] and [JWE] The "cty" (content type) Header Parameter defined by [JWS] and [JWE]
is used by this specification to convey structural information about is used by this specification to convey structural information about
the JWT. the JWT.
In the normal case where nested signing or encryption operations are In the normal case in which nested signing or encryption operations
not employed, the use of this Header Parameter is NOT RECOMMENDED. are not employed, the use of this Header Parameter is NOT
In the case that nested signing or encryption is employed, this RECOMMENDED. In the case that nested signing or encryption is
Header Parameter MUST be present; in this case, the value MUST be employed, this Header Parameter MUST be present; in this case, the
"JWT", to indicate that a Nested JWT is carried in this JWT. While value MUST be "JWT", to indicate that a Nested JWT is carried in this
media type names are not case-sensitive, it is RECOMMENDED that "JWT" JWT. While media type names are not case-sensitive, it is
always be spelled using uppercase characters for compatibility with RECOMMENDED that "JWT" always be spelled using uppercase characters
legacy implementations. See Appendix A.2 for an example of a Nested for compatibility with legacy implementations. See Appendix A.2 for
JWT. an example of a Nested JWT.
5.3. Replicating Claims as Header Parameters 5.3. Replicating Claims as Header Parameters
In some applications using encrypted JWTs, it is useful to have an In some applications using encrypted JWTs, it is useful to have an
unencrypted representation of some Claims. This might be used, for unencrypted representation of some Claims. This might be used, for
instance, in application processing rules to determine whether and instance, in application processing rules to determine whether and
how to process the JWT before it is decrypted. how to process the JWT before it is decrypted.
This specification allows Claims present in the JWT Claims Set to be 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 replicated as Header Parameters in a JWT that is a JWE, as needed by
skipping to change at page 12, line 9 skipping to change at page 12, line 16
unencrypted manner are replicated as Header Parameter values in the unencrypted manner are replicated as Header Parameter values in the
JWT. JWT.
Section 10.4.1 of this specification registers the "iss" (issuer), Section 10.4.1 of this specification registers the "iss" (issuer),
"sub" (subject), and "aud" (audience) Header Parameter names for the "sub" (subject), and "aud" (audience) Header Parameter names for the
purpose of providing unencrypted replicas of these Claims in purpose of providing unencrypted replicas of these Claims in
encrypted JWTs for applications that need them. Other specifications encrypted JWTs for applications that need them. Other specifications
MAY similarly register other names that are registered Claim Names as MAY similarly register other names that are registered Claim Names as
Header Parameter names, as needed. Header Parameter names, as needed.
6. Plaintext JWTs 6. Unsecured JWTs
To support use cases where the JWT content is secured by a means To support use cases in which 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. An Unsecured
JWT is a JWS using the "alg" Header Parameter value "none" and with JWT is a JWS using the "alg" Header Parameter value "none" and with
the empty string for its JWS Signature value, as defined in JSON Web the empty string for its JWS Signature value, as defined in JSON Web
Algorithms (JWA) [JWA]; it is a Plaintext JWS with the JWT Claims Set Algorithms (JWA) [JWA]; it is an Unsecured JWS with the JWT Claims
as its JWS Payload. Set as its JWS Payload.
6.1. Example Plaintext JWT 6.1. Example Unsecured JWT
The following example JOSE Header declares that the encoded object is The following example JOSE Header declares that the encoded object is
a Plaintext JWT: an Unsecured JWT:
{"alg":"none"} {"alg":"none"}
Base64url encoding the octets of the UTF-8 representation of the JOSE Base64url encoding the octets of the UTF-8 representation of the JOSE
Header yields this Encoded JOSE Header: Header yields this Encoded JOSE Header:
eyJhbGciOiJub25lIn0 eyJhbGciOiJub25lIn0
The following is an example of a JWT Claims Set: The following is an example of a JWT Claims Set:
skipping to change at page 13, line 51 skipping to change at page 14, line 10
5. If a nested signing or encryption operation will be performed, 5. 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 JOSE Header "cty" (content type) value of "JWT" in the new JOSE Header
created in that step. created in that step.
6. Otherwise, let the resulting JWT be the JWS or JWE. 6. 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 JWT MUST be rejected for processing. the listed steps fails then the JWT MUST be rejected -- treated by
the application as an invalid input.
1. The JWT MUST contain at least one period ('.') character. 1. The JWT MUST contain at least one period ('.') character.
2. Let the Encoded JOSE Header be the portion of the JWT before the 2. Let the Encoded JOSE Header be the portion of the JWT before the
first period ('.') character. first period ('.') character.
3. The Encoded JOSE Header MUST be successfully base64url decoded 3. The Encoded JOSE 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 15, line 14 skipping to change at page 15, line 22
Comparisons between JSON strings and other Unicode strings MUST be Comparisons between JSON strings and other Unicode strings MUST be
performed by comparing Unicode code points without normalization, as performed by comparing Unicode code points without normalization, as
specified in the String Comparison Rules in Section 5.3 of [JWS]. specified in the String Comparison Rules in Section 5.3 of [JWS].
8. Implementation Requirements 8. Implementation Requirements
This section defines which algorithms and features of this This section defines which algorithms and features of this
specification are mandatory to implement. Applications using this specification are mandatory to implement. Applications using this
specification can impose additional requirements upon implementations specification can impose additional requirements upon implementations
that they use. For instance, an application might require support that they use. For instance, one application might require support
for encrypted JWTs and Nested JWTs; another might require support for for encrypted JWTs and Nested JWTs, while another might require
signing JWTs with ECDSA using the P-256 curve and the SHA-256 hash support for signing JWTs with ECDSA using the P-256 curve and the
algorithm ("ES256"). SHA-256 hash algorithm ("ES256").
Of the signature and MAC algorithms specified in JSON Web Algorithms Of the signature and MAC algorithms specified in JSON Web Algorithms
(JWA) [JWA], only HMAC SHA-256 ("HS256") and "none" MUST be (JWA) [JWA], only HMAC SHA-256 ("HS256") and "none" MUST be
implemented by conforming JWT implementations. It is RECOMMENDED implemented by conforming JWT implementations. It is RECOMMENDED
that implementations also support RSASSA-PKCS1-V1_5 with the SHA-256 that implementations also support RSASSA-PKCS1-V1_5 with the SHA-256
hash algorithm ("RS256") and ECDSA using the P-256 curve and the SHA- hash algorithm ("RS256") and ECDSA using the P-256 curve and the SHA-
256 hash algorithm ("ES256"). Support for other algorithms and key 256 hash algorithm ("ES256"). Support for other algorithms and key
sizes is OPTIONAL. sizes is OPTIONAL.
Support for encrypted JWTs is OPTIONAL. If an implementation Support for encrypted JWTs is OPTIONAL. If an implementation
skipping to change at page 20, line 4 skipping to change at page 20, line 12
o Header Parameter Description: Audience o Header Parameter Description: Audience
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 4.1.3 of [[ this document ]] o Specification Document(s): Section 4.1.3 of [[ this document ]]
11. Security Considerations 11. Security Considerations
All of the security issues that are pertinent to any cryptographic All of the security issues that are pertinent to any cryptographic
application must be addressed by JWT/JWS/JWE/JWK agents. Among these application must be addressed by JWT/JWS/JWE/JWK agents. Among these
issues are protecting the user's asymmetric private and symmetric issues are protecting the user's asymmetric private and symmetric
secret keys, preventing various attacks, and helping avoid mistakes secret keys and employing countermeasures to various attacks.
such as inadvertently encrypting a message to the wrong recipient.
The entire list of security considerations is beyond the scope of
this document, but some significant considerations 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 JOSE Header. Claims Set in the same manner that they do to the JOSE Header.
11.1. Trust Decisions 11.1. Trust Decisions
The contents of a JWT cannot be relied upon in a trust decision The contents of a JWT cannot be relied upon in a trust decision
unless its contents have been cryptographically secured and bound to unless its contents have been cryptographically secured and bound to
the context necessary for the trust decision. In particular, the the context necessary for the trust decision. In particular, the
key(s) used to sign and/or encrypt the JWT will typically need to key(s) used to sign and/or encrypt the JWT will typically need to
verifiably be under the control of the party identified as the issuer verifiably be under the control of the party identified as the issuer
of the JWT. of the JWT.
11.2. Signing and Encryption Order 11.2. Signing and Encryption Order
While syntactically, the signing and encryption operations for Nested While syntactically the signing and encryption operations for Nested
JWTs may be applied in any order, normally senders should sign the JWTs may be applied in any order, normally senders should sign the
message and then encrypt the result (thus encrypting the signature). message and then encrypt the result (thus encrypting the signature).
This prevents attacks in which the signature is stripped, leaving This prevents attacks in which the signature is stripped, leaving
just an encrypted message, as well as providing privacy for the just an encrypted message, as well as providing privacy for the
signer. Furthermore, signatures over encrypted text are not signer. Furthermore, signatures over encrypted text are not
considered valid in many jurisdictions. considered valid in many jurisdictions.
Note that potential concerns about security issues related to the Note that potential concerns about security issues related to the
order of signing and encryption operations are already addressed by order of signing and encryption operations are already addressed by
the underlying JWS and JWE specifications; in particular, because JWE the underlying JWS and JWE specifications; in particular, because JWE
skipping to change at page 21, line 19 skipping to change at page 21, line 24
[ECMAScript] [ECMAScript]
Ecma International, "ECMAScript Language Specification, Ecma International, "ECMAScript Language Specification,
5.1 Edition", ECMA 262, June 2011. 5.1 Edition", ECMA 262, June 2011.
[IANA.MediaTypes] [IANA.MediaTypes]
Internet Assigned Numbers Authority (IANA), "MIME Media Internet Assigned Numbers Authority (IANA), "MIME Media
Types", 2005. Types", 2005.
[JWA] Jones, M., "JSON Web Algorithms (JWA)", [JWA] Jones, M., "JSON Web Algorithms (JWA)",
draft-ietf-jose-json-web-algorithms (work in progress), draft-ietf-jose-json-web-algorithms (work in progress),
July 2014. September 2014.
[JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", [JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
draft-ietf-jose-json-web-encryption (work in progress), draft-ietf-jose-json-web-encryption (work in progress),
July 2014. September 2014.
[JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", draft-ietf-jose-json-web-signature (work Signature (JWS)", draft-ietf-jose-json-web-signature (work
in progress), July 2014. in progress), September 2014.
[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.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
skipping to change at page 22, line 18 skipping to change at page 22, line 26
[MagicSignatures] [MagicSignatures]
Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic
Signatures", January 2011. Signatures", January 2011.
[OASIS.saml-core-2.0-os] [OASIS.saml-core-2.0-os]
Cantor, S., Kemp, J., Philpott, R., and E. Maler, Cantor, S., Kemp, J., Philpott, R., and E. Maler,
"Assertions and Protocol for the OASIS Security Assertion "Assertions and Protocol for the OASIS Security Assertion
Markup Language (SAML) V2.0", OASIS Standard saml-core- Markup Language (SAML) V2.0", OASIS Standard saml-core-
2.0-os, March 2005. 2.0-os, March 2005.
[POSIX.1] Institute of Electrical and Electronics Engineers, "The
Open Group Base Specifications Issue 7", IEEE Std 1003.1,
2013 Edition, 2013.
[RFC3275] Eastlake, D., Reagle, J., and D. Solo, "(Extensible Markup [RFC3275] Eastlake, D., Reagle, J., and D. Solo, "(Extensible Markup
Language) XML-Signature Syntax and Processing", RFC 3275, Language) XML-Signature Syntax and Processing", RFC 3275,
March 2002. March 2002.
[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.
[RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally
Unique IDentifier (UUID) URN Namespace", RFC 4122, Unique IDentifier (UUID) URN Namespace", RFC 4122,
July 2005. July 2005.
skipping to change at page 27, line 4 skipping to change at page 27, line 8
Eric Rescorla, Jim Schaad, Paul Tarjan, Hannes Tschofenig, and Sean Eric Rescorla, Jim Schaad, Paul Tarjan, Hannes Tschofenig, and Sean
Turner. Turner.
Hannes Tschofenig and Derek Atkins chaired the OAuth working group Hannes Tschofenig and Derek Atkins chaired the OAuth working group
and Sean Turner, Stephen Farrell, and Kathleen Moriarty served as and Sean Turner, Stephen Farrell, and Kathleen Moriarty served as
Security area directors during the creation of this specification. Security area directors 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 ]]
-26
o Removed an ambiguity in numeric date representations by specifying
that leap seconds are handled in the manner specified by POSIX.1.
o Addressed Gen-ART review comments by Russ Housley.
o Addressed secdir review comments by Warren Kumari and Stephen
Kent.
o Replaced the terms Plaintext JWS and Plaintext JWT with Unsecured
JWS and Unsecured JWT.
-25 -25
o Reworded the language about JWT implementations ignoring the "typ" o Reworded the language about JWT implementations ignoring the "typ"
parameter, explicitly saying that its processing is performed by parameter, explicitly saying that its processing is performed by
JWT applications. JWT applications.
o Added a Privacy Considerations section. o Added a Privacy Considerations section.
-24 -24
 End of changes. 39 change blocks. 
55 lines changed or deleted 76 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/