1.1.Target Audience

The intended audiences of this document are:¶

• Implementers of JWT libraries (and the JWS and JWE libraries used by those libraries),¶
• Implementers of code that uses such libraries (to the extent that some mechanisms maynot be provided by libraries, or until they are), and¶
• Developers of specifications that rely on JWTs, both inside and outside the IETF.¶

1.2.Conventions Used in this Document

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.¶

2.1.Weak Signatures and Insufficient Signature Validation

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, has led to several attacks:¶

• The algorithm can be changed to "none" by an attacker, and some libraries would trustthis 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 librarieswould try to validate the signature using HMAC-SHA256 and using the RSA public key as theHMAC shared secret (see[McLean] and[CVE-2015-9235]).¶

For mitigations, see Sections3.1 and3.2.¶

2.2.Weak Symmetric Keys

In addition, some applications use a keyed Message Authentication Code (MAC) algorithm, such as"HS256", to sign tokens but supply a weak symmetric key withinsufficient entropy (such as a human-memorable password). Such keysare vulnerable to offline brute-force or dictionary attacks once anattacker gets hold of such a token[Langkemper].¶

For mitigations, seeSection 3.5.¶

2.3.Incorrect Composition of Encryption and Signature

Some libraries that decrypt a JWE-encrypted JWT to obtain a JWS-signed objectdo not always validate the internal signature.¶

For mitigations, seeSection 3.3.¶

2.4.Plaintext Leakage through Analysis of Ciphertext Length

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 exacerbatedwhen the plaintext is initially compressed, because the length of thecompressed plaintext and, thus, the ciphertext depends not only on the length of the original plaintext but alsoon its content.Compression attacks are particularlypowerful when there is attacker-controlled data in the same compressionspace as secret data, which is the case for some attacks on HTTPS.¶

See[Kelsey] for general backgroundon compression and encryption and[Alawatugoda] for a specific example of attacks on HTTP cookies.¶

For mitigations, seeSection 3.6.¶

2.5.Insecure Use of Elliptic Curve Encryption

