RFC 8725: JSON Web Token Best Current Practices

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 encrypted. JWTs are being widely used and deployed as a simple security token format in numerous protocols and applications, both in the area of digital identity and in other application areas. This Best Current Practices document updates RFC 7519 to provide actionable guidance leading to secure implementation and deployment of JWTs.¶
This memo documents an Internet Best Current Practice.¶
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on BCPs is available in Section 2 of RFC 7841.¶
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc8725.¶
Copyright (c) 2020 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.¶
1.1. Target Audience¶
1.2. Conventions Used in this Document¶
2. Threats and Vulnerabilities¶
2.1. Weak Signatures and Insufficient Signature Validation¶
2.2. Weak Symmetric Keys¶
2.3. Incorrect Composition of Encryption and Signature¶
2.4. Plaintext Leakage through Analysis of Ciphertext Length¶
2.5. Insecure Use of Elliptic Curve Encryption¶
2.6. Multiplicity of JSON Encodings¶
2.7. Substitution Attacks¶
2.8. Cross-JWT Confusion¶
2.9. Indirect Attacks on the Server¶
3.1. Perform Algorithm Verification¶
3.2. Use Appropriate Algorithms¶
3.3. Validate All Cryptographic Operations¶
3.4. Validate Cryptographic Inputs¶
3.5. Ensure Cryptographic Keys Have Sufficient Entropy¶
3.6. Avoid Compression of Encryption Inputs¶
3.8. Validate Issuer and Subject¶
3.9. Use and Validate Audience¶
3.10. Do Not Trust Received Claims¶
3.11. Use Explicit Typing¶
3.12. Use Mutually Exclusive Validation Rules for Different Kinds of JWTs¶
4. Security Considerations¶
5. IANA Considerations¶
6.1. Normative References¶
6.2. Informative References¶
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 and/or encrypted. The JWT specification has seen rapid adoption because it encapsulates security-relevant information in one easy-to-protect location, and because it is easy to implement using widely available tools. One application area in which JWTs are commonly used is representing digital identity information, such as OpenID Connect ID Tokens [OpenID.Core] and OAuth 2.0 [RFC6749] access tokens and refresh tokens, the details of which are deployment-specific.¶
Since the JWT specification was published, there have been several widely published attacks on implementations and deployments. Such attacks are the result of under-specified security mechanisms, as well as incomplete implementations and incorrect usage by applications.¶
The goal of this document is to facilitate secure implementation and deployment of JWTs. Many of the recommendations in this document are about implementation and use of the cryptographic mechanisms underlying JWTs that are defined by JSON Web Signature (JWS) [RFC7515], JSON Web Encryption (JWE) [RFC7516], and JSON Web Algorithms (JWA) [RFC7518]. Others are about use of the JWT claims themselves.¶
These are intended to be minimum recommendations for the use of JWTs in the vast majority of implementation and deployment scenarios. Other specifications that reference this document can have stricter requirements related to one or more aspects of the format, based on their particular circumstances; when that is the case, implementers are advised to adhere to those stricter requirements. Furthermore, this document provides a floor, not a ceiling, so stronger options are always allowed (e.g., depending on differing evaluations of the importance of cryptographic strength vs. computational load).¶
Community knowledge about the strength of various algorithms and feasible attacks can change quickly, and experience shows that a Best Current Practice (BCP) document about security is a point-in-time statement. Readers are advised to seek out any errata or updates that apply to this document.¶
The intended audiences of this document are:¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