Configure JWT validation via the API

Use the Cloudflare API to configure JWT validation. A token configuration defines how Cloudflare finds and validates JWTs. You then use a WAF custom rule or a token validation rule to act on the results.

A token configuration defines the JSON Web Key Set (JWKS) used to validate JSON Web Tokens (JWTs). It also defines where Cloudflare finds JWTs in requests.

Token configurations require the following information:

Each item must be a Ruleset Engine expression that resolves to a string.

Currently supported fields are http.request.headers and http.request.cookies.

You can set up to four token sources. If a request has more than one of these fields set, only one will be used. Leading Bearer: strings in request tokens are automatically ignored.

Refer to the Ruleset Engine documentation for details on working with Ruleset Engine fields.

API Shield supports asymmetric RSA and elliptic curve keys and symmetric hash-based message authentication code (HMAC) keys:

Each JWK must have an alg and a kid. The JWT header must contain matching alg and kid values so API Shield can select the correct key.

Provide an alg value for every JWK. The effective algorithm, whether provided or defaulted, must match the alg value in the JWT header. HMAC keys must always specify alg.

For compatibility with identity providers that omit alg, API Shield defaults an RSA key without alg to RS256. RSA key size does not identify which signing algorithm an identity provider uses. Specify alg explicitly if the identity provider uses another supported algorithm.

For an HMAC key, set kty to oct. Set k to the raw symmetric credential encoded with unpadded Base64url. The decoded credential must meet the minimum length for its algorithm.

Cloudflare will remove any fields that are unnecessary from each key and will drop keys that we do not support.

It is highly recommended to validate the output of the API call to check that the resulting keys appear as intended.

The example below shows a JSON object with all of the information necessary to create a token configuration using the Cloudflare API. If you would like to create JWKs for testing, refer to mkjwk JSON Web Key Generator ↗.

{
	"title": "Production JWT configuration",
	"description": "This configuration checks the JWT in the authorization header or cookie.",
	"token_sources": [
		"http.request.headers[\"authorization\"][0]",
		"http.request.cookies[\"Authorization\"][0]"
	],
	"token_type": "jwt",
	"credentials": {
		"keys": [
			{
				"kty": "EC",
				"use": "sig",
				"crv": "P-256",
				"kid": "93UrzmNu1mqXs5cZcvCPkTlMHB2Jya30vSTkiBb0vhU",
				"x": "QG3VFVwUX4IatQvBy7sqBvvmticCZ-eX5-nbtGKBOfI",
				"y": "A3PXCshn7XcG7Ivvd2K_DerW4LHAlIVKdqhrUnczTD0",
				"alg": "ES256"
			}
		]
	}
}

The following example configures JWT validation with an HS256 symmetric key. Replace <BASE64URL_ENCODED_SECRET> with an unpadded Base64url-encoded credential containing at least 32 decoded bytes.

{
	"title": "Production HMAC JWT configuration",
	"description": "This configuration checks the JWT in the authorization header.",
	"token_sources": ["http.request.headers[\"authorization\"][0]"],
	"token_type": "jwt",
	"credentials": {
		"keys": [
			{
				"kty": "oct",
				"alg": "HS256",
				"kid": "production-hmac-key",
				"k": "<BASE64URL_ENCODED_SECRET>"
			}
		]
	}
}

The response includes kty, alg, and kid, but does not include k:

{
	"credentials": {
		"keys": [
			{
				"kty": "oct",
				"alg": "HS256",
				"kid": "production-hmac-key"
			}
		]
	}
}

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 {zone_id} with the relevant zone ID and add your authentication credentials header.

curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/token_validation/config" \
--header 'Content-Type: application/json' \
--data '{
    "title": "Production JWT configuration",
    "description": "This configuration checks the JWT in the authorization header or cookie.",
    "token_sources": [
        "http.request.headers[\"authorization\"][0]",
        "http.request.cookies[\"Authorization\"][0]"
    ],
    "token_type": "jwt",
    "credentials": {
        "keys": [
            {
                "kty": "EC",
                "use": "sig",
                "crv": "P-256",
                "kid": "93UrzmNu1mqXs5cZcvCPkTlMHB2Jya30vSTkiBb0vhU",
                "x": "QG3VFVwUX4IatQvBy7sqBvvmticCZ-eX5-nbtGKBOfI",
                "y": "A3PXCshn7XcG7Ivvd2K_DerW4LHAlIVKdqhrUnczTD0",
                "alg": "ES256"
            }
        ]
    }
}'

