cloudflare-zero-trust-access

Cloudflare Zero Trust Access 技能

使用经过验证的模式和模板，将 Cloudflare Zero Trust Access 身份验证集成到 Cloudflare Workers 应用中。

---

概述

此技能提供 Cloudflare Access 的完整集成模式，让 Workers 应用无需自行管理身份验证基础设施，即可实现应用级身份验证。

什么是 Cloudflare Access？ Cloudflare Access 是一种零信任身份验证机制，位于应用前端，在用户访问 Worker 之前验证其身份。身份验证通过后，Access 会颁发 JWT 令牌，由 Worker 进行验证。

主要优势：

• 无需维护身份验证基础设施
• 可与身份提供商集成（Azure AD、Google、Okta、GitHub）
• 提供用于机器间身份验证的服务令牌
• 内置 MFA 和会话管理
• 全面的审计日志

---

何时使用此技能

在任务涉及以下内容时使用此技能：

• 身份验证：保护 Worker 路由、保障管理面板安全、API 身份验证
• 访问控制：基于角色的访问控制（RBAC）、基于群组的权限、地理位置限制
• 服务身份验证：后端服务调用 Worker API、CI/CD 管道、定时任务
• 多租户：具有组织级身份验证的 SaaS 应用
• CORS + 身份验证：单页应用调用受保护的 API

触发关键词： cloudflare access、zero trust、access authentication、JWT validation、service tokens、cloudflare auth、hono access、workers authentication、protect worker routes、admin authentication

---

集成模式

📖 刚开始使用 Cloudflare Access？ 加载 references/quick-start.md，查看分步设置说明（15–20 分钟）。

模式 1：Hono 中间件（推荐）

使用 @hono/cloudflare-access 通过一行代码集成 Access。

适用场景：

• 使用 Hono 框架构建
• 需要快速、可用于生产环境的设置
• 希望自动验证 JWT 并缓存密钥

模板：templates/hono-basic-setup.ts

设置：

import { Hono } from 'hono'
import { cloudflareAccess } from '@hono/cloudflare-access'

const app = new Hono<{ Bindings: Env }>()

// Public routes
app.get('/', (c) => c.text('Public page'))

// Protected routes
app.use(
  '/admin/*',
  cloudflareAccess({
    domain: (c) => c.env.ACCESS_TEAM_DOMAIN,
  })
)

app.get('/admin/dashboard', (c) => {
  const { email } = c.get('accessPayload')
  return c.text(`Welcome, ${email}!`)
})

配置（wrangler.jsonc）：

{
  "vars": {
    "ACCESS_TEAM_DOMAIN": "your-team.cloudflareaccess.com",
    "ACCESS_AUD": "your-app-aud-tag"
  }
}

优势：

• ✅ 自动验证 JWT
• ✅ 缓存公钥（TTL 为 1 小时）
• ✅ 使用 TypeScript 实现类型安全
• ✅ 经过生产环境验证并持续维护

---

模式 2：手动验证 JWT

适用场景：不使用 Hono，需要自定义验证逻辑

模板：templates/jwt-validation-manual.ts（约 100 行，使用 Web Crypto API）

---

模式 3：服务令牌身份验证

适用场景：CI/CD 管道、后端服务、定时任务（无需交互式登录）

客户端：发送 CF-Access-Client-Id + CF-Access-Client-Secret 标头

服务端：相同的中间件可处理两者，通过 !payload.email && payload.common_name 检测

📄 完整指南：references/service-tokens-guide.md

---

模式 4：CORS + Access

适用场景：SPA（React/Vue/Angular）调用受保护的 API

⚠️ 重要：CORS 中间件必须置于 Access 中间件之前！

// ✅ CORRECT ORDER
app.use('*', cors({ origin: 'https://app.example.com', credentials: true }))
app.use('/api/*', cloudflareAccess({ domain: (c) => c.env.ACCESS_TEAM_DOMAIN }))

原因：OPTIONS 预检请求不包含身份验证标头 → Access 会以 401 拒绝请求

📄 完整模式：templates/cors-access.ts

---

模式 5：多租户

适用场景：按组织进行身份验证的 SaaS、白标应用

架构：在 D1/KV 中存储租户配置 → 为每个请求动态生成中间件

📄 完整模式：templates/multi-tenant.ts 和 references/use-cases.md

---

可避免的常见错误

