JSON Web Token Best Current Practices
Intuit
yaronf.ietf@gmail.com
dick.hardt@gmail.com
Microsoft
mbj@microsoft.com
http://self-issued.info/
Security
OAuth Working Group
Internet-Draft
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.
The goal of this Best Current Practices document is to provide actionable guidance
leading to secure implementation and deployment of JWTs.
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.
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
and OAuth 2.0 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 will actually be about
implementation and use of the cryptographic mechanisms underlying JWTs that are defined by
JSON Web Signature (JWS) ,
JSON Web Encryption (JWE) , and
JSON Web Algorithms (JWA) .
Others will be 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 targets of this document are:
Implementers of JWT libraries (and the JWS and JWE libraries used by them),
Implementers of code that uses such libraries (to the extent that some mechanisms may
not be provided by libraries, or until they are), and
Developers of specifications that rely on JWTs, both inside and outside the IETF.
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 when, and only when, they
appear in all capitals, as shown here.
This section lists some known and possible problems with JWT implementations and deployments.
Each problem description is followed by references to one or more mitigations to those problems.
Signed JSON Web Tokens carry an explicit indication of the signing algorithm,
in the form of the “alg” header parameter, to facilitate cryptographic agility.
This, in conjunction with design flaws in some libraries and applications, have led to several attacks:
The algorithm can be changed to “none” by an attacker, and some libraries would trust
this value and “validate” the JWT without checking any signature.
An “RS256” (RSA, 2048 bit) parameter value can be changed into
“HS256” (HMAC, SHA-256), and some libraries
would try to validate the signature using HMAC-SHA256 and using the RSA public key as the
HMAC shared secret (see and CVE-2015-9235).
For mitigations, see and .
In addition, some applications sign tokens using a weak symmetric key and a keyed
MAC algorithm such as “HS256”. In most cases, these keys are human memorable passwords
that are vulnerable to dictionary attacks .
For mitigations, see .
Some libraries that decrypt a JWE-encrypted JWT to obtain a JWS-signed object
do not always validate the internal signature.
For mitigations, see .
Many encryption algorithms leak information about the length of the plaintext, with a varying amount of
leakage depending on the algorithm and mode of operation. This problem is exacerbated
when the plaintext is initially compressed, because the length of the compressed plaintext and thus, the ciphertext,
depends not only on the length of the original plaintext but also
on its content.
See for general background
on compression and encryption, and for a specific example of attacks on HTTP cookies.
For mitigations, see .
Per , several JOSE libraries fail to validate their inputs correctly
when performing elliptic curve key agreement (the “ECDH-ES” algorithm).
An attacker that is able to send JWEs of its choosing that use invalid curve points and
observe the cleartext outputs resulting from decryption with the invalid curve points
can use this vulnerability to recover the recipient’s private key.
For mitigations, see .
Previous versions of the JSON format such as the obsoleted
allowed several different character
encodings: UTF-8, UTF-16 and UTF-32. This is not the case anymore, with the latest
standard only allowing UTF-8. However older implementations may result in the JWT being
misinterpreted by its recipient, and this could be used by a malicious sender to bypass
the recipient’s validation checks.
For mitigations, see .
There are attacks in which one recipient will have a JWT intended for it
and attempt to use it at a different recipient that it was not intended for.
If not caught, these attacks can result in the attacker gaining access to resources
that it is not entitled to access.
For instance, if an OAuth 2.0 access token is presented to an OAuth 2.0 protected resource
that it is intended for, that protected resource might then attempt to gain access to a different
protected resource by presenting that same access token to the different protected resource,
which the access token is not intended for.
For mitigations, see and .
As JWTs are being used by more different protocols in diverse application areas, it becomes increasingly
important to prevent cases of JWT tokens that have been issued for one purpose
being subverted and used for another.
Note that this is a specific type of substitution attack.
If the JWT could be used in an application context in which it could be confused with other kinds of JWTs,
then mitigations MUST be employed to prevent these substitution attacks.
For mitigations, see , ,
, and .
Various JWT claims are used by the recipient to perform lookup operations, e.g. database and LDAP searches.
Others include URLs that are similarly looked up by the server. Any of these claims can be used by
an attacker as vectors for injection attacks or server-side request forgery (SSRF) attacks.
For mitigations, see .
The best practices listed below should be applied by practitioners
to mitigate the threats listed in the preceding section.
Libraries MUST enable the caller to specify a supported set of algorithms and
MUST NOT use any other algorithms when performing cryptographic operations.
The library MUST ensure that the “alg” or “enc” header specifies the same algorithm
that is used for the cryptographic operation.
Moreover, each key MUST be used with exactly one algorithm,
and this MUST be checked when the cryptographic operation is performed.
As Section 5.2 of says, “it is an application decision which algorithms may
be used in a given context. Even if a JWS can be successfully
validated, unless the algorithm(s) used in the JWS are acceptable to
the application, it SHOULD consider the JWS to be invalid.”
Therefore, applications MUST only allow the use of cryptographically current algorithms
that meet the security requirements of the application.
This set will vary over time as new algorithms are introduced
and existing algorithms are deprecated due to discovered cryptographic weaknesses.
Applications MUST therefore be designed to enable cryptographic agility.
That said, if a JWT is cryptographically protected by a transport layer, such as TLS
using cryptographically current algorithms, there may be no need to apply another layer of
cryptographic protections to the JWT.
In such cases, the use of the “none” algorithm can be perfectly acceptable.
The “none” algorithm should only be used when the JWT is cryptographically protected by other means.
JWTs using “none” are often used in application contexts in which the content is optionally signed;
then the URL-safe claims representation and processing can be the same in both the signed and unsigned cases.
JWT libraries SHOULD NOT generate JWTs using “none” unless explicitly requested to do by the caller.
Applications SHOULD follow these algorithm-specific recommendations:
Avoid all RSA-PKCS1 v1.5 encryption algorithms, preferring RSA-OAEP (, Sec. 7.1).
ECDSA signatures require a unique random value for every message that is signed.
If even just a few bits of the random value are predictable across multiple messages then
the security of the signature scheme may be compromised. In the worst case,
the private key may be recoverable by an attacker. To counter these attacks,
JWT libraries SHOULD implement ECDSA using the deterministic approach defined in .
This approach is completely compatible with existing ECDSA verifiers and so can be implemented
without new algorithm identifiers being required.
All cryptographic operations used in the JWT MUST be validated and the entire JWT MUST be rejected
if any of them fail to validate.
This is true not only of JWTs with a single set of Header Parameters
but also for Nested JWTs, in which both outer and inner operations MUST be validated
using the keys and algorithms supplied by the application.
Some cryptographic operations, such as Elliptic Curve Diffie-Hellman key agreement
(“ECDH-ES”) take inputs that may contain invalid values, such as points not on the specified elliptic curve
or other invalid points (see e.g. , Sec. 7.1).
Either the JWS/JWE library itself must validate these inputs before using them
or it must use underlying cryptographic libraries that do so (or both!).
ECDH-ES ephemeral public key (epk) inputs should be validated according to the recipient’s
chosen elliptic curve. For the NIST prime-order curves P-256, P-384 and P-521, validation MUST
be performed according to Section 5.6.2.3.4 “ECC Partial Public-Key Validation Routine” of
NIST Special Publication 800-56A revision 3 .
Likewise, if the “X25519” or “X448” algorithms are used,
then the security considerations in apply.
The Key Entropy and Random Values advice in Section 10.1 of and
the Password Considerations in Section 8.8 of
MUST be followed.
In particular, human-memorizable passwords MUST NOT be directly used
as the key to a keyed-MAC algorithm such as “HS256”.
In particular, passwords should only be used to perform key encryption, rather than content encryption,
as described in Section 4.8 of .
Note that even when used for key encryption, password-based encryption is still subject to brute-force attacks.
It is RECOMMENDED to avoid any compression of data before encryption
since such compression often reveals information about the plaintext.
, , and all specify that UTF-8 be used for encoding and decoding JSON
used in Header Parameters and JWT Claims Sets. This is also in line with the latest JSON specification .
Implementations and applications MUST do this, and not use or admit the use of
other Unicode encodings for these purposes.
When a JWT contains an “iss” (issuer) claim, the application MUST validate that the cryptographic keys
used for the cryptographic operations in the JWT belong to the issuer.
If they do not, the application MUST reject the JWT.
The means of determining the keys owned by an issuer is application-specific.
As one example, OpenID Connect issuer values are “https” URLs
that reference a JSON metadata document that contains a “jwks_uri” value that is
an “https” URL from which the issuer’s keys are retrieved as a JWK Set .
This same mechanism is used by .
Other applications may use different means of binding keys to issuers.
Similarly, when the JWT contains a “sub” (subject) claim, the application MUST validate that
the subject value corresponds to a valid subject and/or issuer/subject pair at the application.
This may include confirming that the issuer is trusted by the application.
If the issuer, subject, or the pair are invalid, the application MUST reject the JWT.
If the same issuer can issue JWTs that are intended for use by more than one relying party or application,
the JWT MUST contain an “aud” (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 an unintended party.
Furthermore, the relying party or application MUST validate the audience value
and if the audience value is not present or not associated with the recipient,
it MUST reject the JWT.
The “kid” (key ID) header is used by the relying application to perform key lookup. Applications
should ensure that this does not create SQL or LDAP injection vulnerabilities, by validating
and/or sanitizing the received value.
Similarly, blindly following a “jku” (JWK set URL) or “x5u” (X.509 URL) header,
which may contain an arbitrary URL,
could result in server-side request forgery (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.
Confusion of one kind of JWT for another
can be prevented by having all the kinds of JWTs that could otherwise potentially be confused
include an explicit JWT type value and include checking the type value in their validation rules.
Explicit JWT typing is accomplished by using the “typ” header parameter.
For instance, the specification uses the “application/secevent+jwt” media type
to perform explicit typing of Security Event Tokens (SETs).
Per the definition of “typ” in Section 4.1.9 of ,
it is RECOMMENDED that the “application/” prefix be omitted from the “typ” value.
Therefore, for example, the “typ” value used to explicitly 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 name of the format
“application/example+jwt” be used, where “example” 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 from existing kinds of JWTs,
as the validation rules for existing kinds JWTs often do not use the “typ” header parameter value.
Explicit typing is RECOMMENDED for new uses of JWTs.
Each application of JWTs defines a profile specifying the required and optional JWT claims
and the validation rules associated with them.
If more than one kind of JWT can be issued by the same issuer,
the validation rules for those JWTs MUST be written such that they are mutually exclusive,
rejecting JWTs of the wrong kind.
To prevent substitution of JWTs from one context into another, a number of strategies may be employed:
Use explicit typing for different kinds of JWTs.
Then the distinct “typ” values can be used to differentiate between the different kinds of JWTs.
Use different sets of required claims or different required claim values.
Then the validation rules for one kind of JWT will reject those with different claims or values.
Use different sets of required header parameters or different required header parameter values.
Then the validation rules for one kind of JWT will reject those with different header parameters or values.
Use different keys for different kinds of JWTs.
Then the keys used to validate one kind of JWT will fail to validate other kinds of JWTs.
Use different “aud” values for different uses of JWTs from the same issuer.
Then audience validation will reject JWTs substituted into inappropriate contexts.
Use different issuers for different kinds of JWTs.
Then the distinct “iss” values can be used to segregate the different kinds of JWTs.
Given the broad diversity of JWT usage and applications,
the best combination of types, required claims, values, header parameters, key usages, and issuers
to differentiate among different kinds of JWTs
will, in general, be application specific.
For new JWT applications, the use of explicit typing is RECOMMENDED.
This entire document is about security considerations when implementing and deploying JSON Web Tokens.
This document requires no IANA actions.
Thanks to Antonio Sanso for bringing the “ECDH-ES” invalid point attack to the attention
of JWE and JWT implementers. Tim McLean published the RSA/HMAC confusion attack.
Thanks to Nat Sakimura for advocating the use of explicit typing. Thanks to Neil Madden for his
numerous comments, and to Carsten Bormann, Brian Campbell, Brian Carpenter,
Roman Danyliw
and Eric Rescorla for their reviews.
Key words for use in RFCs to Indicate Requirement Levels
In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.
Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA)
This document defines a deterministic digital signature generation procedure. Such signatures are compatible with standard Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA) digital signatures and can be processed with unmodified verifiers, which need not be aware of the procedure described therein. Deterministic signatures retain the cryptographic security features associated with digital signatures but can be more easily implemented in various environments, since they do not need access to a source of high-quality randomness.
The JavaScript Object Notation (JSON) Data Interchange Format
JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data.This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance.
JSON Web Signature (JWS)
JSON Web Signature (JWS) represents content secured with digital signatures or Message Authentication Codes (MACs) using JSON-based data structures. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and an IANA registry defined by that specification. Related encryption capabilities are described in the separate JSON Web Encryption (JWE) specification.
JSON Web Encryption (JWE)
JSON Web Encryption (JWE) represents encrypted content using JSON-based data structures. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and IANA registries defined by that specification. Related digital signature and Message Authentication Code (MAC) capabilities are described in the separate JSON Web Signature (JWS) specification.
JSON Web Algorithms (JWA)
This specification registers cryptographic algorithms and identifiers to be used with the JSON Web Signature (JWS), JSON Web Encryption (JWE), and JSON Web Key (JWK) specifications. It defines several IANA registries for these identifiers.
JSON Web Token (JWT)
JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted.
PKCS #1: RSA Cryptography Specifications Version 2.2
This document provides recommendations for the implementation of public-key cryptography based on the RSA algorithm, covering cryptographic primitives, encryption schemes, signature schemes with appendix, and ASN.1 syntax for representing keys and for identifying the schemes.This document represents a republication of PKCS #1 v2.2 from RSA Laboratories' Public-Key Cryptography Standards (PKCS) series. By publishing this RFC, change control is transferred to the IETF.This document also obsoletes RFC 3447.
CFRG Elliptic Curve Diffie-Hellman (ECDH) and Signatures in JSON Object Signing and Encryption (JOSE)
This document defines how to use the Diffie-Hellman algorithms "X25519" and "X448" as well as the signature algorithms "Ed25519" and "Ed448" from the IRTF CFRG elliptic curves work in JSON Object Signing and Encryption (JOSE).
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words
RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.
PKCS #1: RSA Encryption Version 1.5
This document describes a method for encrypting data using the RSA public-key cryptosystem. This memo provides information for the Internet community. It does not specify an Internet standard of any kind.
The OAuth 2.0 Authorization Framework
The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849. [STANDARDS-TRACK]
The JavaScript Object Notation (JSON) Data Interchange Format
JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data.This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance.
JSON Web Key (JWK)
A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key. This specification also defines a JWK Set JSON data structure that represents a set of JWKs. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and IANA registries established by that specification.
OAuth 2.0 Authorization Server Metadata
This specification defines a metadata format that an OAuth 2.0 client can use to obtain the information needed to interact with an OAuth 2.0 authorization server, including its endpoint locations and authorization server capabilities.
Security Event Token (SET)
This specification defines the Security Event Token (SET) data structure. A SET describes statements of fact from the perspective of an issuer about a subject. These statements of fact represent an event that occurred directly to or about a security subject, for example, a statement about the issuance or revocation of a token on behalf of a subject. This specification is intended to enable representing security- and identity-related events. A SET is a JSON Web Token (JWT), which can be optionally signed and/or encrypted. SETs can be distributed via protocols such as HTTP.
American National Standard X9.62: The Elliptic Curve Digital Signature Algorithm (ECDSA)
Protecting Encrypted Cookies from Compression Side-Channel Attacks
Compression and Information Leakage of Plaintext
Attacking JWT Authentication
Critical vulnerabilities in JSON Web Token libraries
Recommendation for Pair-Wise Key Establishment Schemes Using Discrete Logarithm Cryptography, Draft NIST Special Publication 800-56A Revision 3
In search of CurveSwap: Measuring elliptic curve implementations in the wild
Critical Vulnerability Uncovered in JSON Encryption
OpenID Connect Core 1.0
[[ to be removed by the RFC editor before publication as an RFC ]]
Second AD review.
Removed unworkable recommendation to pad encrypted passwords.
Implemented WGLC feedback.
Feedback from Brian Campbell.
Initial WG draft. No change from the latest individual version.