Cloudflare Access

使用 Cloudflare Access，你可以限制谁有权访问应用程序。你决定谁获得批准，并且在 Worker 运行之前检查每个请求。获批访问者可以通过，其他人则看到登录页或被阻止。

你可以保护：

• 单个应用程序：在其预览 URL、生产 URL 或两者上要求登录。
• 账户中的所有 Worker：默认保护每个现有和新创建的 Worker。
• 特定自定义域名和主机名：在主机名或路由级别限制访问。

要在 Workers 中使用 Access，你需要：

• 账户已启用 Zero Trust。如果尚未开启 Zero Trust，请先完成 Zero Trust 设置，然后返回 Workers 仪表板。
• 管理 Workers 和 Access 应用程序的权限。

要求账户中每个 Worker 登录，包括你将来部署的 Worker。你可以仅在预览部署上要求登录，或在生产和预览部署上都要求登录。

仪表板路径：Workers & Pages 概览页 > Protect all Workers（保护所有 Worker）。

1. 在 Cloudflare 仪表板中，前往 Workers & Pages 页面。

   前往 Workers & Pages ↗

2. 找到 Protect all Workers（保护所有 Worker） 卡片。

3. 如果卡片显示 Not enabled（未启用），选择 Enable Access（启用 Access）。

4. 选择 Previews only（仅预览） 或 All traffic（所有流量）。

5. 在 Authentication policy（身份验证策略） 下，选择现有策略或配置策略选项之一。

6. 选择 Enable Access（启用 Access）。

7. （可选）审查会话持续时间。

   

8. 选择 Apply Access（应用 Access）。

要仅保护每个 Worker 的预览部署，请创建带有 all_preview_workers 目标的自托管 Access 应用程序：

"destinations": [
  {
    "type": "all_preview_workers"
  }
]

要保护每个 Worker 的生产和预览部署，请改用 all_workers：

"destinations": [
  {
    "type": "all_workers"
  }
]

在 POST /accounts/{account_id}/access/apps 请求中发送这些 destinations。有关完整请求架构，包括策略选项、会话设置和高级 Access 选项，请参阅 Access applications API。

要求单个 Worker 登录。这会自动保护与该 Worker 关联的每个域名，包括其路由、Custom Domains、workers.dev 主机名和预览。你可以仅在预览部署上要求登录，或在生产和预览部署上都要求登录。

仪表板路径：Workers & Pages > 选择你的 Worker > Access。

1. 在 Cloudflare 仪表板中，前往 Workers & Pages 页面。

   前往 Workers & Pages ↗

2. 从应用程序列表中选择你的 Worker。

3. 选择 Access 选项卡。

4. 选择 Protect this Worker behind Access（通过 Access 保护此 Worker）。

5. 选择 Previews only（仅预览） 或 All traffic（所有流量）。

6. 在 Authentication policy（身份验证策略） 下，选择现有策略或配置策略选项之一。

7. （可选）审查会话持续时间。

   

8. 选择 Apply Access（应用 Access）。

要仅保护一个 Worker 的预览部署，请创建带有 preview_worker 目标的自托管 Access 应用程序。将 worker_id 设为 Worker 的 ID：

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/access/apps" \
  --request POST \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --json '{
    "type": "self_hosted",
    "name": "Access for my-worker",
    "destinations": [
      {
        "type": "preview_worker",
        "worker_id": "c81a2d22c29840ed9d61681a3270dbff"
      }
    ],
    "policies": [
      {
        "decision": "allow",
        "include": [
          {
            "email_domain": {
              "domain": "example.com"
            }
          }
        ]
      }
    ]
  }'

要保护 Worker 的生产和预览部署，请改用 worker：

"destinations": [
  {
    "type": "worker",
    "worker_id": "c81a2d22c29840ed9d61681a3270dbff"
  }
]

有关完整请求架构，包括策略选项和会话设置，请参阅 Access applications API。

当只有路由到 Worker 的特定 URL 应要求登录时使用基于主机名的 Access，例如 workers.dev 主机名、Custom Domain、子域名或路径。基于主机名的 Access 仅保护该确切 URL，而保护一个 Worker 无论访问方式如何都会保护整个 Worker。例如使用基于主机名的 Access，你可以保护 my-worker.example.workers.dev、admin.example.com，或单个路径如 example.com/login，以便仅将 Worker 的一部分设为私有。

在仪表板和 API 中，都通过创建自托管应用程序并将主机名或路径用作应用程序域名来保护主机名或路径。

如果账户级 Access 保护所有 Worker，你可以通过添加 Worker 级绕过将特定 Worker 设为公开。绕过意味着 Access 不对该 Worker 要求登录。

仪表板路径：Workers & Pages > 选择你的 Worker > Access。

1. 在 Cloudflare 仪表板中，前往 Workers & Pages 页面。

   前往 Workers & Pages ↗

