< draft-ietf-oauth-json-web-token-27.txt   draft-ietf-oauth-json-web-token-28.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: March 29, 2015 Ping Identity Expires: April 17, 2015 Ping Identity
N. Sakimura N. Sakimura
NRI NRI
September 25, 2014 October 14, 2014
JSON Web Token (JWT) JSON Web Token (JWT)
draft-ietf-oauth-json-web-token-27 draft-ietf-oauth-json-web-token-28
Abstract Abstract
JSON Web Token (JWT) is a compact, URL-safe means of representing JSON Web Token (JWT) is a compact, URL-safe means of representing
claims to be transferred between two parties. The claims in a JWT claims to be transferred between two parties. The claims in a JWT
are encoded as a JavaScript Object Notation (JSON) object that is are encoded as a JavaScript Object Notation (JSON) object that is
used as the payload of a JSON Web Signature (JWS) structure or as the used as the payload of a JSON Web Signature (JWS) structure or as the
plaintext of a JSON Web Encryption (JWE) structure, enabling the plaintext of a JSON Web Encryption (JWE) structure, enabling the
claims to be digitally signed or MACed and/or encrypted. claims to be digitally signed or MACed and/or encrypted.
The suggested pronunciation of JWT is the same as the English word
"jot".
Status of this Memo Status of this Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
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 March 29, 2015. This Internet-Draft will expire on April 17, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 36 skipping to change at page 2, line 33
4.1.6. "iat" (Issued At) Claim . . . . . . . . . . . . . . . 10 4.1.6. "iat" (Issued At) Claim . . . . . . . . . . . . . . . 10
4.1.7. "jti" (JWT ID) Claim . . . . . . . . . . . . . . . . . 10 4.1.7. "jti" (JWT ID) Claim . . . . . . . . . . . . . . . . . 10
4.2. Public Claim Names . . . . . . . . . . . . . . . . . . . . 10 4.2. Public Claim Names . . . . . . . . . . . . . . . . . . . . 10
4.3. Private Claim Names . . . . . . . . . . . . . . . . . . . 10 4.3. Private Claim Names . . . . . . . . . . . . . . . . . . . 10
5. JOSE Header . . . . . . . . . . . . . . . . . . . . . . . . . 10 5. JOSE Header . . . . . . . . . . . . . . . . . . . . . . . . . 10
5.1. "typ" (Type) Header Parameter . . . . . . . . . . . . . . 11 5.1. "typ" (Type) Header Parameter . . . . . . . . . . . . . . 11
5.2. "cty" (Content Type) Header Parameter . . . . . . . . . . 11 5.2. "cty" (Content Type) Header Parameter . . . . . . . . . . 11
5.3. Replicating Claims as Header Parameters . . . . . . . . . 11 5.3. Replicating Claims as Header Parameters . . . . . . . . . 11
6. Unsecured JWTs . . . . . . . . . . . . . . . . . . . . . . . . 12 6. Unsecured JWTs . . . . . . . . . . . . . . . . . . . . . . . . 12
6.1. Example Unsecured JWT . . . . . . . . . . . . . . . . . . 12 6.1. Example Unsecured JWT . . . . . . . . . . . . . . . . . . 12
7. Rules for Creating and Validating a JWT . . . . . . . . . . . 13 7. Creating and Validating JWTs . . . . . . . . . . . . . . . . . 13
7.1. String Comparison Rules . . . . . . . . . . . . . . . . . 15 7.1. Creating a JWT . . . . . . . . . . . . . . . . . . . . . . 13
8. Implementation Requirements . . . . . . . . . . . . . . . . . 15 7.2. Validating a JWT . . . . . . . . . . . . . . . . . . . . . 14
7.3. String Comparison Rules . . . . . . . . . . . . . . . . . 15
8. Implementation Requirements . . . . . . . . . . . . . . . . . 16
9. URI for Declaring that Content is a JWT . . . . . . . . . . . 16 9. URI for Declaring that Content is a JWT . . . . . . . . . . . 16
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16
10.1. JSON Web Token Claims Registry . . . . . . . . . . . . . . 16 10.1. JSON Web Token Claims Registry . . . . . . . . . . . . . . 16
10.1.1. Registration Template . . . . . . . . . . . . . . . . 17 10.1.1. Registration Template . . . . . . . . . . . . . . . . 18
10.1.2. Initial Registry Contents . . . . . . . . . . . . . . 17 10.1.2. Initial Registry Contents . . . . . . . . . . . . . . 18
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 . . . . . . . . . . . 19
10.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 18 10.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 19
10.3. Media Type Registration . . . . . . . . . . . . . . . . . 18 10.3. Media Type Registration . . . . . . . . . . . . . . . . . 19
10.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 18 10.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 19
10.4. Header Parameter Names Registration . . . . . . . . . . . 19 10.4. Header Parameter Names Registration . . . . . . . . . . . 20
10.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 19 10.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 20
11. Security Considerations . . . . . . . . . . . . . . . . . . . 21
11. Security Considerations . . . . . . . . . . . . . . . . . . . 20 11.1. Trust Decisions . . . . . . . . . . . . . . . . . . . . . 21
11.1. Trust Decisions . . . . . . . . . . . . . . . . . . . . . 20 11.2. Signing and Encryption Order . . . . . . . . . . . . . . . 21
11.2. Signing and Encryption Order . . . . . . . . . . . . . . . 20 12. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 22
12. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 20 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22
13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21 13.1. Normative References . . . . . . . . . . . . . . . . . . . 22
13.1. Normative References . . . . . . . . . . . . . . . . . . . 21 13.2. Informative References . . . . . . . . . . . . . . . . . . 23
13.2. Informative References . . . . . . . . . . . . . . . . . . 22 Appendix A. JWT Examples . . . . . . . . . . . . . . . . . . . . 24
Appendix A. JWT Examples . . . . . . . . . . . . . . . . . . . . 23 A.1. Example Encrypted JWT . . . . . . . . . . . . . . . . . . 24
A.1. Example Encrypted JWT . . . . . . . . . . . . . . . . . . 23 A.2. Example Nested JWT . . . . . . . . . . . . . . . . . . . . 25
A.2. Example Nested JWT . . . . . . . . . . . . . . . . . . . . 24 Appendix B. Relationship of JWTs to SAML Assertions . . . . . . . 26
Appendix B. Relationship of JWTs to SAML Assertions . . . . . . . 25 Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs) . . 27
Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs) . . 26 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 27
Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 26 Appendix E. Document History . . . . . . . . . . . . . . . . . . 28
Appendix E. Document History . . . . . . . . . . . . . . . . . . 27 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 34
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 40 skipping to change at page 4, line 40
These terms defined by the JSON Web Signature (JWS) [JWS] These terms defined by the JSON Web Signature (JWS) [JWS]
specification are incorporated into this specification: "JSON Web specification are incorporated into this specification: "JSON Web
Signature (JWS)", "Base64url Encoding", "Header Parameter", "JOSE Signature (JWS)", "Base64url Encoding", "Header Parameter", "JOSE
Header", "JWS Compact Serialization", "JWS Payload", "JWS Signature", Header", "JWS Compact Serialization", "JWS Payload", "JWS Signature",
and "Unsecured JWS". and "Unsecured JWS".
These terms defined by the JSON Web Encryption (JWE) [JWE] These terms defined by the JSON Web Encryption (JWE) [JWE]
specification are incorporated into this specification: "JSON Web specification are incorporated into this specification: "JSON Web
Encryption (JWE)", "Content Encryption Key (CEK)", "JWE Compact Encryption (JWE)", "Content Encryption Key (CEK)", "JWE Compact
Serialization", "JWE Encrypted Key", "JWE Initialization Vector", Serialization", "JWE Encrypted Key", "JWE Initialization Vector", and
"JWE Plaintext". "JWE Plaintext".
These terms defined by the Internet Security Glossary, Version 2
[RFC4949] are incorporated into this specification: "Ciphertext" and
"Plaintext".
These terms are defined by this specification: 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.
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.
skipping to change at page 6, line 30 skipping to change at page 6, line 31
or more name/value pairs (or members), where the names are strings or more name/value pairs (or members), where the names are strings
and the values are arbitrary JSON values. These members are the and the values are arbitrary JSON values. These members are the
claims represented by the JWT. This JSON object MAY contain white claims represented by the JWT. This JSON object MAY contain white
space and/or line breaks. space and/or line breaks.
The member names within the JWT Claims Set are referred to as Claim The member names within the JWT Claims Set are referred to as Claim
Names. The corresponding values are referred to as Claim Values. Names. The corresponding values are referred to as Claim Values.
The contents of the JOSE Header describe the cryptographic operations The contents of the JOSE Header describe the cryptographic operations
applied to the JWT Claims Set. If the JOSE Header is for a JWS applied to the JWT Claims Set. If the JOSE Header is for a JWS
object, the JWT is represented as a JWS, and the claims are digitally object, the JWT is represented as a JWS and the claims are digitally
signed or MACed, with the JWT Claims Set being the JWS Payload. If signed or MACed, with the JWT Claims Set being the JWS Payload. If
the JOSE Header is for a JWE object, the JWT is represented as a JWE, the JOSE Header is for a JWE object, the JWT is represented as a JWE
and the claims are encrypted, with the JWT Claims Set being the JWE and the claims are encrypted, with the JWT Claims Set being the JWE
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.
skipping to change at page 8, line 23 skipping to change at page 8, line 26
. .
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.
4. JWT Claims 4. JWT Claims
The JWT Claims Set represents a JSON object whose members are the The JWT Claims Set represents a JSON object whose members are the
claims conveyed by the JWT. The Claim Names within a JWT Claims Set claims conveyed by the JWT. The Claim Names within a JWT Claims Set
MUST be unique; recipients MUST either reject JWTs with duplicate MUST be unique; JWT parsers MUST either reject JWTs with duplicate
Claim Names or use a JSON parser that returns only the lexically last Claim Names or use a JSON parser that returns only the lexically last
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 MUST be ignored. by implementations MUST be ignored.
skipping to change at page 9, line 16 skipping to change at page 9, line 16
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 MUST either be scoped to be
unique in the context of the issuer or MAY be globally unique. The locally unique in the context of the issuer or be globally unique.
processing of this claim is generally application specific. The 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 recipients that the JWT is The "aud" (audience) claim identifies the recipients 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 the audience claim. If the principal identify itself with a value in the 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 when this claim is present, then the JWT MUST be "aud" claim when this claim is present, then the JWT MUST be
skipping to change at page 10, line 19 skipping to change at page 10, line 19
The "iat" (issued at) claim identifies the time at which the JWT was The "iat" (issued at) claim identifies the time at which the JWT was
issued. This claim can be used to determine the age of the JWT. Its issued. This claim can be used to determine the age of the JWT. Its
value MUST be a number containing a NumericDate value. Use of this value MUST be a number containing a NumericDate value. Use of this
claim is OPTIONAL. claim is OPTIONAL.
4.1.7. "jti" (JWT ID) Claim 4.1.7. "jti" (JWT ID) Claim
The "jti" (JWT ID) claim provides a unique identifier for the JWT. The "jti" (JWT ID) claim provides a unique identifier for the JWT.
The identifier value MUST be assigned in a manner that ensures that The identifier value MUST be assigned in a manner that ensures that
there is a negligible probability that the same value will be there is a negligible probability that the same value will be
accidentally assigned to a different data object. The "jti" claim accidentally assigned to a different data object; if the application
can be used to prevent the JWT from being replayed. The "jti" value uses multiple issuers, collisions MUST be prevented among values
is a case-sensitive string. Use of this claim is OPTIONAL. produced by different issuers as well. The "jti" claim can be used
to prevent the JWT from being replayed. The "jti" value 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.
skipping to change at page 13, line 17 skipping to change at page 13, line 20
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):
eyJhbGciOiJub25lIn0 eyJhbGciOiJub25lIn0
. .
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
. .
7. Rules for Creating and Validating a JWT 7. Creating and Validating JWTs
7.1. Creating a JWT
To create a JWT, the following steps MUST be taken. The order of the To create a JWT, the following steps MUST be taken. 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 JOSE 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 specification. 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 Message as the JWS * If the JWT is a JWS, create a JWS using the Message as the JWS
Payload; all steps specified in [JWS] for creating a JWS MUST Payload; all steps specified in [JWS] for creating a JWS MUST
be followed. be followed.
skipping to change at page 14, line 7 skipping to change at page 14, line 12
the JWE Plaintext; all steps specified in [JWE] for creating a the JWE Plaintext; all 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 JOSE Header "cty" (content type) value of "JWT" in the new JOSE Header
created in that step. created in that step.
6. Otherwise, let the resulting JWT be the JWS or JWE. 6. Otherwise, let the resulting JWT be the JWS or JWE.
7.2. Validating a JWT
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 -- treated by the listed steps fails then the JWT MUST be rejected -- treated by
the application as an invalid input. the application as an invalid input.
1. The JWT MUST contain at least one period ('.') character. 1. Verify that the JWT contains at least one period ('.')
character.
2. Let the Encoded JOSE Header be the portion of the JWT before the 2. Let the Encoded JOSE Header be the portion of the JWT before the
first period ('.') character. first period ('.') character.
3. The Encoded JOSE Header MUST be successfully base64url decoded 3. Base64url decode the Encoded JOSE Header following the
following the restriction given in this specification that no restriction that no line breaks, white space, or other
padding characters have been used. additional characters have been used.
4. The resulting JOSE Header MUST be completely valid JSON syntax 4. Verify that the resulting octet sequence is a UTF-8 encoded
conforming to RFC 7159 [RFC7159]. representation of a completely valid JSON object conforming to
RFC 7159 [RFC7159]; let the JOSE Header be this JSON object.
5. The resulting JOSE Header MUST be validated to only include 5. Verify that the resulting JOSE Header includes only parameters
parameters and values whose syntax and semantics are both and values whose syntax and semantics are both understood and
understood and supported or that are specified as being ignored supported or that are specified as being ignored when not
when not understood. 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, follow the steps specified in [JWS] for
validating a JWS MUST be followed. Let the Message be the validating a JWS. Let the Message be the result of base64url
result of base64url decoding the JWS Payload. decoding the JWS Payload.
* Else, if the JWT is a JWE, all steps specified in [JWE] for * Else, if the JWT is a JWE, follow the steps specified in
validating a JWE MUST be followed. Let the Message be the [JWE] for validating a JWE. Let the Message be the JWE
JWE Plaintext. Plaintext.
8. If the JOSE 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, base64url decode the Message following the
restriction that no line breaks, white space, or other
additional characters have been used.
10. The JWT Claims Set MUST be completely valid JSON syntax 10. Verify that the resulting octet sequence is a UTF-8 encoded
conforming to RFC 7159 [RFC7159]. representation of a completely valid JSON object conforming to
RFC 7159 [RFC7159]; let the JWT Claims Set be this JSON object.
7.1. String Comparison Rules Finally, note that it is an application decision which algorithms may
be used in a given context. Even if a JWT can be successfully
validated, unless the algorithm(s) used in the JWT are acceptable to
the application, it SHOULD reject the JWT.
7.3. 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 members and values in JSON objects. For example, in checking what
is, the Unicode string encoding "alg" will be checked against the the algorithm is, the Unicode string encoding "alg" will be checked
member names in the JOSE Header to see if there is a matching Header against the member names in the JOSE Header to see if there is a
Parameter name. matching Header Parameter name.
Comparisons between JSON strings and other Unicode strings MUST be The JSON rules for doing member name comparison are described in
performed by comparing Unicode code points without normalization, as Section 8.3 of RFC 7159 [RFC7159]. Since the only string comparison
specified in the String Comparison Rules in Section 5.3 of [JWS]. operations that are performed are equality and inequality, the same
rules can be used for comparing both member names and member values
against known strings.
These comparison rules MUST be used for all JSON string comparisons
except in cases where the definition of the member explicitly calls
out that a different comparison rule is to be used for that member
value. In this specification, only the "typ" and "cty" member values
do not use these comparison rules.
Some applications may include case-insensitive information in a case-
sensitive value, such as including a DNS name as part of the "iss"
(issuer) claim value. In those cases, the application may need to
define a convention for the canonical case to use for representing
the case-insensitive portions, such as lowercasing them, if more than
one party might need to produce the same value so that they can be
compared. (However if all other parties consume whatever value the
producing party emitted verbatim without attempting to compare it to
an independently produced value, then the case used by the producer
will not matter.)
8. Implementation Requirements 8. Implementation Requirements
This section defines which algorithms and features of this This section defines which algorithms and features of this
specification are mandatory to implement. Applications using this specification are mandatory to implement. Applications using this
specification can impose additional requirements upon implementations specification can impose additional requirements upon implementations
that they use. For instance, one application might require support that they use. For instance, one application might require support
for encrypted JWTs and Nested JWTs, while another might require for encrypted JWTs and Nested JWTs, while another might require
support for signing JWTs with ECDSA using the P-256 curve and the support for signing JWTs with ECDSA using the P-256 curve and the
SHA-256 hash algorithm ("ES256"). SHA-256 hash algorithm ("ES256").
skipping to change at page 16, line 40 skipping to change at page 17, line 26
for access token type: example"). [[ Note to the RFC Editor: The name for access token type: example"). [[ Note to the RFC Editor: The name
of the mailing list should be determined in consultation with the of the mailing list should be determined in consultation with the
IESG and IANA. Suggested name: jwt-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. Registration requests that are undetermined for a period successful. Registration requests that are undetermined for a period
longer than 21 days can be brought to the IESG's attention (using the longer than 21 days can be brought to the IESG's attention (using the
iesg@iesg.org mailing list) for resolution. iesg@ietf.org mailing list) for resolution.
Criteria that should be applied by the Designated Expert(s) includes Criteria that should be applied by the Designated Expert(s) includes
determining whether the proposed registration duplicates existing determining whether the proposed registration duplicates existing
functionality, determining whether it is likely to be of general functionality, determining whether it is likely to be of general
applicability or whether it is useful only for a single application, applicability or whether it is useful only for a single application,
and whether the registration makes sense. and whether the registration description is clear.
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.
It is suggested that multiple Designated Experts be appointed who are It is suggested that multiple Designated Experts be appointed who are
able to represent the perspectives of different applications using able to represent the perspectives of different applications using
this specification, in order to enable broadly-informed review of this specification, in order to enable broadly-informed review of
registration decisions. In cases where a registration decision could registration decisions. In cases where a registration decision could
be perceived as creating a conflict of interest for a particular be perceived as creating a conflict of interest for a particular
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).
[[ Note to the RFC Editor and IANA: Pearl Liang of ICANN had
requested that the draft supply the following proposed registry
description information.
o Protocol Category: JSON Web Token (JWT)
o Registry Location: http://www.iana.org/assignments/jwt
o Webpage Title: (same as the protocol category)
o Registry Name: JSON Web Token Claims
]]
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
skipping to change at page 18, line 49 skipping to change at page 19, line 49
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: IESG o Change Controller: IESG
o Specification Document(s): [[this document]] o Specification Document(s): [[this document]]
10.3. Media Type Registration 10.3. Media Type Registration
10.3.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 Types registry [IANA.MediaTypes], which [RFC2046] in the MIME Media Types registry [IANA.MediaTypes] in the
can be used to indicate that the content is a JWT. manner described in RFC 6838 [RFC6838], which 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: 8bit; JWT values are encoded as a series o Encoding considerations: 8bit; JWT values are encoded as a series
of base64url encoded values (some of which may be the empty of base64url encoded values (some of which may be the empty
string) 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, Android, Windows Azure, numerous
others
o Fragment identifier considerations: n/a
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
o Provisional registration? No
10.4. Header Parameter Names Registration 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 in JWE objects, per Section 5.3. Header Parameters in JWE objects, per Section 5.3.
10.4.1. Registry Contents 10.4.1. Registry Contents
skipping to change at page 20, line 32 skipping to change at page 21, line 35
The contents of a JWT cannot be relied upon in a trust decision The contents of a JWT cannot be relied upon in a trust decision
unless its contents have been cryptographically secured and bound to unless its contents have been cryptographically secured and bound to
the context necessary for the trust decision. In particular, the the context necessary for the trust decision. In particular, the
key(s) used to sign and/or encrypt the JWT will typically need to key(s) used to sign and/or encrypt the JWT will typically need to
verifiably be under the control of the party identified as the issuer verifiably be under the control of the party identified as the issuer
of the JWT. of the JWT.
11.2. Signing and Encryption Order 11.2. Signing and Encryption Order
While syntactically the signing and encryption operations for Nested While syntactically the signing and encryption operations for Nested
JWTs may be applied in any order, normally senders should sign the JWTs may be applied in any order, if both signing and encryption are
message and then encrypt the result (thus encrypting the signature). necessary, normally producers should sign the message and then
This prevents attacks in which the signature is stripped, leaving encrypt the result (thus encrypting the signature). This prevents
just an encrypted message, as well as providing privacy for the attacks in which the signature is stripped, leaving just an encrypted
signer. Furthermore, signatures over encrypted text are not message, as well as providing privacy for the signer. Furthermore,
considered valid in many jurisdictions. signatures over encrypted text are not 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.
12. Privacy Considerations 12. Privacy Considerations
A JWT may contain privacy-sensitive information. When this is the A JWT may contain privacy-sensitive information. When this is the
case, measures must be taken to prevent disclosure of this case, measures MUST be taken to prevent disclosure of this
information to unintended parties. One way to achieve this is to use information to unintended parties. One way to achieve this is to use
an encrypted JWT. Another way is to ensure that JWTs containing an encrypted JWT and authenticate the recipient. Another way is to
unencrypted privacy-sensitive information are only transmitted over ensure that JWTs containing unencrypted privacy-sensitive information
encrypted channels or protocols, such as TLS. are only transmitted using protocols utilizing encryption that
support endpoint authentication, such as TLS. Of course, including
only necessary privacy-sensitive information in a JWT is the most
basic means of minimizing any potential privacy issues.
13. References 13. References
13.1. Normative References 13.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] [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),
September 2014. October 2014.
[JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", [JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
draft-ietf-jose-json-web-encryption (work in progress), draft-ietf-jose-json-web-encryption (work in progress),
September 2014. October 2014.
[JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", draft-ietf-jose-json-web-signature (work Signature (JWS)", draft-ietf-jose-json-web-signature (work
in progress), September 2014. in progress), October 2014.
[RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part Two: Media Types", RFC 2046, Extensions (MIME) Part Two: Media Types", RFC 2046,
November 1996. November 1996.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005. RFC 3986, January 2005.
[RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace [RFC4949] Shirey, R., "Internet Security Glossary, Version 2",
for OAuth", RFC 6755, October 2012. RFC 4949, August 2007.
[RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, March 2014. Interchange Format", RFC 7159, March 2014.
13.2. Informative References 13.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",
skipping to change at page 22, line 42 skipping to change at page 23, line 48
Internet: Timestamps", RFC 3339, July 2002. Internet: Timestamps", RFC 3339, July 2002.
[RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally
Unique IDentifier (UUID) URN Namespace", RFC 4122, Unique IDentifier (UUID) URN Namespace", RFC 4122,
July 2005. July 2005.
[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
for OAuth", RFC 6755, October 2012.
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
Specifications and Registration Procedures", BCP 13,
RFC 6838, January 2013.
[SWT] Hardt, D. and Y. Goland, "Simple Web Token (SWT)", [SWT] Hardt, D. and Y. Goland, "Simple Web Token (SWT)",
Version 0.9.5.1, November 2009. Version 0.9.5.1, November 2009.
[W3C.CR-xml11-20021015] [W3C.CR-xml11-20021015]
Cowan, J., "Extensible Markup Language (XML) 1.1", W3C Cowan, J., "Extensible Markup Language (XML) 1.1", W3C
CR CR-xml11-20021015, October 2002. CR CR-xml11-20021015, October 2002.
[W3C.REC-xml-c14n-20010315] [W3C.REC-xml-c14n-20010315]
Boyer, J., "Canonical XML Version 1.0", World Wide Web Boyer, J., "Canonical XML Version 1.0", World Wide Web
Consortium Recommendation REC-xml-c14n-20010315, Consortium Recommendation REC-xml-c14n-20010315,
skipping to change at page 26, line 39 skipping to change at page 28, line 5
Solutions for signing JSON content were previously explored by Magic Solutions for signing JSON content were previously explored by Magic
Signatures [MagicSignatures], JSON Simple Sign [JSS], and Canvas Signatures [MagicSignatures], JSON Simple Sign [JSS], and Canvas
Applications [CanvasApp], all of which influenced this draft. Applications [CanvasApp], all of which influenced this draft.
This specification is the work of the OAuth Working Group, which This specification is the work of the OAuth Working Group, which
includes dozens of active and dedicated participants. In particular, includes dozens of active and dedicated participants. In particular,
the following individuals contributed ideas, feedback, and wording the following individuals contributed ideas, feedback, and wording
that influenced this specification: that influenced this specification:
Dirk Balfanz, Richard Barnes, Brian Campbell, Breno de Medeiros, Dick Dirk Balfanz, Richard Barnes, Brian Campbell, Alissa Cooper, Breno de
Hardt, Joe Hildebrand, Jeff Hodges, Edmund Jay, Yaron Y. Goland, Medeiros, Stephen Farrell, Dick Hardt, Joe Hildebrand, Jeff Hodges,
Warren Kumari, Ben Laurie, James Manger, Prateek Mishra, Kathleen Edmund Jay, Yaron Y. Goland, Warren Kumari, Ben Laurie, Barry Leiba,
Moriarty, Tony Nadalin, Axel Nennker, John Panzer, Emmanuel Raviart, Ted Lemon, James Manger, Prateek Mishra, Kathleen Moriarty, Tony
David Recordon, Eric Rescorla, Jim Schaad, Paul Tarjan, Hannes Nadalin, Axel Nennker, John Panzer, Emmanuel Raviart, David Recordon,
Tschofenig, Sean Turner, and Tom Yu. Eric Rescorla, Jim Schaad, Paul Tarjan, Hannes Tschofenig, Sean
Turner, and Tom Yu.
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 ]]
-28
o Addressed IESG review comments by Alissa Cooper, Barry Leiba,
Stephen Farrell, Ted Lemon, and Richard Barnes.
o Changed the RFC 6755 reference to be informative, based upon
related IESG review feedback on draft-ietf-oauth-saml2-bearer.
-27 -27
o Removed unused reference to RFC 4648. o Removed unused reference to RFC 4648.
o Changed to use the term "authenticated encryption" instead of o Changed to use the term "authenticated encryption" instead of
"encryption", where appropriate. "encryption", where appropriate.
o Changed the registration review period to three weeks. o Changed the registration review period to three weeks.
o Acknowledged additional contributors. o Acknowledged additional contributors.
 End of changes. 45 change blocks. 
99 lines changed or deleted 173 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/