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.

Each JWT issuer typically publishes public keys (JWKS) for verification at a known URL on the Internet. If you do not know where to get them, contact your identity administrator.

To automatically keep your JWKS up to date when your identity provider refreshes them, you can use a Worker. Refer to Configure Workers to automatically update keys to learn more about setting up the Worker.

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.

You can rate limit requests based on any claim inside of a JSON Web Token (JWT), such as:

• Registered claims like aud or sub
• Custom claims like userEmail, including nested custom claims like user.email

Rate limiting based on JWT claim values will only work on valid JSON Web Tokens. If you do not block invalid JSON Web Tokens on your path, the JWT claims will all be counted and possibly blocked if high traffic is detected in the Point of Presence (PoP).

You must also count the JWT claim that uniquely identifies the user. If you select a claim that is the same for many of your users, their rate limits will all be counted together.

If you offer multiple tiers on your website or application and you want to enforce rate limiting based on the tiers, such as:

• If "aud": "free-tier", rate limit to five requests per minute.
• If "aud": "premium-tier", rate limit to 50 requests per minute.

You can follow the rate limiting rule example below:

(http.request.method eq "GET" and
http.host eq "<YOUR_DOMAIN>" and
http.request.uri.path matches "</EXAMPLE_PATH>" and
lookup_json_string(http.request.jwt.claims["<JWT_TOKEN_CONFIGURATION_ID>"][0], "aud") eq "free-tier"

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.