Skip to content

[API Shield] Document default JWK algorithm #32271

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
janrueth wants to merge 1 commit into
base: production
Choose a base branch
from
+17 −0
Open

[API Shield] Document default JWK algorithm #32271

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions src/content/docs/api-shield/security/jwt-validation/api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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 <GlossaryTooltip term="API call">API call</GlossaryTooltip> 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"
Expand Down
Loading