draft-ietf-oauth-json-web-token-11.txt   draft-ietf-oauth-json-web-token-12.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 30, 2014 Ping Identity Expires: April 10, 2014 Ping Identity
N. Sakimura N. Sakimura
NRI NRI
July 29, 2013 October 7, 2013
JSON Web Token (JWT) JSON Web Token (JWT)
draft-ietf-oauth-json-web-token-11 draft-ietf-oauth-json-web-token-12
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 30, 2014. This Internet-Draft will expire on April 10, 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
skipping to change at page 2, line 19 skipping to change at page 2, line 19
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 . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 7 4. JWT Claims . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4.1. Reserved Claim Names . . . . . . . . . . . . . . . . . . . 8 4.1. Registered Claim Names . . . . . . . . . . . . . . . . . . 8
4.1.1. "iss" (Issuer) Claim . . . . . . . . . . . . . . . . . 8 4.1.1. "iss" (Issuer) Claim . . . . . . . . . . . . . . . . . 8
4.1.2. "sub" (Subject) Claim . . . . . . . . . . . . . . . . 8 4.1.2. "sub" (Subject) Claim . . . . . . . . . . . . . . . . 8
4.1.3. "aud" (Audience) Claim . . . . . . . . . . . . . . . . 8 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 . . . . . . . . . . . . . . . 9
4.1.7. "jti" (JWT ID) Claim . . . . . . . . . . . . . . . . . 9 4.1.7. "jti" (JWT ID) Claim . . . . . . . . . . . . . . . . . 9
4.1.8. "typ" (Type) Claim . . . . . . . . . . . . . . . . . . 9
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. JWT Header . . . . . . . . . . . . . . . . . . . . . . . . . . 10 5. JWT Header . . . . . . . . . . . . . . . . . . . . . . . . . . 10
5.1. "typ" (Type) Header Parameter . . . . . . . . . . . . . . 10 5.1. "typ" (Type) Header Parameter . . . . . . . . . . . . . . 10
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 . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . 12 7. Rules for Creating and Validating a JWT . . . . . . . . . . . 12
7.1. String Comparison Rules . . . . . . . . . . . . . . . . . 14 7.1. String Comparison Rules . . . . . . . . . . . . . . . . . 14
8. Cryptographic Algorithms . . . . . . . . . . . . . . . . . . . 14 8. Cryptographic Algorithms . . . . . . . . . . . . . . . . . . . 14
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 9. URI for Declaring that Content is a JWT . . . . . . . . . . . 15
9.1. JSON Web Token Claims Registry . . . . . . . . . . . . . . 15 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15
9.1.1. Registration Template . . . . . . . . . . . . . . . . 16 10.1. JSON Web Token Claims Registry . . . . . . . . . . . . . . 15
9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 16 10.1.1. Registration Template . . . . . . . . . . . . . . . . 16
9.2. Sub-Namespace Registration of 10.1.2. Initial Registry Contents . . . . . . . . . . . . . . 17
10.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 10.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 17
9.3. JSON Web Signature and Encryption Type Values 10.3. Media Type Registration . . . . . . . . . . . . . . . . . 18
Registration . . . . . . . . . . . . . . . . . . . . . . . 17 10.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 18
9.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 17 10.4. Registration of JWE Header Parameter Names . . . . . . . . 18
9.4. Media Type Registration . . . . . . . . . . . . . . . . . 17 10.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 18
9.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 17
9.5. Registration of JWE Header Parameter Names . . . . . . . . 18 11. Security Considerations . . . . . . . . . . . . . . . . . . . 19
9.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 18 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 20
10. Security Considerations . . . . . . . . . . . . . . . . . . . 19 12.1. Normative References . . . . . . . . . . . . . . . . . . . 20
11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19 12.2. Informative References . . . . . . . . . . . . . . . . . . 21
11.1. Normative References . . . . . . . . . . . . . . . . . . . 19 Appendix A. JWT Examples . . . . . . . . . . . . . . . . . . . . 22
11.2. Informative References . . . . . . . . . . . . . . . . . . 20 A.1. Example Encrypted JWT . . . . . . . . . . . . . . . . . . 22
Appendix A. JWT Examples . . . . . . . . . . . . . . . . . . . . 21
A.1. Example Encrypted JWT . . . . . . . . . . . . . . . . . . 21
A.2. Example Nested JWT . . . . . . . . . . . . . . . . . . . . 22 A.2. Example Nested JWT . . . . . . . . . . . . . . . . . . . . 22
Appendix B. Relationship of JWTs to SAML Assertions . . . . . . . 24 Appendix B. Relationship of JWTs to SAML Assertions . . . . . . . 24
Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs) . . 25 Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs) . . 25
Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 25 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 25
Appendix E. Document History . . . . . . . . . . . . . . . . . . 25 Appendix E. Document History . . . . . . . . . . . . . . . . . . 25
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 28 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 29
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]
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)
[JWE] structure, enabling the claims to be digitally signed or MACed [JWE] structure, enabling the claims to be digitally signed or MACed
skipping to change at page 4, line 25 skipping to change at page 4, line 25
Serialization or the JWE Compact Serialization. Serialization or the JWE Compact Serialization.
The suggested pronunciation of JWT is the same as the English word The suggested pronunciation of JWT is the same as the English word
"jot". "jot".
1.1. Notational Conventions 1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in Key words for use in document are to be interpreted as described in Key words for use in
RFCs to Indicate Requirement Levels [RFC2119]. RFCs to Indicate Requirement Levels [RFC2119]. If these words are
used without being spelled in uppercase then they are to be
interpreted with their normal natural language meanings.
2. Terminology 2. Terminology
JSON Web Token (JWT) A string representing a set of claims as a JSON JSON Web Token (JWT) A string representing a set of claims as a JSON
object that is encoded in a JWS or JWE, enabling the claims to be object that is encoded in a JWS or JWE, enabling the claims to be
digitally signed or MACed and/or encrypted. digitally signed or MACed and/or encrypted.
Base64url Encoding The URL- and filename-safe Base64 encoding Base64url Encoding Base64 encoding using the URL- and filename-safe
described in RFC 4648 [RFC4648], Section 5, with the (non URL- character set defined in Section 5 of RFC 4648 [RFC4648], with all
safe) '=' padding characters omitted, as permitted by Section 3.2. trailing '=' characters omitted (as permitted by Section 3.2).
(See Appendix C of [JWS] for notes on implementing base64url (See Appendix C of [JWS] for notes on implementing base64url
encoding without padding.) encoding without padding.)
JSON Text Object A UTF-8 [RFC3629] encoded text string representing JSON Text Object A UTF-8 [RFC3629] encoded text string representing
a JSON object; the syntax of JSON objects is defined in Section a JSON object; the syntax of JSON objects is defined in Section
2.2 of [RFC4627]. 2.2 of [RFC4627].
JWT Header A JSON Text Object that describes the cryptographic JWT Header A JSON Text Object that describes the cryptographic
operations applied to the JWT. When the JWT is digitally signed operations applied to the JWT. When the JWT is digitally signed
or MACed, the JWT Header is a JWS Header. When the JWT is or MACed, the JWT Header is a JWS Header. When the JWT is
encrypted, the JWT Header is a JWE Header. encrypted, the JWT Header is a JWE Header.
Header Parameter A name/value pair that is member of the JWT Header.
Header Parameter Name The name of a member of the JWT Header. Header Parameter Name The name of a member of the JWT Header.
Header Parameter Value The value of a member of the JWT Header. Header Parameter Value The value of a member of the JWT Header.
JWT Claims Set A JSON Text Object that contains the Claims conveyed JWT Claims Set A JSON Text Object that contains the Claims conveyed
by the JWT. by the JWT.
Claim A piece of information asserted about a subject. A Claim is Claim A piece of information asserted about a subject. A Claim is
represented as a name/value pair consisting of a Claim Name and a represented as a name/value pair consisting of a Claim Name and a
Claim Value. Claim Value.
skipping to change at page 5, line 30 skipping to change at page 5, line 34
Encoded JWT Header Base64url encoding of the JWT Header. Encoded JWT Header Base64url encoding of the JWT Header.
Nested JWT A JWT in which nested signing and/or encryption are Nested JWT A JWT in which nested signing and/or encryption are
employed. In nested JWTs, a JWT is used as the payload or employed. In nested JWTs, a JWT is used as the payload or
plaintext value of an enclosing JWS or JWE structure, plaintext value of an enclosing JWS or JWE structure,
respectively. respectively.
Plaintext JWT A JWT whose Claims are not integrity protected or Plaintext JWT A JWT whose Claims are not integrity protected or
encrypted. encrypted.
Collision Resistant Namespace A namespace that allows names to be Collision Resistant Name A name in a namespace that enables names to
allocated in a manner such that they are highly unlikely to be allocated in a manner such that they are highly unlikely to
collide with other names. For instance, collision resistance can collide with other names. Examples of collision resistant
be achieved through administrative delegation of portions of the namespaces include: Domain Names, Object Identifiers (OIDs) as
namespace or through use of collision-resistant name allocation defined in the ITU-T X.660 and X.670 Recommendation series, and
functions. Examples of Collision Resistant Namespaces include: Universally Unique IDentifiers (UUIDs) [RFC4122]. When using an
Domain Names, Object Identifiers (OIDs) as defined in the ITU-T administratively delegated namespace, the definer of a name needs
X.660 and X.670 Recommendation series, and Universally Unique to take reasonable precautions to ensure they are in control of
IDentifiers (UUIDs) [RFC4122]. When using an administratively the portion of the namespace they use to define the name.
delegated namespace, the definer of a name needs to take
reasonable precautions to ensure they are in control of the
portion of the namespace they use to define the name.
StringOrURI A JSON string value, with the additional requirement StringOrURI A JSON string value, with the additional requirement
that while arbitrary string values MAY be used, any value that while arbitrary string values MAY be used, any value
containing a ":" character MUST be a URI [RFC3986]. StringOrURI containing a ":" character MUST be a URI [RFC3986]. StringOrURI
values are compared as case-sensitive strings with no values are compared as case-sensitive strings with no
transformations or canonicalizations applied. transformations or canonicalizations applied.
IntDate A JSON numeric value representing the number of seconds from IntDate A JSON numeric value representing the number of seconds from
1970-01-01T0:0:0Z UTC until the specified UTC date/time. See RFC 1970-01-01T0:0:0Z UTC until the specified UTC date/time. See RFC
3339 [RFC3339] for details regarding date/times in general and UTC 3339 [RFC3339] for details regarding date/times in general and UTC
skipping to change at page 6, line 36 skipping to change at page 6, line 41
A JWT is represented as a sequence of URL-safe parts separated by A JWT is represented as a sequence of URL-safe parts separated by
period ('.') characters. Each part contains a base64url encoded period ('.') characters. Each part contains a base64url encoded
value. The number of parts in the JWT is dependent upon the value. The number of parts in the JWT is dependent upon the
representation of the resulting JWS or JWE object using the JWS representation of the resulting JWS or JWE object using the JWS
Compact Serialization or the JWE Compact Serialization. Compact Serialization or the JWE Compact Serialization.
3.1. Example JWT 3.1. Example JWT
The following example JWT Header declares that the encoded object is The following example JWT Header declares that the encoded object is
a JSON Web Token (JWT) and the JWT is MACed using the HMAC SHA-256 a JSON Web Token (JWT) and the JWT is a JWS that is MACed using the
algorithm: HMAC SHA-256 algorithm:
{"typ":"JWT", {"typ":"JWT",
"alg":"HS256"} "alg":"HS256"}
The following octet sequence is the UTF-8 representation of the JWT
Header/JWS Header above:
[123, 34, 116, 121, 112, 34, 58, 34, 74, 87, 84, 34, 44, 13, 10, 32,
34, 97, 108, 103, 34, 58, 34, 72, 83, 50, 53, 54, 34, 125]
Base64url encoding the octets of the UTF-8 representation of the JWT Base64url encoding the octets of the UTF-8 representation of the JWT
Header yields this Encoded JWS Header value, which is used as the Header yields this Encoded JWT Header value (which is also the
Encoded JWT Header: underlying encoded JWS Header value):
eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
The following is an example of a JWT Claims Set: The following is an example of a JWT Claims Set:
{"iss":"joe", {"iss":"joe",
"exp":1300819380, "exp":1300819380,
"http://example.com/is_root":true} "http://example.com/is_root":true}
The following octet sequence, which is the UTF-8 representation of The following octet sequence, which is the UTF-8 representation of
the JWT Claims Set above, is the JWS Payload: the JWT Claims Set above, is the JWS Payload:
[123, 34, 105, 115, 115, 34, 58, 34, 106, 111, 101, 34, 44, 13, 10, [123, 34, 105, 115, 115, 34, 58, 34, 106, 111, 101, 34, 44, 13, 10,
32, 34, 101, 120, 112, 34, 58, 49, 51, 48, 48, 56, 49, 57, 51, 56, 32, 34, 101, 120, 112, 34, 58, 49, 51, 48, 48, 56, 49, 57, 51, 56,
48, 44, 13, 10, 32, 34, 104, 116, 116, 112, 58, 47, 47, 101, 120, 97, 48, 44, 13, 10, 32, 34, 104, 116, 116, 112, 58, 47, 47, 101, 120, 97,
109, 112, 108, 101, 46, 99, 111, 109, 47, 105, 115, 95, 114, 111, 109, 112, 108, 101, 46, 99, 111, 109, 47, 105, 115, 95, 114, 111,
111, 116, 34, 58, 116, 114, 117, 101, 125] 111, 116, 34, 58, 116, 114, 117, 101, 125]
Base64url encoding the JWS Payload yields this Encoded JWS Payload Base64url encoding the JWS Payload yields this encoded JWS Payload
(with line breaks for display purposes only): (with line breaks for display purposes only):
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly
9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ 9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ
Signing the Encoded JWS Header and Encoded JWS Payload with the HMAC MACing the encoded JWS Header and encoded JWS Payload with the HMAC
SHA-256 algorithm and base64url encoding the signature in the manner SHA-256 algorithm and base64url encoding the HMAC value in the manner
specified in [JWS], yields this Encoded JWS Signature: specified in [JWS], yields this encoded JWS Signature:
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
Concatenating these parts in this order with period ('.') characters Concatenating these encoded parts in this order with period ('.')
between the parts yields this complete JWT (with line breaks for characters between the parts yields this complete JWT (with line
display purposes only): breaks for display purposes only):
eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
. .
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
. .
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
This computation is illustrated in more detail in Appendix A.1 of This computation is illustrated in more detail in Appendix A.1 of
[JWS]. See Appendix A.1 for an example of an encrypted JWT. [JWS]. See Appendix A.1 for an example of an encrypted JWT.
skipping to change at page 8, line 8 skipping to change at page 8, line 21
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.
There are three classes of JWT Claim Names: Reserved Claim Names, There are three classes of JWT Claim Names: Registered Claim Names,
Public Claim Names, and Private Claim Names. Public Claim Names, and Private Claim Names.
4.1. Reserved Claim Names 4.1. Registered Claim Names
The following Claim Names are reserved. None of the claims defined The following Claim Names are registered in the IANA JSON Web Token
Claims registry defined in Section 10.1. None of the claims defined
below are intended to be mandatory to use, but rather, provide a below are intended to be mandatory to use, but rather, provide a
starting point for a set of useful, interoperable claims. All the starting point for a set of useful, interoperable claims. All the
names are short because a core goal of JWTs is for the representation names are short because a core goal of JWTs is for the representation
to be compact. Additional reserved Claim Names can be defined via to be compact.
the IANA JSON Web Token Claims registry Section 9.1.
4.1.1. "iss" (Issuer) Claim 4.1.1. "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 a case sensitive string containing a StringOrURI The "iss" value is a case sensitive string containing a StringOrURI
value. Use of this claim is OPTIONAL. value. Use of this claim is OPTIONAL.
4.1.2. "sub" (Subject) Claim 4.1.2. "sub" (Subject) Claim
The "sub" (subject) claim identifies the principal that is the The "sub" (subject) claim identifies the principal that is the
subject of the JWT. The Claims in a JWT are normally statements subject of the JWT. The Claims in a JWT are normally statements
about the subject. The processing of this claim is generally about the subject. The subject value MAY be scoped to be locally
application specific. The "sub" value is a case sensitive string unique in the context of the issuer or MAY be globally unique. The
containing a StringOrURI value. Use of this claim is OPTIONAL. processing of this claim is generally application specific. The
"sub" value is a case sensitive string containing a StringOrURI
value. Use of this claim is OPTIONAL.
4.1.3. "aud" (Audience) Claim 4.1.3. "aud" (Audience) Claim
The "aud" (audience) claim identifies the audiences that the JWT is The "aud" (audience) claim identifies the audiences that the JWT is
intended for. Each principal intended to process the JWT MUST intended for. Each principal intended to process the JWT MUST
identify itself with a value in audience claim. If the principal identify itself with a value in audience claim. If the principal
processing the claim does not identify itself with a value in the processing the claim does not identify itself with a value in the
"aud" claim, then the JWT MUST be rejected. In the general case, the "aud" claim, then the JWT MUST be rejected. In the general case, the
"aud" value is an array of case sensitive strings, each containing a "aud" value is an array of case sensitive strings, each containing a
StringOrURI value. In the special case when the JWT has one StringOrURI value. In the special case when the JWT has one
skipping to change at page 9, line 41 skipping to change at page 10, line 6
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.
4.1.8. "typ" (Type) Claim
The "typ" (type) claim MAY be used to declare a type for the contents
of this JWT Claims Set in an application-specific manner in contexts
where this is useful to the application. The "typ" value is a case
sensitive string. Use of this claim is OPTIONAL.
The values used for the "typ" claim come from the same value space as
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 defined in
be a Public Name: a value that contains a Collision Resistant Section 10.1 or be a Public Name: a value that contains a Collision
Namespace. In each case, the definer of the name or value needs to Resistant Name. In each case, the definer of the name or value needs
take reasonable precautions to make sure they are in control of the to take reasonable precautions to make sure they are in control of
part of the namespace they use to define the Claim Name. the part of the namespace they use to define the Claim Name.
4.3. Private Claim Names 4.3. Private Claim Names
A producer and consumer of a JWT MAY agree to use Claim Names that A producer and consumer of a JWT MAY agree to use Claim Names that
are Private Names: names that are not Reserved Names Section 4.1 or are Private Names: names that are not Registered Claim Names
Public Names Section 4.2. Unlike Public Names, Private Names are Section 4.1 or Public Claim Names Section 4.2. Unlike Public Claim
subject to collision and should be used with caution. Names, Private Claim Names are 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; recipients 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.
5.1. "typ" (Type) Header Parameter 5.1. "typ" (Type) Header Parameter
The "typ" (type) header parameter MAY be used to declare the type of The "typ" (type) Header Parameter defined by [JWS] and [JWE] is used
this JWT in an application-specific manner in contexts where this is to declare the MIME Media Type [IANA.MediaTypes] of this complete JWT
useful to the application. This parameter has no effect upon the JWT in contexts where this is useful to the application. This parameter
processing. If present, it is RECOMMENDED that its value be either has no effect upon the JWT processing. If present, it is RECOMMENDED
"JWT" or "urn:ietf:params:oauth:token-type:jwt" to indicate that this that its value be "JWT" to indicate that this object is a JWT. While
object is a JWT. The "typ" value is a case sensitive string. Use of media type names are not case sensitive, it is RECOMMENDED that "JWT"
this header parameter is OPTIONAL. always be spelled using uppercase characters for compatibility with
legacy implementations. Use of this Header Parameter is OPTIONAL.
5.2. "cty" (Content Type) Header Parameter 5.2. "cty" (Content Type) Header Parameter
The "cty" (content type) header parameter is used to declare The "cty" (content type) Header Parameter defined by [JWS] and [JWE]
structural information about the JWT. Its value MUST be a string. is used by this specification to convey structural information about
the JWT.
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. See "JWT", to indicate that a Nested JWT is carried in this JWT. While
Appendix A.2 for an example of a Nested JWT. media type names are not case sensitive, it is RECOMMENDED that "JWT"
always be spelled using uppercase characters for compatibility with
The values used for the "cty" header parameter come from the same legacy implementations. See Appendix A.2 for an example of a Nested
value space as the "typ" header parameter, with the same rules JWT.
applying.
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
the application. If such replicated Claims are present, the the application. If such replicated Claims are present, the
application receiving them SHOULD verify that their values are application receiving them SHOULD verify that their values are
identical. It is the responsibility of the application to ensure identical. It is the responsibility of the application to ensure
that only claims that are safe to be transmitted in an unencrypted that only claims that are safe to be transmitted in an unencrypted
manner are replicated as Header Parameter values in the JWT. manner are replicated as Header Parameter Values in the JWT.
This specification reserves the "iss" (issuer), "sub" (subject), and This specification registers the "iss" (issuer), "sub" (subject), and
"aud" (audience) Header Parameter Names for the purpose of providing "aud" (audience) Header Parameter Names for the purpose of providing
unencrypted replicas of these Claims in encrypted JWTs for unencrypted replicas of these Claims in encrypted JWTs for
applications that need them. Other specifications MAY similarly applications that need them. Other specifications MAY similarly
reserve other names that are reserved Claim Names as Header Parameter register other names that are registered Claim Names as Header
Names, as needed. 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.
6.1. Example Plaintext JWT 6.1. Example Plaintext JWT
The following example JWT Header declares that the encoded object is The following example JWT Header declares that the encoded object is
a Plaintext JWT: a Plaintext JWT:
{"alg":"none"} {"alg":"none"}
skipping to change at page 12, line 24 skipping to change at page 12, line 24
eyJhbGciOiJub25lIn0 eyJhbGciOiJub25lIn0
The following is an example of a JWT Claims Set: The following is an example of a JWT Claims Set:
{"iss":"joe", {"iss":"joe",
"exp":1300819380, "exp":1300819380,
"http://example.com/is_root":true} "http://example.com/is_root":true}
Base64url encoding the octets of the UTF-8 representation of the JWT Base64url encoding the octets of the UTF-8 representation of the JWT
Claims Set yields this Encoded JWS Payload (with line breaks for Claims Set yields this encoded JWS Payload (with line breaks for
display purposes only): display purposes only):
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
The Encoded JWS Signature is the empty string. The encoded JWS Signature is the empty string.
Concatenating these parts in this order with period ('.') characters Concatenating these encoded parts in this order with period ('.')
between the parts yields this complete JWT (with line breaks for characters between the parts yields this complete JWT (with line
display purposes only): breaks for display purposes only):
eyJhbGciOiJub25lIn0 eyJhbGciOiJub25lIn0
. .
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
. .
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 need be 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 need be performed the representation and no canonicalization need be performed
before 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:
skipping to change at page 15, line 24 skipping to change at page 15, line 24
("RSA1_5"), AES Key Wrap with 128 and 256 bit keys ("A128KW" and ("RSA1_5"), AES Key Wrap with 128 and 256 bit keys ("A128KW" and
"A256KW"), and the composite authenticated encryption algorithm using "A256KW"), and the composite authenticated encryption algorithm using
AES CBC and HMAC SHA-2 ("A128CBC-HS256" and "A256CBC-HS512") MUST be AES CBC and HMAC SHA-2 ("A128CBC-HS256" and "A256CBC-HS512") MUST be
implemented by conforming implementations. It is RECOMMENDED that implemented by conforming implementations. It is RECOMMENDED that
implementations also support using ECDH-ES to agree upon a key used implementations also support using ECDH-ES to agree upon a key used
to wrap the Content Encryption Key ("ECDH-ES+A128KW" and to wrap the Content Encryption Key ("ECDH-ES+A128KW" and
"ECDH-ES+A256KW") and AES in Galois/Counter Mode (GCM) with 128 bit "ECDH-ES+A256KW") and AES in Galois/Counter Mode (GCM) with 128 bit
and 256 bit keys ("A128GCM" and "A256GCM"). Support for other and 256 bit keys ("A128GCM" and "A256GCM"). Support for other
algorithms and key sizes is OPTIONAL. algorithms and key sizes is OPTIONAL.
9. IANA Considerations 9. URI for Declaring that Content is a JWT
9.1. JSON Web Token Claims Registry This specification registers the URN
"urn:ietf:params:oauth:token-type:jwt" for use by applications that
declare content types using URIs (rather than, for instance, MIME
Media Types) to indicate that the content referred to is a JWT.
10. IANA Considerations
10.1. JSON Web Token Claims Registry
This specification establishes the IANA JSON Web Token Claims This specification establishes the IANA JSON Web Token Claims
registry for reserved JWT Claim Names. The registry records the registry for JWT Claim Names. The registry records the Claim Name
reserved Claim Name and a reference to the specification that defines and a reference to the specification that defines it. This
it. This specification registers the Claim Names defined in specification registers the Claim Names defined in Section 4.1.
Section 4.1.
Values are registered with a Specification Required [RFC5226] after a Values are registered with a Specification Required [RFC5226] after a
two-week review period on the [TBD]@ietf.org mailing list, on the two-week review period on the [TBD]@ietf.org mailing list, on the
advice of one or more Designated Experts. However, to allow for the advice of one or more Designated Experts. However, to allow for the
allocation of values prior to publication, the Designated Expert(s) allocation of values prior to publication, the Designated Expert(s)
may approve registration once they are satisfied that such a may approve registration once they are satisfied that such a
specification will be published. specification will be published.
Registration requests must be sent to the [TBD]@ietf.org mailing list Registration requests must be sent to the [TBD]@ietf.org mailing list
for review and comment, with an appropriate subject (e.g., "Request for review and comment, with an appropriate subject (e.g., "Request
for access token type: example"). [[ Note to RFC-EDITOR: The name of for access token type: example"). [[ Note to the RFC Editor: The name
the mailing list should be determined in consultation with the IESG of the mailing list should be determined in consultation with the
and IANA. Suggested name: claims-reg-review. ]] IESG and IANA. Suggested name: jwt-reg-review. ]]
Within the review period, the Designated Expert(s) will either Within the review period, the Designated Expert(s) will either
approve or deny the registration request, communicating this decision approve or deny the registration request, communicating this decision
to the review list and IANA. Denials should include an explanation to the review list and IANA. Denials should include an explanation
and, if applicable, suggestions as to how to make the request and, if applicable, suggestions as to how to make the request
successful. successful. Registration requests that are undetermined for a period
longer than 21 days can be brought to the IESG's attention (using the
iesg@iesg.org mailing list) for resolution.
Criteria that should be applied by the Designated Expert(s) includes
determining whether the proposed registration duplicates existing
functionality, determining whether it is likely to be of general
applicability or whether it is useful only for a single application,
and whether the registration makes sense.
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 It is suggested that multiple Designated Experts be appointed who are
able to represent the perspectives of different applications using
this specification, in order to enable broadly-informed review of
registration decisions. In cases where a registration decision could
be perceived as creating a conflict of interest for a particular
Expert, that Expert should defer to the judgment of the other
Expert(s).
10.1.1. Registration Template
Claim Name: Claim Name:
The name requested (e.g., "example"). This name is case The name requested (e.g., "example"). Because a core goal of this
sensitive. Names that match other registered names in a case specification is for the resulting representations to be compact,
insensitive manner SHOULD NOT be accepted. it is RECOMMENDED that the name be short -- not to exceed 8
characters without a compelling reason to do so. This name is
case sensitive. Names may not match other registered names in a
case insensitive manner unless the Designated Expert(s) state that
there is a compelling reason to allow an exception in this
particular case.
Change Controller: Change Controller:
For Standards Track RFCs, state "IETF". For others, give the name For Standards Track RFCs, state "IESG". 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,
email address, home page URI) may also be included. email address, home page URI) may also be included.
Specification Document(s): Specification Document(s):
Reference to the document(s) that specify the parameter, Reference to the document(s) that specify the parameter,
preferably including URI(s) that can be used to retrieve copies of preferably including URI(s) that can be used to retrieve copies of
the document(s). An indication of the relevant sections may also the document(s). An indication of the relevant sections may also
be included but is not required. be included but is not required.
9.1.2. Initial Registry Contents 10.1.2. Initial Registry Contents
o Claim Name: "iss" o Claim Name: "iss"
o Change Controller: IETF o Change Controller: IESG
o Specification Document(s): Section 4.1.1 of [[ this document ]] o Specification Document(s): Section 4.1.1 of [[ this document ]]
o Claim Name: "sub" o Claim Name: "sub"
o Change Controller: IETF o Change Controller: IESG
o Specification Document(s): Section 4.1.2 of [[ this document ]] o Specification Document(s): Section 4.1.2 of [[ this document ]]
o Claim Name: "aud" o Claim Name: "aud"
o Change Controller: IETF 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 ]]
o Claim Name: "exp" o Claim Name: "exp"
o Change Controller: IETF o Change Controller: IESG
o Specification Document(s): Section 4.1.4 of [[ this document ]] o Specification Document(s): Section 4.1.4 of [[ this document ]]
o Claim Name: "nbf" o Claim Name: "nbf"
o Change Controller: IETF o Change Controller: IESG
o Specification Document(s): Section 4.1.5 of [[ this document ]] o Specification Document(s): Section 4.1.5 of [[ this document ]]
o Claim Name: "iat" o Claim Name: "iat"
o Change Controller: IETF o Change Controller: IESG
o Specification Document(s): Section 4.1.6 of [[ this document ]] o Specification Document(s): Section 4.1.6 of [[ this document ]]
o Claim Name: "jti" o Claim Name: "jti"
o Change Controller: IETF o Change Controller: IESG
o Specification Document(s): Section 4.1.7 of [[ this document ]] o Specification Document(s): Section 4.1.7 of [[ this document ]]
o Claim Name: "typ" 10.2. Sub-Namespace Registration of
o Change Controller: IETF urn:ietf:params:oauth:token-type:jwt
o Specification Document(s): Section 4.1.8 of [[ this document ]]
9.2. Sub-Namespace Registration of urn:ietf:params:oauth:token-type:jwt
9.2.1. Registry Contents 10.2.1. Registry Contents
This specification registers the value "token-type:jwt" in the IANA This specification registers the value "token-type:jwt" in the IANA
urn:ietf:params:oauth registry established in An IETF URN Sub- urn:ietf:params:oauth registry established in An IETF URN Sub-
Namespace for OAuth [RFC6755], which can be used to indicate that the Namespace for OAuth [RFC6755], which can be used to indicate that the
content is a JWT. content is a JWT.
o URN: urn:ietf:params:oauth:token-type:jwt o URN: urn:ietf:params:oauth:token-type:jwt
o Common Name: JSON Web Token (JWT) Token Type o Common Name: JSON Web Token (JWT) Token Type
o Change Controller: IETF o Change Controller: IESG
o Specification Document(s): [[this document]] o Specification Document(s): [[this document]]
9.3. JSON Web Signature and Encryption Type Values Registration 10.3. Media Type Registration
9.3.1. Registry Contents
This specification registers the "JWT" type value in the IANA JSON
Web Signature and Encryption Type Values registry [JWS], which can be
used to indicate that the content is a JWT.
o "typ" Header Parameter Value: "JWT"
o Abbreviation for MIME Type: application/jwt
o Change Controller: IETF
o Specification Document(s): Section 5.1 of [[ this document ]]
9.4. Media Type Registration
9.4.1. Registry Contents 10.3.1. Registry Contents
This specification registers the "application/jwt" Media Type This specification registers the "application/jwt" Media Type
[RFC2046] in the MIME Media Type registry [RFC4288], which can be [RFC2046] in the MIME Media Types registry [IANA.MediaTypes], which
used to indicate that the content is a JWT. can be used to indicate that the content is a JWT.
o Type Name: application o Type Name: application
o Subtype Name: jwt o Subtype Name: jwt
o Required Parameters: n/a o Required Parameters: n/a
o Optional Parameters: n/a o Optional Parameters: n/a
o Encoding considerations: JWT values are encoded as a series of o Encoding considerations: 8bit; JWT values are encoded as a series
base64url encoded values (some of which may be the empty string) of base64url encoded values (some of which may be the empty
separated by period ('.') characters string) separated by period ('.') characters.
o Security Considerations: See the Security Considerations section o Security Considerations: See the Security Considerations section
of [[ this document ]] of [[ this document ]]
o Interoperability Considerations: n/a o Interoperability Considerations: n/a
o Published Specification: [[ this document ]] o Published Specification: [[ this document ]]
o Applications that use this media type: OpenID Connect, Mozilla o Applications that use this media type: OpenID Connect, Mozilla
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: IESG
9.5. Registration of JWE Header Parameter Names 10.4. Registration of JWE Header Parameter Names
This specification registers specific reserved Claim Names defined in This specification registers specific Claim Names defined in
Section 4.1 in the IANA JSON Web Signature and Encryption Header Section 4.1 in the IANA JSON Web Signature and Encryption Header
Parameters registry [JWS] for use by Claims replicated as Header Parameters registry defined in [JWS] for use by Claims replicated as
Parameters, per Section 5.3. Header Parameters, per Section 5.3.
9.5.1. Registry Contents 10.4.1. Registry Contents
o Header Parameter Name: "iss" o Header Parameter Name: "iss"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IESG
o Specification Document(s): Section 4.1.1 of [[ this document ]] o Specification Document(s): Section 4.1.1 of [[ this document ]]
o Header Parameter Name: "sub" o Header Parameter Name: "sub"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IESG
o Specification Document(s): Section 4.1.2 of [[ this document ]] o Specification Document(s): Section 4.1.2 of [[ this document ]]
o Header Parameter Name: "aud" o Header Parameter Name: "aud"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IETF 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 ]]
10. Security Considerations 11. 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
to JWT, as do the JWE security considerations when encryption is to JWT, as do the JWE security considerations when encryption is
skipping to change at page 19, line 36 skipping to change at page 19, line 48
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
only supports the use of authenticated encryption algorithms, only supports the use of authenticated encryption algorithms,
cryptographic concerns about the potential need to sign after cryptographic concerns about the potential need to sign after
encryption that apply in many contexts do not apply to this encryption that apply in many contexts do not apply to this
specification. specification.
11. References 12. References
12.1. Normative References
11.1. Normative References
[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]
Internet Assigned Numbers Authority (IANA), "MIME Media
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 2013. October 2013.
[JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web
Encryption (JWE)", draft-ietf-jose-json-web-encryption Encryption (JWE)", draft-ietf-jose-json-web-encryption
(work in progress), July 2013. (work in progress), October 2013.
[JWK] Jones, M., "JSON Web Key (JWK)", [JWK] Jones, M., "JSON Web Key (JWK)",
draft-ietf-jose-json-web-key (work in progress), draft-ietf-jose-json-web-key (work in progress),
July 2013. October 2013.
[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 2013. in progress), October 2013.
[RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part Two: Media Types", RFC 2046, Extensions (MIME) Part Two: Media Types", RFC 2046,
November 1996. November 1996.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the
Internet: Timestamps", RFC 3339, July 2002. Internet: Timestamps", RFC 3339, July 2002.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003. 10646", STD 63, RFC 3629, November 2003.
[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,
RFC 3986, January 2005. RFC 3986, January 2005.
[RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and
Registration Procedures", RFC 4288, December 2005.
[RFC4627] Crockford, D., "The application/json Media Type for [RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006. JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, October 2006. Encodings", RFC 4648, October 2006.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226, IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008. May 2008.
[RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace
for OAuth", RFC 6755, October 2012. for OAuth", RFC 6755, October 2012.
11.2. Informative References 12.2. Informative References
[CanvasApp] [CanvasApp]
Facebook, "Canvas Applications", 2010. Facebook, "Canvas Applications", 2010.
[JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign",
September 2010. September 2010.
[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.
skipping to change at page 23, line 8 skipping to change at page 23, line 24
RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key, RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key,
o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256
algorithm to produce the Ciphertext, and algorithm to produce the Ciphertext, and
o the Plaintext is itself a JWT. o the Plaintext is itself a JWT.
{"alg":"RSA1_5","enc":"A128CBC-HS256","cty":"JWT"} {"alg":"RSA1_5","enc":"A128CBC-HS256","cty":"JWT"}
Base64url encoding the octets of the UTF-8 representation of the JWE Base64url encoding the octets of the UTF-8 representation of the JWE
Header yields this Encoded JWE Header value: Header yields this encoded JWE Header value:
eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiY3R5IjoiSldUIn0 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiY3R5IjoiSldUIn0
The computation of this JWT is identical to the computation of the The computation of this JWT is identical to the computation of the
JWE in Appendix A.2 of [JWE], other than that different JWE Header, JWE in Appendix A.2 of [JWE], other than that different JWE Header,
Plaintext, Initialization Vector, and Content Encryption Key values Plaintext, Initialization Vector, and Content Encryption Key values
are used. (The RSA key used is the same.) are used. (The RSA key used is the same.)
The Payload used is the octets of the ASCII representation of the JWT The Payload used is the octets of the ASCII representation of the JWT
at the end of Appendix Section A.2.1 of [JWS] (with all whitespace at the end of Appendix Section A.2.1 of [JWS] (with all whitespace
skipping to change at page 25, line 46 skipping to change at page 25, line 46
Laurie, James Manger, Prateek Mishra, Tony Nadalin, Axel Nennker, Laurie, James Manger, Prateek Mishra, Tony Nadalin, Axel Nennker,
John Panzer, Emmanuel Raviart, David Recordon, Eric Rescorla, Jim John Panzer, Emmanuel Raviart, David Recordon, Eric Rescorla, Jim
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 ]]
-12
o Tracked the JOSE change refining the "typ" and "cty" definitions
to always be MIME Media Types, with the omission of "application/"
prefixes recommended for brevity. For compatibility with legacy
implementations, it is RECOMMENDED that "JWT" always be spelled
using uppercase characters when used as a "typ" or "cty" value.
As side effects, this change removed the "typ" Claim definition
and narrowed the uses of the URI
"urn:ietf:params:oauth:token-type:jwt".
o Updated base64url definition to match JOSE definition.
o Changed terminology from "Reserved Claim Name" to "Registered
Claim Name" to match JOSE terminology change.
o Applied other editorial changes to track parallel JOSE changes.
o Clarified that the subject value may be scoped to be locally
unique in the context of the issuer or may be globally unique.
-11 -11
o Added a Nested JWT example. o Added a Nested JWT example.
o Added "sub" to the list of Claims registered for use as Header o Added "sub" to the list of Claims registered for use as Header
Parameter values when an unencrypted representation is required in Parameter values when an unencrypted representation is required in
an encrypted JWT. an encrypted JWT.
-10 -10
o Allowed Claims to be replicated as Header Parameters in encrypted o Allowed Claims to be replicated as Header Parameters in encrypted
JWTs as needed by applications that require an unencrypted JWTs as needed by applications that require an unencrypted
 End of changes. 84 change blocks. 
184 lines changed or deleted 214 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/