1# Configuration
2 
3## Schema Validation 2.0 Setup
4 
5> ⚠️ **Classic Schema Validation deprecated.** Use Schema Validation 2.0.
6 
7**Upload schema (Dashboard):**
8```
9Security > API Shield > Schema Validation > Add validation
10- Upload .yml/.yaml/.json (OpenAPI v3.0)
11- Endpoints auto-added to Endpoint Management
12- Action: Log | Block | None
13- Body inspection: JSON payloads
14```
15 
16**Change validation action:**
17```
18Security > API Shield > Settings > Schema Validation
19Per-endpoint: Filter → ellipses → Change action
20Default action: Set global mitigation action
21```
22 
23**Migration from Classic:**
24```
251. Export existing schema (if available)
262. Delete all Classic schema validation rules
273. Wait 5 min for cache clear
284. Re-upload via Schema Validation 2.0 interface
295. Verify in Security > Events
30```
31 
32**Fallthrough rule** (catch-all unknown endpoints):
33```
34Security > API Shield > Settings > Fallthrough > Use Template
35- Select hostnames
36- Create rule with cf.api_gateway.fallthrough_triggered
37- Action: Log (discover) or Block (strict)
38```
39 
40**Body inspection:** Supports `application/json`, `*/*`, `application/*`. Disable origin MIME sniffing to prevent bypasses.
41 
42## JWT Validation
43 
44**Setup token config:**
45```
46Security > API Shield > Settings > JWT Settings > Add configuration
47- Name: "Auth0 JWT Config"
48- Location: Header/Cookie + name (e.g., "Authorization")
49- JWKS: Paste public keys from IdP
50```
51 
52**Create validation rule:**
53```
54Security > API Shield > API Rules > Add rule
55- Hostname: api.example.com
56- Deselect endpoints to ignore
57- Token config: Select config
58- Enforce presence: Ignore or Mark as non-compliant
59- Action: Log/Block/Challenge
60```
61 
62**Rate limit by JWT claim:**
63```wirefilter
64lookup_json_string(http.request.jwt.claims["{config_id}"][0], "sub")
65```
66 
67**Special cases:**
68- Two JWTs, different IdPs: Create 2 configs, select both, "Validate all"
69- IdP migration: 2 configs + 2 rules, adjust actions per state
70- Bearer prefix: API Shield handles with/without
71- Nested claims: Dot notation `user.email`
72 
73## Mutual TLS (mTLS)
74 
75**Setup:**
76```
77SSL/TLS > Client Certificates > Create Certificate
78- Generate CF-managed CA (all plans)
79- Upload custom CA (Enterprise, max 5)
80```
81 
82**Configure mTLS rule:**
83```
84Security > API Shield > mTLS
85- Select hostname(s)
86- Choose certificate(s)
87- Action: Block/Log/Challenge
88```
89 
90**Test:**
91```bash
92openssl req -x509 -newkey rsa:4096 -keyout client-key.pem -out client-cert.pem -days 365
93curl https://api.example.com/endpoint --cert client-cert.pem --key client-key.pem
94```
95 
96## Session Identifiers
97 
98Critical for BOLA Detection, Sequence Mitigation, and analytics. Configure header/cookie that uniquely IDs API users.
99 
100**Examples:** JWT sub claim, session token, API key, custom user ID header
101 
102**Configure:**
103```
104Security > API Shield > Settings > Session Identifiers
105- Type: Header/Cookie
106- Name: "X-User-ID" or "Authorization"
107```
108 
109## BOLA Detection
110 
111Detects Broken Object Level Authorization attacks (enumeration + parameter pollution).
112 
113**Enable:**
114```
115Security > API Shield > Schema Validation > [Select Schema] > BOLA Detection
116- Enable detection
117- Threshold: Sensitivity level (Low/Medium/High)
118- Action: Log or Block
119```
120 
121**Requirements:**
122- Schema Validation 2.0 enabled
123- Session identifiers configured
124- Minimum traffic: 1000+ requests/day per endpoint
125 
126## Authentication Posture
127 
128Identifies unprotected or inconsistently protected endpoints.
129 
130**View report:**
131```
132Security > API Shield > Authentication Posture
133- Shows endpoints lacking JWT/mTLS
134- Highlights mixed authentication patterns
135```
136 
137**Remediate:**
1381. Review flagged endpoints
1392. Add JWT validation rules
1403. Configure mTLS for sensitive endpoints
1414. Monitor posture score
142 
143## Volumetric Abuse + GraphQL
144 
145**Volumetric Abuse Detection:**
146`Security > API Shield > Settings > Volumetric Abuse Detection`
147- Enable per-endpoint monitoring, set thresholds, action: Log | Challenge | Block
148 
149**GraphQL Protection:**
150`Security > API Shield > Settings > GraphQL Protection`
151- Max query depth: 10, max size: 100KB, block introspection (production)
152 
153## Terraform
154 
155```hcl
156# Session identifier
157resource "cloudflare_api_shield" "main" {
158  zone_id = var.zone_id
159  auth_id_characteristics {
160    type = "header"
161    name = "Authorization"
162  }
163}
164 
165# Add endpoint
166resource "cloudflare_api_shield_operation" "users_get" {
167  zone_id  = var.zone_id
168  method   = "GET"
169  host     = "api.example.com"
170  endpoint = "/api/users/{id}"
171}
172 
173# JWT validation rule
174resource "cloudflare_ruleset" "jwt_validation" {
175  zone_id = var.zone_id
176  name    = "API JWT Validation"
177  kind    = "zone"
178  phase   = "http_request_firewall_custom"
179 
180  rules {
181    action = "block"
182    expression = "(http.host eq \"api.example.com\" and not is_jwt_valid(http.request.jwt.payload[\"{config_id}\"][0]))"
183    description = "Block invalid JWTs"
184  }
185}
186```
187 
188## See Also
189 
190- [api.md](api.md) - API endpoints and Workers integration
191- [patterns.md](patterns.md) - Firewall rules and deployment patterns
192- [gotchas.md](gotchas.md) - Troubleshooting and limits
193