Per[Sanso], several Javascript Object Signing and Encryption (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 andobserve the cleartext outputs resulting from decryption with the invalid curve pointscan use this vulnerability to recover the recipient's private key.¶

For mitigations, seeSection 3.4.¶

2.6.Multiplicity of JSON Encodings

Previous versions of the JSON format, such as the obsoleted[RFC7159], allowed several different characterencodings: UTF-8, UTF-16, and UTF-32. This is not the case anymore, with the lateststandard[RFC8259] only allowing UTF-8 exceptfor internal use within a "closed ecosystem". This ambiguity, where older implementations and those used within closed environments may generatenon-standard encodings, may result in the JWT beingmisinterpreted by its recipient. This, in turn, could be used by a malicious sender to bypassthe recipient's validation checks.¶

For mitigations, seeSection 3.7.¶

2.7.Substitution Attacks

There are attacks in which one recipient will be given a JWT that was intended for itand will attempt to use it at a different recipient for which that JWT was not intended.For instance, if an OAuth 2.0[RFC6749] accesstoken is legitimately presented to an OAuth 2.0 protected resource for which it is intended, that protected resource might then presentthat same access token to a different protected resource for which the access token is not intended,in an attempt to gain access. If such situations are not caught, this can result inthe attacker gaining access to resources that it is not entitled to access.¶

For mitigations, see Sections3.8 and3.9.¶

2.8.Cross-JWT Confusion

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 purposebeing 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 beconfused with other kinds of JWTs, then mitigationsMUST be employed to prevent these substitution attacks.¶

For mitigations, see Sections3.8,3.9,3.11, and3.12.¶

2.9.Indirect Attacks on the Server

Various JWT claims are used by the recipient to perform lookup operations,such as database and Lightweight Directory Access Protocol (LDAP) searches.Others include URLs that are similarly looked up by the server. Any of these claims can be used byan attacker as vectors for injection attacks or server-side request forgery (SSRF) attacks.¶

For mitigations, seeSection 3.10.¶

3.1.Perform Algorithm Verification

LibrariesMUST enable the caller to specify a supported set of algorithms andMUST NOT use any other algorithms when performing cryptographic operations.The libraryMUST ensure that the "alg" or "enc" header specifies the same algorithmthat is used for the cryptographic operation.Moreover, each keyMUST be used with exactly one algorithm,and thisMUST be checked when the cryptographic operation is performed.¶

3.2.Use Appropriate Algorithms

AsSection 5.2 of [RFC7515] says,"it is an application decision which algorithms may be used in a given context. Even if a JWS can be successfullyvalidated, unless the algorithm(s) used in the JWS are acceptable tothe application, itSHOULD consider the JWS to be invalid."¶

Therefore, applicationsMUST 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 introducedand existing algorithms are deprecated due to discovered cryptographic weaknesses.ApplicationsMUST therefore be designed to enable cryptographic agility.¶

That said, if a JWT is cryptographically protected end-to-end by a transport layer, such as TLS using cryptographically current algorithms, there may be no need to apply another layer ofcryptographic 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 boththe signed and unsigned cases. JWT librariesSHOULD NOT generate JWTs using "none" unlessexplicitly requested to do so by the caller. Similarly, JWT librariesSHOULD NOT consume JWTs using "none" unless explicitly requested by the caller.¶

ApplicationsSHOULD follow these algorithm-specific recommendations:¶

• Avoid all RSA-PKCS1 v1.5 encryption algorithms ([RFC8017],Section 7.2), preferring RSAES-OAEP ([RFC8017],Section 7.1).¶
• Elliptic Curve Digital Signature Algorithm (ECDSA) signatures[ANSI-X962-2005] 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, thenthe 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 librariesSHOULD implement ECDSA using the deterministicapproach defined in[RFC6979]. This approach is completely compatible with existing ECDSA verifiers and so can be implementedwithout new algorithm identifiers being required.¶

3.3.Validate All Cryptographic Operations

All cryptographic operations used in the JWTMUST be validated and the entire JWTMUST be rejected if any of them fail to validate.This is true not only of JWTs with a single set of Header Parametersbut also for Nested JWTs in which both outer and inner operationsMUST be validatedusing the keys and algorithms supplied by the application.¶

3.4.Validate Cryptographic Inputs

Some cryptographic operations, such as Elliptic Curve Diffie-Hellman key agreement("ECDH-ES"), take inputs that may contain invalid values. This includes points not onthe specified elliptic curve or other invalid points (e.g.,[Valenta], Section 7.1).The JWS/JWE library itself must validate these inputs before using them,or it must use underlying cryptographic libraries that do so (or both!).¶

Elliptic Curve Diffie-Hellman Ephemeral Static (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,validationMUST be performed according to Section 5.6.2.3.4 (ECC Partial Public-Key ValidationRoutine) of "Recommendation for Pair-Wise Key-Establishment Schemes Using Discrete Logarithm Cryptography"[nist-sp-800-56a-r3].If the "X25519" or "X448"[RFC8037] algorithms are used,then the security considerations in[RFC8037] apply.¶

3.5.Ensure Cryptographic Keys Have Sufficient Entropy

The Key Entropy and Random Values advice inSection 10.1 of [RFC7515] and the Password Considerations inSection 8.8 of [RFC7518]MUST be followed.In particular, human-memorizable passwordsMUST NOT be directly usedas the key to a keyed-MAC algorithm such as "HS256".Moreover, passwords should only be used to perform key encryption, ratherthan content encryption, as described inSection 4.8 of [RFC7518].Note that even when used for key encryption, password-based encryption is still subject to brute-force attacks.¶

3.6.Avoid Compression of Encryption Inputs

Compression of dataSHOULD NOT be done before encryption, becausesuch compressed data often reveals information about the plaintext.¶

3.7.Use UTF-8

[RFC7515],[RFC7516], and[RFC7519] 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 thelatest JSON specification[RFC8259]. Implementations and applicationsMUST do this and not use or admit the use ofother Unicode encodings for these purposes.¶

3.8.Validate Issuer and Subject

When a JWT contains an "iss" (issuer) claim, the applicationMUST validate that the cryptographic keys used for the cryptographic operations in the JWT belong to the issuer.If they do not, the applicationMUST reject the JWT.¶

The means of determining the keys owned by an issuer is application-specific.As one example, OpenID Connect[OpenID.Core]issuer values are "https" URLs that reference a JSON metadata document that contains a "jwks_uri" value that isan "https" URL from which the issuer's keys are retrieved as a JWK Set[RFC7517]. This same mechanism is used by[RFC8414].Other applications may use different means of binding keys to issuers.¶

Similarly, when the JWT contains a "sub" (subject) claim, the applicationMUST 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 applicationMUST reject the JWT.¶

3.9.Use and Validate Audience

If the same issuer can issue JWTs that are intended for use by more than one relying party or application, the JWTMUST contain an "aud" (audience) claim that can be usedto determine whether the JWT is being used by an intended party or was substituted by an attacker at an unintended party.¶

In such cases, the relying party or applicationMUST validate the audience value, and if the audience value is not present or not associated with the recipient,itMUST reject the JWT.¶

3.10.Do Not Trust Received Claims

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 validatingand/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. ApplicationsSHOULD protect against such attacks, e.g., by matching the URL to a whitelist of allowed locationsand ensuring no cookies are sent in the GET request.¶

3.11.Use Explicit Typing

Sometimes, one kind of JWT can be confused for another. If a particularkind of JWT is subject to such confusion, that JWT can include an explicitJWT type value, and the validation rules can specify checking the type.This mechanism can prevent such confusion.Explicit JWT typing is accomplished by using the "typ" Header Parameter.For instance, the[RFC8417] specification usesthe "application/secevent+jwt" media type to perform explicit typing of Security Event Tokens (SETs).¶

Per the definition of "typ" inSection 4.1.9 of [RFC7515],it isRECOMMENDED that the "application/" prefix be omitted from the "typ" value.Therefore, for example, the "typ" value used to explicitly include a type for a SETSHOULD be "secevent+jwt".When explicit typing is employed for a JWT, it isRECOMMENDEDthat 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 valueMUST be present in the inner JWT of the Nested JWT (the JWTwhose payload is the JWT Claims Set). In some cases, the same "typ" Header Parameter value will 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 of JWTs often do not use the "typ" Header Parameter value.Explicit typing isRECOMMENDED for new uses of JWTs.¶

3.12.Use Mutually Exclusive Validation Rules for Different Kinds 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 JWTsMUST be written such thatthey are mutually exclusive, rejecting JWTs of the wrong kind.To prevent substitution of JWTs from one context into another,application developers may employ a number of strategies:¶

• 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 issuersto differentiate among different kinds of JWTswill, in general, be application-specific.As discussed inSection 3.11, for new JWT applications, the use of explicit typing isRECOMMENDED.¶