2. 从应用程序列表中选择你的 Worker。

3. 选择 Access 选项卡。

4. 选择将该 Worker 设为公开或绕过账户级 Access 的选项。

5. 确认更改。

创建带有绕过策略的 Worker 级 Access 应用程序。使用 worker 目标，将 worker_id 设为 Worker 的 ID，并将策略 decision 设为 bypass，同时使用匹配所有人的 include 规则：

"policies": [
  {
    "decision": "bypass",
    "include": [
      {
        "everyone": {}
      }
    ]
  }
]

开启 Access 时，选择谁可以登录。无论你保护所有 Worker 还是一个 Worker，都可使用相同的策略选项。

你可以添加一条或多条策略。匹配任何选定策略的访问者都可以登录。

对于高级策略配置，例如多个身份提供商、设备态势规则、服务令牌、复杂策略排序或自定义登录或阻止页面，请在创建后于 Zero Trust 中编辑 Access 应用程序。有关完整选项集，请参阅 Access 策略。

当 Cloudflare Access 验证直接调用 Worker 的请求时，Worker 可以通过 ctx.access 读取已登录用户的身份——包括电子邮件、组、设备态势以及更多身份字段。无需额外配置或 JWT 解析。

使用它来个性化响应、实施细粒度权限，或按用户记录活动。

如果 Access 未验证该请求，ctx.access 为 undefined。

export default {
	async fetch(request, env, ctx) {
		if (!ctx.access) {
			return new Response("Access required", { status: 403 });
		}

		const identity = await ctx.access.getIdentity();
		const email = identity?.email ?? "unknown";

		return new Response(`Hello, ${email}`);
	},
};

export default {
	async fetch(request, env, ctx) {
		if (!ctx.access) {
			return new Response("Access required", { status: 403 });
		}

		const identity = await ctx.access.getIdentity();
		const email = identity?.email ?? "unknown";

		return new Response(`Hello, ${email}`);
	},
};

使用 wrangler dev 或 Cloudflare Vite Plugin 进行本地开发时，你可以模拟已验证的 Cloudflare Access 身份，而无需部署或经过 Access 登录流程。

在 wrangler.jsonc 的 access 配置中添加 dev 块：

{
	"access": {
		"dev": {
			"aud": "my-app",
			"identity": { "email": "[email protected]" }
		}
	}
}

[access.dev]
aud = "my-app"

  [access.dev.identity]
  email = "[email protected]"

• aud（必需）—— Access 应用程序的 audience 标签，可作为 ctx.access.aud 使用。没有它 Wrangler 不会启动。
• identity（可选）—— 模拟由 ctx.access.getIdentity() 返回的已验证用户身份声明（电子邮件、姓名、组等）。如果你的 Worker 读取用户身份则包含它。如果你的 Worker 仅检查 Access 是否启用则省略它。

要作为不同用户测试，请更改身份字段并重启。要测试未经身份验证的请求，请移除 dev 块——ctx.access 将为 undefined，与生产中未经过 Access 的请求相同。

export default {
	async fetch(request, env, ctx) {
		if (!ctx.access) {
			return new Response("Not authenticated", { status: 403 });
		}

		const identity = await ctx.access.getIdentity();
		const email = identity?.email ?? "unknown";

		return new Response(`Hello, ${email}`);
	},
};

export default {
	async fetch(request, env, ctx) {
		if (!ctx.access) {
			return new Response("Not authenticated", { status: 403 });
		}

		const identity = await ctx.access.getIdentity();
		const email = identity?.email ?? "unknown";

		return new Response(`Hello, ${email}`);
	},
};

使用此配置时，访问 localhost:8787 会返回 Hello, [email protected]。

身份对象接受与生产 Access 身份形状匹配的任何字段。完整列表请参阅 Application token — User identity。

一个 Worker 可能受多条 Access 规则保护。当多条规则可能适用于同一请求时，最具体的规则首先生效：

1. 基于主机名或路径的 Access：当请求匹配该主机名或路径时首先适用，例如 admin.example.com 或 example.com/login。
2. Worker 级 Access：接下来适用于选定 Worker 的路由、Custom Domains、workers.dev 主机名和预览。
3. 账户级 Worker Access：最后作为账户上所有 Worker 或所有 Worker 预览的回退。

例如，如果 Worker 同时具有账户级 Access 和 Worker 级规则，则 Worker 级规则控制该 Worker。如果还存在匹配的基于主机名或路径的 Access 应用，则该主机名或路径规则控制匹配的 URL。

如果你移除更具体的规则，更广泛的规则可能仍会保护该 Worker。例如，移除 Worker 级 Access 可能露出其下的账户级 Access。

• Access applications API
• Access 策略
• 自托管 Access 应用程序
• 路由和域名
• 预览 URL