The response will be in a Cloudflare v4 response envelope and the result contains the created configuration. Note the returned ID. You can use it to reference the token configuration in JWT claim fields or token validation rules.

{
	"result": {
		"id": "d5902294-00c3-4aed-b517-57e752e9cd58",
		"token_type": "JWT",
		"title": "Production JWT configuration",
		"description": "This configuration checks the JWT in the authorization header or cookie.",
		"token_sources": [
			"http.request.headers[\"authorization\"][0]",
			"http.request.cookies[\"Authorization\"][0]"
		],
		"credentials": {
			"keys": [
				{
					"x": "QG3VFVwUX4IatQvBy7sqBvvmticCZ-eX5-nbtGKBOfI",
					"y": "A3PXCshn7XcG7Ivvd2K_DerW4LHAlIVKdqhrUnczTD0",
					"alg": "ES256",
					"crv": "P-256",
					"kid": "93UrzmNu1mqXs5cZcvCPkTlMHB2Jya30vSTkiBb0vhU",
					"kty": "EC"
				}
			]
		},
		"created_at": "2023-11-08T16:45:17.236841Z",
		"last_updated": "2023-11-08T16:45:17.236841Z"
	},
	"success": true,
	"errors": [],
	"messages": []
}

If API Shield defaults an omitted algorithm, the response includes the effective algorithm in result. The messages array also contains one message for each defaulted key:

{
	"code": 110003,
	"message": "keys[0].alg was omitted and defaulted to \"RS256\" (kid \"key-1\")"
}

Inspect both result and messages to confirm the effective credentials.

After you create a token configuration, Cloudflare checks every request in the zone for a JWT at the configured token sources and validates any token it finds. You do not need a token validation rule or an operation in Endpoint Management for validation. Rules determine how Cloudflare acts on the results.

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.
• Token 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.

To reference a custom claim in a rule expression, you can use lookup_json_* functions like lookup_json_string() with your token configuration ID and the claim name. For a complete example, refer to Issue challenge for admin user in JWT claim based on attack score. For all available fields and standard claims, refer to the JWT validation fields reference.

Token validation rules enforce a security policy using existing token configurations and operations in Endpoint Management.

Token validation rules can be configured using the Cloudflare API or dashboard.

Selectors control to which operations from Endpoint Management Cloudflare applies the action of a token validation rule.

If you only need enforcement on specific hostnames or subdomains of your apex domain, use the hostname in a selector to include matching operations in the JWT validation rule.

If you need to exclude endpoints from enforcement, use the endpoint's operation ID in a selector. For example, you can exclude an endpoint that issues or refreshes JWTs.

To find the operation ID, refer to Endpoint Management or use the Cloudflare API.

A token validation rule's expression defines a security policy that a request must meet.

For example, the expression is_jwt_valid("51231d16-01f1-48e3-93f8-91c99e81288e") or is_jwt_valid("51231d16-01f1-48e3-93f8-91c99e81288e") will trigger if an incoming request does not have at least one valid authentication token.

These expressions are similar to expressions used in Ruleset Engine, with a few key differences:

• The token validation rule actions trigger if the expression evaluates false, as opposed to Ruleset expressions.
• The token validation rules can use dedicated functions that reference token configurations.

Operators such as or, and, eq, and more are usable in expressions in the same way as in expressions used in Ruleset Engine.

The following functions can be used to interact with JWT Tokens on a request:

• is_jwt_valid(token_configuration_id) — Returns true if the request has a valid token according to the token configuration with the ID token_configuration_id.
• is_jwt_present(token_configuration_id) — Returns true if the request has a token as configured in the token configuration with the ID token_configuration_id.

These functions are only available in token validation rules. They are not available in WAF custom rules.

Refer to the following example use cases to understand which security policy to use. For most use cases, Cloudflare recommends requiring a valid token across your API and excluding any paths that are used to establish or refresh tokens using selectors.

The is_jwt_present("51231d16-01f1-48e3-93f8-91c99e81288e") expression will trigger an action if a request is missing a JWT.

