draft-ietf-oauth-jwt-bcp-04.txt   draft-ietf-oauth-jwt-bcp-05.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: May 12, 2019 Amazon Expires: October 18, 2019
M. Jones M. Jones
Microsoft Microsoft
November 08, 2018 April 16, 2019
JSON Web Token Best Current Practices JSON Web Token Best Current Practices
draft-ietf-oauth-jwt-bcp-04 draft-ietf-oauth-jwt-bcp-05
Abstract Abstract
JSON Web Tokens, also known as JWTs, are URL-safe JSON-based security JSON Web Tokens, also known as JWTs, are URL-safe JSON-based security
tokens that contain a set of claims that can be signed and/or tokens that contain a set of claims that can be signed and/or
encrypted. JWTs are being widely used and deployed as a simple encrypted. JWTs are being widely used and deployed as a simple
security token format in numerous protocols and applications, both in security token format in numerous protocols and applications, both in
the area of digital identity, and in other application areas. The the area of digital identity, and in other application areas. The
goal of this Best Current Practices document is to provide actionable goal of this Best Current Practices document is to provide actionable
guidance leading to secure implementation and deployment of JWTs. guidance leading to secure implementation and deployment of JWTs.
skipping to change at page 1, line 39 skipping to change at page 1, line 39
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 https://datatracker.ietf.org/drafts/current/. Drafts is at https://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 12, 2019. This Internet-Draft will expire on October 18, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2019 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
(https://trustee.ietf.org/license-info) in effect on the date of (https://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 . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Target Audience . . . . . . . . . . . . . . . . . . . . . 3 1.1. Target Audience . . . . . . . . . . . . . . . . . . . . . 4
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 . . . . . . . . . . . . . . . . . . . 5
2.3. Multiplicity of JSON encodings . . . . . . . . . . . . . 5 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 . . . . . . . . . . . . . . . . . . . 6
3. Best Practices . . . . . . . . . . . . . . . . . . . . . . . 6 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 . . . . . . . . . . 7 3.3. Validate All Cryptographic Operations . . . . . . . . . . 7
3.4. Validate Cryptographic Inputs . . . . . . . . . . . . . . 7 3.4. Validate Cryptographic Inputs . . . . . . . . . . . . . . 7
3.5. Ensure Cryptographic Keys have Sufficient Entropy . . . . 8 3.5. Ensure Cryptographic Keys have Sufficient Entropy . . . . 8
3.6. Avoid Length-Dependent Encryption Inputs . . . . . . . . 8 3.6. Avoid Length-Dependent Encryption Inputs . . . . . . . . 8
3.7. Use UTF-8 . . . . . . . . . . . . . . . . . . . . . . . . 8 3.7. Use UTF-8 . . . . . . . . . . . . . . . . . . . . . . . . 8
3.8. Validate Issuer and Subject . . . . . . . . . . . . . . . 8 3.8. Validate Issuer and Subject . . . . . . . . . . . . . . . 8
3.9. Use and Validate Audience . . . . . . . . . . . . . . . . 9 3.9. Use and Validate Audience . . . . . . . . . . . . . . . . 9
skipping to change at page 2, line 44 skipping to change at page 2, line 44
3.11. Use Explicit Typing . . . . . . . . . . . . . . . . . . . 9 3.11. Use Explicit Typing . . . . . . . . . . . . . . . . . . . 9
3.12. Use Mutually Exclusive Validation Rules for Different 3.12. Use Mutually Exclusive Validation Rules for Different
Kinds of JWTs . . . . . . . . . . . . . . . . . . . . . . 10 Kinds of JWTs . . . . . . . . . . . . . . . . . . . . . . 10
4. Security Considerations . . . . . . . . . . . . . . . . . . . 11 4. Security Considerations . . . . . . . . . . . . . . . . . . . 11
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 11
7.1. Normative References . . . . . . . . . . . . . . . . . . 11 7.1. Normative References . . . . . . . . . . . . . . . . . . 11
7.2. Informative References . . . . . . . . . . . . . . . . . 12 7.2. Informative References . . . . . . . . . . . . . . . . . 12
Appendix A. Document History . . . . . . . . . . . . . . . . . . 14 Appendix A. Document History . . . . . . . . . . . . . . . . . . 14
A.1. draft-ietf-oauth-jwt-bcp-04 . . . . . . . . . . . . . . . 14 A.1. draft-ietf-oauth-jwt-bcp-05 . . . . . . . . . . . . . . . 14
A.2. draft-ietf-oauth-jwt-bcp-03 . . . . . . . . . . . . . . . 14 A.2. draft-ietf-oauth-jwt-bcp-04 . . . . . . . . . . . . . . . 14
A.3. draft-ietf-oauth-jwt-bcp-02 . . . . . . . . . . . . . . . 14 A.3. draft-ietf-oauth-jwt-bcp-03 . . . . . . . . . . . . . . . 14
A.4. draft-ietf-oauth-jwt-bcp-01 . . . . . . . . . . . . . . . 14 A.4. draft-ietf-oauth-jwt-bcp-02 . . . . . . . . . . . . . . . 14
A.5. draft-ietf-oauth-jwt-bcp-00 . . . . . . . . . . . . . . . 14 A.5. draft-ietf-oauth-jwt-bcp-01 . . . . . . . . . . . . . . . 14
A.6. draft-sheffer-oauth-jwt-bcp-01 . . . . . . . . . . . . . 14 A.6. draft-ietf-oauth-jwt-bcp-00 . . . . . . . . . . . . . . . 14
A.7. draft-sheffer-oauth-jwt-bcp-00 . . . . . . . . . . . . . 14 A.7. draft-sheffer-oauth-jwt-bcp-01 . . . . . . . . . . . . . 14
A.8. draft-sheffer-oauth-jwt-bcp-00 . . . . . . . . . . . . . 14
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14
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
skipping to change at page 5, line 11 skipping to change at page 5, line 20
attacks [Langkemper]. attacks [Langkemper].
For mitigations, see Section 3.5. For mitigations, see Section 3.5.
2.3. Multiplicity of JSON encodings 2.3. Multiplicity of JSON encodings
Previous versions of the JSON format [RFC8259] allowed several Previous versions of the JSON format [RFC8259] allowed several
different character encodings: UTF-8, UTF-16 and UTF-32. This is not different character encodings: UTF-8, UTF-16 and UTF-32. This is not
the case anymore, with the latest standard only allowing UTF-8. the case anymore, with the latest standard only allowing UTF-8.
However older implementations may result in the JWT being However older implementations may result in the JWT being
misinterpreted by its recipient. misinterpreted by its recipient, and this could be used by a
malicious sender to bypass the recipient's validation checks.
For mitigations, see Section 3.7. For mitigations, see Section 3.7.
2.4. Incorrect Composition of Encryption and Signature 2.4. Incorrect Composition of Encryption and Signature
Some libraries that decrypt a JWE-encrypted JWT to obtain a JWS- Some libraries that decrypt a JWE-encrypted JWT to obtain a JWS-
signed object do not always validate the internal signature. signed object do not always validate the internal signature.
For mitigations, see Section 3.3. For mitigations, see Section 3.3.
skipping to change at page 8, line 24 skipping to change at page 8, line 29
encryption, password-based encryption is still subject to brute-force encryption, password-based encryption is still subject to brute-force
attacks. attacks.
3.6. Avoid Length-Dependent Encryption Inputs 3.6. Avoid Length-Dependent Encryption Inputs
Many encryption algorithms leak information about the length of the Many encryption algorithms leak information about the length of the
plaintext, with a varying amount of leakage depending on the plaintext, with a varying amount of leakage depending on the
algorithm and mode of operation. Sensitive information, such as algorithm and mode of operation. Sensitive information, such as
passwords, SHOULD be padded before being encrypted. It is passwords, SHOULD be padded before being encrypted. It is
RECOMMENDED to avoid any compression of data before encryption since RECOMMENDED to avoid any compression of data before encryption since
such compression often reveals information about the plaintext. such compression often reveals information about the plaintext. See
[Kelsey] for general background on compression and encryption, and
[Alawatugoda] for a specific example of attacks on HTTP cookies.
3.7. Use UTF-8 3.7. Use UTF-8
[RFC7515], [RFC7516], and [RFC7519] all specify that UTF-8 be used [RFC7515], [RFC7516], and [RFC7519] all specify that UTF-8 be used
for encoding and decoding JSON used in Header Parameters and JWT for encoding and decoding JSON used in Header Parameters and JWT
Claims Sets. This is also in line with the latest JSON specification Claims Sets. This is also in line with the latest JSON specification
[RFC8259]. Implementations and applications MUST do this, and not [RFC8259]. Implementations and applications MUST do this, and not
use or admit the use of other Unicode encodings for these purposes. use or admit the use of other Unicode encodings for these purposes.
3.8. Validate Issuer and Subject 3.8. Validate Issuer and Subject
skipping to change at page 9, line 22 skipping to change at page 9, line 29
(audience) claim that can be used to determine whether the JWT is (audience) claim that can be used to determine whether the JWT is
being used by an intended party or was substituted by an attacker at being used by an intended party or was substituted by an attacker at
an unintended party. Furthermore, the relying party or application an unintended party. Furthermore, the relying party or application
MUST validate the audience value and if the audience value is not MUST validate the audience value and if the audience value is not
present or not associated with the recipient, it MUST reject the JWT. present or not associated with the recipient, it MUST reject the JWT.
3.10. Do Not Trust Received Claims 3.10. Do Not Trust Received Claims
The "kid" (key ID) header is used by the relying application to The "kid" (key ID) header is used by the relying application to
perform key lookup. Applications should ensure that this does not perform key lookup. Applications should ensure that this does not
create SQL or LDAP injection vulnerabilities. create SQL or LDAP injection vulnerabilities, by validating and/or
sanitizing the received value.
Similarly, blindly following a "jku" (JWK set URL) header, which may Similarly, blindly following a "jku" (JWK set URL) header, which may
contain an arbitrary URL, could result in server-side request forgery contain an arbitrary URL, could result in server-side request forgery
(SSRF) attacks. (SSRF) attacks. Applications should protect against such attacks,
e.g., by matching the URL to a whitelist of allowed locations, and
ensuring no cookies are sent in the GET request.
3.11. Use Explicit Typing 3.11. Use Explicit Typing
Confusion of one kind of JWT for another can be prevented by having Confusion of one kind of JWT for another can be prevented by having
all the kinds of JWTs that could otherwise potentially be confused all the kinds of JWTs that could otherwise potentially be confused
include an explicit JWT type value and include checking the type include an explicit JWT type value and include checking the type
value in their validation rules. Explicit JWT typing is accomplished value in their validation rules. Explicit JWT typing is accomplished
by using the "typ" header parameter. For instance, the by using the "typ" header parameter. For instance, the
[I-D.ietf-secevent-token] specification uses the "application/ [I-D.ietf-secevent-token] specification uses the "application/
secevent+jwt" media type to perform explicit typing of Security Event secevent+jwt" media type to perform explicit typing of Security Event
skipping to change at page 11, line 20 skipping to change at page 11, line 30
5. IANA Considerations 5. IANA Considerations
This document requires no IANA actions. This document requires no IANA actions.
6. Acknowledgements 6. 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. Tim McLean attack to the attention of JWE and JWT implementers. Tim McLean
published the RSA/HMAC confusion attack. Thanks to Nat Sakimura for published the RSA/HMAC confusion attack. Thanks to Nat Sakimura for
advocating the use of explicit typing. Thanks to Neil Madden for his advocating the use of explicit typing. Thanks to Neil Madden for his
numerous comments, and to Carsten Bormann, Brian Campbell and Eric numerous comments, and to Carsten Bormann, Brian Campbell, Brian
Rescorla for their reviews. Carpenter and Eric Rescorla for their reviews.
7. References 7. References
7.1. Normative References 7.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-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
skipping to change at page 12, line 21 skipping to change at page 12, line 33
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259, Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017, DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>. <https://www.rfc-editor.org/info/rfc8259>.
7.2. Informative References 7.2. Informative References
[Alawatugoda]
Alawatugoda, J., Stebila, D., and C. Boyd, "Protecting
Encrypted Cookies from Compression Side-Channel Attacks",
Financial Cryptography and Data Security pp. 86-106,
DOI 10.1007/978-3-662-47854-7_6, 2015.
[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-10 (work in progress), March 2018. discovery-10 (work in progress), March 2018.
[I-D.ietf-secevent-token] [I-D.ietf-secevent-token]
Hunt, P., Jones, M., Denniss, W., and M. Ansari, "Security Hunt, P., Jones, M., Denniss, W., and M. Ansari, "Security
Event Token (SET)", draft-ietf-secevent-token-13 (work in Event Token (SET)", draft-ietf-secevent-token-13 (work in
progress), May 2018. progress), May 2018.
[Kelsey] Kelsey, J., "Compression and Information Leakage of
Plaintext", Fast Software Encryption pp. 263-276,
DOI 10.1007/3-540-45661-9_21, 2002.
[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/>.
[nist-sp-800-56a-r3] [nist-sp-800-56a-r3]
Barker, E., Chen, L., Keller, S., Roginsky, A., Vassilev, Barker, E., Chen, L., Keller, S., Roginsky, A., Vassilev,
A., and R. Davis, "Recommendation for Pair-Wise Key A., and R. Davis, "Recommendation for Pair-Wise Key
Establishment Schemes Using Discrete Logarithm Establishment Schemes Using Discrete Logarithm
Cryptography, Draft NIST Special Publication 800-56A Cryptography, Draft NIST Special Publication 800-56A
skipping to change at page 14, line 9 skipping to change at page 14, line 9
[Valenta] Valenta, L., Sullivan, N., Sanso, A., and N. Heninger, "In [Valenta] Valenta, L., Sullivan, N., Sanso, A., and N. Heninger, "In
search of CurveSwap: Measuring elliptic curve search of CurveSwap: Measuring elliptic curve
implementations in the wild", March 2018, implementations in the wild", March 2018,
<https://ia.cr/2018/298>. <https://ia.cr/2018/298>.
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-04 A.1. draft-ietf-oauth-jwt-bcp-05
- Genart review comments.
A.2. draft-ietf-oauth-jwt-bcp-04
- AD review comments. - AD review comments.
A.2. draft-ietf-oauth-jwt-bcp-03 A.3. draft-ietf-oauth-jwt-bcp-03
- Acknowledgements. - Acknowledgements.
A.3. draft-ietf-oauth-jwt-bcp-02 A.4. draft-ietf-oauth-jwt-bcp-02
- Implemented WGLC feedback. - Implemented WGLC feedback.
A.4. draft-ietf-oauth-jwt-bcp-01 A.5. draft-ietf-oauth-jwt-bcp-01
- Feedback from Brian Campbell. - Feedback from Brian Campbell.
A.5. draft-ietf-oauth-jwt-bcp-00 A.6. 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.6. draft-sheffer-oauth-jwt-bcp-01 A.7. draft-sheffer-oauth-jwt-bcp-01
- Added explicit typing. - Added explicit typing.
A.7. draft-sheffer-oauth-jwt-bcp-00 A.8. 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
Dick Hardt Dick Hardt
Amazon
EMail: dick@amazon.com EMail: dick.hardt@gmail.com
Michael B. Jones Michael B. Jones
Microsoft Microsoft
EMail: mbj@microsoft.com EMail: mbj@microsoft.com
URI: http://self-issued.info/ URI: http://self-issued.info/
 End of changes. 25 change blocks. 
30 lines changed or deleted 51 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/