此技能可避免 8 种有记录的错误。完整详情：references/common-errors.md

错误 #1：CORS 预检请求被阻止（节省 45 分钟）

问题：OPTIONS 请求返回 401，导致 CORS 失效

解决方案：将 CORS 中间件置于 Access 中间件之前

// ✅ Correct
app.use('*', cors())
app.use('/api/*', cloudflareAccess({ domain: '...' }))

---

错误 #2：缺少 JWT 标头（节省 30 分钟）

问题：请求未经过 Access，因此没有 JWT 标头

解决方案：通过 Access URL 访问 Worker，而不是直接访问 *.workers.dev

✅ https://team.cloudflareaccess.com/...
❌ https://worker.workers.dev

---

错误 #3：团队名称无效（节省 15 分钟）

问题：硬编码或错误的团队名称会导致 “Invalid issuer”

解决方案：使用环境变量

// ✅ Correct
cloudflareAccess({ domain: (c) => c.env.ACCESS_TEAM_DOMAIN })

// ❌ Wrong
cloudflareAccess({ domain: 'my-team.cloudflareaccess.com' })

---

错误 #4-8（快速参考）

#	错误	解决方案
4	密钥缓存竞争	使用 @hono/cloudflare-access（自动缓存）
5	服务令牌标头错误	使用 CF-Access-Client-Id/Secret（而不是 Authorization）
6	令牌过期（1 小时后返回 401）	妥善处理，并重定向到登录页面
7	策略重叠	使用最具体的路径
8	开发/生产环境不匹配	使用特定于环境的配置

📄 完整错误详情：references/common-errors.md（每次实现约节省 2.5 小时）

---

模板

模板	用途
hono-basic-setup.ts	标准 Hono + Access 集成
jwt-validation-manual.ts	使用 Web Crypto 手动验证 JWT
service-token-auth.ts	服务令牌模式
cors-access.ts	CORS + Access（正确的顺序）
multi-tenant.ts	多租户架构
wrangler.jsonc	完整的 Wrangler 配置
.env.example	环境变量模板
types.ts	TypeScript 定义

脚本

脚本	用法
test-access-jwt.sh	./test-access-jwt.sh <jwt-token> - 解码并验证 JWT
create-service-token.sh	./create-service-token.sh [name] - 服务令牌设置指南

---

使用场景

使用场景	模板	要点
管理员仪表板	hono-basic-setup.ts	电子邮件域策略
API 身份验证	hono-basic-setup.ts	混合用户/服务策略
SPA + API	cors-access.ts	CORS 必须先于 Access！
CI/CD 流水线	service-token-auth.ts	将服务令牌存入机密
多租户 SaaS	multi-tenant.ts	D1 租户配置

📄 详细使用场景：references/use-cases.md

---

何时加载参考资料

参考文件	加载时机……
references/quick-start.md	为新用户逐步设置、首次集成
references/common-errors.md	调试身份验证问题、预防模式（包含全部 8 个错误）
references/jwt-payload-structure.md	访问 JWT 声明、用户令牌与服务令牌
references/service-tokens-guide.md	设置机器对机器身份验证
references/access-policy-setup.md	仪表板配置、策略创建
references/use-cases.md	特定场景的详细实现
references/value-proposition.md	令牌效率指标、工作流指南、生产环境验证

---

软件包版本

软件包	版本
@hono/cloudflare-access	0.3.1
hono	4.12.12
@cloudflare/workers-types	4.20260408.0

已验证：2025-12-14 | 令牌节省：约 58% | 已通过生产环境测试：✅

---

不适用场景

此技能适用于使用 Cloudflare Access 的 Cloudflare Workers。以下情况请勿使用：

• ❌ Cloudflare Pages（请改用 @cloudflare/pages-plugin-cloudflare-access）
• ❌ 非 Cloudflare 平台
• ❌ 自定义 JWT 身份验证（非 Access）
• ❌ Auth.js 或其他身份验证库
• ❌ 自托管身份验证

对于这些场景，请使用适当的技能或库。

---

其他资源

Cloudflare 文档：

• Access 概览
• JWT 验证
• 服务令牌

软件包：

• @hono/cloudflare-access
• Hono 框架

仪表板：

• Zero Trust 仪表板

---

技能版本：1.0.0 最后更新：2025-10-28 预防错误数：8 令牌节省：58% 节省时间：2.5 小时 已通过生产环境测试：✅