draft-ietf-oauth-json-web-token-21.txt   draft-ietf-oauth-json-web-token-22.txt 
OAuth Working Group M. Jones OAuth Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track J. Bradley Intended status: Standards Track J. Bradley
Expires: December 12, 2014 Ping Identity Expires: December 22, 2014 Ping Identity
N. Sakimura N. Sakimura
NRI NRI
June 10, 2014 June 20, 2014
JSON Web Token (JWT) JSON Web Token (JWT)
draft-ietf-oauth-json-web-token-21 draft-ietf-oauth-json-web-token-22
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 December 12, 2014. This Internet-Draft will expire on December 22, 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 2, line 48 skipping to change at page 2, line 48
8. Implementation Requirements . . . . . . . . . . . . . . . . . 15 8. Implementation Requirements . . . . . . . . . . . . . . . . . 15
9. URI for Declaring that Content is a JWT . . . . . . . . . . . 16 9. URI for Declaring that Content is a JWT . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . 17
10.1.2. Initial Registry Contents . . . . . . . . . . . . . . 17 10.1.2. Initial Registry Contents . . . . . . . . . . . . . . 17
10.2. Sub-Namespace Registration of 10.2. Sub-Namespace Registration of
urn:ietf:params:oauth:token-type:jwt . . . . . . . . . . . 18 urn:ietf:params:oauth:token-type:jwt . . . . . . . . . . . 18
10.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 18 10.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 18
10.3. Media Type Registration . . . . . . . . . . . . . . . . . 18 10.3. Media Type Registration . . . . . . . . . . . . . . . . . 18
10.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 18 10.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 19
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 . . . . . . . . . . . . . . . . . . . 20 11. Security Considerations . . . . . . . . . . . . . . . . . . . 20
11.1. Trust Decisions . . . . . . . . . . . . . . . . . . . . . 20
11.2. Signing and Encryption Order . . . . . . . . . . . . . . . 20
12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21
12.1. Normative References . . . . . . . . . . . . . . . . . . . 21 12.1. Normative References . . . . . . . . . . . . . . . . . . . 21
12.2. Informative References . . . . . . . . . . . . . . . . . . 21 12.2. Informative References . . . . . . . . . . . . . . . . . . 22
Appendix A. JWT Examples . . . . . . . . . . . . . . . . . . . . 22 Appendix A. JWT Examples . . . . . . . . . . . . . . . . . . . . 23
A.1. Example Encrypted JWT . . . . . . . . . . . . . . . . . . 23 A.1. Example Encrypted JWT . . . . . . . . . . . . . . . . . . 23
A.2. Example Nested JWT . . . . . . . . . . . . . . . . . . . . 23 A.2. Example Nested JWT . . . . . . . . . . . . . . . . . . . . 23
Appendix B. Relationship of JWTs to SAML Assertions . . . . . . . 25 Appendix B. Relationship of JWTs to SAML Assertions . . . . . . . 25
Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs) . . 26 Appendix C. Relationship of JWTs to Simple Web Tokens (SWTs) . . 26
Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 26 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 26
Appendix E. Document History . . . . . . . . . . . . . . . . . . 26 Appendix E. Document History . . . . . . . . . . . . . . . . . . 26
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 31 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 31
1. Introduction 1. Introduction
skipping to change at page 11, line 16 skipping to change at page 11, line 16
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 Parameters 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 by JWT applications to declare the MIME Media Type [IANA.MediaTypes]
in contexts where this is useful to the application. This parameter of this complete JWT. This is intended for use by the JWT
has no effect upon the JWT processing. If present, it is RECOMMENDED application when values that are not JWTs could also be present in an
that its value be "JWT" to indicate that this object is a JWT. While application data structure that can contain a JWT object; the
media type names are not case-sensitive, it is RECOMMENDED that "JWT" application can use this value to disambiguate among the different
always be spelled using uppercase characters for compatibility with kinds of objects that might be present. It will typically not be
legacy implementations. Use of this Header Parameter is OPTIONAL. used by applications when it is already known that the object is a
JWT. This parameter 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 media type names are not case-sensitive,
it is RECOMMENDED that "JWT" always be spelled using uppercase
characters for compatibility with legacy implementations. Use of
this Header Parameter is OPTIONAL.
5.2. "cty" (Content Type) Header Parameter 5.2. "cty" (Content Type) Header Parameter
The "cty" (content type) Header Parameter defined by [JWS] and [JWE] The "cty" (content type) Header Parameter defined by [JWS] and [JWE]
is used by this specification to convey structural information about is used by this specification to convey structural information about
the JWT. the JWT.
In the normal case where nested signing or encryption operations are In the normal case where nested signing or encryption operations are
not employed, the use of this Header Parameter is NOT RECOMMENDED. not employed, the use of this Header Parameter is NOT RECOMMENDED.
In the case that nested signing or encryption is employed, this In the case that nested signing or encryption is employed, this
skipping to change at page 20, line 11 skipping to change at page 20, line 17
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 faced by any cryptographic application All of the security issues faced by any cryptographic application
must be faced by a JWT/JWS/JWE/JWK agent. Among these issues are must be faced by a JWT/JWS/JWE/JWK agent. Among these issues are
protecting the user's private and symmetric keys, preventing various protecting the user's asymmetric private and symmetric secret keys,
attacks, and helping the user avoid mistakes such as inadvertently preventing various attacks, and helping avoid mistakes such as
encrypting a message for the wrong recipient. The entire list of inadvertently encrypting a message to the wrong recipient. The
security considerations is beyond the scope of this document. entire list of security considerations is beyond the scope of this
document.
All the security considerations in the JWS specification also apply All the security considerations in the JWS specification also apply
to JWT, as do the JWE security considerations when encryption is to JWT, as do the JWE security considerations when encryption is
employed. In particular, the JWS JSON Security Considerations and employed. In particular, the JWS JSON Security Considerations and
Unicode Comparison Security Considerations apply equally to the JWT Unicode Comparison Security Considerations apply equally to the JWT
Claims Set in the same manner that they do to the JWS Header. Claims Set in the same manner that they do to the JWS Header.
11.1. Trust Decisions
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.
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, normally senders should sign the
message and then encrypt the result (thus encrypting the signature). message and then encrypt the result (thus encrypting the signature).
This prevents attacks in which the signature is stripped, leaving This prevents attacks in which the signature is stripped, leaving
just an encrypted message, as well as providing privacy for the just an encrypted message, as well as providing privacy for the
signer. Furthermore, signatures over encrypted text are not signer. Furthermore, signatures over encrypted text are not
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
Types", 2005. Types", 2005.
skipping to change at page 26, line 48 skipping to change at page 26, line 48
Schaad, Paul Tarjan, Hannes Tschofenig, and Sean Turner. Schaad, Paul Tarjan, Hannes Tschofenig, and Sean Turner.
Hannes Tschofenig and Derek Atkins chaired the OAuth working group Hannes Tschofenig and Derek Atkins chaired the OAuth working group
and Sean Turner, Stephen Farrell, and Kathleen Moriarty served as and Sean Turner, Stephen Farrell, and Kathleen Moriarty served as
Security area directors during the creation of this specification. Security area directors during the creation of this specification.
Appendix E. Document History Appendix E. Document History
[[ to be removed by the RFC Editor before publication as an RFC ]] [[ to be removed by the RFC Editor before publication as an RFC ]]
-22
o Revised the introduction to the Security Considerations section.
Also introduced subsection headings for security considerations
items.
o Added text about when applications typically would and would not
use the "typ" header parameter.
-21 -21
o Removed unnecessary informative JWK spec reference. o Removed unnecessary informative JWK spec reference.
-20 -20
o Changed the RFC 6755 reference to be normative. o Changed the RFC 6755 reference to be normative.
o Changed the JWK reference to be informative. o Changed the JWK reference to be informative.
o Described potential sources of ambiguity in representing the JSON o Described potential sources of ambiguity in representing the JSON
objects used in the examples. The octets of the actual UTF-8 objects used in the examples. The octets of the actual UTF-8
 End of changes. 14 change blocks. 
25 lines changed or deleted 48 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/