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 流水线、cron 作业
• 多租户：具有组织级身份验证的 SaaS 应用
• CORS + 身份验证：单页应用调用受保护的 API

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

---

集成模式

模式 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

使用 Web Crypto API 实现自定义验证逻辑。

适用场景：

• 未使用 Hono 框架
• 需要执行超出标准检查范围的自定义验证
• 希望完全控制 JWT 验证过程

模板：templates/jwt-validation-manual.ts

主要函数：

// Validate JWT signature and claims
async function validateAccessJWT(
  token: string,
  env: Env
): Promise<AccessJWTPayload> {
  // 1. Decode header to get kid
  // 2. Fetch public keys (with caching)
  // 3. Verify signature using Web Crypto API
  // 4. Validate aud, exp, iss
  // 5. Return payload
}

复杂度：约 100 行 依赖项：无（使用 Web Crypto API）

---

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

使用服务令牌进行机器间身份验证。

适用场景：

• 后端服务调用你的 Worker API
• CI/CD 流水线
• 自动化脚本和 cron 作业
• 无需交互式登录

模板：templates/service-token-auth.ts

客户端（发送请求）：

const response = await fetch('https://api.example.com/data', {
  headers: {
    'CF-Access-Client-Id': env.SERVICE_TOKEN_ID,
    'CF-Access-Client-Secret': env.SERVICE_TOKEN_SECRET,
  },
})

服务端（Worker）：

// Same validation as user JWTs - middleware handles both
app.use('/api/*', cloudflareAccess({
  domain: (c) => c.env.ACCESS_TEAM_DOMAIN
}))

app.get('/api/data', (c) => {
  const payload = c.get('accessPayload')

  // Detect service token vs user
  const isService = !payload.email && payload.common_name

  return c.json({
    authenticated_by: isService ? 'service-token' : 'user',
    identifier: payload.email || payload.common_name,
  })
})

设置指南：references/service-tokens-guide.md

---

模式 4：CORS + Access

使用 Access 身份验证处理跨源请求。

适用场景：

• SPA（React/Vue/Angular）调用受保护的 API
• 前端和 API 位于不同的域名
• 跨源身份验证请求

模板：templates/cors-access.ts

重要：CORS 中间件必须放在 Access 中间件之前！

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

// ✅ CORRECT ORDER
app.use('*', cors({
  origin: 'https://app.example.com',
  credentials: true, // Allow cookies
}))

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

// ❌ WRONG ORDER - WILL FAIL!
// Access blocks OPTIONS preflight requests

原因：OPTIONS 预检请求不包含身份验证标头。如果 Access 先运行，就会以 401 阻止这些请求。

前端：

fetch('https://api.example.com/api/data', {
  credentials: 'include', // ← Critical!
  method: 'POST',
})

---

模式 5：多租户

为不同租户/组织配置不同的 Access 设置。

适用场景：

• 具有组织级身份验证的 SaaS
• 每位客户都有独立的 Access 团队
• 白标应用

模板：templates/multi-tenant.ts

架构：

• 将租户配置存储在 D1 或 KV 中
• 根据租户 ID 动态应用中间件
• 从子域名、路径或标头中获取租户 ID

示例：

// Subdomain-based: tenant1.example.com, tenant2.example.com
app.use('/app/*', async (c, next) => {
  const tenantId = getTenantFromSubdomain(c.req.url)
  const tenant = await getTenantConfig(tenantId, c.env.DB)

  // Apply tenant-specific Access
  return cloudflareAccess({
    domain: tenant.access_team_domain
  })(c, next)
})

---

可预防的常见错误

此技能可预防 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 访问 Access 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：密钥缓存竞争（节省 20 分钟）

问题：首次请求失败，后续请求正常

解决方案：使用 @hono/cloudflare-access（自动处理缓存）

---

错误 #5：服务令牌标头（节省 10 分钟）

问题：标头名称错误，令牌无法使用

解决方案：使用准确的标头名称：

// ✅ Correct
'CF-Access-Client-Id': '...'
'CF-Access-Client-Secret': '...'

// ❌ Wrong
'Authorization': 'Bearer ...'

---

错误 #6：令牌过期（节省 10 分钟）

问题：用户在 1 小时后突然收到 401

解决方案：妥善处理，并重定向到登录页面

if (error.message.includes('expired')) {
  return c.json({ error: 'Session expired', code: 'TOKEN_EXPIRED' }, 401)
}

---

错误 #7：多个策略（节省 30 分钟）

问题：重叠的 Access 应用导致冲突

解决方案：使用最具体的路径，避免重叠

---

错误 #8：开发环境与生产环境不匹配（节省 15 分钟）

问题：代码在开发环境中运行正常，在生产环境中失败

解决方案：使用环境专属配置

{
  "env": {
    "dev": {
      "vars": { "ACCESS_TEAM_DOMAIN": "dev-team.cloudflareaccess.com" }
    },
    "production": {
      "vars": { "ACCESS_TEAM_DOMAIN": "prod-team.cloudflareaccess.com" }
    }
  }
}

总计节省时间：每次实现约 2.5 小时

---

模板

核心模板

1. hono-basic-setup.ts - 标准的 Hono + Access 集成

   • 公共和受保护的路由
   • 用户信息访问
   • 错误处理

2. jwt-validation-manual.ts - 手动验证 JWT

   • Web Crypto API 的使用
   • 密钥缓存
   • 完整的验证逻辑

3. service-token-auth.ts - 服务令牌模式

   • 客户端和服务端示例
   • 服务令牌与用户令牌的识别
   • 最佳实践

4. cors-access.ts - CORS + Access 集成

   • 正确的中间件顺序
   • 前端示例（fetch、axios）
   • 故障排查指南