It can be combined with a log action in the token validation rule to log requests that are missing an authentication header.

The is_jwt_valid("51231d16-01f1-48e3-93f8-91c99e81288e") expression will trigger an action if a request does not have a valid JWT.

It can be combined with a block action in the token validation rule to block requests with no or invalid credentials.

The is_jwt_valid("51231d16-01f1-48e3-93f8-91c99e81288e") or is_jwt_valid("fddfc39e-3686-4683-ab23-bf917da6bb43") expressions will trigger an action if a request does not have at least one valid token.

This can occur if you need to split JWKs into multiple token configurations.

The is_jwt_valid("51231d16-01f1-48e3-93f8-91c99e81288e") or not is_jwt_present("51231d16-01f1-48e3-93f8-91c99e81288e") expressions will trigger an action if a request has an invalid token, ignoring requests with no tokens at all.

Only one token validation rule can apply to an operation. If an operation is covered by multiple rules, then the rule with highest precedence will take effect.

You can configure which operations JWT validation is enforced on using the selector field.

For example, the following selector will apply a rule to all operations in v1.example.com and v2.example.com, except for two operations on these hosts:

{
	"include": [
		{
			"host": ["v1.example.com", "v2.example.com"]
		}
	],
	"exclude": [
		{
			"operation_ids": [
				"f9c5615e-fe15-48ce-bec6-cfc1946f1bec", // POST v1.example.com/login
				"56828eae-035a-4396-ba07-51c66d680a04" // POST v2.example.com/login
			]
		}
	]
}

Operations can be included at a host level and ignored on a per-operation basis.

You can use the POST /zones/{zone_id}/token_validation/rules/preview endpoint to see the operations covered by this rule:

curl --request PUT \
'https://api.cloudflare.com/client/v4/zones/{zone_id}/token_validation/rules/preview' \
--header 'Content-Type: application/json' \
--data '{
    "include": [
        {
            "host": [
                "v1.example.com",
                "v2.example.com"
            ]
        }
    ],
    "exclude": [
        {
            "operation_ids": [
                "f9c5615e-fe15-48ce-bec6-cfc1946f1bec", // POST v1.example.com/login
                "56828eae-035a-4396-ba07-51c66d680a04"  // POST v2.example.com/login
            ]
        }
    ]
}'

The response will include all operations on a zone with an additional state field.

The state field can be ignored, excluded, or included. Included operations will match the hostname selectors you specified. Excluded operations will match the operation IDs you specified in the selector. Ignored operations are those that do not match anything specified in the selector.

{
	"result": {
		"operations": [
			{
				"operation_id": "ed15fcb6-5a73-41cd-91af-8c61e5bb1cdb",
				"method": "GET",
				"host": "example.com",
				"endpoint": "/api/accounts/{var1}",
				"last_updated": "2023-05-24T14:54:34.806506Z",
				"state": "ignored"
			},
			{
				"operation_id": "e7a582cd-3cfb-4061-ab5b-722e6e42f545",
				"method": "GET",
				"host": "v1.example.com",
				"endpoint": "/api/accounts/{var1}",
				"last_updated": "2023-05-24T14:54:34.806506Z",
				"state": "included"
			},
			{
				"operation_id": "ddd5df5a-795c-40ce-b38c-38e9d7ef9ae8",
				"method": "GET",
				"host": "v2.example.com",
				"endpoint": "/api/accounts/{var1}",
				"last_updated": "2023-05-24T14:54:34.806506Z",
				"state": "included"
			},
			{
				"operation_id": "4d20befb-0120-45d5-9b29-5835fd41b44e",
				"method": "GET",
				"host": "v3.example.com",
				"endpoint": "/api/accounts/{var1}",
				"last_updated": "2023-05-24T14:54:34.806506Z",
				"state": "ignored"
			},
			{
				"operation_id": "f9c5615e-fe15-48ce-bec6-cfc1946f1bec",
				"method": "POST",
				"host": "v1.example.com",
				"endpoint": "/login",
				"last_updated": "2023-05-24T14:54:34.806506Z",
				"state": "excluded"
			},
			{
				"operation_id": "56828eae-035a-4396-ba07-51c66d680a04",
				"method": "POST",
				"host": "v2.example.com",
				"endpoint": "/login",
				"last_updated": "2023-05-24T14:54:34.806506Z",
				"state": "excluded"
			},
			{
				"operation_id": "cf86874c-8d0c-4337-ae14-4e2459b541ac",
				"method": "GET",
				"host": "v3.example.com",
				"endpoint": "login",
				"last_updated": "2023-05-24T14:54:34.806506Z",
				"state": "ignored"
			}
		],
		"total": 7,
		"included": 2,
		"excluded": 2,
		"ignored": 3,
		"selected_hosts": ["v1.example.com", "v2.example.com"],
		"available_hosts": [
			"example.com",
			"v1.example.com",
			"v1.example.com",
			"v3.example.com"
		]
	},
	"success": true,
	"errors": [],
	"messages": [],
	"result_info": {
		"page": 1,
		"per_page": 20,
		"count": 20,
		"total_count": 1631
	}
}

