JSON Web Tokens validation

JSON web tokens (JWT) are often used as part of an authentication component on many web applications. Since JWTs are crucial to identifying users and their access, ensuring the token's integrity is important.

API Shield's JWT validation cryptographically verifies incoming JWTs before they reach your API origin. It detects tokens that are expired, tampered with, or not yet valid. You then create a rule to act on the validation results.

JWT validation has two parts: a token configuration that tells Cloudflare how to find and verify JWTs, and a rule that acts on the validation results.

After you create a token configuration, Cloudflare checks every request in the zone for a JWT at the configured locations. When Cloudflare finds a JWT, it validates the token and makes the verified claims available in http.request.jwt.claims fields. For available fields and standard claims, refer to the JWT validation fields reference. You do not need a rule or an operation in Endpoint Management for validation. Rules determine how Cloudflare acts on the results.

JWT issuers that use asymmetric algorithms typically publish public keys (JWKS) for verification at a known URL on the Internet. Issuers that use HMAC algorithms share a symmetric credential with the validator. If you do not know where to get your issuer's verification keys or symmetric credential, contact your identity administrator.

For supported algorithms and symmetric key requirements, refer to Configure JWT validation via the API.

Token configurations do not automatically retrieve or refresh keys from a JWKS URL. Add updated JWK values directly, or use a Worker to synchronize the token configuration with your identity provider. To configure automatic updates, refer to Configure Workers to automatically update keys.

For new security policies, Cloudflare generally recommends using WAF custom rules.

• WAF custom rules — use these for zone-wide policies based on verified JWT claims. Custom rules can combine claims with other signals, such as attack score. Endpoints do not need to be in Endpoint Management.
• JWT validation rules — use these when enforcement must apply only to specific operations in Endpoint Management. These rules support the is_jwt_valid() and is_jwt_present() functions, which are not available in custom rules.

Cloudflare validates JWTs the same way regardless of which rule type you choose.

For example, to reference a simple string claim in a rule expression, use lookup_json_string() with your token configuration ID and the claim name:

lookup_json_string(http.request.jwt.claims["<TOKEN_CONFIGURATION_ID>"][0], "claim_name")

For a complete example, refer to Issue challenge for admin user in JWT claim based on attack score. For all available fields, refer to the JWT validation fields reference.

JWT validation rules use operations from Endpoint Management to control where Cloudflare applies their log or block action.

If you expect that two different JWTs should be present in a request and you want to validate both, you must create two different token configurations. When selecting the two configurations in your validation rule, select Validate all configurations under Validation behavior for multiple configurations.

If you expect to migrate between two different identity providers, you must create two different token configurations and two different validation rules, each corresponding to its own configuration. With this setup, you can change the action for different validation rules depending on the state of your migration.

API Shield will verify JSON Web Tokens regardless of whether they have the Bearer prefix.

Rate Limiting can use string claims from a valid JSON Web Token (JWT) as rate-limit characteristics. This includes registered claims, such as sub, and custom claims.

For nested claims, pass each object key separately to lookup_json_string(). For example, use "user", "email" to access user.email.

Only valid JWTs populate JWT claim fields. If a rule also matches requests without the selected claim, those requests use a separate missing-value counter. Refer to Missing field versus empty value.

For per-user limits, select a claim that uniquely identifies the user, such as sub when it is unique within your application. Requests with the same characteristic value share a rate-limit counter.

To apply different per-user limits by tier, create one rate limiting rule for each tier. Match the tier claim in the rule expression and use a separate user identifier claim as the rate-limit characteristic.

For example, a free-tier rule can use:

lookup_json_string(http.request.jwt.claims["<JWT_TOKEN_CONFIGURATION_ID>"][0], "tier") eq "free"

Use sub as the rate-limit characteristic and set the limit to five requests per minute. Create another rule that matches "tier" eq "premium" and applies the appropriate premium-tier limit.

Due to cross-origin resource sharing (CORS) security, web browsers will send "pre-flight" requests using the OPTIONS verb to API endpoints before sending a GET (or other verb) request. By definition, OPTIONS preflight requests do not include credentials (authentication headers or cookies) and are anonymous.

If you expect web browsers to be valid clients of your API, and to prevent blocking OPTIONS requests from those browsers, Cloudflare recommends adding or http.request.method eq "OPTIONS" to your JWT validation rules.

JWT validation is available for all API Shield customers. Enterprise customers who have not purchased API Shield can preview API Shield as a non-contract service ↗︎ in the Cloudflare dashboard or by contacting your account team.

JWT validation only operates on JWTs sent in client request headers or cookies. If your clients send JWTs in a POST body, contact your account team.