draft-ietf-oauth-json-web-token-22.txt   draft-ietf-oauth-json-web-token-23.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: December 22, 2014 Ping Identity Expires: December 22, 2014 Ping Identity
N. Sakimura N. Sakimura
NRI NRI
June 20, 2014 June 20, 2014
JSON Web Token (JWT) JSON Web Token (JWT)
draft-ietf-oauth-json-web-token-22 draft-ietf-oauth-json-web-token-23
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 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 . . . . . . . . . . . . . . . . . 9 4.1.1. "iss" (Issuer) Claim . . . . . . . . . . . . . . . . . 8
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 . . . . . . . . . . . . . . . 10 4.1.6. "iat" (Issued At) Claim . . . . . . . . . . . . . . . 9
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. JWT Header . . . . . . . . . . . . . . . . . . . . . . . . . . 10 5. JOSE Header . . . . . . . . . . . . . . . . . . . . . . . . . 10
5.1. "typ" (Type) Header Parameter . . . . . . . . . . . . . . 11 5.1. "typ" (Type) Header Parameter . . . . . . . . . . . . . . 10
5.2. "cty" (Content Type) Header Parameter . . . . . . . . . . 11 5.2. "cty" (Content Type) Header Parameter . . . . . . . . . . 11
5.3. Replicating Claims as Header Parameters . . . . . . . . . 11 5.3. Replicating Claims as Header Parameters . . . . . . . . . 11
6. Plaintext JWTs . . . . . . . . . . . . . . . . . . . . . . . . 12 6. Plaintext JWTs . . . . . . . . . . . . . . . . . . . . . . . . 12
6.1. Example Plaintext JWT . . . . . . . . . . . . . . . . . . 12 6.1. Example Plaintext JWT . . . . . . . . . . . . . . . . . . 12
7. Rules for Creating and Validating a JWT . . . . . . . . . . . 13 7. Rules for Creating and Validating a JWT . . . . . . . . . . . 13
7.1. String Comparison Rules . . . . . . . . . . . . . . . . . 15 7.1. String Comparison Rules . . . . . . . . . . . . . . . . . 14
8. Implementation Requirements . . . . . . . . . . . . . . . . . 15 8. Implementation Requirements . . . . . . . . . . . . . . . . . 15
9. URI for Declaring that Content is a JWT . . . . . . . . . . . 16 9. URI for Declaring that Content is a JWT . . . . . . . . . . . 15
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 . . . . . . . . . . . . . . . . . . 19 10.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 18
10.4. Registration of JWE Header Parameter Names . . . . . . . . 19 10.4. Header Parameter Names Registration . . . . . . . . . . . 19
10.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 19 10.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 19
11. Security Considerations . . . . . . . . . . . . . . . . . . . 20 11. Security Considerations . . . . . . . . . . . . . . . . . . . 19
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. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 20
12.1. Normative References . . . . . . . . . . . . . . . . . . . 21 12.1. Normative References . . . . . . . . . . . . . . . . . . . 20
12.2. Informative References . . . . . . . . . . . . . . . . . . 22 12.2. Informative References . . . . . . . . . . . . . . . . . . 21
Appendix A. JWT Examples . . . . . . . . . . . . . . . . . . . . 23 Appendix A. JWT Examples . . . . . . . . . . . . . . . . . . . . 22
A.1. Example Encrypted JWT . . . . . . . . . . . . . . . . . . 23 A.1. Example Encrypted JWT . . . . . . . . . . . . . . . . . . 22
A.2. Example Nested JWT . . . . . . . . . . . . . . . . . . . . 23 A.2. Example Nested JWT . . . . . . . . . . . . . . . . . . . . 23
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 . . . . . . . . . . . . . . . . . . 26
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 31 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)
[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 31 skipping to change at page 4, line 31
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in Key "OPTIONAL" in this document are to be interpreted as described in Key
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]
specification are incorporated into this specification: "JSON Web
Signature (JWS)", "Base64url Encoding", "Header Parameter", "JOSE
Header", "JWS Compact Serialization", "JWS Payload", "JWS Signature",
and "Plaintext JWS".
These terms defined by the JSON Web Encryption (JWE) [JWE]
specification are incorporated into this specification: "JSON Web
Encryption (JWE)", "Content Encryption Key (CEK)", "JWE Compact
Serialization", "JWE Encrypted Key", "JWE Initialization Vector",
"JWE Plaintext".
These terms are defined by this specification:
JSON Web Token (JWT) JSON Web Token (JWT)
A string representing a set of claims as a JSON object that is A string representing a set of claims as a JSON object that is
encoded in a JWS or JWE, enabling the claims to be digitally encoded in a JWS or JWE, enabling the claims to be digitally
signed or MACed and/or encrypted. signed or MACed and/or encrypted.
Base64url Encoding
Base64 encoding using the URL- and filename-safe character set
defined in Section 5 of RFC 4648 [RFC4648], with all trailing '='
characters omitted (as permitted by Section 3.2) and without the
inclusion of any line breaks, white space, or other additional
characters. (See Appendix C of [JWS] for notes on implementing
base64url encoding without padding.)
JWT Header
A JSON object that describes the cryptographic operations applied
to the JWT. When the JWT is digitally signed or MACed, the JWT
Header is a JWS Header. When the JWT is encrypted, the JWT Header
is a JWE Header.
Header Parameter
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 Value
The value of a member of the JWT Header.
JWT Claims Set JWT Claims Set
A JSON object that contains the Claims conveyed by the JWT. A JSON object that contains the Claims conveyed by the JWT.
Claim Claim
A piece of information asserted about a subject. A Claim is 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.
Claim Name Claim Name
The name portion of a Claim representation. A Claim Name is The name portion of a Claim representation. A Claim Name is
always a string. always a string.
Claim Value Claim Value
The value portion of a Claim representation. A Claim Value can be The value portion of a Claim representation. A Claim Value can be
any JSON value. any JSON value.
Encoded JWT Header Encoded JOSE Header
Base64url encoding of the JWT 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 Plaintext 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
skipping to change at page 6, line 30 skipping to change at page 6, line 23
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 [RFC7159], the JSON object consists of zero or more per Section 4 of [RFC7159], the JSON object consists of zero or more
name/value pairs (or members), where the names are strings and the name/value pairs (or members), where the names are strings and the
values are arbitrary JSON values. These members are the claims values are arbitrary JSON values. These members are the claims
represented by the JWT. represented by the JWT.
The member names within the JWT Claims Set are referred to as Claim The member names within the JWT Claims Set are referred to as Claim
Names. The corresponding values are referred to as Claim Values. Names. The corresponding values are referred to as Claim Values.
The contents of the JWT Header describe the cryptographic operations The contents of the JOSE Header describe the cryptographic operations
applied to the JWT Claims Set. If the JWT Header is a JWS Header, the applied to the JWT Claims Set. If the JOSE Header is for a JWS
JWT is represented as a JWS, and the claims are digitally signed or object, the JWT is represented as a JWS, and the claims are digitally
MACed, with the JWT Claims Set being the JWS Payload. If the JWT signed or MACed, with the JWT Claims Set being the JWS Payload. If
Header is a JWE Header, the JWT is represented as a JWE, and the the JOSE Header is for a JWE object, the JWT is represented as a JWE,
claims are encrypted, with the JWT Claims Set being the input and the claims are encrypted, with the JWT Claims Set being the JWE
Plaintext. A JWT may be enclosed in another JWE or JWS structure to Plaintext. A JWT may be enclosed in another JWE or JWS structure to
create a Nested JWT, enabling nested signing and encryption to be create a Nested JWT, enabling nested signing and encryption to be
performed. performed.
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 JOSE Header declares that the encoded object is
a JSON Web Token (JWT) and the JWT is a JWS that is MACed using the a JSON Web Token (JWT) and the JWT is a JWS that is MACed using the
HMAC SHA-256 algorithm: HMAC SHA-256 algorithm:
{"typ":"JWT", {"typ":"JWT",
"alg":"HS256"} "alg":"HS256"}
To remove potential ambiguities in the representation of the JSON To remove potential ambiguities in the representation of the JSON
object above, the octet sequence for the actual UTF-8 representation object above, the octet sequence for the actual UTF-8 representation
used in this example for the JWT Header/JWS Header above is also used in this example for the JOSE Header above is also included
included below. (Note that ambiguities can arise due to differing below. (Note that ambiguities can arise due to differing platform
platform representations of line breaks (CRLF versus LF), differing representations of line breaks (CRLF versus LF), differing spacing at
spacing at the beginning and ends of lines, whether the last line has the beginning and ends of lines, whether the last line has a
a terminating line break or not, and other causes. In the terminating line break or not, and other causes. In the
representation used in this example, the first line has no leading or representation used in this example, the first line has no leading or
trailing spaces, a CRLF line break (13, 10) occurs between the first trailing spaces, a CRLF line break (13, 10) occurs between the first
and second lines, the second line has one leading space (32) and no and second lines, the second line has one leading space (32) and no
trailing spaces, and the last line does not have a terminating line trailing spaces, and the last line does not have a terminating line
break.) The octets representing the UTF-8 representation of the JWS break.) The octets representing the UTF-8 representation of the JOSE
Header in this example (using JSON array notation) are: Header in this example (using JSON array notation) are:
[123, 34, 116, 121, 112, 34, 58, 34, 74, 87, 84, 34, 44, 13, 10, 32, [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] 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 JOSE
Header yields this Encoded JWT Header value (which is also the Header yields this Encoded JOSE Header value:
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 used The following octet sequence, which is the UTF-8 representation used
skipping to change at page 7, line 52 skipping to change at page 7, line 43
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
Computing the MAC of the encoded JWS Header and encoded JWS Payload Computing the MAC of the encoded JOSE Header and encoded JWS Payload
with the HMAC SHA-256 algorithm and base64url encoding the HMAC value with the HMAC SHA-256 algorithm and base64url encoding the HMAC value
in the manner specified in [JWS], yields this encoded JWS Signature: in the manner specified in [JWS], yields this encoded JWS Signature:
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
Concatenating these encoded parts in this order with period ('.') Concatenating these encoded parts in this order with period ('.')
characters between the parts yields this complete JWT (with line characters between the parts yields this complete JWT (with line
breaks for display purposes only): breaks for display purposes only):
eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
skipping to change at page 10, line 43 skipping to change at page 10, line 34
the 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 Registered Claim Names are Private Names: names that are not Registered Claim Names
Section 4.1 or Public Claim Names Section 4.2. Unlike Public Claim Section 4.1 or Public Claim Names Section 4.2. Unlike Public Claim
Names, Private Claim Names are subject to collision and should be Names, Private Claim Names are subject to collision and should be
used with caution. used with caution.
5. JWT Header 5. JOSE Header
The members of the JSON object represented by the JWT Header describe For a JWT object, the members of the JSON object represented by the
the cryptographic operations applied to the JWT and optionally, JOSE Header describe the cryptographic operations applied to the JWT
additional properties of the JWT. The member names within the JWT and optionally, additional properties of the JWT. Depending upon
Header are referred to as Header Parameter Names. These names MUST whether the JWT is a JWS or JWE, the corresponding rules for the JOSE
be unique; recipients MUST either reject JWTs with duplicate Header Header values apply.
Parameter Names or use a JSON parser that returns only the lexically
last duplicate member name, as specified in Section 15.12 (The JSON
Object) of ECMAScript 5.1 [ECMAScript]. The corresponding values are
referred to as Header Parameter Values.
JWS Header Parameters are defined by [JWS]. JWE Header Parameters This specification further specifies the use of the following Header
are defined by [JWE]. This specification further specifies the use Parameters in both the cases where the JWT is a JWS and where it is a
of the following Header Parameters in both the cases where the JWT is 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 defined by [JWS] and [JWE] is used The "typ" (type) Header Parameter defined by [JWS] and [JWE] is used
by JWT applications to declare the MIME Media Type [IANA.MediaTypes] by JWT applications to declare the MIME Media Type [IANA.MediaTypes]
of this complete JWT. This is intended for use by the JWT of this complete JWT. This is intended for use by the JWT
application when values that are not JWTs could also be present in an application when values that are not JWTs could also be present in an
application data structure that can contain a JWT object; the application data structure that can contain a JWT object; the
application can use this value to disambiguate among the different application can use this value to disambiguate among the different
kinds of objects that might be present. It will typically not be kinds of objects that might be present. It will typically not be
skipping to change at page 12, line 12 skipping to change at page 11, line 46
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, unless the application defines other specific processing identical, unless the application defines other specific processing
rules for these Claims. It is the responsibility of the application rules for these Claims. It is the responsibility of the application
to ensure that only claims that are safe to be transmitted in an to ensure that only claims that are safe to be transmitted in an
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. 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 "alg" Header Parameter value "none" and with
defined in JSON Web Algorithms (JWA) [JWA]; it is a JWS with the the empty string for its JWS Signature value, as defined in JSON Web
empty string for its JWS Signature value. Algorithms (JWA) [JWA]; it is a Plaintext JWS with the JWT Claims Set
as its JWS Payload.
6.1. Example Plaintext JWT 6.1. Example Plaintext JWT
The following example JWT Header declares that the encoded object is The following example JOSE Header declares that the encoded object is
a Plaintext JWT: a Plaintext JWT:
{"alg":"none"} {"alg":"none"}
Base64url encoding the octets of the UTF-8 representation of the JWT Base64url encoding the octets of the UTF-8 representation of the JOSE
Header yields this Encoded JWT 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:
{"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
skipping to change at page 13, line 34 skipping to change at page 13, line 24
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 JOSE 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. Depending upon whether the JWT is a JWS or JWE, there are two 4. Depending upon whether the JWT is a JWS or JWE, there are two
cases: cases:
* If the JWT is a JWS, create a JWS using the JWT Header as the * If the JWT is a JWS, create a JWS using the Message as the JWS
JWS Header and the Message as the JWS Payload; all steps Payload; all steps specified in [JWS] for creating a JWS MUST
specified in [JWS] for creating a JWS MUST be followed. be followed.
* Else, if the JWT is a JWE, create a JWE using the JWT Header * Else, if the JWT is a JWE, create a JWE using the Message as
as the JWE Header and the Message as the JWE Plaintext; all the JWE Plaintext; all steps specified in [JWE] for creating a
steps specified in [JWE] for creating a JWE MUST be followed. JWE MUST be followed.
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 JWT Header created "cty" (content type) value of "JWT" in the new JOSE Header
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 for processing.
1. The JWT MUST contain at least one period ('.') character. 1. The JWT MUST contain at least one period ('.') character.
2. Let the Encoded JWT Header be the portion of the JWT before the 2. Let the Encoded JOSE Header be the portion of the JWT before the
first period ('.') character. first period ('.') character.
3. The Encoded JWT Header MUST be successfully base64url decoded 3. The Encoded 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.
4. The resulting JWT Header MUST be completely valid JSON syntax 4. The resulting JOSE Header MUST be completely valid JSON syntax
conforming to [RFC7159]. conforming to [RFC7159].
5. The resulting JWT Header MUST be validated to only include 5. The resulting JOSE Header MUST be validated to only include
parameters and values whose syntax and semantics are both parameters and values whose syntax and semantics are both
understood and supported or that are specified as being ignored understood and supported or that are specified as being ignored
when not understood. when not understood.
6. Determine whether the JWT is a JWS or a JWE using any of the 6. Determine whether the JWT is a JWS or a JWE using any of the
methods described in Section 9 of [JWE]. methods described in Section 9 of [JWE].
7. Depending upon whether the JWT is a JWS or JWE, there are two 7. Depending upon whether the JWT is a JWS or JWE, there are two
cases: cases:
* If the JWT is a JWS, all steps specified in [JWS] for * If the JWT is a JWS, all steps specified in [JWS] for
validating a JWS MUST be followed. Let the Message be the validating a JWS MUST be followed. Let the Message be the
result of base64url decoding the JWS Payload. result of base64url decoding the JWS Payload.
* Else, if the JWT is a JWE, all steps specified in [JWE] for * Else, if the JWT is a JWE, all steps specified in [JWE] for
validating a JWE MUST be followed. Let the Message be the validating a JWE MUST be followed. Let the Message be the
JWE Plaintext. JWE Plaintext.
8. If the JWT Header contains a "cty" (content type) value of 8. If the JOSE Header contains a "cty" (content type) value of
"JWT", then the Message is a JWT that was the subject of nested "JWT", then the Message is a JWT that was the subject of nested
signing or encryption operations. In this case, return to Step signing or encryption operations. In this case, return to Step
1, using the Message as the JWT. 1, using the Message as the JWT.
9. Otherwise, let the JWT Claims Set be the Message. 9. Otherwise, let the JWT Claims Set be the Message.
10. The JWT Claims Set MUST be completely valid JSON syntax 10. The JWT Claims Set MUST be completely valid JSON syntax
conforming to [RFC7159]. conforming to [RFC7159].
7.1. String Comparison Rules 7.1. String Comparison Rules
Processing a JWT inevitably requires comparing known strings to Processing a JWT inevitably requires comparing known strings to
values in JSON objects. For example, in checking what the algorithm values in JSON objects. For example, in checking what the algorithm
is, the Unicode string encoding "alg" will be checked against the is, the Unicode string encoding "alg" will be checked against the
member names in the JWT Header to see if there is a matching Header member names in the JOSE Header to see if there is a matching Header
Parameter Name. Parameter name.
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
skipping to change at page 19, line 32 skipping to change at page 19, line 20
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: IESG o Change Controller: IESG
10.4. Registration of JWE Header Parameter Names 10.4. Header Parameter Names Registration
This specification registers specific 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 defined in [JWS] for use by Claims replicated as Parameters registry defined in [JWS] for use by Claims replicated as
Header Parameters, per Section 5.3. Header Parameters in JWE objects, per Section 5.3.
10.4.1. Registry Contents 10.4.1. Registry Contents
o Header Parameter Name: "iss" o Header Parameter Name: "iss"
o Header Parameter Description: Issuer o Header Parameter Description: Issuer
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.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"
skipping to change at page 20, line 27 skipping to change at page 20, line 13
protecting the user's asymmetric private and symmetric secret keys, protecting the user's asymmetric private and symmetric secret keys,
preventing various attacks, and helping avoid mistakes such as preventing various attacks, and helping avoid mistakes such as
inadvertently encrypting a message to the wrong recipient. The inadvertently encrypting a message to the wrong recipient. The
entire list of security considerations is beyond the scope of this entire list of security considerations is beyond the scope of this
document. 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
employed. In particular, the JWS JSON Security Considerations and employed. In particular, the JWS JSON Security Considerations and
Unicode Comparison Security Considerations apply equally to the JWT Unicode Comparison Security Considerations apply equally to the JWT
Claims Set in the same manner that they do to the JWS Header. Claims Set in the same manner that they do to the 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.
skipping to change at page 23, line 15 skipping to change at page 22, line 47
Appendix A. JWT Examples Appendix A. JWT Examples
This section contains examples of JWTs. For other example JWTs, see This section contains examples of JWTs. For other example JWTs, see
Section 6.1 and Appendices A.1, A.2, and A.3 of [JWS]. Section 6.1 and Appendices A.1, A.2, and A.3 of [JWS].
A.1. Example Encrypted JWT A.1. Example Encrypted JWT
This example encrypts the same claims as used in Section 3.1 to the This example encrypts the same claims as used in Section 3.1 to the
recipient using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256. recipient using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256.
The following example JWE Header (with line breaks for display The following example JOSE Header declares that:
purposes only) declares that:
o the Content Encryption Key is encrypted to the recipient using the o the Content Encryption Key is encrypted to the recipient using the
RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and
o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256
algorithm to produce the Ciphertext. algorithm to produce the JWE Ciphertext.
{"alg":"RSA1_5","enc":"A128CBC-HS256"} {"alg":"RSA1_5","enc":"A128CBC-HS256"}
Other than using the octets of the UTF-8 representation of the JWT Other than using the octets of the UTF-8 representation of the JWT
Claims Set from Section 3.1 as the plaintext value, the computation Claims Set from Section 3.1 as the plaintext value, the computation
of this JWT is identical to the computation of the JWE in Appendix of this JWT is identical to the computation of the JWE in Appendix
A.2 of [JWE], including the keys used. A.2 of [JWE], including the keys used.
The final result in this example (with line breaks for display The final result in this example (with line breaks for display
purposes only) is: purposes only) is:
skipping to change at page 24, line 10 skipping to change at page 23, line 41
This example shows how a JWT can be used as the payload of a JWE or This example shows how a JWT can be used as the payload of a JWE or
JWS to create a Nested JWT. In this case, the JWT Claims Set is JWS to create a Nested JWT. In this case, the JWT Claims Set is
first signed, and then encrypted. first signed, and then encrypted.
The inner signed JWT is identical to the example in Appendix A.2 of The inner signed JWT is identical to the example in Appendix A.2 of
[JWS]. Therefore, its computation is not repeated here. This [JWS]. Therefore, its computation is not repeated here. This
example then encrypts this inner JWT to the recipient using RSAES- example then encrypts this inner JWT to the recipient using RSAES-
PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256. PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256.
The following example JWE Header (with line breaks for display The following example JOSE Header declares that:
purposes only) declares that:
o the Content Encryption Key is encrypted to the recipient using the o the Content Encryption Key is encrypted to the recipient using the
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 JWE 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 JOSE
Header yields this encoded JWE Header value: Header yields this encoded JOSE 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 JOSE Header,
Plaintext, Initialization Vector, and Content Encryption Key values Plaintext, JWE Initialization Vector, and Content Encryption Key
are used. (The RSA key used is the same.) values 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 A.2.1 of [JWS] (with all whitespace and line at the end of Appendix A.2.1 of [JWS] (with all whitespace and line
breaks removed), which is a sequence of 458 octets. breaks removed), which is a sequence of 458 octets.
The Initialization Vector value used (using JSON array notation) is: The JWE Initialization Vector value used (using JSON array notation)
is:
[82, 101, 100, 109, 111, 110, 100, 32, 87, 65, 32, 57, 56, 48, 53, [82, 101, 100, 109, 111, 110, 100, 32, 87, 65, 32, 57, 56, 48, 53,
50] 50]
This example uses the Content Encryption Key represented by the This example uses the Content Encryption Key represented by the
base64url encoded value below: base64url encoded value below:
GawgguFyGrWKav7AX4VKUg GawgguFyGrWKav7AX4VKUg
The final result for this Nested JWT (with line breaks for display The final result for this Nested JWT (with line breaks for display
skipping to change at page 26, line 48 skipping to change at page 26, line 48
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, 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 ]]
-23
o Replaced the terms JWS Header, JWE Header, and JWT Header with a
single JOSE Header term defined in the JWS specification. This
also enabled a single Header Parameter definition to be used and
reduced other areas of duplication between specifications.
-22 -22
o Revised the introduction to the Security Considerations section. o Revised the introduction to the Security Considerations section.
Also introduced subsection headings for security considerations Also introduced subsection headings for security considerations
items. items.
o Added text about when applications typically would and would not o Added text about when applications typically would and would not
use the "typ" header parameter. use the "typ" header parameter.
-21 -21
o Removed unnecessary informative JWK spec reference. o Removed unnecessary informative JWK spec reference.
 End of changes. 50 change blocks. 
112 lines changed or deleted 104 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/