[API Shield] JWT Validation/Volumetric abuse detection rate limiting use case (cloudflare#23770)

* jwt validation use case

* partial

* punctuation

* Apply suggestion from @pedrosousa

Co-authored-by: Pedro Sousa <[email protected]>

* Apply suggestion from @pedrosousa

Co-authored-by: Pedro Sousa <[email protected]>

* Apply suggestion from @pedrosousa

Co-authored-by: Pedro Sousa <[email protected]>

---------

Co-authored-by: Pedro Sousa <[email protected]>

Author: 2 people

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"
 
 <GlossaryTooltip term="JSON web token (JWT)">JSON web tokens (JWT)</GlossaryTooltip> 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.
 
@@ -50,7 +50,6 @@ To automatically keep your JWKS up to date when your identity provider refreshes
 
 ### Add a JWT validation rule
 
-
 <Tabs syncKey="dashNewNav">
   <TabItem label="Old dashboard">
     <Steps>
@@ -104,6 +103,8 @@ 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.
 
+<Render file="rate-limit-user" />
+
 ## 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.

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 
+
+<Render file="rate-limit-user" />
+
 ## 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).

src/content/partials/api-shield/rate-limit-user.mdx

@@ -0,0 +1,31 @@
+---
+{}
+
+---
+
+### 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`
+- 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).
+
+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="Example rule expression"
+(http.request.method eq "GET" and
+http.host eq "<YOUR_DOMAIN>" and
+http.request.uri.path matches "</EXAMPLE_PATH>" and
+lookup_json_string(http.request.jwt.claims["<JWT_TOKEN_CONFIGURATION_ID>"][0], "aud") eq "free-tier"
+```