| < 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.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/ | ||||