draft-ietf-oauth-json-web-token-31.txt   draft-ietf-oauth-json-web-token-32.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: May 23, 2015 Ping Identity Expires: June 12, 2015 Ping Identity
N. Sakimura N. Sakimura
NRI NRI
November 19, 2014 December 9, 2014
JSON Web Token (JWT) JSON Web Token (JWT)
draft-ietf-oauth-json-web-token-31 draft-ietf-oauth-json-web-token-32
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 38 skipping to change at page 1, line 38
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 May 23, 2015. This Internet-Draft will expire on June 12, 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 39 skipping to change at page 2, line 39
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. Creating and Validating JWTs . . . . . . . . . . . . . . . . . 13 7. Creating and Validating JWTs . . . . . . . . . . . . . . . . . 13
7.1. Creating a JWT . . . . . . . . . . . . . . . . . . . . . . 13 7.1. Creating a JWT . . . . . . . . . . . . . . . . . . . . . . 13
7.2. Validating a JWT . . . . . . . . . . . . . . . . . . . . . 14 7.2. Validating a JWT . . . . . . . . . . . . . . . . . . . . . 14
7.3. String Comparison Rules . . . . . . . . . . . . . . . . . 15 7.3. String Comparison Rules . . . . . . . . . . . . . . . . . 15
8. Implementation Requirements . . . . . . . . . . . . . . . . . 16 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 . . . . . . . . . . . . . . . . . . . . . 17 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16
10.1. JSON Web Token Claims Registry . . . . . . . . . . . . . . 17 10.1. JSON Web Token Claims Registry . . . . . . . . . . . . . . 16
10.1.1. Registration Template . . . . . . . . . . . . . . . . 18 10.1.1. Registration Template . . . . . . . . . . . . . . . . 18
10.1.2. Initial Registry Contents . . . . . . . . . . . . . . 18 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 . . . . . . . . . . . 19 urn:ietf:params:oauth:token-type:jwt . . . . . . . . . . . 19
10.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 19 10.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 19
10.3. Media Type Registration . . . . . . . . . . . . . . . . . 19 10.3. Media Type Registration . . . . . . . . . . . . . . . . . 19
10.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 20 10.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 19
10.4. Header Parameter Names Registration . . . . . . . . . . . 20 10.4. Header Parameter Names Registration . . . . . . . . . . . 20
10.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 20 10.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 20
11. Security Considerations . . . . . . . . . . . . . . . . . . . 21 11. Security Considerations . . . . . . . . . . . . . . . . . . . 21
11.1. Trust Decisions . . . . . . . . . . . . . . . . . . . . . 21 11.1. Trust Decisions . . . . . . . . . . . . . . . . . . . . . 21
11.2. Signing and Encryption Order . . . . . . . . . . . . . . . 21 11.2. Signing and Encryption Order . . . . . . . . . . . . . . . 21
12. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 22 12. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 22
13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22
13.1. Normative References . . . . . . . . . . . . . . . . . . . 22 13.1. Normative References . . . . . . . . . . . . . . . . . . . 22
13.2. Informative References . . . . . . . . . . . . . . . . . . 23 13.2. Informative References . . . . . . . . . . . . . . . . . . 23
Appendix A. JWT Examples . . . . . . . . . . . . . . . . . . . . 24 Appendix A. JWT Examples . . . . . . . . . . . . . . . . . . . . 24
A.1. Example Encrypted JWT . . . . . . . . . . . . . . . . . . 24 A.1. Example Encrypted JWT . . . . . . . . . . . . . . . . . . 24
A.2. Example Nested JWT . . . . . . . . . . . . . . . . . . . . 25 A.2. Example Nested JWT . . . . . . . . . . . . . . . . . . . . 25
Appendix B. Relationship of JWTs to SAML Assertions . . . . . . . 27 Appendix B. Relationship of JWTs to SAML Assertions . . . . . . . 26
Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs) . . 27 Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs) . . 27
Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 27 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 27
Appendix E. Document History . . . . . . . . . . . . . . . . . . 28 Appendix E. Document History . . . . . . . . . . . . . . . . . . 28
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 34 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 34
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 6, line 32 skipping to change at page 6, line 32
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 before or after any JSON values or space and/or line breaks before or after any JSON values or
structural characters, in accordance with Section 2 of RFC 7159 structural characters, in accordance with Section 2 of RFC 7159
[RFC7159]. [RFC7159].
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, the
object, the JWT is represented as a JWS and the claims are digitally JWT is represented as a JWS and the claims are digitally signed or
signed or MACed, with the JWT Claims Set being the JWS Payload. If MACed, with the JWT Claims Set being the JWS Payload. If the JOSE
the JOSE Header is for a JWE object, the JWT is represented as a JWE Header is for a JWE, the JWT is represented as a JWE and the claims
and the claims are encrypted, with the JWT Claims Set being the JWE are encrypted, with the JWT Claims Set being the JWE Plaintext. A
Plaintext. A JWT may be enclosed in another JWE or JWS structure to JWT may be enclosed in another JWE or JWS structure to create a
create a Nested JWT, enabling nested signing and encryption to be 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 using the JWS Compact
Compact Serialization or the JWE Compact Serialization. Serialization or JWE using the JWE Compact Serialization.
3.1. Example JWT 3.1. Example JWT
The following example JOSE Header declares that the encoded object is The following example JOSE Header declares that the encoded object is
a JSON Web Token (JWT) and the JWT is a JWS that is MACed using the a JSON Web Token (JWT) and the JWT is a JWS that is MACed using the
HMAC SHA-256 algorithm: HMAC SHA-256 algorithm:
{"typ":"JWT", {"typ":"JWT",
"alg":"HS256"} "alg":"HS256"}
skipping to change at page 13, line 26 skipping to change at page 13, line 24
eyJhbGciOiJub25lIn0 eyJhbGciOiJub25lIn0
. .
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
. .
7. Creating and Validating JWTs 7. Creating and Validating JWTs
7.1. Creating a JWT 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 are performed. 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.
skipping to change at page 14, line 18 skipping to change at page 14, line 14
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 7.2. Validating a JWT
When validating a JWT, the following steps MUST be taken. The order When validating a JWT, the following steps are performed. 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. Verify that the JWT contains at least one period ('.') 1. Verify that the JWT contains at least one period ('.')
character. 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.
skipping to change at page 20, line 41 skipping to change at page 20, line 35
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 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 JWEs, per Section 5.3.
10.4.1. Registry Contents 10.4.1. Registry Contents
o Header Parameter Name: "iss" o Header Parameter Name: "iss"
o Header Parameter Description: Issuer o Header Parameter Description: Issuer
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 4.1.1 of [[ this document ]] o Specification Document(s): Section 4.1.1 of [[ this document ]]
o Header Parameter Name: "sub" o Header Parameter Name: "sub"
o Header Parameter Description: Subject 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 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 that are pertinent to any cryptographic All of the security issues that are pertinent to any cryptographic
application must be addressed by JWT/JWS/JWE/JWK agents. Among these application must be addressed by JWT/JWS/JWE/JWK agents. Among these
skipping to change at page 22, line 36 skipping to change at page 22, line 31
[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),
November 2014. December 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),
November 2014. December 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), November 2014. in progress), December 2014.
[RFC20] Cerf, V., "ASCII format for Network Interchange", RFC 20, [RFC20] Cerf, V., "ASCII format for Network Interchange", RFC 20,
October 1969. October 1969.
[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.
skipping to change at page 28, line 30 skipping to change at page 28, line 21
Turner, and Tom Yu. 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 ]]
-32
o Replaced uses of the phrases "JWS object" and "JWE object" with
"JWS" and "JWE".
o Applied other minor editorial improvements.
-31 -31
o Updated the example IANA registration request subject line. o Updated the example IANA registration request subject line.
-30 -30
o Applied privacy wording supplied by Stephen Farrell. o Applied privacy wording supplied by Stephen Farrell.
o Clarified where white space and line breaks may occur in JSON o Clarified where white space and line breaks may occur in JSON
objects by referencing Section 2 of RFC 7159. objects by referencing Section 2 of RFC 7159.
 End of changes. 18 change blocks. 
25 lines changed or deleted 31 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/