Operations with a included state will be covered by the token validation rule. The response also shows the hostnames of included operations in result.selected_hosts and shows all hostnames used by all zone operations in result.available_hosts.

You can also send an empty object in the request body:

curl --request PUT \
'https://api.cloudflare.com/client/v4/zones/{zone_id}/token_validation/rules/preview' \
--header 'Content-Type: application/json' \
--data '{ }'

The response will show all zone operations and all possible hosts, which you can use to build your own selector.

The example below shows a JSON object with all the necessary information to create a token validation rule using the Cloudflare API.

Replace any token configurations IDs and operation IDs with the IDs that exist in your zone.

[
	{
		"title": "JWT Validation on v1 and v2.example.com",
		"description": "Log requests without a valid authorization header.",
		"action": "log",
		"enabled": true,
		"expression": "is_jwt_valid(\"00170473-ec24-410e-968a-9905cf0a7d03\")",
		"selector": {
			"include": [
				{
					"host": ["v1.example.com", "v2.example.com"]
				}
			],
			"exclude": [
				{
					"operation_ids": [
						"f9c5615e-fe15-48ce-bec6-cfc1946f1bec",
						"56828eae-035a-4396-ba07-51c66d680a04"
					]
				}
			]
		}
	}
]

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 {zone_id} with the relevant zone ID and add your authentication credentials header.

Replace any token configurations IDs and operation IDs with the IDs that exist in your zone.

A single request can create multiple rules. To do so, pass multiple rule objects in the JSON array of the request body.

curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/token_validation/rules/bulk" \
--header 'Content-Type: application/json' \
--data '[
    {
        "title": "JWT Validation on v1 and v2.example.com",
        "description": "Log requests without a valid authorization header.",
        "action": "log",
        "enabled": true,
        "expression": "is_jwt_valid(\"00170473-ec24-410e-968a-9905cf0a7d03\")",
        "selector": {
            "include": [
                {
                    "host": [
                        "v1.example.com",
                        "v2.example.com"
                    ]
                }
            ],
            "exclude": [
                {
                    "operation_ids": [
                        "f9c5615e-fe15-48ce-bec6-cfc1946f1bec",
                        "56828eae-035a-4396-ba07-51c66d680a04"
                    ]
                }
            ]
        }
    }
]'

The response will be in a Cloudflare v4 response envelope and the result contains the created rules. Note the returned ID for each rule, which can be used to edit or delete an existing rule.

{
	"result": [
		{
			"id": "5ec7c417-6964-4b24-b82c-a23a7ec8f90c",
			"title": "JWT Validation on v1 and v2.example.com",
			"description": "Log requests without a valid authorization header.",
			"action": "log",
			"enabled": true,
			"expression": "is_jwt_valid(\"00170473-ec24-410e-968a-9905cf0a7d03\")",
			"selector": {
				"include": [
					{
						"host": ["v1.example.com", "v2.example.com"]
					}
				],
				"exclude": [
					{
						"operation_ids": [
							"f9c5615e-fe15-48ce-bec6-cfc1946f1bec",
							"56828eae-035a-4396-ba07-51c66d680a04"
						]
					}
				]
			},
			"created_at": "2023-10-18T12:08:09.575388Z",
			"last_updated": "2023-10-18T12:08:09.575388Z",
			"modified_by": "user@cloudflare.com"
		}
	],
	"success": true,
	"errors": [],
	"messages": []
}

