Cloudflare API Shield API Gateway 接口全解端点管理、JWT 校验与 Workers 安全上下文集成指南【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skillsCloudflare API Shield 是面向 API 的发现、保护与监控安全套件其全部能力都暴露在一组以/zones/{zone_id}/api_gateway为基路径的 REST 接口上。本文以该 API 参考为主线逐节讲解端点管理、API 发现、会话标识配置、JWT 校验、BOLA 检测、认证态势与 GraphQL 防护的请求/响应模型并结合仓库内同目录的 configuration.md、patterns.md 与 gotchas.md 补充面板操作、防火墙规则与使用限制读完可独立完成 API Gateway 的自动化配置与 Workers 运行时安全上下文读取。接口总览一切从/api_gateway基路径开始API Shield 的编程接口统一以/zones/{zone_id}/api_gateway为前缀见 api.md其中{zone_id}为要保护的域名所属 Zone 的 ID。所有请求均走 Cloudflare v4 REST API认证方式推荐使用BearerAPI Token完整鉴权方案见 API 参考的认证章节。按功能维度接口可以划分为七个模块模块核心路径职责Endpoint Management/operations受保护端点的增删查API Discovery/discovery/operations自动发现并纳管真实 APIConfig/configuration会话标识Session Identifier配置Token Validation/token_validation、/jwt_validation_rulesJWT 校验配置与规则BOLA Detection/user_schemas/{schema_id}/bola对象级越权攻击检测Auth Posture/discovery/authentication_posture认证覆盖态势报告GraphQL Protection/settings/graphql_protectionGraphQL 查询深度/大小限制这七个模块与面板Security API Shield中的功能一一对应下文逐一展开。Endpoint Management端点管理的完整 CRUDEndpoint Management 用于维护需要被 API Shield 保护的端点清单是 Schema Validation、JWT 校验等一切能力的作用对象。接口定义见 api.mdGET /operations # List 列出全部端点 GET /operations/{op_id} # Get single 查询单个端点 POST /operations/item # Create 创建{endpoint,host,method} POST /operations # Bulk 批量创建{operations:[{endpoint,host,method}]} DELETE /operations/{op_id} # Delete 删除单个端点 DELETE /operations # Bulk delete 批量删除{operation_ids:[...]}几个关键设计点端点的三元组标识是{endpoint, host, method}即“路径模板 域名 HTTP 方法”。路径支持变量归一化例如/profile/238会被自动归一化为/profile/{var1}见 gotchas.md因此创建时应使用路径模板而非具体实例。批量操作一次到位批量创建用operations数组批量删除用operation_ids数组适合首次接入时全量灌入 OpenAPI 导出的端点集合。在面板中上传 OpenAPI v3.0 的.yml/.yaml/.json规范文件后端点会被自动加入 Endpoint Management见 configuration.md与POST /operations/item手动创建的效果一致。Terraform 中对应的资源是cloudflare_api_shield_operation见 configuration.mdresource cloudflare_api_shield_operation users_get { zone_id var.zone_id method GET host api.example.com endpoint /api/users/{id} }API Discovery自动发现影子 API 并导出 OpenAPIDiscovery 模块用于发现实际流量中出现的、尚未被纳管的 API是治理“影子 API”Shadow API的入口。接口见 api.mdGET /discovery/operations # List 列出已发现的端点 PATCH /discovery/operations/{op_id} # Update 更新单个{state:saved|ignored} PATCH /discovery/operations # Bulk 批量更新{operation_ids:{id:{state}}} GET /discovery # OpenAPI export 导出 OpenAPI 规范使用要点发现结果需要“确认”通过PATCH将端点状态置为saved纳入管理或ignored忽略批量更新时按{operation_ids:{id:{state}}}的映射结构提交。GET /discovery直接导出 OpenAPI可将发现结果一键转成标准 OpenAPI 规范再回灌到 Schema Validation 2.0 或内部文档系统形成闭环。触发条件有硬性门槛发现依赖机器学习模型要求 10 天内至少 500 次请求、且来自边缘的 2xx 响应Workers 直连请求不计入模型每日更新见 gotchas.md。API Discovery 属 Enterprise 功能支持 10K 操作见 patterns.md。Configuration会话标识Session Identifier是安全分析的地基会话标识用于唯一标识 API 调用者是 BOLA Detection、Sequence Mitigation 与安全分析的前提。对应的配置接口见 api.mdGET /configuration # Get 读取当前会话标识配置 PUT /configuration # Update 更新{auth_id_characteristics:[{name,type:header|cookie}]}auth_id_characteristics数组中的每一项描述一个识别维度type只能取header或cookiename为具体的请求头或 Cookie 名。常见取值包括 JWT 的sub声明、会话 Token、API Key 或自定义用户 ID 请求头如X-User-ID、Authorization详见 configuration.md。对应的 Terraform 资源是cloudflare_api_shield见 configuration.mdresource cloudflare_api_shield main { zone_id var.zone_id auth_id_characteristics { type header name Authorization } }从源码结构看api.md 的PUT /configuration与上述 Terraform 资源配置在语义上一一对应是同一配置在 REST 与 IaC 两种形态下的表达。Token ValidationJWT 校验的配置与规则Token Validation 负责配置 JWT 校验来源与校验规则是 API 认证安全的程序化入口。接口见 api.mdGET /token_validation # List 列出校验配置 POST /token_validation # Create 创建{name,location:{header:...},jwks:...} POST /jwt_validation_rules # Rule 创建规则{name,hostname,token_validation_id,action:block}创建 Token 配置POST /token_validation的请求体包含三要素name配置名称例如Auth0 JWT ConfiglocationToken 位置目前仅支持 Header 或 Cookie不支持查询参数与请求体例如{header: Authorization}API Shield 会自动兼容有无Bearer前缀两种情况jwks身份提供方IdP的 JWKS 公钥集 JSON 字符串用于本地完成签名校验。创建校验规则POST /jwt_validation_rules将 Token 配置绑定到具体主机名并决定处置动作{name, hostname, token_validation_id, action:block}。在面板中等价的完整流程见 configuration.md选择主机名、按需排除端点、绑定 Token 配置、设置“Enforce presence”忽略或标记为非合规、最后指定 Log/Block/Challenge 动作。进阶场景双 IdP 并存 / 迁移创建 2 个 Token 配置与 2 条规则选择“Validate all”按迁移阶段分别调整动作即可见 configuration.md。嵌套声明JWT 声明最多支持 10 层嵌套使用点号记法如user.email见 gotchas.md。按 JWT 声明限速结合 Rate Limiting用lookup_json_string提取sub作为计数维度见 configuration.md。Workers Integration在 Workers 运行时读取安全上下文API Shield 的校验结果会通过req.cf对象注入 Workers 请求上下文使边缘代码可以直接消费安全决策。三类典型用法见 api.md。读取 Access JWT Claimsexport default { async fetch(req, env) { // Access validated JWT payload const jwt req.cf?.jwt?.payload?.[env.JWT_CONFIG_ID]?.[0]; if (jwt) { const userId jwt.sub; const role jwt.role; } } }JWT 载荷按config_id为键存放[0]为同配置下的首个 Tokenenv.JWT_CONFIG_ID应与POST /token_validation创建的配置 ID 对应。由此可在 Worker 内实现基于sub、role等声明的细粒度授权。读取 mTLS 信息export default { async fetch(req, env) { const tls req.cf?.tlsClientAuth; if (tls?.certVerified SUCCESS) { const fingerprint tls.certFingerprintSHA256; // Authenticated client } } }certVerified SUCCESS表示客户端证书校验通过certFingerprintSHA256可用于识别具体客户端实现证书级别的准入与审计。动态更新 JWKS密钥轮换场景下可用 Cron Trigger 定时拉取 IdP 的最新 JWKS 并 PATCH 回 API Gatewayexport default { async scheduled(event, env) { const jwks await (await fetch(https://auth.example.com/.well-known/jwks.json)).json(); await fetch(https://api.cloudflare.com/client/v4/zones/${env.ZONE_ID}/api_gateway/token_validation/${env.CONFIG_ID}, { method: PATCH, headers: {Authorization: Bearer ${env.CF_API_TOKEN}, Content-Type: application/json}, body: JSON.stringify({jwks: JSON.stringify(jwks)}) }); } }该模式解决了 IdP 更换签名密钥后 Token 校验失效的痛点CF_API_TOKEN、ZONE_ID、CONFIG_ID建议通过 Secrets 注入避免明文出现在代码中。Firewall Fields在 WAF 规则中引用安全字段API Shield 将各类检测结果暴露为可编程的防火墙字段可直接用于 WAF 自定义规则。字段清单见 api.md。核心字段cf.api_gateway.auth_id_present // Session ID 是否存在 cf.api_gateway.request_violates_schema // 是否违反 Schema cf.api_gateway.fallthrough_triggered // 是否未匹配任何端点影子 API cf.tls_client_auth.cert_verified // mTLS 证书是否有效 cf.tls_client_auth.cert_fingerprint_sha256典型用法cf.api_gateway.fallthrough_triggered配合自定义规则可对未纳管端点采取 Log先发现或 Block严格模式动作详见 patterns.md。JWT 校验的现代与兼容语法2026// Modern validation syntax is_jwt_valid(http.request.jwt.payload[{config_id}][0]) // Legacy (still supported) cf.api_gateway.jwt_claims_valid // Extract claims lookup_json_string(http.request.jwt.payload[{config_id}][0], claim_name)gotchas.md 明确建议优先使用is_jwt_valid(...)现代语法旧的cf.api_gateway.jwt_claims_valid仍受支持但应逐步迁移。声明提取用lookup_json_string其路径格式与配置章节的claims[{config_id}][0]保持一致。风险标签2026// BOLA detection cf.api_gateway.cf-risk-bola-enumeration // 检测到顺序资源访问如 /users/1、/users/2、/users/3 cf.api_gateway.cf-risk-bola-pollution // 检测到参数污染重复/超量参数 // Authentication posture cf.api_gateway.cf-risk-missing-auth // 端点缺少认证 cf.api_gateway.cf-risk-mixed-auth // 认证模式不一致风险标签由机器学习生成启用前置条件见下文 BOLA 章节标签规则组合示例见 patterns.md。BOLA Detection对象级越权攻击检测BOLABroken Object Level AuthorizationOWASP API1:2023检测通过分析资源访问序列识别两类攻击枚举顺序遍历/users/1、/users/2…与参数污染。程序化配置接口见 api.mdGET /user_schemas/{schema_id}/bola # Get 读取 BOLA 配置 PATCH /user_schemas/{schema_id}/bola # Update 更新{enabled:true}注意该接口挂在user_schemas/{schema_id}之下意味着 BOLA 检测是绑定在具体 Schema 上的能力。启用检测需要同时满足三个前提见 configuration.md已启用 Schema Validation 2.0已配置会话标识Session Identifiers每个端点日均流量不低于 1000 次请求。检测灵敏度可设 Low/Medium/High动作可选 Log 或 Block。结合风险标签可构造组合拦截规则见 patterns.md// Comprehensive BOLA rule (cf.api_gateway.cf-risk-bola-enumeration or cf.api_gateway.cf-risk-bola-pollution) and http.host eq api.example.com // Action: Block风险标签首次生效通常需要 2448 小时的模型训练见 gotchas.md上线初期建议先用 Log 模式观察误报。Auth Posture认证覆盖态势报告Auth Posture 用于审计哪些端点缺少认证或认证模式不一致接口见 api.mdGET /discovery/authentication_posture # 列出未受保护/认证不一致的端点返回的端点可按风险标签cf-risk-missing-auth、cf-risk-mixed-auth在 WAF 规则中消费见 patterns.md例如先以 Log 动作审计// Log endpoints lacking authentication (cf.api_gateway.cf-risk-missing-auth and http.host eq api.example.com) // Action: Log (for audit)报告每日刷新一次见 gotchas.md。修复闭环为审查标记端点 → 补充 JWT 校验规则 → 对敏感端点启用 mTLS → 持续跟踪态势得分见 configuration.md。GraphQL Protection查询深度与大小限制GraphQL 防护用于遏制深度嵌套与超大体积查询带来的资源耗尽攻击。接口见 api.mdGET /settings/graphql_protection # Get 读取当前限制 PUT /settings/graphql_protection # Set 设置{max_depth,max_size}参数取值边界见 gotchas.mdmax_depth范围为 150默认 10max_size范围为 1KB1MB默认 100KB。面板中还可开启生产环境屏蔽 introspection。对应 WAF 规则见 patterns.md// Block oversized queries (http.request.uri.path eq /graphql and cf.api_gateway.graphql_query_size gt 100000) // Action: Block // Block deep nested queries (http.request.uri.path eq /graphql and cf.api_gateway.graphql_query_depth gt 10) // Action: Block调优建议先用 Log 模式观察合法查询的深度/大小分布再逐步收紧限制避免误伤复杂但合法的业务查询见 gotchas.md。端到端实战从 Schema 到拦截规则的完整链路将上述接口串联即可完成一条“上传 Schema → 配置 JWT → 建规则 → 设动作”的完整防护链路见 patterns.md# 1. Upload OpenAPI schema POST /zones/{zone_id}/api_gateway/user_schemas # 2. Configure JWT validation POST /zones/{zone_id}/api_gateway/token_validation { name: Auth0, location: {header: Authorization}, jwks: {...} } # 3. Create JWT rule POST /zones/{zone_id}/api_gateway/jwt_validation_rules # 4. Set schema validation action PUT /zones/{zone_id}/api_gateway/settings/schema_validation {validation_default_mitigation_action: block}生产落地建议遵循渐进式上线Progressive Rollout见 patterns.mdLog 阶段Schema 与 JWT 规则动作均设为 Log观察误报部分拦截仅对关键端点改为 Block持续监控防火墙事件全面执行默认动作改为 Block并用fallthrough_triggered自定义规则兜底未纳管端点。监控侧可借助 Logpush 输出APIGatewayAuthIDPresent、APIGatewayRequestViolatesSchema、APIGatewayFallthroughDetected、JWTValidationResult等字段做离线分析见 patterns.md。关键限制与注意事项使用上述接口前需知悉以下边界完整清单见 gotchas.md限制项值OpenAPI 版本仅 v3.0.x无外部引用Schema 操作数上限10KEnterprise可申请更高JWT 校验来源仅 Header/Cookie端点发现门槛10 天 500 请求BOLA 检测门槛每端点日均 1000 请求GraphQL 深度/大小150默认 10/ 1KB1MB默认 100KBJWT 声明嵌套最多 10 层mTLS 自定义 CA最多 5 个CF 托管 CA 不限Schema 上传大小5MB另外注意Classic Schema Validation 已废弃新配置一律走 Schema Validation 2.0从 Classic 迁移后需等待约 5 分钟缓存清理并在Security Events中复核动作见 configuration.md。延伸阅读API Shield 参考总览 - 功能选择决策树与阅读顺序API Shield 配置指南 - Schema Validation 2.0、JWT、mTLS、会话标识的面板配置API Shield 规则与模式 - WAF 规则示例、渐进式上线与 OWASP 映射API Shield 排障手册 - 常见错误、误报处理与限制清单Cloudflare REST API 认证与 SDK - Token 配置与多语言 SDK 调用方式【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考