JSON Web 令牌 (JWT) 通常用作许多 Web 应用程序上身份验证组件的一部分。由于 JWT 对于识别用户及其访问权限至关重要,因此确保令牌的完整性非常重要。
API Shield 的 JWT 验证会在传入 JWT 到达您的 API 源站之前对其进行密码学验证。它会检测已过期、被篡改或尚未生效的令牌。然后您可以创建规则,根据验证结果采取操作。
JWT 验证包含两部分:告诉 Cloudflare 如何查找和验证 JWT 的令牌配置,以及对验证结果采取操作的规则。
创建令牌配置后,Cloudflare 会检查该 zone 中每个请求在已配置位置是否存在 JWT。当 Cloudflare 找到 JWT 时,它会验证该令牌,并将已验证的声明提供为 http.request.jwt.claims 字段。可用字段和标准声明请参阅 JWT 验证字段参考。验证不需要规则或端点管理中的操作。规则决定 Cloudflare 如何对结果采取操作。
-
在 Cloudflare 仪表板中,前往安全 Settings(设置) 页面。
前往 Settings(设置) ↗ -
按 API 滥用 过滤。
-
在 Token configurations(令牌配置) 上,选择 Configure tokens(配置令牌)。
-
为您的配置添加名称。
-
选择 Cloudflare 在传入请求中可以在何处找到此配置的 JWT(例如标头或 cookie)及其名称。
-
复制并粘贴您的 JWT 签发者的验证密钥 (JWKS)。您可以提供非对称公钥,或与 HMAC 算法一起使用的对称密钥。
使用非对称算法的 JWT 签发者通常在互联网上的已知 URL 处发布公钥 (JWKS) 以供验证。使用 HMAC 算法的签发者会与验证方共享对称凭据。如果您不知道从哪里获取签发者的验证密钥或对称凭据,请联系您的身份管理员。
有关受支持的算法和对称密钥要求,请参阅通过 API 配置 JWT 验证。
令牌配置不会自动从 JWKS URL 检索或刷新密钥。请直接添加更新后的 JWK 值,或使用 Worker 将令牌配置与您的身份提供程序同步。要配置自动更新,请参阅配置 Workers 以自动更新密钥。
WAF 自定义规则支持覆盖整个 zone 的策略以及限定到所选端点的策略。它们还可以将 JWT 验证结果和已验证声明与其他安全信号(例如攻击评分)结合使用。
无论您选择哪种规则类型,Cloudflare 验证 JWT 的方式都相同。
API JWT 验证规则在规则表达式的评估结果为 false 时运行其操作。WAF 自定义规则在表达式的评估结果为 true 时运行其操作。以下示例匹配违反 JWT 策略的请求,适用于操作为 Block 或 Log 的 WAF 自定义规则。
在 WAF 自定义规则中,cf.api_gateway.tokens.presented 包含请求中找到的令牌的令牌配置 ID。cf.api_gateway.tokens.valid 字段包含通过验证的令牌的配置 ID。cf.api_gateway.operation_id 字段包含请求匹配到的端点 ID。
要要求提供有效令牌,请使用:
not any(cf.api_gateway.tokens.valid[*] == "<TOKEN_CONFIGURATION_ID>")此表达式也会匹配没有令牌的请求。如果只要求令牌存在,请使用:
not any(cf.api_gateway.tokens.presented[*] == "<TOKEN_CONFIGURATION_ID>")要匹配无效令牌但忽略没有令牌的请求,请使用:
any(cf.api_gateway.tokens.presented[*] == "<TOKEN_CONFIGURATION_ID>") and
not any(cf.api_gateway.tokens.valid[*] == "<TOKEN_CONFIGURATION_ID>")要接受来自两个令牌配置中任一配置的有效令牌,请使用:
not (
any(cf.api_gateway.tokens.valid[*] == "<TOKEN_CONFIGURATION_ID_1>") or
any(cf.api_gateway.tokens.valid[*] == "<TOKEN_CONFIGURATION_ID_2>")
)每个已保存端点在端点管理详情中都有一个端点 ID,也称为操作 ID。要仅将策略应用于所选端点,请使用其完整端点 ID:
cf.api_gateway.operation_id in {"<ENDPOINT_ID_1>" "<ENDPOINT_ID_2>"} and
not any(cf.api_gateway.tokens.valid[*] == "<TOKEN_CONFIGURATION_ID>")当请求匹配已保存端点时,cf.api_gateway.fallthrough_detected 字段为 false。要将策略应用于某个主机名上的已保存端点(所选端点除外),请使用:
http.host eq "api.example.com" and
not cf.api_gateway.fallthrough_detected and
not (cf.api_gateway.operation_id in {"<EXCLUDED_ENDPOINT_ID_1>" "<EXCLUDED_ENDPOINT_ID_2>"}) and
not any(cf.api_gateway.tokens.valid[*] == "<TOKEN_CONFIGURATION_ID>")要引用简单字符串声明,请将 lookup_json_string() 与您的令牌配置 ID 和声明名称一起使用:
lookup_json_string(http.request.jwt.claims["<TOKEN_CONFIGURATION_ID>"][0], "claim_name")完整示例请参阅根据攻击评分为 JWT 声明中的管理员用户发出质询。所有可用字段请参阅 JWT 验证字段参考。
JWT 验证规则使用端点管理中的操作来控制 Cloudflare 在何处应用其 log 或 block 操作。
-
在 Cloudflare 仪表板中,前往安全 规则 页面。
前往 Security rules(安全规则) ↗ -
在 API JWT 验证规则上,选择 Create rule(创建规则)。
-
为您的规则添加名称。
-
选择主机名,以使用该规则保护包含已保存端点的请求。
-
取消勾选您希望从 JWT 验证规则强制执行中排除的任何端点。
-
选择与传入请求相对应的令牌配置。
-
选择是否在这些端点上严格强制要求令牌存在。
- 您可能不期望 100% 的客户端在其请求中发送 JWT。如果是这种情况,请选择 忽略 (Ignore)。JWT 验证仍将验证存在的 JWT。
- 否则,您可能期望所有发往所选主机名和端点的请求都包含 JWT。如果是这种情况,请选择 标记为不合规 (Mark as non-compliant)。
-
选择对不合规请求采取的操作。例如,未通过验证的 JWT(已过期、被篡改或签名错误的令牌),或者在前面步骤中选择 标记为不合规 时缺少 JWT 的请求。
-
选择 Save(保存)。
如果您期望在请求中应该存在两个不同的 JWT 并且您想验证这两个 JWT,您必须创建两个不同的令牌配置。在您的验证规则中选择这两个配置时,在 多个配置的验证行为 下选择 验证所有配置。
如果您期望在两个不同的身份提供商之间进行迁移,您必须创建两个不同的令牌配置和两个不同的验证规则,每个规则对应其自己的配置。通过此设置,您可以根据迁移状态更改不同验证规则的操作。
无论 JSON Web Token 是否具有 Bearer 前缀,API Shield 都会对其进行验证。
Rate Limiting 可以将有效 JSON Web Token(JWT)中的字符串声明用作速率限制特征。这包括 sub 等注册声明和自定义声明。
对于嵌套声明,向 lookup_json_string() 分别传入每个对象键。例如,使用 "user", "email" 访问 user.email。
只有有效的 JWT 才会填充 JWT 声明字段。如果规则也匹配不包含所选声明的请求,这些请求会使用单独的缺失值计数器。请参阅缺失字段与空值。
对于按用户限制,选择能唯一标识用户的声明,例如在应用中具有唯一性的 sub。特征值相同的请求共享速率限制计数器。
要按级别应用不同的用户限额,请为每个级别创建一个速率限制规则。在规则表达式中匹配级别声明,并使用单独的用户标识声明作为速率限制特征。
例如,免费级别的规则可以使用:
lookup_json_string(http.request.jwt.claims["<JWT_TOKEN_CONFIGURATION_ID>"][0], "tier") eq "free"使用 sub 作为速率限制特征,将限额设置为每分钟五个请求。创建另一个规则,匹配 "tier" eq "premium" 并应用对应的高级级别限额。
由于跨源资源共享 (CORS) 安全,Web 浏览器在发送 GET(或其他动词)请求之前,会使用 OPTIONS 动词向 API 端点发送“预检”请求。根据定义,OPTIONS 预检请求不包含凭据(身份验证标头或 cookie),并且是匿名的。
如果您的 API 的有效客户端包括 Web 浏览器,并且为了防止阻止来自这些浏览器的 OPTIONS 请求,Cloudflare 建议在您的 JWT 验证规则中添加 or http.request.method eq "OPTIONS"。
所有 API Shield 客户均可使用 JWT 验证。未购买 API Shield 的企业版客户可以在 Cloudflare 仪表板中预览 作为非合同服务的 API Shield ↗,或通过联系您的账户团队来进行预览。
JWT 验证仅对在客户端请求标头或 cookie 中发送的 JWT 起作用。如果您的客户端在 POST 正文中发送 JWT,请联系您的账户团队。