draft-ietf-oauth-json-web-token-29.txt   draft-ietf-oauth-json-web-token-30.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: April 20, 2015 Ping Identity Expires: April 27, 2015 Ping Identity
N. Sakimura N. Sakimura
NRI NRI
October 17, 2014 October 24, 2014
JSON Web Token (JWT) JSON Web Token (JWT)
draft-ietf-oauth-json-web-token-29 draft-ietf-oauth-json-web-token-30
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 April 20, 2015. This Internet-Draft will expire on April 27, 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 . . . . . . . . . . . . . . . . . . . . . 16 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17
10.1. JSON Web Token Claims Registry . . . . . . . . . . . . . . 16 10.1. JSON Web Token Claims Registry . . . . . . . . . . . . . . 17
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 . . . . . . . . . . . . . . . . . . 19 10.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 20
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 . . . . . . . 26 Appendix B. Relationship of JWTs to SAML Assertions . . . . . . . 27
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 24 skipping to change at page 6, line 24
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 RFC 7159 [RFC7159], the JSON object consists of zero per Section 4 of RFC 7159 [RFC7159], the JSON object consists of zero
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 before or after any JSON values or
structural characters, in accordance with Section 2 of RFC 7159
[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
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 17, line 8 skipping to change at page 17, line 15
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 on a Specification Required [RFC5226] basis Values are registered on a Specification Required [RFC5226] basis
after a three-week review period on the [TBD]@ietf.org mailing list, after a three-week review period on the jwt-reg-review@ietf.org
on the advice of one or more Designated Experts. However, to allow mailing list, on the advice of one or more Designated Experts.
for the allocation of values prior to publication, the Designated However, to allow for the allocation of values prior to publication,
Expert(s) may approve registration once they are satisfied that such the Designated Expert(s) may approve registration once they are
a specification will be published. satisfied that such a specification will be published.
Registration requests must be sent to the [TBD]@ietf.org mailing list Registration requests must be sent to the jwt-reg-review@ietf.org
for review and comment, with an appropriate subject (e.g., "Request mailing list for review and comment, with an appropriate subject
for access token type: example"). [[ Note to the RFC Editor: The name (e.g., "Request for access token type: example").
of the mailing list should be determined in consultation with the
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@ietf.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
skipping to change at page 22, line 13 skipping to change at page 22, line 18
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 and authenticate the recipient. Another way is to an encrypted JWT and authenticate the recipient. Another way is to
ensure that JWTs containing unencrypted privacy-sensitive information ensure that JWTs containing unencrypted privacy-sensitive information
are only transmitted using protocols utilizing encryption that are only transmitted using protocols utilizing encryption that
support endpoint authentication, such as TLS. Of course, including support endpoint authentication, such as TLS. Omitting privacy-
only necessary privacy-sensitive information in a JWT is the most sensitive information from a JWT is the simplest way of minimizing
basic means of minimizing any potential privacy issues. 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]
skipping to change at page 28, line 21 skipping to change at page 28, line 30
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 ]]
-30
o Applied privacy wording supplied by Stephen Farrell.
o Clarified where white space and line breaks may occur in JSON
objects by referencing Section 2 of RFC 7159.
o Specified that registration reviews occur on the
jwt-reg-review@ietf.org mailing list.
-29 -29
o Used real values for examples in the IANA Registration Template. o Used real values for examples in the IANA Registration Template.
-28 -28
o Addressed IESG review comments by Alissa Cooper, Barry Leiba, o Addressed IESG review comments by Alissa Cooper, Barry Leiba,
Stephen Farrell, Ted Lemon, and Richard Barnes. Stephen Farrell, Ted Lemon, and Richard Barnes.
o Changed the RFC 6755 reference to be informative, based upon o Changed the RFC 6755 reference to be informative, based upon
 End of changes. 12 change blocks. 
22 lines changed or deleted 32 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/