JSON Web Token Best Current Practices
RFC 8725

Document Type RFC - Best Current Practice (February 2020; No errata)
Updates RFC 7519
Also known as BCP 225
Last updated 2020-02-19
Replaces draft-sheffer-oauth-jwt-bcp
Stream IETF
Formats plain text html xml pdf htmlized bibtex
Stream WG state Submitted to IESG for Publication
Document shepherd Hannes Tschofenig
Shepherd write-up Show (last changed 2018-07-17)
IESG IESG state RFC 8725 (Best Current Practice)
Consensus Boilerplate Yes
Telechat date
Responsible AD Roman Danyliw
Send notices to Hannes Tschofenig <hannes.tschofenig@arm.com>
IANA IANA review state Version Changed - Review Needed
IANA action state No IANA Actions

Internet Engineering Task Force (IETF)                        Y. Sheffer
Request for Comments: 8725                                        Intuit
BCP: 225                                                        D. Hardt
Updates: 7519                                                           
Category: Best Current Practice                                 M. Jones
ISSN: 2070-1721                                                Microsoft
                                                           February 2020

                 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.

Status of This Memo

   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

Copyright Notice

   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.

Table of Contents

   1.  Introduction
     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.  Best Practices
     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.7.  Use UTF-8
     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.  References
     6.1.  Normative References
     6.2.  Informative References
   Authors' Addresses

1.  Introduction

   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

   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
Show full document text