It is best practice to rotate keys regularly. You can add a new key, start issuing JWTs with that key, and then remove the old key.

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.

Credential updates use the same algorithm compatibility behavior as configuration creation. The response includes normalized credentials and a message for each defaulted algorithm.

Use PUT to replace the complete key set. Every symmetric key in a PUT request must include k. Keys omitted from the request are removed.

curl --request PUT \
'https://api.cloudflare.com/client/v4/zones/{zone_id}/token_validation/config/{config_id}/credentials' \
--header 'Content-Type: application/json' \
--data '{
    "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 {zone_id} with the relevant zone ID and add your authentication credentials header.

Use PATCH to update the complete key set without resubmitting stored symmetric credentials. Cloudflare matches an existing key using its alg and kid values.

• Omit k for a matching symmetric key to preserve its credential.
• Include a new k value to rotate the credential.
• Include k when adding a symmetric key that does not already exist.
• Omit a key from keys to remove it from the configuration.
• Do not set k to null.

This example preserves the credential for production-hmac-key while adding an EC key:

curl --request PATCH \
'https://api.cloudflare.com/client/v4/zones/{zone_id}/token_validation/config/{config_id}/credentials' \
--header 'Content-Type: application/json' \
--data '{
    "keys": [
        {
            "kty": "oct",
            "alg": "HS256",
            "kid": "production-hmac-key"
        },
        {
            "kty": "EC",
            "alg": "ES256",
            "crv": "P-256",
            "kid": "production-ec-key",
            "x": "<BASE64URL_ENCODED_X_COORDINATE>",
            "y": "<BASE64URL_ENCODED_Y_COORDINATE>"
        }
    ]
}'

This example rotates the credential for the existing HMAC key:

curl --request PATCH \
'https://api.cloudflare.com/client/v4/zones/{zone_id}/token_validation/config/{config_id}/credentials' \
--header 'Content-Type: application/json' \
--data '{
    "keys": [
        {
            "kty": "oct",
            "alg": "HS256",
            "kid": "production-hmac-key",
            "k": "<NEW_BASE64URL_ENCODED_SECRET>"
        }
    ]
}'

Token validation rules can be updated with a PATCH request. A single PATCH request can update multiple rules.

A PATCH request is specified as a JSON array in the request body. Each item in that array contains updates to a single rule, defined by id.

The following example updates one rule and disables another:

curl --request PATCH \
"https://api.cloudflare.com/client/v4/zones/{zone_id}/token_validation/rules/bulk"  \
--header "Content-Type: application/json" \
--data '[
    {
        "id": "714d3dd0-cc59-4911-862f-8a27e22353cc",
        "action": "log",
        "title": "updated title"
    },
    {
        "id": "7124f9bc-d6b5-430d-b488-b6bc2892f2fb",
        "enabled": false
    }
]'

Rules can be reordered by setting a position field in the PATCH body.

This example places rule 714d3dd0-cc59-4911-862f-8a27e22353cc after rule 7124f9bc-d6b5-430d-b488-b6bc2892f2fb:

curl --request PATCH \
"https://api.cloudflare.com/client/v4/zones/{zone_id}/token_validation/rules/bulk" \
--header 'Content-Type: application/json' \
--data '[
    {
        "id": "714d3dd0-cc59-4911-862f-8a27e22353cc",
        "position": {
            "after": "7124f9bc-d6b5-430d-b488-b6bc2892f2fb"
        }
    }
]'

This example places rule 714d3dd0-cc59-4911-862f-8a27e22353cc before rule 7124f9bc-d6b5-430d-b488-b6bc2892f2fb:

curl --request PATCH \
"https://api.cloudflare.com/client/v4/zones/{zone_id}/token_validation/rules/bulk" \
--header 'Content-Type: application/json' \
--data '[
    {
        "id": "714d3dd0-cc59-4911-862f-8a27e22353cc",
        "position": {
            "before": "7124f9bc-d6b5-430d-b488-b6bc2892f2fb"
        }
    }
]'

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. Cloudflare makes verified claims available as http.request.jwt.claims fields. WAF custom rules can act on these claims. Token validation rules can act on token presence and validity.

8. Security Analytics events in the Cloudflare dashboard for the API Shield - Token Validation service will explain violation reasons in the Token validation violations section of the event.