Cloudflare Docs
API Shield
Visit API Shield on GitHub
Set theme to dark (⇧+D)

Configure JWT Validation

Use the Cloudflare API to configure JWT Validation, which validates the integrity and validity of JWTs sent by clients to your API or web application.

  1. Gather the information on the JWT issuer you want to verify tokens from.
  2. Create a Token Validation Configuration JSON object.
  3. POST the JSON object to the Cloudflare API to create a new security policy.
  4. Observe requests that may be failing the new security policy.

​​ Required information

Field nameDescriptionExampleNotes
token typeThis specifies the type of token to validate.jwtOnly jwt is currently supported.
titleA human-readable name for the configuration that allows to quickly identify the purpose of the configuration.Production JWT configuration
descriptionA human-readable description that gives more details than title which serves as a means to allow customers to better document the use of the configuration.This configuration is used for all endpoints in endpoint management and checks the JWT in the authorization header.
actionHow we should configure the firewall to act on the validation result.blockpossible: log or block
enabledThis enables or disables acting on the validation result.truepossible: true or false
allow_absent_tokenHow API Shield should handle requests that do not have a JWT present. Setting this to true allows hybrid endpoints where JWTs, if present, must be valid, but JWTs are still allowed to be absent.truepossible: true or false
token_schemaThis describes where the JWT can be found on a request. Currently, we only support extracting them from headers.See example below.The type must be header. The name field denotes the header name from which to extract the JWT.
credentialsThis describes the cryptographic public keys that should be used to validate JWTs. This field must be a JSON web key.See example below.See note below.

​​ Create a Token Validation Configuration JSON object

Refer to the example below to view the configuration using information required for the setup. If you would like to create JWKs for testing, see mkjwk JSON Web Key Generator.

{
"token_type": "jwt",
"title": "example title",
"description": "example description",
"action": "block",
"allow_absent_token": true,
"enabled": true,
"token_schema": {
"type": "header",
"name": "authorization"
},
"credentials": {
"keys": [
{
"kty": "EC",
"use": "sig",
"kid": "test",
"x": "-0LNzBheJPn-Zy6JmanTIUX7xc3jgqU714IQY0oU6mw",
"y": "KONxBybUcRsJQmtu17jMAHsILSw009AuU3ulfUGv3FI",
"alg": "ES256"
}
]
}
}

​​ Send the configuration to Cloudflare’s API

Use cURL or any other API client tool to send the new configuration to Cloudflare’s API to enable JWT Validation. Make sure to replace {zoneID} with the relevant zone ID and add your authentication credentials header.

Example using cURL:

curl -X POST 'https://api.cloudflare.com/client/v4/zones/{zoneID}/api_gateway/token_validation' \
-H 'Content-Type: application/json' \
-d '{
"token_type": "jwt",
"title": "example title",
"description": "example description",
"action": "block",
"allow_absent_token": true,
"enabled": true,
"token_schema": {
"type": "header",
"name": "authorization"
},
"credentials": {
"keys": [
{
"kty": "EC",
"use": "sig",
"kid": "test",
"x": "-0LNzBheJPn-Zy6JmanTIUX7xc3jgqU714IQY0oU6mw",
"y": "KONxBybUcRsJQmtu17jMAHsILSw009AuU3ulfUGv3FI",
"alg": "ES256"
}
]
}
}'

The response will be in a Cloudflare v4 response envelope and the result contains the created configuration. Note the rule ID in the response in order to view any requests failing the policy.

​​ Observe requests matching the policy

  1. Log in to the Cloudflare dashboard and select your account and domain.
  2. Navigate to Security > Events to view the Firewall Events.
  3. Filter for a specific rule ID. The rule ID used for filtering can be obtained from the response after creating the POST command to send the token validation configuration to Cloudflare’s API.

​​ Maintenance

​​ Update the keys

It is best practice to rotate keys after some time. To support updating the keys, Cloudflare allows up to 4 keys per configuration. This allows you to add a second, new key to an already existing key. You can start issuing JWTs with the new key only and remove the old key after some time. Additionally, this feature allows the deployment of testing or development keys next to production keys.

The input to updating the keys is the same as when creating a configuration where you supplied the initial keys using the credentials key and needs to be a JWK.

Use the PUT command to update keys.

Example with cURL:

curl -X PUT 'https://api.cloudflare.com/client/v4/zones/{zoneID}/api_gateway/token_validation/{configID}/credentials' \
-H 'Content-Type: application/json' \
-d '{
"keys": [
{
"kty": "EC",
"use": "sig",
"kid": "test",
"x": "-0LNzBheJPn-Zy6JmanTIUX7xc3jgqU714IQY0oU6mw",
"y": "KONxBybUcRsJQmtu17jMAHsILSw009AuU3ulfUGv3FI",
"alg": "ES256"
},
{
"kty": "EC",
"crv": "P-256",
"kid": "test-2",
"x": "iIbPRbOeLzjGPvv7iwmzCOTU03R0xDqbenp2D6GUcWo",
"y": "tDkEh95PnfWwIXciCtdBBVA7wfghx_egmZ1Zcvu2lWw",
"alg": "ES256"
}
]
}'

Make sure to replace {zoneID} with the relevant zone ID and add your authentication credentials header.

​​ Update parts of the configuration

You may want to first log requests that fail the policy in the firewall and only later block them. Similarly, requirements may change and other parts of the configuration need to be changed. To support this, we allow modifying parts of an existing configuration.

Use PATCH to update other configuration parameters.

Example with cURL:

curl -X PATCH 'https://api.cloudflare.com/client/v4/zones/{zoneID}/api_gateway/token_validation/{configID}' \
-H 'Content-Type: application/json' \
-d '{
"description": "example description",
"allow_absent_token": false,
}'

Make sure to replace {zoneID} with the relevant zone ID and add your authentication credentials header.

​​ How it works

​​ Acting on JWT Validation

JWT Validation manages the Cloudflare firewall on your behalf. There is no need to create firewall rules and customers may not create custom firewall rules with JWT validation properties. Your token validation configuration applies to the entire zone.

There are three properties in a token validation configuration that control how the firewall is configured: enabled, action, and allow_absent_token. Refer to the required information for setup for example values of these fields.

PropertyDescription
enabledThis acts as a global on/off switch.
allow_absent_tokenThis enables a hybrid mode in which the firewall will not act on requests that completely lack a JWT.
actionThis allows to either block a request or log the request.

​​ Performing JWT Validation

Here is an overview of how JWT Validation processes incoming requests:

  1. We extract the JWT in accordance with the configuration from the incoming request.
  2. We decode the JWT and look for the JWTs header KID claim.
  3. We use the KID and ALG claim to find the correct keys in the list of supplied keys.
  1. We validate the authenticity of the JWT by checking the signature using the selected key.
  2. Should the JWT contain an EXP claim (expiration time), we validate that the JWT is not expired.
  1. Should the JWT contain a NBF claim (not before time), we validate that the JWT is already valid.
  1. The final validation result and whether a token was present at all is made available to the firewall which applies the policy’s configured action (log/block).