From ec3f8cc9bac0fae7851b4fad3a0222c38fa6af83 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20R=C3=BCth?= <1324490+janrueth@users.noreply.github.com> Date: Thu, 23 Jul 2026 13:33:41 +0200 Subject: [PATCH] [API Shield] Document default JWK algorithm --- .../api-shield/security/jwt-validation/api.mdx | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/src/content/docs/api-shield/security/jwt-validation/api.mdx b/src/content/docs/api-shield/security/jwt-validation/api.mdx index 366208e70f3..4fe52270c73 100644 --- a/src/content/docs/api-shield/security/jwt-validation/api.mdx +++ b/src/content/docs/api-shield/security/jwt-validation/api.mdx @@ -51,6 +51,10 @@ Refer to the [Ruleset Engine documentation](/ruleset-engine/rules-language/field API Shield supports credentials of type `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `PS512`, `ES256`, and `ES384`. RSA keys must be at least 2048-bit. Each JSON web key must have a “KID” which must be present in the JWT's header as well to allow API Shield to match them. +Provide an `alg` value for every JSON web key. The effective algorithm, whether provided or defaulted, must match the `alg` value in the JWT header. + +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. + We allow up to 4 different keys in order to aid in key rollover. Cloudflare will remove any fields that are unnecessary from each key and will drop keys that we do not support. @@ -151,6 +155,17 @@ The response will be in a Cloudflare `v4` response envelope and the result conta } ``` +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: + +```json title="Example message for a defaulted algorithm" +{ + "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. + ## Token validation rules Token validation rules allow you to enforce a security policy using existing token configurations. @@ -514,6 +529,8 @@ Cloudflare will remove any fields that are unnecessary from each key and will dr It is highly recommended to validate the output of the API call to check that the resulting keys appear as intended. ::: +Credential updates use the same algorithm compatibility behavior as configuration creation. The response includes normalized credentials and a message for each defaulted algorithm. + Use the `PUT` command to update keys. ```bash title="Example using cURL"