< draft-ietf-oauth-jwt-bcp-00.txt   draft-ietf-oauth-jwt-bcp-01.txt >
OAuth Working Group Y. Sheffer OAuth Working Group Y. Sheffer
Internet-Draft Intuit Internet-Draft Intuit
Intended status: Best Current Practice D. Hardt Intended status: Best Current Practice D. Hardt
Expires: January 20, 2018 Amazon Expires: September 24, 2018 Amazon
M. Jones M. Jones
Microsoft Microsoft
July 19, 2017 March 23, 2018
JSON Web Token Best Current Practices JSON Web Token Best Current Practices
draft-ietf-oauth-jwt-bcp-00 draft-ietf-oauth-jwt-bcp-01
Abstract Abstract
JSON Web Tokens, also known as JWTs [RFC7519], are URL-safe JSON- JSON Web Tokens, also known as JWTs [RFC7519], are URL-safe JSON-
based security tokens that contain a set of claims that can be signed based security tokens that contain a set of claims that can be signed
and/or encrypted. JWTs are being widely used and deployed as a and/or encrypted. JWTs are being widely used and deployed as a
simple security token format in numerous protocols and applications, simple security token format in numerous protocols and applications,
both in the area of digital identity, and in other application areas. both in the area of digital identity, and in other application areas.
The goal of this Best Current Practices document is to provide The goal of this Best Current Practices document is to provide
actionable guidance leading to secure implementation and deployment actionable guidance leading to secure implementation and deployment
skipping to change at page 1, line 40 skipping to change at page 1, line 40
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 January 20, 2018. This Internet-Draft will expire on September 24, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2017 IETF Trust and the persons identified as the Copyright (c) 2018 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
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Target Audience . . . . . . . . . . . . . . . . . . . . . 3 1.1. Target Audience . . . . . . . . . . . . . . . . . . . . . 3
1.2. Conventions used in this document . . . . . . . . . . . . 4 1.2. Conventions used in this document . . . . . . . . . . . . 4
2. Threats and Vulnerabilities . . . . . . . . . . . . . . . . . 4 2. Threats and Vulnerabilities . . . . . . . . . . . . . . . . . 4
2.1. Weak Signatures and Insufficient Signature Validation . . 4 2.1. Weak Signatures and Insufficient Signature Validation . . 4
2.2. Weak symmetric keys . . . . . . . . . . . . . . . . . . . 4 2.2. Weak symmetric keys . . . . . . . . . . . . . . . . . . . 4
2.3. Multiplicity of JSON encodings . . . . . . . . . . . . . 4 2.3. Multiplicity of JSON encodings . . . . . . . . . . . . . 5
2.4. Incorrect Composition of Encryption and Signature . . . . 5 2.4. Incorrect Composition of Encryption and Signature . . . . 5
2.5. Insecure Use of Elliptic Curve Encryption . . . . . . . . 5 2.5. Insecure Use of Elliptic Curve Encryption . . . . . . . . 5
2.6. Substitution Attacks . . . . . . . . . . . . . . . . . . 5 2.6. Substitution Attacks . . . . . . . . . . . . . . . . . . 5
2.7. Cross-JWT Confusion . . . . . . . . . . . . . . . . . . . 5 2.7. Cross-JWT Confusion . . . . . . . . . . . . . . . . . . . 5
3. Best Practices . . . . . . . . . . . . . . . . . . . . . . . 5 3. Best Practices . . . . . . . . . . . . . . . . . . . . . . . 6
3.1. Perform Algorithm Verification . . . . . . . . . . . . . 6 3.1. Perform Algorithm Verification . . . . . . . . . . . . . 6
3.2. Use Appropriate Algorithms . . . . . . . . . . . . . . . 6 3.2. Use Appropriate Algorithms . . . . . . . . . . . . . . . 6
3.3. Validate All Cryptographic Operations . . . . . . . . . . 6 3.3. Validate All Cryptographic Operations . . . . . . . . . . 6
3.4. Validate Cryptographic Inputs . . . . . . . . . . . . . . 6 3.4. Validate Cryptographic Inputs . . . . . . . . . . . . . . 7
3.5. Ensure Cryptographic Keys have Sufficient Entropy . . . . 7 3.5. Ensure Cryptographic Keys have Sufficient Entropy . . . . 7
3.6. Use UTF-8 . . . . . . . . . . . . . . . . . . . . . . . . 7 3.6. Use UTF-8 . . . . . . . . . . . . . . . . . . . . . . . . 7
3.7. Validate Issuer and Subject . . . . . . . . . . . . . . . 7 3.7. Validate Issuer and Subject . . . . . . . . . . . . . . . 7
3.8. Use and Validate Audience . . . . . . . . . . . . . . . . 7 3.8. Use and Validate Audience . . . . . . . . . . . . . . . . 8
3.9. Use Explicit Typing . . . . . . . . . . . . . . . . . . . 8 3.9. Use Explicit Typing . . . . . . . . . . . . . . . . . . . 8
3.10. Use Mutually Exclusive Validation Rules for Different 3.10. Use Mutually Exclusive Validation Rules for Different
Kinds of JWTs . . . . . . . . . . . . . . . . . . . . . . 8 Kinds of JWTs . . . . . . . . . . . . . . . . . . . . . . 8
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9
6. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 9
6.1. Normative References . . . . . . . . . . . . . . . . . . 9 6.1. Normative References . . . . . . . . . . . . . . . . . . 10
6.2. Informative References . . . . . . . . . . . . . . . . . 10 6.2. Informative References . . . . . . . . . . . . . . . . . 10
Appendix A. Document History . . . . . . . . . . . . . . . . . . 11 Appendix A. Document History . . . . . . . . . . . . . . . . . . 12
A.1. draft-ietf-oauth-jwt-bcp-00 . . . . . . . . . . . . . . . 11 A.1. draft-ietf-oauth-jwt-bcp-01 . . . . . . . . . . . . . . . 12
A.2. draft-sheffer-oauth-jwt-bcp-01 . . . . . . . . . . . . . 11 A.2. draft-ietf-oauth-jwt-bcp-00 . . . . . . . . . . . . . . . 12
A.3. draft-sheffer-oauth-jwt-bcp-00 . . . . . . . . . . . . . 11 A.3. draft-sheffer-oauth-jwt-bcp-01 . . . . . . . . . . . . . 12
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 A.4. draft-sheffer-oauth-jwt-bcp-00 . . . . . . . . . . . . . 12
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12
1. Introduction 1. Introduction
JSON Web Tokens, also known as JWTs [RFC7519], are URL-safe JSON- JSON Web Tokens, also known as JWTs [RFC7519], are URL-safe JSON-
based security tokens that contain a set of claims that can be signed based security tokens that contain a set of claims that can be signed
and/or encrypted. The JWT specification has seen rapid adoption and/or encrypted. The JWT specification has seen rapid adoption
because it encapsulates security-relevant information in one, easy to because it encapsulates security-relevant information in one, easy to
protect location, and because it is easy to implement using widely- protect location, and because it is easy to implement using widely-
available tools. One application area in which JWTs are commonly available tools. One application area in which JWTs are commonly
used is representing digital identity information, such as OpenID used is representing digital identity information, such as OpenID
skipping to change at page 8, line 26 skipping to change at page 8, line 34
Tokens (SETs). Tokens (SETs).
Per the definition of "typ" in Section 4.1.9 of [RFC7515], it is Per the definition of "typ" in Section 4.1.9 of [RFC7515], it is
RECOMMENDED that the "application/" prefix be omitted from the "typ" RECOMMENDED that the "application/" prefix be omitted from the "typ"
value. Therefore, for example, the "typ" value used to explicitly value. Therefore, for example, the "typ" value used to explicitly
include a type for a SET SHOULD be "secevent+jwt". When explicit include a type for a SET SHOULD be "secevent+jwt". When explicit
typing is employed for a JWT, it is RECOMMENDED that a media type typing is employed for a JWT, it is RECOMMENDED that a media type
name of the format "application/example+jwt" be used, where "example" name of the format "application/example+jwt" be used, where "example"
is replaced by the identifier for the specific kind of JWT. is replaced by the identifier for the specific kind of JWT.
When applying explicit typing to a Nested JWT, the "typ" header
parameter containing the explicit type value MUST be present in the
inner JWT of the Nested JWT (the JWT whose payload is the JWT Claims
Set). The same "typ" header parameter value MAY be present in the
outer JWT as well, to explicitly type the entire Nested JWT.
Note that the use of explicit typing may not achieve disambiguation Note that the use of explicit typing may not achieve disambiguation
from existing kinds of JWTs, as the validation rules for existing from existing kinds of JWTs, as the validation rules for existing
kinds JWTs often do not use the "typ" header parameter value. kinds JWTs often do not use the "typ" header parameter value.
Explicit typing is RECOMMENDED for new uses of JWTs. Explicit typing is RECOMMENDED for new uses of JWTs.
3.10. Use Mutually Exclusive Validation Rules for Different Kinds of 3.10. Use Mutually Exclusive Validation Rules for Different Kinds of
JWTs JWTs
Each application of JWTs defines a profile specifying the required Each application of JWTs defines a profile specifying the required
and optional JWT claims and the validation rules associated with and optional JWT claims and the validation rules associated with
skipping to change at page 9, line 35 skipping to change at page 10, line 4
This document requires no IANA actions. This document requires no IANA actions.
5. Acknowledgements 5. Acknowledgements
Thanks to Antonio Sanso for bringing the "ECDH-ES" invalid point Thanks to Antonio Sanso for bringing the "ECDH-ES" invalid point
attack to the attention of JWE and JWT implementers. Thanks to Nat attack to the attention of JWE and JWT implementers. Thanks to Nat
Sakimura for advocating the use of explicit typing. Sakimura for advocating the use of explicit typing.
6. References 6. References
6.1. Normative References 6.1. Normative References
[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, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-
<http://www.rfc-editor.org/info/rfc2119>. editor.org/info/rfc2119>.
[RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
2014, <http://www.rfc-editor.org/info/rfc7159>. 2014, <https://www.rfc-editor.org/info/rfc7159>.
[RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
2015, <http://www.rfc-editor.org/info/rfc7515>. 2015, <https://www.rfc-editor.org/info/rfc7515>.
[RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
RFC 7516, DOI 10.17487/RFC7516, May 2015, RFC 7516, DOI 10.17487/RFC7516, May 2015,
<http://www.rfc-editor.org/info/rfc7516>. <https://www.rfc-editor.org/info/rfc7516>.
[RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518,
DOI 10.17487/RFC7518, May 2015, DOI 10.17487/RFC7518, May 2015, <https://www.rfc-
<http://www.rfc-editor.org/info/rfc7518>. editor.org/info/rfc7518>.
[RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
<http://www.rfc-editor.org/info/rfc7519>. <https://www.rfc-editor.org/info/rfc7519>.
6.2. Informative References 6.2. Informative References
[I-D.ietf-oauth-discovery] [I-D.ietf-oauth-discovery]
Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0
Authorization Server Metadata", draft-ietf-oauth- Authorization Server Metadata", draft-ietf-oauth-
discovery-06 (work in progress), March 2017. discovery-10 (work in progress), March 2018.
[I-D.ietf-secevent-token] [I-D.ietf-secevent-token]
Hunt, P., Denniss, W., Ansari, M., and M. Jones, "Security Hunt, P., Jones, M., Denniss, W., and M. Ansari, "Security
Event Token (SET)", draft-ietf-secevent-token-02 (work in Event Token (SET)", draft-ietf-secevent-token-07 (work in
progress), June 2017. progress), March 2018.
[Langkemper] [Langkemper]
Langkemper, S., "Attacking JWT Authentication", September Langkemper, S., "Attacking JWT Authentication", September
2016, <https://www.sjoerdlangkemper.nl/2016/09/28/ 2016, <https://www.sjoerdlangkemper.nl/2016/09/28/
attacking-jwt-authentication/>. attacking-jwt-authentication/>.
[OpenID.Core] [OpenID.Core]
Sakimura, N., Bradley, J., Jones, M., Medeiros, B., and C. Sakimura, N., Bradley, J., Jones, M., Medeiros, B., and C.
Mortimore, "OpenID Connect Core 1.0", November 2014, Mortimore, "OpenID Connect Core 1.0", November 2014,
<http://openid.net/specs/openid-connect-core-1_0.html>. <http://openid.net/specs/openid-connect-core-1_0.html>.
[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
RFC 6749, DOI 10.17487/RFC6749, October 2012, RFC 6749, DOI 10.17487/RFC6749, October 2012,
<http://www.rfc-editor.org/info/rfc6749>. <https://www.rfc-editor.org/info/rfc6749>.
[RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517,
DOI 10.17487/RFC7517, May 2015, DOI 10.17487/RFC7517, May 2015, <https://www.rfc-
<http://www.rfc-editor.org/info/rfc7517>. editor.org/info/rfc7517>.
[Sanso] Sanso, A., "Critical Vulnerability Uncovered in JSON [Sanso] Sanso, A., "Critical Vulnerability Uncovered in JSON
Encryption", March 2017, Encryption", March 2017,
<https://blogs.adobe.com/security/2017/03/critical- <https://blogs.adobe.com/security/2017/03/critical-
vulnerability-uncovered-in-json-encryption.html>. vulnerability-uncovered-in-json-encryption.html>.
Appendix A. Document History Appendix A. 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 ]]
A.1. draft-ietf-oauth-jwt-bcp-00 A.1. draft-ietf-oauth-jwt-bcp-01
- Feedback from Brian Campbell.
A.2. draft-ietf-oauth-jwt-bcp-00
- Initial WG draft. No change from the latest individual version. - Initial WG draft. No change from the latest individual version.
A.2. draft-sheffer-oauth-jwt-bcp-01 A.3. draft-sheffer-oauth-jwt-bcp-01
- Added explicit typing. - Added explicit typing.
A.3. draft-sheffer-oauth-jwt-bcp-00 A.4. draft-sheffer-oauth-jwt-bcp-00
- Initial version. - Initial version.
Authors' Addresses Authors' Addresses
Yaron Sheffer Yaron Sheffer
Intuit Intuit
EMail: yaronf.ietf@gmail.com EMail: yaronf.ietf@gmail.com
 End of changes. 27 change blocks. 
35 lines changed or deleted 45 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/