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.
- Gather the information on the JWT issuer you want to verify tokens from.
- Create a Token Validation Configuration JSON object.
POST
the JSON object to the Cloudflare API to create a new security policy.- Observe requests that may be failing the new security policy.
Required information
Field name | Description | Example | Notes |
---|---|---|---|
token type | This specifies the type of token to validate. | jwt | Only jwt is currently supported. |
title | A human-readable name for the configuration that allows to quickly identify the purpose of the configuration. | Production JWT configuration | |
description | A 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. | |
action | How we should configure the firewall to act on the validation result. | block | possible: log or block |
enabled | This enables or disables acting on the validation result. | true | possible: true or false |
allow_absent_token | How 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. | true | possible: true or false |
token_schema | This 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. |
credentials | This 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
- Log in to the Cloudflare dashboard and select your account and domain.
- Navigate to Security > Events to view the Firewall Events.
- 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.
Property | Description |
---|---|
enabled | This acts as a global on/off switch. |
allow_absent_token | This enables a hybrid mode in which the firewall will not act on requests that completely lack a JWT. |
action | This allows to either block a request or log the request. |
Performing JWT Validation
Here is an overview of how JWT Validation processes incoming requests:
- We extract the JWT in accordance with the configuration from the incoming request.
- We decode the JWT and look for the JWTs header KID claim.
- We use the KID and ALG claim to find the correct keys in the list of supplied keys.
- We validate the authenticity of the JWT by checking the signature using the selected key.
- Should the JWT contain an EXP claim (expiration time), we validate that the JWT is not expired.
- Should the JWT contain a NBF claim (not before time), we validate that the JWT is already valid.
- 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
).