draft-ietf-oauth-json-web-token-17.txt   draft-ietf-oauth-json-web-token-18.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: September 3, 2014 Ping Identity Expires: September 4, 2014 Ping Identity
N. Sakimura N. Sakimura
NRI NRI
March 2, 2014 March 3, 2014
JSON Web Token (JWT) JSON Web Token (JWT)
draft-ietf-oauth-json-web-token-17 draft-ietf-oauth-json-web-token-18
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 September 3, 2014. This Internet-Draft will expire on September 4, 2014.
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 3, line 12 skipping to change at page 3, line 12
10.4. Registration of JWE Header Parameter Names . . . . . . . . 19 10.4. Registration of JWE Header Parameter Names . . . . . . . . 19
10.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 19 10.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 19
11. Security Considerations . . . . . . . . . . . . . . . . . . . 19 11. Security Considerations . . . . . . . . . . . . . . . . . . . 19
12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 20 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 20
12.1. Normative References . . . . . . . . . . . . . . . . . . . 20 12.1. Normative References . . . . . . . . . . . . . . . . . . . 20
12.2. Informative References . . . . . . . . . . . . . . . . . . 21 12.2. Informative References . . . . . . . . . . . . . . . . . . 21
Appendix A. JWT Examples . . . . . . . . . . . . . . . . . . . . 22 Appendix A. JWT Examples . . . . . . . . . . . . . . . . . . . . 22
A.1. Example Encrypted JWT . . . . . . . . . . . . . . . . . . 22 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 . . . . . . . 24 Appendix B. Relationship of JWTs to SAML Assertions . . . . . . . 25
Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs) . . 25 Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs) . . 25
Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 25 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 25
Appendix E. Document History . . . . . . . . . . . . . . . . . . 26 Appendix E. Document History . . . . . . . . . . . . . . . . . . 26
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 30 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 30
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
skipping to change at page 4, line 39 skipping to change at page 4, line 39
2. Terminology 2. Terminology
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 Base64url Encoding
Base64 encoding using the URL- and filename-safe character set Base64 encoding using the URL- and filename-safe character set
defined in Section 5 of RFC 4648 [RFC4648], with all trailing '=' defined in Section 5 of RFC 4648 [RFC4648], with all trailing '='
characters omitted (as permitted by Section 3.2). (See Appendix C characters omitted (as permitted by Section 3.2) and without the
of [JWS] for notes on implementing base64url encoding without inclusion of any line breaks, white space, or other additional
padding.) characters. (See Appendix C of [JWS] for notes on implementing
base64url encoding without padding.)
JWT Header JWT Header
A JSON object that describes the cryptographic operations applied A JSON object that describes the cryptographic operations applied
to the JWT. When the JWT is digitally signed or MACed, the JWT 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 Header is a JWS Header. When the JWT is encrypted, the JWT Header
is a JWE Header. is a JWE Header.
Header Parameter Header Parameter
A name/value pair that is member of the JWT Header. A name/value pair that is member of the JWT Header.
skipping to change at page 8, line 29 skipping to change at page 8, line 29
MUST be unique; recipients MUST either reject JWTs with duplicate MUST be unique; recipients 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 SHOULD be ignored. by implementations MUST be ignored.
There are three classes of JWT Claim Names: Registered Claim Names, There are three classes of JWT Claim Names: Registered Claim Names,
Public Claim Names, and Private Claim Names. Public Claim Names, and Private Claim Names.
4.1. Registered Claim Names 4.1. Registered Claim Names
The following Claim Names are registered in the IANA JSON Web Token The following Claim Names are registered in the IANA JSON Web Token
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 or implement in all cases,
starting point for a set of useful, interoperable claims. All the but rather, provide a starting point for a set of useful,
names are short because a core goal of JWTs is for the representation interoperable claims. Applications using JWTs should define which
to be compact. specific claims they use and when they are required or optional. All
the names are short because a core goal of JWTs is for the
representation 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 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 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, then the JWT MUST be rejected. In the general case, the "aud" claim when this claim is present, then the JWT MUST be
"aud" value is an array of case-sensitive strings, each containing a rejected. In the general case, the "aud" value is an array of case-
StringOrURI value. In the special case when the JWT has one sensitive strings, each containing a StringOrURI value. In the
audience, the "aud" value MAY be a single case-sensitive string special case when the JWT has one audience, the "aud" value MAY be a
containing a StringOrURI value. The interpretation of audience single case-sensitive string containing a StringOrURI value. The
values is generally application specific. Use of this claim is interpretation of audience values is generally application specific.
OPTIONAL. Use of this claim is OPTIONAL.
4.1.4. "exp" (Expiration Time) Claim 4.1.4. "exp" (Expiration Time) Claim
The "exp" (expiration time) claim identifies the expiration time on The "exp" (expiration time) claim identifies the expiration time on
or after which the JWT MUST NOT be accepted for processing. The or after which the JWT MUST NOT be accepted for processing. The
processing of the "exp" claim requires that the current date/time processing of the "exp" claim requires that the current date/time
MUST be before the expiration date/time listed in the "exp" claim. MUST be before the expiration date/time listed in the "exp" claim.
Implementers MAY provide for some small leeway, usually no more than Implementers MAY provide for some small leeway, usually no more than
a few minutes, to account for clock skew. Its value MUST be a number a few minutes, to account for clock skew. Its value MUST be a number
containing an IntDate value. Use of this claim is OPTIONAL. containing an IntDate value. Use of this claim is OPTIONAL.
skipping to change at page 10, line 48 skipping to change at page 10, line 48
additional properties of the JWT. The member names within the JWT additional properties of the JWT. The member names within the JWT
Header are referred to as Header Parameter Names. These names MUST Header are referred to as Header Parameter Names. These names MUST
be unique; recipients MUST either reject JWTs with duplicate Header be unique; recipients MUST either reject JWTs with duplicate Header
Parameter Names or use a JSON parser that returns only the lexically Parameter Names or use a JSON parser that returns only the lexically
last duplicate member name, as specified in Section 15.12 (The JSON last duplicate member name, as specified in Section 15.12 (The JSON
Object) of ECMAScript 5.1 [ECMAScript]. The corresponding values are Object) of ECMAScript 5.1 [ECMAScript]. The corresponding values are
referred to as Header Parameter Values. referred to as Header Parameter Values.
JWS Header Parameters are defined by [JWS]. JWE Header Parameters JWS Header Parameters are defined by [JWS]. JWE Header Parameters
are defined by [JWE]. This specification further specifies the use are defined by [JWE]. This specification further specifies the use
of the following Header Parameter in both the cases where the JWT is of the following Header Parameters 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"
skipping to change at page 11, line 43 skipping to change at page 11, line 43
In some applications using encrypted JWTs, it is useful to have an In some applications using encrypted JWTs, it is useful to have an
unencrypted representation of some Claims. This might be used, for unencrypted representation of some Claims. This might be used, for
instance, in application processing rules to determine whether and instance, in application processing rules to determine whether and
how to process the JWT before it is decrypted. how to process the JWT before it is decrypted.
This specification allows Claims present in the JWT Claims Set to be This specification allows Claims present in the JWT Claims Set to be
replicated as Header Parameters in a JWT that is a JWE, as needed by replicated as Header Parameters in a JWT that is a JWE, as needed by
the application. If such replicated Claims are present, the the application. If such replicated Claims are present, the
application receiving them SHOULD verify that their values are application receiving them SHOULD verify that their values are
identical. It is the responsibility of the application to ensure identical, unless the application defines other specific processing
that only claims that are safe to be transmitted in an unencrypted rules for these Claims. It is the responsibility of the application
manner are replicated as Header Parameter Values in the JWT. to ensure that only claims that are safe to be transmitted in an
unencrypted manner are replicated as Header Parameter Values in the
JWT.
This specification registers the "iss" (issuer), "sub" (subject), and Section 10.4.1 of this specification registers the "iss" (issuer),
"aud" (audience) Header Parameter Names for the purpose of providing "sub" (subject), and "aud" (audience) Header Parameter Names for the
unencrypted replicas of these Claims in encrypted JWTs for purpose of providing unencrypted replicas of these Claims in
applications that need them. Other specifications MAY similarly encrypted JWTs for applications that need them. Other specifications
register other names that are registered Claim Names as Header MAY similarly register other names that are registered Claim Names as
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 "none" JWS "alg" Header Parameter Value
defined in JSON Web Algorithms (JWA) [JWA]; it is a JWS with the defined in JSON Web Algorithms (JWA) [JWA]; it is a JWS with the
empty string for its JWS Signature value. empty string for its JWS Signature value.
skipping to change at page 13, line 7 skipping to change at page 13, line 13
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. Rules for Creating and Validating a JWT
To create a JWT, one MUST perform these steps. 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 JWT Header containing the desired set of Header 3. Create a JWT Header containing the desired set of Header
Parameters. The JWT MUST conform to either the [JWS] or [JWE] Parameters. The JWT MUST conform to either the [JWS] or [JWE]
specifications. Note that white space is explicitly allowed in specifications. Note that white space is explicitly allowed in
the representation and no canonicalization need be performed the representation and no canonicalization need be performed
before encoding. before encoding.
4. Base64url encode the octets of the UTF-8 representation of the 4. Depending upon whether the JWT is a JWS or JWE, there are two
JWT Header. Let this be the Encoded JWT Header.
5. 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 JWT Header as the
JWS Header and the Message as the JWS Payload; all steps JWS Header and the Message as the JWS Payload; all steps
specified in [JWS] for creating a JWS MUST be followed. specified in [JWS] for creating a JWS MUST 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 JWT Header
as the JWE Header and the Message as the JWE Plaintext; all as the JWE Header and the Message as the JWE Plaintext; all
steps specified in [JWE] for creating a JWE MUST be followed. steps specified in [JWE] for creating a JWE MUST be followed.
6. 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 JWT Header created
in that step. in that step.
7. 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 JWT 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 JWT Header MUST be successfully base64url decoded
skipping to change at page 20, line 21 skipping to change at page 20, line 22
considered valid in many jurisdictions. considered valid in many jurisdictions.
Note that potential concerns about security issues related to the Note that potential concerns about security issues related to the
order of signing and encryption operations are already addressed by order of signing and encryption operations are already addressed by
the underlying JWS and JWE specifications; in particular, because JWE the underlying JWS and JWE specifications; in particular, because JWE
only supports the use of authenticated encryption algorithms, only supports the use of authenticated encryption algorithms,
cryptographic concerns about the potential need to sign after cryptographic concerns about the potential need to sign after
encryption that apply in many contexts do not apply to this encryption that apply in many contexts do not apply to this
specification. specification.
The contents of a JWT cannot be relied upon in a trust decision
unless its contents have been cryptographically secured and bound to
the context necessary for the trust decision. In particular, the
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
of the JWT.
12. References 12. References
12.1. Normative References 12.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
skipping to change at page 26, line 20 skipping to change at page 26, line 28
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 ]]
-18
o Clarified that the base64url encoding includes no line breaks,
white space, or other additional characters.
o Removed circularity in the audience claim definition.
o Clarified that it is entirely up to applications which claims to
use.
o Changed "SHOULD" to "MUST" in "in the absence of such
requirements, all claims that are not understood by
implementations MUST be ignored".
o Clarified that applications can define their own processing rules
for claims replicated in header parameters, rather than always
requiring that they be identical in the JWT Header and JWT Claims
Set.
o Removed a JWT creation step that duplicated a step in the
underlying JWS or JWE creation.
o Added security considerations about using JWTs in trust decisions.
-17 -17
o Corrected RFC 2119 terminology usage. o Corrected RFC 2119 terminology usage.
o Replaced references to draft-ietf-json-rfc4627bis with RFC 7158. o Replaced references to draft-ietf-json-rfc4627bis with RFC 7158.
-16 -16
o Changed some references from being normative to informative, per o Changed some references from being normative to informative, per
JOSE issue #90. JOSE issue #90.
 End of changes. 21 change blocks. 
40 lines changed or deleted 73 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/