draft-ietf-oauth-json-web-token-12.txt   draft-ietf-oauth-json-web-token-13.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: April 10, 2014 Ping Identity Expires: May 16, 2014 Ping Identity
N. Sakimura N. Sakimura
NRI NRI
October 7, 2013 November 12, 2013
JSON Web Token (JWT) JSON Web Token (JWT)
draft-ietf-oauth-json-web-token-12 draft-ietf-oauth-json-web-token-13
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 April 10, 2014. This Internet-Draft will expire on May 16, 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4. JWT Claims . . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.1. Registered Claim Names . . . . . . . . . . . . . . . . . . 8 4.1. Registered Claim Names . . . . . . . . . . . . . . . . . . 8
4.1.1. "iss" (Issuer) Claim . . . . . . . . . . . . . . . . . 8 4.1.1. "iss" (Issuer) Claim . . . . . . . . . . . . . . . . . 8
4.1.2. "sub" (Subject) Claim . . . . . . . . . . . . . . . . 8 4.1.2. "sub" (Subject) Claim . . . . . . . . . . . . . . . . 8
4.1.3. "aud" (Audience) Claim . . . . . . . . . . . . . . . . 9 4.1.3. "aud" (Audience) Claim . . . . . . . . . . . . . . . . 8
4.1.4. "exp" (Expiration Time) Claim . . . . . . . . . . . . 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.2. Public Claim Names . . . . . . . . . . . . . . . . . . . . 10 4.2. Public Claim Names . . . . . . . . . . . . . . . . . . . . 9
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 . . . . . . . . . . 10
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 . . . . . . . . . . . . . . . . . . 11
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. URI for Declaring that Content is a JWT . . . . . . . . . . . 15 9. URI for Declaring that Content is a JWT . . . . . . . . . . . 15
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15
10.1. JSON Web Token Claims Registry . . . . . . . . . . . . . . 15 10.1. JSON Web Token Claims Registry . . . . . . . . . . . . . . 15
10.1.1. Registration Template . . . . . . . . . . . . . . . . 16 10.1.1. Registration Template . . . . . . . . . . . . . . . . 16
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 . . . . . . . . . . . 17 urn:ietf:params:oauth:token-type:jwt . . . . . . . . . . . 17
skipping to change at page 4, line 41 skipping to change at page 4, line 41
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 Base64 encoding using the URL- and filename-safe Base64url Encoding Base64 encoding using the URL- and filename-safe
character set defined in Section 5 of RFC 4648 [RFC4648], with all character set defined in Section 5 of RFC 4648 [RFC4648], with all
trailing '=' 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 JWT Header A JSON object that describes the cryptographic operations
a JSON object; the syntax of JSON objects is defined in Section applied to the JWT. When the JWT is digitally signed or MACed,
2.2 of [RFC4627]. the JWT Header is a JWS Header. When the JWT is encrypted, the
JWT Header is a JWE Header.
JWT Header A JSON Text 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 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 object that contains the Claims conveyed by
by the JWT. 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.
Claim Name The name portion of a Claim representation. A Claim Name Claim Name The name portion of a Claim representation. A Claim Name
is always a string. is always a string.
Claim Value The value portion of a Claim representation. A Claim Claim Value The value portion of a Claim representation. A Claim
Value can be any JSON value. Value can be any JSON value.
skipping to change at page 5, line 34 skipping to change at page 5, line 30
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 Name A name in a namespace that enables names to Collision-Resistant Name A name in a namespace that enables names to
be 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. Examples of collision resistant collide with other names. Examples of collision-resistant
namespaces include: Domain Names, Object Identifiers (OIDs) as namespaces include: Domain Names, Object Identifiers (OIDs) as
defined in the ITU-T X.660 and X.670 Recommendation series, and defined in the ITU-T X.660 and X.670 Recommendation series, and
Universally Unique IDentifiers (UUIDs) [RFC4122]. When using an Universally Unique IDentifiers (UUIDs) [RFC4122]. When using an
administratively delegated namespace, the definer of a name needs administratively delegated namespace, the definer of a name needs
to take reasonable precautions to ensure they are in control of to take reasonable precautions to ensure they are in control of
the portion of the namespace they use to define the name. 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
skipping to change at page 7, line 31 skipping to change at page 7, line 26
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
MACing the encoded JWS Header and encoded JWS Payload with the HMAC Computing the MAC of the encoded JWS Header and encoded JWS Payload
SHA-256 algorithm and base64url encoding the HMAC value in the manner with the HMAC SHA-256 algorithm and base64url encoding the HMAC value
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
. .
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
skipping to change at page 8, line 37 skipping to change at page 8, line 30
Claims registry defined in Section 10.1. None of the claims defined 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. to be compact.
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 subject value MAY be scoped to be locally about the subject. The subject value MAY be scoped to be locally
unique in the context of the issuer or MAY be globally unique. The unique in the context of the issuer or MAY be globally unique. The
processing of this claim is generally application specific. The processing of this claim is generally application specific. The
"sub" value is a case sensitive string containing a StringOrURI "sub" 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.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
audience, the "aud" value MAY be a single case sensitive string audience, the "aud" value MAY be a single case-sensitive string
containing a StringOrURI value. The interpretation of audience containing a StringOrURI value. The interpretation of audience
values is generally application specific. Use of this claim is values is generally application specific. Use of this claim is
OPTIONAL. OPTIONAL.
4.1.4. "exp" (Expiration Time) Claim 4.1.4. "exp" (Expiration Time) Claim
The "exp" (expiration time) claim identifies the expiration time on The "exp" (expiration time) claim identifies the expiration time on
or after which the JWT MUST NOT be accepted for processing. The or after which the JWT MUST NOT be accepted for processing. The
processing of the "exp" claim requires that the current date/time processing of the "exp" claim requires that the current date/time
MUST be before the expiration date/time listed in the "exp" claim. MUST be before the expiration date/time listed in the "exp" claim.
skipping to change at page 10, line 4 skipping to change at page 9, line 43
value MUST be a number containing an IntDate value. Use of this value MUST be a number containing an IntDate value. Use of this
claim is OPTIONAL. claim is OPTIONAL.
4.1.7. "jti" (JWT ID) Claim 4.1.7. "jti" (JWT ID) Claim
The "jti" (JWT ID) claim provides a unique identifier for the JWT. The "jti" (JWT ID) claim provides a unique identifier for the JWT.
The identifier value MUST be assigned in a manner that ensures that The identifier value MUST be assigned in a manner that ensures that
there is a negligible probability that the same value will be there is a negligible probability that the same value will be
accidentally assigned to a different data object. The "jti" claim accidentally assigned to a different data object. The "jti" claim
can be used to prevent the JWT from being replayed. The "jti" value can be used to prevent the JWT from being replayed. The "jti" value
is a case sensitive string. Use of this claim is OPTIONAL. is a case-sensitive string. Use of this claim is OPTIONAL.
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 defined in registered in the IANA JSON Web Token Claims registry defined in
Section 10.1 or be a Public Name: a value that contains a Collision Section 10.1 or be a Public Name: a value that contains a Collision-
Resistant Name. In each case, the definer of the name or value needs Resistant Name. In each case, the definer of the name or value needs
to take reasonable precautions to make sure they are in control of to take reasonable precautions to make sure they are in control of
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
skipping to change at page 10, line 48 skipping to change at page 10, line 39
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 defined by [JWS] and [JWE] is used The "typ" (type) Header Parameter defined by [JWS] and [JWE] is used
to declare the MIME Media Type [IANA.MediaTypes] of this complete JWT to declare the MIME Media Type [IANA.MediaTypes] of this complete JWT
in contexts where this is useful to the application. This parameter in contexts where this is useful to the application. This parameter
has no effect upon the JWT processing. If present, it is RECOMMENDED has no effect upon the JWT processing. If present, it is RECOMMENDED
that its value be "JWT" to indicate that this object is a JWT. While that its value be "JWT" to indicate that this object is a JWT. While
media type names are not case sensitive, it is RECOMMENDED that "JWT" media type names are not case-sensitive, it is RECOMMENDED that "JWT"
always be spelled using uppercase characters for compatibility with always be spelled using uppercase characters for compatibility with
legacy implementations. Use of this Header Parameter is OPTIONAL. 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 defined by [JWS] and [JWE] The "cty" (content type) Header Parameter defined by [JWS] and [JWE]
is used by this specification to convey structural information about is used by this specification to convey structural information about
the JWT. the JWT.
In the normal case where nested signing or encryption operations are In the normal case 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
this Header Parameter is REQUIRED; in this case, the value MUST be In the case that nested signing or encryption is employed, this
Header Parameter MUST be present; in this case, the value MUST be
"JWT", to indicate that a Nested JWT is carried in this JWT. While "JWT", to indicate that a Nested JWT is carried in this JWT. While
media type names are not case sensitive, it is RECOMMENDED that "JWT" media type names are not case-sensitive, it is RECOMMENDED that "JWT"
always be spelled using uppercase characters for compatibility with always be spelled using uppercase characters for compatibility with
legacy implementations. See Appendix A.2 for an example of a Nested legacy implementations. See Appendix A.2 for an example of a Nested
JWT. JWT.
5.3. Replicating Claims as Header Parameters 5.3. Replicating Claims as Header Parameters
In some applications using encrypted JWTs, it is useful to have an In some applications using encrypted JWTs, it is useful to have an
unencrypted representation of some Claims. This might be used, for unencrypted representation of some Claims. This might be used, for
instance, in application processing rules to determine whether and instance, in application processing rules to determine whether and
how to process the JWT before it is decrypted. how to process the JWT before it is decrypted.
skipping to change at page 14, line 44 skipping to change at page 14, line 35
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 JWT 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. Cryptographic Algorithms 8. Cryptographic Algorithms
JWTs use JSON Web Signature (JWS) [JWS] and JSON Web Encryption (JWE) JWTs use JSON Web Signature (JWS) [JWS] and JSON Web Encryption (JWE)
[JWE] to sign and/or encrypt the contents of the JWT. [JWE] to sign and/or encrypt the contents of the JWT.
Of the JWA signing algorithms, only HMAC SHA-256 ("HS256") and "none" Of the signature and MAC algorithms specified in JSON Web Algorithms
MUST be implemented by conforming JWT implementations. It is (JWA) [JWA], only HMAC SHA-256 ("HS256") and "none" MUST be
RECOMMENDED that implementations also support RSASSA-PKCS1-V1_5 with implemented by conforming JWT implementations. It is RECOMMENDED
the SHA-256 hash algorithm ("RS256") and ECDSA using the P-256 curve that implementations also support RSASSA-PKCS1-V1_5 with the SHA-256
and the SHA-256 hash algorithm ("ES256"). Support for other hash algorithm ("RS256") and ECDSA using the P-256 curve and the SHA-
algorithms and key sizes is OPTIONAL. 256 hash algorithm ("ES256"). Support for other algorithms and key
sizes is OPTIONAL.
If an implementation provides encryption capabilities, of the JWA If an implementation provides encryption capabilities, of the
encryption algorithms, only RSAES-PKCS1-V1_5 with 2048 bit keys encryption algorithms specified in [JWA], only RSAES-PKCS1-V1_5 with
("RSA1_5"), AES Key Wrap with 128 and 256 bit keys ("A128KW" and 2048 bit keys ("RSA1_5"), AES Key Wrap with 128 and 256 bit keys
"A256KW"), and the composite authenticated encryption algorithm using ("A128KW" and "A256KW"), and the composite authenticated encryption
AES CBC and HMAC SHA-2 ("A128CBC-HS256" and "A256CBC-HS512") MUST be algorithm using AES CBC and HMAC SHA-2 ("A128CBC-HS256" and
implemented by conforming implementations. It is RECOMMENDED that "A256CBC-HS512") MUST be implemented by conforming implementations.
implementations also support using ECDH-ES to agree upon a key used It is RECOMMENDED that implementations also support using ECDH-ES to
to wrap the Content Encryption Key ("ECDH-ES+A128KW" and agree upon a key used to wrap the Content Encryption Key
"ECDH-ES+A256KW") and AES in Galois/Counter Mode (GCM) with 128 bit ("ECDH-ES+A128KW" and "ECDH-ES+A256KW") and AES in Galois/Counter
and 256 bit keys ("A128GCM" and "A256GCM"). Support for other Mode (GCM) with 128 bit and 256 bit keys ("A128GCM" and "A256GCM").
algorithms and key sizes is OPTIONAL. Support for other algorithms and key sizes is OPTIONAL.
9. URI for Declaring that Content is a JWT 9. URI for Declaring that Content is a JWT
This specification registers the URN This specification registers the URN
"urn:ietf:params:oauth:token-type:jwt" for use by applications that "urn:ietf:params:oauth:token-type:jwt" for use by applications that
declare content types using URIs (rather than, for instance, MIME declare content types using URIs (rather than, for instance, MIME
Media Types) to indicate that the content referred to is a JWT. Media Types) to indicate that the content referred to is a JWT.
10. IANA Considerations 10. IANA Considerations
skipping to change at page 16, line 39 skipping to change at page 16, line 31
Expert, that Expert should defer to the judgment of the other Expert, that Expert should defer to the judgment of the other
Expert(s). Expert(s).
10.1.1. Registration Template 10.1.1. Registration Template
Claim Name: Claim Name:
The name requested (e.g., "example"). Because a core goal of this The name requested (e.g., "example"). Because a core goal of this
specification is for the resulting representations to be compact, specification is for the resulting representations to be compact,
it is RECOMMENDED that the name be short -- not to exceed 8 it is RECOMMENDED that the name be short -- not to exceed 8
characters without a compelling reason to do so. This name is characters without a compelling reason to do so. This name is
case sensitive. Names may not match other registered names in a case-sensitive. Names may not match other registered names in a
case insensitive manner unless the Designated Expert(s) state that case-insensitive manner unless the Designated Expert(s) state that
there is a compelling reason to allow an exception in this there is a compelling reason to allow an exception in this
particular case. particular case.
Claim Description:
Brief description of the Claim (e.g., "Example description").
Change Controller: Change Controller:
For Standards Track RFCs, state "IESG". 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.
10.1.2. Initial Registry Contents 10.1.2. Initial Registry Contents
o Claim Name: "iss" o Claim Name: "iss"
o Claim Description: Issuer
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 Claim Name: "sub" o Claim Name: "sub"
o Claim Description: Subject
o Change Controller: IESG 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 Claim Description: Audience
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 4.1.3 of [[ this document ]] o Specification Document(s): Section 4.1.3 of [[ this document ]]
o Claim Name: "exp" o Claim Name: "exp"
o Claim Description: Expiration Time
o Change Controller: IESG 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 Claim Description: Not Before
o Change Controller: IESG 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 Claim Description: Issued At
o Change Controller: IESG 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 Claim Description: JWT ID
o Change Controller: IESG 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 ]]
10.2. Sub-Namespace Registration of 10.2. Sub-Namespace Registration of
urn:ietf:params:oauth:token-type:jwt urn:ietf:params:oauth:token-type:jwt
10.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-
skipping to change at page 18, line 50 skipping to change at page 18, line 50
10.4. Registration of JWE Header Parameter Names 10.4. Registration of JWE Header Parameter Names
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, 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 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"
o Header Parameter Description: Subject
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.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 Description: Audience
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 4.1.3 of [[ this document ]] o Specification Document(s): Section 4.1.3 of [[ this document ]]
11. Security Considerations 11. Security Considerations
All of the security issues 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
skipping to change at page 20, line 16 skipping to change at page 20, line 19
[ECMAScript] [ECMAScript]
Ecma International, "ECMAScript Language Specification, Ecma International, "ECMAScript Language Specification,
5.1 Edition", ECMA 262, June 2011. 5.1 Edition", ECMA 262, June 2011.
[IANA.MediaTypes] [IANA.MediaTypes]
Internet Assigned Numbers Authority (IANA), "MIME Media Internet Assigned Numbers Authority (IANA), "MIME Media
Types", 2005. Types", 2005.
[JWA] Jones, M., "JSON Web Algorithms (JWA)", [JWA] Jones, M., "JSON Web Algorithms (JWA)",
draft-ietf-jose-json-web-algorithms (work in progress), draft-ietf-jose-json-web-algorithms (work in progress),
October 2013. November 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), October 2013. (work in progress), November 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),
October 2013. November 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), October 2013. in progress), November 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
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.
[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.
skipping to change at page 25, line 48 skipping to change at page 25, 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 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 ]]
-13
o Added Claim Description registry field.
o Used Header Parameter Description registry field.
o Removed the phrases "JWA signing algorithms" and "JWA encryption
algorithms".
o Removed the term JSON Text Object.
-12 -12
o Tracked the JOSE change refining the "typ" and "cty" definitions o Tracked the JOSE change refining the "typ" and "cty" definitions
to always be MIME Media Types, with the omission of "application/" to always be MIME Media Types, with the omission of "application/"
prefixes recommended for brevity. For compatibility with legacy prefixes recommended for brevity. For compatibility with legacy
implementations, it is RECOMMENDED that "JWT" always be spelled implementations, it is RECOMMENDED that "JWT" always be spelled
using uppercase characters when used as a "typ" or "cty" value. using uppercase characters when used as a "typ" or "cty" value.
As side effects, this change removed the "typ" Claim definition As side effects, this change removed the "typ" Claim definition
and narrowed the uses of the URI and narrowed the uses of the URI
"urn:ietf:params:oauth:token-type:jwt". "urn:ietf:params:oauth:token-type:jwt".
o Updated base64url definition to match JOSE definition. o Updated base64url definition to match JOSE definition.
skipping to change at page 29, line 17 skipping to change at page 29, line 26
Michael B. Jones Michael B. Jones
Microsoft Microsoft
Email: mbj@microsoft.com Email: mbj@microsoft.com
URI: http://self-issued.info/ URI: http://self-issued.info/
John Bradley John Bradley
Ping Identity Ping Identity
Email: ve7jtb@ve7jtb.com Email: ve7jtb@ve7jtb.com
URI: http://www.thread-safe.com/
Nat Sakimura Nat Sakimura
Nomura Research Institute Nomura Research Institute
Email: n-sakimura@nri.co.jp Email: n-sakimura@nri.co.jp
URI: http://nat.sakimura.org/
 End of changes. 48 change blocks. 
62 lines changed or deleted 82 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/