5. multi-tenant.ts - 多租户架构

   • 子域名、路径和标头策略
   • D1 租户配置
   • 动态中间件

配置模板

6. wrangler.jsonc - 完整的 Wrangler 配置

   • 环境变量
   • 绑定（D1、KV、R2）
   • 开发/暂存/生产环境

7. .env.example - 环境变量模板

   • 必需项：ACCESS_TEAM_DOMAIN、ACCESS_AUD
   • 可选项：服务令牌、CORS 配置
   • 设置说明

8. types.ts - TypeScript 类型定义

   • AccessJWTPayload 接口
   • ServiceTokenJWTPayload 接口
   • 类型守卫和辅助函数

---

参考文档

references/ 中的完整指南：

1. common-errors.md（约 800 字）

   • 全部 8 个错误及其解决方案
   • 错误 → 症状 → 原因 → 解决方案 → 预防
   • 来源链接和节省的时间

2. jwt-payload-structure.md（约 1,200 字）

   • 完整的 JWT 字段参考
   • 用户令牌与服务令牌的区别
   • 类型定义和示例

3. service-tokens-guide.md（约 1,100 字）

   • 创建服务令牌
   • 将令牌添加到策略
   • 使用场景（CI/CD、微服务、定时任务）
   • 轮换最佳实践

4. access-policy-setup.md（约 1,400 字）

   • 控制面板配置步骤
   • 策略示例
   • 身份提供商设置
   • 测试和故障排查

---

辅助脚本

位于 scripts/ 中：

1. test-access-jwt.sh - JWT 测试工具

   • 解码 JWT 标头和载荷
   • 获取公钥
   • 验证签名和声明
   • 用法：./test-access-jwt.sh <jwt-token>

2. create-service-token.sh - 服务令牌设置指南

   • 交互式设置说明
   • 代码示例（curl、Node.js、Python、GitHub Actions）
   • 最佳实践检查清单
   • 用法：./create-service-token.sh [token-name]

---

快速开始

1. 安装软件包

npm install hono @hono/cloudflare-access

2. 配置访问权限

控制面板：

1. 前往 Zero Trust > Access > Applications
2. 为你的 Worker 域名创建应用
3. 创建策略（例如，“电子邮件地址以 @company.com 结尾”）
4. 复制 Application Audience (AUD) 标签

wrangler.jsonc：

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

3. 添加到 Worker

以 templates/hono-basic-setup.ts 为起点：

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

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

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

app.get('/admin/dashboard', (c) => {
  const { email } = c.get('accessPayload')
  return c.json({ email })
})

export default app

4. 部署并测试

npx wrangler deploy

访问：https://your-worker.example.com/admin/dashboard

预期结果：重定向到 Access 登录页面，完成身份验证后返回仪表盘。

---

使用场景

保护管理仪表盘

要求：通过电子邮件身份验证保护管理路由

模板：hono-basic-setup.ts

策略：电子邮件地址以 @company.com 结尾

---

API 身份验证

要求：保护 API，同时允许访问公开页面

模板：hono-basic-setup.ts + 独立路由

策略：服务令牌 + 员工电子邮件地址

---

SPA + 受保护的 API

要求：React 应用调用需要身份验证的 API

模板：cors-access.ts

关键：在 Access 之前使用 CORS 中间件

---

CI/CD 流水线

要求：GitHub Actions 调用 Worker API

模板：service-token-auth.ts

设置：将服务令牌存入 GitHub Secrets

---

多租户 SaaS

要求：为不同组织配置不同的 Access

模板：multi-tenant.ts

架构：将租户配置存储在 D1 中，使用动态中间件

---

软件包信息

软件包	版本	用途
@hono/cloudflare-access	0.3.1	Hono 中间件（推荐）
hono	4.10.3	Web 框架
@cloudflare/workers-types	4.20251014.0	TypeScript 类型

验证日期：2025-10-28

无 Node.js 依赖：所有软件包均使用 Web 标准 API，与 Workers 运行时完全兼容。

---

Token 效率

不使用此技能：约 5,550 个 token

• Cloudflare 文档：2,500 个 token
• 库文档：450 个 token
• GitHub 问题研究：1,000 个 token
• 手动实现：1,600 个 token

使用此技能：约 2,300 个 token

• SKILL.md：1,500 个 token
• 模板：500 个 token
• 快速设置：300 个 token

节省：3,250 个 token（约 58%）

---

生产环境测试

库：@hono/cloudflare-access 正在积极维护 下载量：每周约 3,000 次 GitHub：属于 Hono 中间件集合的一部分（10k+ 星）

生产环境使用：已验证可在商业项目中正常运行。

---

工作流

当用户请求集成 Access 时：

1. 评估模式：哪种集成模式合适？（Hono 中间件、手动集成、服务令牌、CORS、多租户）

2. 查看模板：从 templates/ 复制相关模板

3. 配置环境：在 wrangler.jsonc 中设置 ACCESS_TEAM_DOMAIN 和 ACCESS_AUD

4. 设置控制面板：引导用户创建 Access 策略（使用 references/access-policy-setup.md）

5. 避免错误：应用 references/common-errors.md 中的解决方案

6. 测试：部署并验证身份验证流程

---

不适用场景

此技能适用于使用 Cloudflare Access 的 Cloudflare Workers。请勿用于：

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

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

---

Additional Resources

Cloudflare Documentation:

• Access Overview
• JWT Validation
• Service Tokens

Packages:

• @hono/cloudflare-access
• Hono Framework

Dashboard:

• Zero Trust Dashboard

---

Skill Version: 1.0.0 Last Updated: 2025-10-28 Errors Prevented: 8 Token Savings: 58% Time Savings: 2.5 hours Production Tested: ✅