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

​​ 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 Open external link .

{
    "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 Open external link 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.

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

4. We validate the authenticity of the JWT by checking the signature using the selected key.
5. Should the JWT contain an EXP claim (expiration time), we validate that the JWT is not expired.

6. Should the JWT contain a NBF claim (not before time), we validate that the JWT is already valid.

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