From ee3d7ef59cffaa00bd09ec1cc54778e3e73808ce Mon Sep 17 00:00:00 2001 From: Patricia Loraine Santa Ana Date: Thu, 17 Jul 2025 13:48:33 -0700 Subject: [PATCH 1/6] jwt validation use case --- .../security/jwt-validation/index.mdx | 25 ++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/src/content/docs/api-shield/security/jwt-validation/index.mdx b/src/content/docs/api-shield/security/jwt-validation/index.mdx index b0b395a7e5676a2..0948f5252b423b2 100644 --- a/src/content/docs/api-shield/security/jwt-validation/index.mdx +++ b/src/content/docs/api-shield/security/jwt-validation/index.mdx @@ -50,7 +50,6 @@ To automatically keep your JWKS up to date when your identity provider refreshes ### Add a JWT validation rule - @@ -104,6 +103,30 @@ If you expect to migrate between two different identity providers, you must crea API Shield will verify JSON Web Tokens regardless of whether or not they have the `Bearer` prefix. +### Rate limit by user (JWT claim) + +You can rate limit requests based on any claim inside of a JSON Web Token (JWT), such as registered claims like `aud` or `sub`, or custom claims like `userEmail` or nested custom claims like `user.email`. + +Rate limiting based on JWT claim values will only work on valid JSON Web Tokens. If you do not block invalid JSON Web Tokens on your path, the [JWT claims will all be counted and possibly blocked](https://developers.cloudflare.com/waf/rate-limiting-rules/parameters/#missing-field-versus-empty-value) if high traffic is detected in the Point of Presence (PoP). + +You must also count the JWT claim that uniquely identifies the user. If you select a claim that is the same for many of your users, their rate limits will all be counted together. + +### Rate limit by user tier + +If you offer multiple tiers on your website or application and you want to enforce rate limiting based on the tiers, such as: + +- If `"aud": "free-tier"`, rate limit to five requests per minute +- If `"aud": "premium-tier"`, rate limit to 50 requests per minute + +You can follow the rate limiting rule example below: + +```txt title="Rule example" +(http.request.method eq "GET" and +http.host eq "" and +http.request.uri.path matches "" and +lookup_json_string(http.request.jwt.claims[""][0], "aud") eq "free-tier" +``` + ## Availability JWT validation is available for all API Shield customers. Enterprise customers who have not purchased API Shield can preview [API Shield as a non-contract service](https://dash.cloudflare.com/?to=/:account/:zone/security/api-shield) in the Cloudflare dashboard or by contacting your account team. From 6f5a673c5101fd985a539f464baf64236996bfa0 Mon Sep 17 00:00:00 2001 From: Patricia Loraine Santa Ana Date: Thu, 17 Jul 2025 13:58:07 -0700 Subject: [PATCH 2/6] partial --- .../security/jwt-validation/index.mdx | 26 ++--------------- .../security/volumetric-abuse-detection.mdx | 6 +++- .../partials/api-shield/rate-limit-user.mdx | 28 +++++++++++++++++++ 3 files changed, 35 insertions(+), 25 deletions(-) create mode 100644 src/content/partials/api-shield/rate-limit-user.mdx diff --git a/src/content/docs/api-shield/security/jwt-validation/index.mdx b/src/content/docs/api-shield/security/jwt-validation/index.mdx index 0948f5252b423b2..e5d944472a8e0fe 100644 --- a/src/content/docs/api-shield/security/jwt-validation/index.mdx +++ b/src/content/docs/api-shield/security/jwt-validation/index.mdx @@ -6,7 +6,7 @@ sidebar: --- -import { GlossaryTooltip, Steps, Tabs, TabItem } from "~/components" +import { GlossaryTooltip, Steps, Tabs, TabItem, Render } from "~/components" JSON web tokens (JWT) are often used as part of an authentication component on many web applications today. Since JWTs are crucial to identifying users and their access, ensuring the token’s integrity is important. @@ -103,29 +103,7 @@ If you expect to migrate between two different identity providers, you must crea API Shield will verify JSON Web Tokens regardless of whether or not they have the `Bearer` prefix. -### Rate limit by user (JWT claim) - -You can rate limit requests based on any claim inside of a JSON Web Token (JWT), such as registered claims like `aud` or `sub`, or custom claims like `userEmail` or nested custom claims like `user.email`. - -Rate limiting based on JWT claim values will only work on valid JSON Web Tokens. If you do not block invalid JSON Web Tokens on your path, the [JWT claims will all be counted and possibly blocked](https://developers.cloudflare.com/waf/rate-limiting-rules/parameters/#missing-field-versus-empty-value) if high traffic is detected in the Point of Presence (PoP). - -You must also count the JWT claim that uniquely identifies the user. If you select a claim that is the same for many of your users, their rate limits will all be counted together. - -### Rate limit by user tier - -If you offer multiple tiers on your website or application and you want to enforce rate limiting based on the tiers, such as: - -- If `"aud": "free-tier"`, rate limit to five requests per minute -- If `"aud": "premium-tier"`, rate limit to 50 requests per minute - -You can follow the rate limiting rule example below: - -```txt title="Rule example" -(http.request.method eq "GET" and -http.host eq "" and -http.request.uri.path matches "" and -lookup_json_string(http.request.jwt.claims[""][0], "aud") eq "free-tier" -``` + ## Availability diff --git a/src/content/docs/api-shield/security/volumetric-abuse-detection.mdx b/src/content/docs/api-shield/security/volumetric-abuse-detection.mdx index 9a94ed7ab713990..48fbb3777d05a35 100644 --- a/src/content/docs/api-shield/security/volumetric-abuse-detection.mdx +++ b/src/content/docs/api-shield/security/volumetric-abuse-detection.mdx @@ -7,7 +7,7 @@ sidebar: --- -import { GlossaryTooltip, Steps } from "~/components" +import { GlossaryTooltip, Steps, Render } from "~/components" Cloudflare Volumetric Abuse Detection helps you set up a system of adaptive rate limiting. @@ -60,6 +60,10 @@ Refer to the [Rules documentation](https://developers.cloudflare.com/waf/rate-li [Rate limit recommendations are available via the API](/api/resources/api_gateway/subresources/operations/methods/get/) if you would like to dynamically update rate limits over time. +## Special cases + + + ## Limitations API Shield will always calculate recommendations when session identifiers are configured. To enable session-based rate limits, [subscribe to Advanced Rate Limiting](/waf/rate-limiting-rules/#availability). diff --git a/src/content/partials/api-shield/rate-limit-user.mdx b/src/content/partials/api-shield/rate-limit-user.mdx new file mode 100644 index 000000000000000..e4825b02ca3f446 --- /dev/null +++ b/src/content/partials/api-shield/rate-limit-user.mdx @@ -0,0 +1,28 @@ +--- +{} + +--- + +### Rate limit by user (JWT claim) + +You can rate limit requests based on any claim inside of a JSON Web Token (JWT), such as registered claims like `aud` or `sub`, or custom claims like `userEmail` or nested custom claims like `user.email`. + +Rate limiting based on JWT claim values will only work on valid JSON Web Tokens. If you do not block invalid JSON Web Tokens on your path, the [JWT claims will all be counted and possibly blocked](https://developers.cloudflare.com/waf/rate-limiting-rules/parameters/#missing-field-versus-empty-value) if high traffic is detected in the Point of Presence (PoP). + +You must also count the JWT claim that uniquely identifies the user. If you select a claim that is the same for many of your users, their rate limits will all be counted together. + +### Rate limit by user tier + +If you offer multiple tiers on your website or application and you want to enforce rate limiting based on the tiers, such as: + +- If `"aud": "free-tier"`, rate limit to five requests per minute +- If `"aud": "premium-tier"`, rate limit to 50 requests per minute + +You can follow the rate limiting rule example below: + +```txt title="Rule example" +(http.request.method eq "GET" and +http.host eq "" and +http.request.uri.path matches "" and +lookup_json_string(http.request.jwt.claims[""][0], "aud") eq "free-tier" +``` From ee4cbf1ff02aba92a416ecee1b98258105959f5c Mon Sep 17 00:00:00 2001 From: Patricia Loraine Santa Ana Date: Thu, 17 Jul 2025 13:59:52 -0700 Subject: [PATCH 3/6] punctuation --- src/content/partials/api-shield/rate-limit-user.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/partials/api-shield/rate-limit-user.mdx b/src/content/partials/api-shield/rate-limit-user.mdx index e4825b02ca3f446..8c4055e257fa1c6 100644 --- a/src/content/partials/api-shield/rate-limit-user.mdx +++ b/src/content/partials/api-shield/rate-limit-user.mdx @@ -15,8 +15,8 @@ You must also count the JWT claim that uniquely identifies the user. If you sele If you offer multiple tiers on your website or application and you want to enforce rate limiting based on the tiers, such as: -- If `"aud": "free-tier"`, rate limit to five requests per minute -- If `"aud": "premium-tier"`, rate limit to 50 requests per minute +- If `"aud": "free-tier"`, rate limit to five requests per minute. +- If `"aud": "premium-tier"`, rate limit to 50 requests per minute. You can follow the rate limiting rule example below: From 3c22108ba62a9c03f1c39df31b1fc41258749a99 Mon Sep 17 00:00:00 2001 From: Patricia Santa Ana <103445940+patriciasantaana@users.noreply.github.com> Date: Fri, 18 Jul 2025 08:04:08 -0700 Subject: [PATCH 4/6] Apply suggestion from @pedrosousa Co-authored-by: Pedro Sousa <680496+pedrosousa@users.noreply.github.com> --- src/content/partials/api-shield/rate-limit-user.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/partials/api-shield/rate-limit-user.mdx b/src/content/partials/api-shield/rate-limit-user.mdx index 8c4055e257fa1c6..54509b53bdf2d88 100644 --- a/src/content/partials/api-shield/rate-limit-user.mdx +++ b/src/content/partials/api-shield/rate-limit-user.mdx @@ -20,7 +20,7 @@ If you offer multiple tiers on your website or application and you want to enfor You can follow the rate limiting rule example below: -```txt title="Rule example" +```txt title="Example rule expression" (http.request.method eq "GET" and http.host eq "" and http.request.uri.path matches "" and From da300b22b69a520d7bca144801d88e683bfa2233 Mon Sep 17 00:00:00 2001 From: Patricia Santa Ana <103445940+patriciasantaana@users.noreply.github.com> Date: Fri, 18 Jul 2025 08:04:14 -0700 Subject: [PATCH 5/6] Apply suggestion from @pedrosousa Co-authored-by: Pedro Sousa <680496+pedrosousa@users.noreply.github.com> --- src/content/partials/api-shield/rate-limit-user.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/partials/api-shield/rate-limit-user.mdx b/src/content/partials/api-shield/rate-limit-user.mdx index 54509b53bdf2d88..99a346a1aa8b715 100644 --- a/src/content/partials/api-shield/rate-limit-user.mdx +++ b/src/content/partials/api-shield/rate-limit-user.mdx @@ -7,7 +7,7 @@ You can rate limit requests based on any claim inside of a JSON Web Token (JWT), such as registered claims like `aud` or `sub`, or custom claims like `userEmail` or nested custom claims like `user.email`. -Rate limiting based on JWT claim values will only work on valid JSON Web Tokens. If you do not block invalid JSON Web Tokens on your path, the [JWT claims will all be counted and possibly blocked](https://developers.cloudflare.com/waf/rate-limiting-rules/parameters/#missing-field-versus-empty-value) if high traffic is detected in the Point of Presence (PoP). +Rate limiting based on JWT claim values will only work on valid JSON Web Tokens. If you do not block invalid JSON Web Tokens on your path, the [JWT claims will all be counted and possibly blocked](/waf/rate-limiting-rules/parameters/#missing-field-versus-empty-value) if high traffic is detected in the Point of Presence (PoP). You must also count the JWT claim that uniquely identifies the user. If you select a claim that is the same for many of your users, their rate limits will all be counted together. From dec66aaf15e8f62381736100b7a8d002fa1a55c3 Mon Sep 17 00:00:00 2001 From: Patricia Santa Ana <103445940+patriciasantaana@users.noreply.github.com> Date: Fri, 18 Jul 2025 08:04:20 -0700 Subject: [PATCH 6/6] Apply suggestion from @pedrosousa Co-authored-by: Pedro Sousa <680496+pedrosousa@users.noreply.github.com> --- src/content/partials/api-shield/rate-limit-user.mdx | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/content/partials/api-shield/rate-limit-user.mdx b/src/content/partials/api-shield/rate-limit-user.mdx index 99a346a1aa8b715..9cdc3591641dfcf 100644 --- a/src/content/partials/api-shield/rate-limit-user.mdx +++ b/src/content/partials/api-shield/rate-limit-user.mdx @@ -5,7 +5,10 @@ ### Rate limit by user (JWT claim) -You can rate limit requests based on any claim inside of a JSON Web Token (JWT), such as registered claims like `aud` or `sub`, or custom claims like `userEmail` or nested custom claims like `user.email`. +You can rate limit requests based on any claim inside of a JSON Web Token (JWT), such as: + +- Registered claims like `aud` or `sub` +- Custom claims like `userEmail`, including nested custom claims like `user.email` Rate limiting based on JWT claim values will only work on valid JSON Web Tokens. If you do not block invalid JSON Web Tokens on your path, the [JWT claims will all be counted and possibly blocked](/waf/rate-limiting-rules/parameters/#missing-field-versus-empty-value) if high traffic is detected in the Point of Presence (PoP).