外部评估规则

使用 Cloudflare Access，您可以创建根据自定义条件对用户进行评估的 Allow（允许）或 Block（阻止）策略。这是通过在您的策略中添加**External Evaluation（外部评估）**规则来完成的。External Evaluation 选择器需要两个值：

Evaluate URL — 包含您的业务逻辑的 API 端点。
Keys URL — Access 用来验证响应来自您的 API 的密钥。

在用户向您的身份提供商进行身份验证后，Access 会将用户的身份发送到 Evaluate URL 处的外部 API。外部 API 向 Access 返回 True 或 False 响应，然后 Access 将允许或拒绝该用户的访问。为了防止中间人攻击，Access 会使用您的 Access 账户密钥对所有请求进行签名，并检查响应是否由 Keys URL 处的密钥签名。

您可以使用任何 API 服务来设置外部评估规则，但为了快速入门，我们建议使用 Cloudflare Workers。

使用 Cloudflare Workers 设置外部 API 和密钥

前提条件

Workers 账户
安装 npm ↗
安装 Node.js ↗
受 Access 保护的应用程序

1. 创建新的 Worker

打开终端并克隆我们的示例项目。

npm create cloudflare@latest my-worker -- --template https://github.com/cloudflare/workers-access-external-auth-example

转到项目目录。
```
cd my-worker
```
创建一个 Workers KV 命名空间来存储密钥。如果您想按原样运行示例，绑定（binding）名称应为 KV。
```
npx wrangler kv namespace create "KV"
```
该命令将输出绑定名称和 KV 命名空间 ID，例如：
```
  [[kv_namespaces]]
   binding = "KV"
   id = "YOUR_KV_NAMESPACE_ID"
```
在编辑器中打开 Wrangler 配置文件并插入以下内容：
- [[kv_namespaces]]：添加在上一步中生成的输出。
- <TEAM_NAME>：您的 Cloudflare One 团队名称（team name）。

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "workers_dev": true,
  // Set this to today's date
  "compatibility_date": "2026-08-17",
  "main": "index.js",
  "kv_namespaces": [
    {
      "binding": "KV",
      "id": "YOUR_KV_NAMESPACE_ID"
    }
  ],
  "vars": {
    "TEAM_DOMAIN": "<TEAM_NAME>.cloudflareaccess.com",
    "DEBUG": false
  }
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker"
workers_dev = true
# Set this to today's date
compatibility_date = "2026-08-17"
main = "index.js"

[[kv_namespaces]]
binding = "KV"
id = "YOUR_KV_NAMESPACE_ID"

[vars]
TEAM_DOMAIN = "<TEAM_NAME>.cloudflareaccess.com"
DEBUG = false

2. 编写您的业务逻辑

打开 index.js 并修改 externalEvaluation 函数，以便对 Access 发送的任何基于身份的数据执行逻辑。

将 Worker 部署到 Cloudflare 的全球网络。
```
npx wrangler deploy
```

Worker 将被部署到您在 my-worker.<YOUR_SUBDOMAIN>.workers.dev 的 *.workers.dev 子域。

3. 生成密钥

要生成 RSA 私钥/公钥对：

打开浏览器并访问 https://my-worker.<YOUR_SUBDOMAIN>.workers.dev/keys。
（可选）验证密钥是否已存储在 KV 命名空间中：
1. 在 Cloudflare 仪表板中，转到 Workers KV 页面。 Go to Workers KV ↗
2. 选择 my-worker-KV 旁的 View（查看）。

目前不支持其他密钥格式（例如 DSA）。

4. 创建外部评估规则

在 Cloudflare 仪表板 ↗中，转到 Zero Trust > Access controls（访问控制） > Policies（策略）。
编辑现有策略或选择 Add a policy（添加策略）。
在您的策略中添加以下规则：

规则类型	选择器	Evaluate URL（评估 URL）	Keys URL（密钥 URL）
Include（包含）	External Evaluation（外部评估）	`https://my-worker.<YOUR_SUBDOMAIN>.workers.dev/`	`https://my-worker.<YOUR_SUBDOMAIN>.workers.dev/keys/`

保存策略。
转到 Access controls（访问控制） > Applications（应用程序） 并编辑您要对其应用外部评估规则的应用程序。
在 Policies（策略） 选项卡中，添加包含外部评估规则的策略。
选择 Save（保存）。

当用户登录您的应用程序时，Access 现在将根据您的业务逻辑检查其电子邮件、设备、位置和其他基于身份的数据。

排查 Worker 故障

要调试您的外部评估规则：

转到您的 Worker 目录。
```
cd my-worker
```
在编辑器中打开 Wrangler 配置文件，并将 debug 变量设置为 TRUE。
部署您的更改。
```
npx wrangler deploy
```
接下来，启动会话以输出 Worker 的实时日志。
```
wrangler tail -f pretty
```
登录您的 Access 应用程序。

会话日志应显示传入和传出的 JWT。传入的 JWT 由 Access 发送到 Worker API，而传出的 JWT 由 Worker 发送回 Access。
要解码 JWT 的内容，您可以将令牌复制到 jwt.io ↗ 中。

传入的 JWT 应包含用户的身份数据。传出的 JWT 应类似于：
```
{
"success": true,
"iat": 1655409315,
"exp": 1655409375,
"nonce": "9J2E9Xg6wYj8tlnA5MV4Zgp6t8rzmS0Q"
}
```
Access 会检查传出的 JWT 是否满足以下所有标准：
- 令牌由 Keys URL 签名。
- 到期时间尚未过。
- API 返回 "success": true。
- nonce 与传入的 JWT 相比没有改变。nonce 值对每个请求都是唯一的。
如果任何条件失败，外部评估规则的计算结果将为 false。