draft-ietf-oauth-json-web-token-23.txt   draft-ietf-oauth-json-web-token-24.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 22, 2014 Ping Identity Expires: January 2, 2015 Ping Identity
N. Sakimura N. Sakimura
NRI NRI
June 20, 2014 July 1, 2014
JSON Web Token (JWT) JSON Web Token (JWT)
draft-ietf-oauth-json-web-token-23 draft-ietf-oauth-json-web-token-24
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 22, 2014. This Internet-Draft will expire on January 2, 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 6, line 15 skipping to change at page 6, line 15
IntDate IntDate
A JSON numeric value representing the number of seconds from 1970- A JSON numeric value representing the number of seconds from 1970-
01-01T0:0:0Z UTC until the specified UTC date/time. See RFC 3339 01-01T0:0:0Z UTC until the specified UTC date/time. See RFC 3339
[RFC3339] for details regarding date/times in general and UTC in [RFC3339] for details regarding date/times in general and UTC in
particular. particular.
3. JSON Web Token (JWT) Overview 3. JSON Web Token (JWT) Overview
JWTs represent a set of claims as a JSON object that is encoded in a JWTs represent a set of claims as a JSON object that is encoded in a
JWS and/or JWE structure. This JSON object is the JWT Claims Set. As JWS and/or JWE structure. This JSON object is the JWT Claims Set. As
per Section 4 of [RFC7159], the JSON object consists of zero or more per Section 4 of RFC 7159 [RFC7159], the JSON object consists of zero
name/value pairs (or members), where the names are strings and the or more name/value pairs (or members), where the names are strings
values are arbitrary JSON values. These members are the claims and the values are arbitrary JSON values. These members are the
represented by the JWT. claims represented by the JWT.
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
skipping to change at page 14, line 15 skipping to change at page 14, line 15
1. The JWT MUST contain at least one period ('.') character. 1. The JWT MUST contain 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. The Encoded JOSE Header MUST be successfully base64url decoded
following the restriction given in this specification that no following the restriction given in this specification that no
padding characters have been used. padding characters have been used.
4. The resulting JOSE Header MUST be completely valid JSON syntax 4. The resulting JOSE Header MUST be completely valid JSON syntax
conforming to [RFC7159]. conforming to RFC 7159 [RFC7159].
5. The resulting JOSE Header MUST be validated to only include 5. The resulting JOSE Header MUST be validated to only include
parameters and values whose syntax and semantics are both parameters and values whose syntax and semantics are both
understood and supported or that are specified as being ignored understood and supported or that are specified as being ignored
when not understood. when not 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
skipping to change at page 14, line 44 skipping to change at page 14, line 44
JWE Plaintext. JWE 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, let the JWT Claims Set be the Message.
10. The JWT Claims Set MUST be completely valid JSON syntax 10. The JWT Claims Set MUST be completely valid JSON syntax
conforming to [RFC7159]. conforming to RFC 7159 [RFC7159].
7.1. String Comparison Rules 7.1. String Comparison Rules
Processing a JWT inevitably requires comparing known strings to Processing a JWT inevitably requires comparing known strings to
values in JSON objects. For example, in checking what the algorithm values in JSON objects. For example, in checking what the algorithm
is, the Unicode string encoding "alg" will be checked against the is, the Unicode string encoding "alg" will be checked against the
member names in the JOSE Header to see if there is a matching Header member names in the JOSE Header to see if there is a matching Header
Parameter name. Parameter name.
Comparisons between JSON strings and other Unicode strings MUST be Comparisons between JSON strings and other Unicode strings MUST be
skipping to change at page 16, line 14 skipping to change at page 16, line 14
10. IANA Considerations 10. IANA Considerations
10.1. JSON Web Token Claims Registry 10.1. JSON Web Token Claims Registry
This specification establishes the IANA JSON Web Token Claims This specification establishes the IANA JSON Web Token Claims
registry for JWT Claim Names. The registry records the Claim Name registry for JWT Claim Names. The registry records the Claim Name
and a reference to the specification that defines it. This and a reference to the specification that defines it. This
specification registers the Claim Names defined in Section 4.1. specification registers the Claim Names defined in Section 4.1.
Values are registered with a Specification Required [RFC5226] after a Values are registered on a Specification Required [RFC5226] basis
two-week review period on the [TBD]@ietf.org mailing list, on the after a two-week review period on the [TBD]@ietf.org mailing list, on
advice of one or more Designated Experts. However, to allow for the the advice of one or more Designated Experts. However, to allow for
allocation of values prior to publication, the Designated Expert(s) the allocation of values prior to publication, the Designated
may approve registration once they are satisfied that such a Expert(s) may approve registration once they are satisfied that such
specification will be published. a specification will be published.
Registration requests must be sent to the [TBD]@ietf.org mailing list Registration requests must be sent to the [TBD]@ietf.org mailing list
for review and comment, with an appropriate subject (e.g., "Request for review and comment, with an appropriate subject (e.g., "Request
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
skipping to change at page 19, line 49 skipping to change at page 19, line 49
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 faced by any cryptographic application All of the security issues that are pertinent to any cryptographic
must be faced by a JWT/JWS/JWE/JWK agent. Among these issues are application must be addressed by JWT/JWS/JWE/JWK agents. Among these
protecting the user's asymmetric private and symmetric secret keys, issues are protecting the user's asymmetric private and symmetric
preventing various attacks, and helping avoid mistakes such as secret keys, preventing various attacks, and helping avoid mistakes
inadvertently encrypting a message to the wrong recipient. The such as inadvertently encrypting a message to the wrong recipient.
entire list of security considerations is beyond the scope of this The entire list of security considerations is beyond the scope of
document. this document, but some significant considerations are listed here.
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 JOSE Header. Claims Set in the same manner that they do to the JOSE Header.
11.1. Trust Decisions 11.1. Trust Decisions
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
skipping to change at page 21, line 9 skipping to change at page 21, line 9
[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),
June 2014. July 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),
June 2014. July 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), June 2014. in progress), July 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,
skipping to change at page 26, line 36 skipping to change at page 26, line 36
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, Breno de Medeiros, Dick
Hardt, Joe Hildebrand, Jeff Hodges, Edmund Jay, Yaron Y. Goland, Ben Hardt, Joe Hildebrand, Jeff Hodges, Edmund Jay, Yaron Y. Goland, Ben
Laurie, James Manger, Prateek Mishra, Tony Nadalin, Axel Nennker, Laurie, James Manger, Prateek Mishra, Kathleen Moriarty, Tony
John Panzer, Emmanuel Raviart, David Recordon, Eric Rescorla, Jim Nadalin, Axel Nennker, John Panzer, Emmanuel Raviart, David Recordon,
Schaad, Paul Tarjan, Hannes Tschofenig, and Sean Turner. Eric Rescorla, Jim 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 ]]
-24
o Cleaned up the reference syntax in a few places.
o Applied minor wording changes to the Security Considerations
section.
-23 -23
o Replaced the terms JWS Header, JWE Header, and JWT Header with a o Replaced the terms JWS Header, JWE Header, and JWT Header with a
single JOSE Header term defined in the JWS specification. This single JOSE Header term defined in the JWS specification. This
also enabled a single Header Parameter definition to be used and also enabled a single Header Parameter definition to be used and
reduced other areas of duplication between specifications. reduced other areas of duplication between specifications.
-22 -22
o Revised the introduction to the Security Considerations section. o Revised the introduction to the Security Considerations section.
Also introduced subsection headings for security considerations Also introduced subsection headings for security considerations
items. items.
 End of changes. 15 change blocks. 
29 lines changed or deleted 37 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/