⚡

Cloudflare零信任访问技能 cloudflare-zero-trust-access

此技能用于在Cloudflare Workers中集成Cloudflare零信任访问认证，提供JWT验证、服务令牌、CORS处理等功能，简化应用级安全实现。关键词：Cloudflare Access、零信任、JWT验证、Hono框架、Workers认证、服务令牌、CORS、云安全、身份认证。

零信任架构 0 次安装 0 次浏览 更新于 3/7/2026

名称: cloudflare-zero-trust-access 描述: Cloudflare零信任访问认证用于Workers。用于JWT验证、服务令牌、CORS，或处理预检拦截、缓存竞争条件、缺失JWT头部等问题。

关键词: Cloudflare Access, 零信任, Cloudflare零信任访问, 访问认证, JWT验证, 访问jwt, 服务令牌, hono cloudflare access, hono-cloudflare-access 中间件, workers认证, 保护worker路由, 管理员认证, 访问策略, 身份提供商, azure ad访问, google workspace访问, okta访问, github访问, rbac cloudflare, 地理限制, 多租户访问, cors访问, CORS预检拦截, JWT头部缺失, 访问密钥缓存, 团队不匹配, 访问声明 许可证: MIT 允许工具:

  • 读取
  • 写入
  • 编辑
  • Bash 元数据: 版本: “1.0.0” 类别: 认证 框架: hono 平台: cloudflare-workers 包版本: “@hono/cloudflare-access”: “0.3.1” “hono”: “4.10.3” “@cloudflare/workers-types”: “4.20251014.0” 预防错误: 8 令牌节省: “58%” 时间节省: “2.5小时” 生产测试: true 最后验证: “2025-10-28”

Cloudflare零信任访问技能

使用已验证模式和模板，将Cloudflare零信任访问认证集成到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, 零信任, 访问认证, JWT验证, 服务令牌, cloudflare认证, hono访问, workers认证, 保护worker路由, 管理员认证

集成模式

📖 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 }>()

// 公共路由
app.get('/', (c) => c.text('公共页面'))

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

app.get('/admin/dashboard', (c) => {
  const { email } = c.get('accessPayload')
  return c.text(`欢迎，${email}！`)
})

配置 (wrangler.jsonc):

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

优势:

  • ✅ 自动JWT验证
  • ✅ 公钥缓存（1小时TTL）
  • ✅ 使用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中间件之前！

// ✅ 正确顺序
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中间件之前

// ✅ 正确
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分钟）

问题: 硬编码或错误的团队名称导致“无效发行者”

解决方案: 使用环境变量

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

// ❌ 错误
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 手动JWT验证使用Web Crypto
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 [名称] - 服务令牌设置指南

使用案例

使用案例 模板 关键点
管理员仪表板 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.10.7
@cloudflare/workers-types 4.20251126.0

验证: 2025-12-14 | 令牌节省: ~58% | 生产测试: ✅

何时不使用

此技能用于 Cloudflare Workers 与 Cloudflare Access。请勿用于：

  • ❌ Cloudflare Pages（使用 @cloudflare/pages-plugin-cloudflare-access 代替）
  • ❌ 非Cloudflare平台
  • ❌ 自定义JWT认证（非Access）
  • ❌ Auth.js或其他认证库
  • ❌ 自托管认证

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

额外资源

Cloudflare文档:

包:

仪表板:

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