cloudflare-zero-trust-access

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cloudflare Zero Trust Access Skill

Cloudflare Zero Trust Access 技能方案

Integrate Cloudflare Zero Trust Access authentication with Cloudflare Workers applications using proven patterns and templates.

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

Overview

概述

This skill provides complete integration patterns for Cloudflare Access, enabling application-level authentication for Workers without managing your own auth infrastructure.

What is Cloudflare Access? Cloudflare Access is Zero Trust authentication that sits in front of your application, validating users before they reach your Worker. After authentication, Access issues JWT tokens that your Worker validates.

Key Benefits:

No auth infrastructure to maintain
Integrates with identity providers (Azure AD, Google, Okta, GitHub)
Service tokens for machine-to-machine auth
Built-in MFA and session management
Comprehensive audit logs

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

什么是Cloudflare Access？ Cloudflare Access是一种零信任身份验证服务，部署在你的应用前端，在用户到达Worker之前验证其身份。验证通过后，Access会颁发JWT令牌，供Worker进行校验。

核心优势:

无需维护自有身份验证基础设施
与身份提供商（Azure AD、Google、Okta、GitHub）集成
支持机器对机器身份验证的服务令牌
内置多因素认证（MFA）和会话管理
全面的审计日志

When to Use This Skill

适用场景

Trigger this skill when tasks involve:

Authentication: Protecting Worker routes, securing admin dashboards, API authentication
Access Control: Role-based access (RBAC), group-based permissions, geographic restrictions
Service Auth: Backend services calling Worker APIs, CI/CD pipelines, cron jobs
Multi-Tenant: SaaS apps with organization-level authentication
CORS + Auth: Single-page applications calling protected APIs

Keywords to Trigger: cloudflare access, zero trust, access authentication, JWT validation, service tokens, cloudflare auth, hono access, workers authentication, protect worker routes, admin authentication

当任务涉及以下内容时，可使用本技能方案：

身份验证：保护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

Integration Patterns

集成模式

📖 New to Cloudflare Access? Load

references/quick-start.md

for step-by-step setup instructions (15-20 minutes).

📖 首次接触Cloudflare Access？ 查看

references/quick-start.md

获取分步设置指南（15-20分钟）。

Pattern 1: Hono Middleware (Recommended)

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

Use

@hono/cloudflare-access

for one-line Access integration.

When to Use:

Building with Hono framework
Need quick, production-ready setup
Want automatic JWT validation and key caching

Template:

templates/hono-basic-setup.ts

Setup:

typescript

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}!`)
})

Configuration (

wrangler.jsonc

jsonc

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

Benefits:

✅ Automatic JWT validation
✅ Public key caching (1-hour TTL)
✅ Type-safe with TypeScript
✅ Production-tested and maintained

使用

@hono/cloudflare-access

实现一键式Access集成。

适用场景:

基于Hono框架构建应用
需要快速搭建生产就绪的验证环境
希望自动完成JWT验证和密钥缓存

模板:

templates/hono-basic-setup.ts

设置步骤:

typescript

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

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

// 公开路由
app.get('/', (c) => c.text('Public page'))

// 受保护路由
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

jsonc

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

优势:

✅ 自动JWT验证
✅ 公钥缓存（1小时TTL）
✅ TypeScript类型安全
✅ 经过生产环境测试和维护

Pattern 2: Manual JWT Validation

模式2：手动JWT验证

When to Use: Not using Hono, need custom validation logic

Template:

templates/jwt-validation-manual.ts

(~100 lines, uses Web Crypto API)

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

模板:

templates/jwt-validation-manual.ts

（约100行，使用Web Crypto API）

Pattern 3: Service Token Authentication

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

When to Use: CI/CD pipelines, backend services, cron jobs (no interactive login)

Client: Send

CF-Access-Client-Id

CF-Access-Client-Secret

headers

Server: Same middleware handles both - detect via

!payload.email && payload.common_name

📄 Full guide:

references/service-tokens-guide.md

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

客户端: 发送

CF-Access-Client-Id

CF-Access-Client-Secret

请求头

服务端: 同一中间件可处理两种验证场景 - 通过

!payload.email && payload.common_name

进行检测

📄 完整指南:

references/service-tokens-guide.md

Pattern 4: CORS + Access

模式4：CORS + Access

When to Use: SPA (React/Vue/Angular) calling protected API

⚠️ CRITICAL: CORS middleware MUST come BEFORE Access middleware!

typescript

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

Why: OPTIONS preflight has no auth headers → Access blocks with 401

📄 Full pattern:

templates/cors-access.ts

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

⚠️ 关键注意事项: CORS中间件必须在Access中间件之前！

typescript

// ✅ 正确顺序
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

Pattern 5: Multi-Tenant

模式5：多租户

When to Use: SaaS with per-org authentication, white-label apps

Architecture: Tenant config in D1/KV → Dynamic middleware per request

📄 Full pattern:

templates/multi-tenant.ts

and

references/use-cases.md

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

架构: 租户配置存储在D1/KV中 → 针对每个请求动态加载中间件

📄 完整模式:

templates/multi-tenant.ts

和

references/use-cases.md

Common Errors Prevented

常见错误规避

This skill prevents 8 documented errors. Full details:

references/common-errors.md

本技能方案可预防8种已记录的错误。详细内容：

references/common-errors.md

Error #1: CORS Preflight Blocked (45 min saved)

错误#1：CORS预检请求被拦截（节省45分钟排查时间）

Problem: OPTIONS requests return 401, breaking CORS

Solution: CORS middleware BEFORE Access middleware

typescript

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

问题: OPTIONS请求返回401，导致CORS功能失效

解决方案: 将CORS中间件放在Access中间件之前

typescript

// ✅ 正确写法
app.use('*', cors())
app.use('/api/*', cloudflareAccess({ domain: '...' }))

Error #2: Missing JWT Header (30 min saved)

错误#2：JWT头缺失（节省30分钟排查时间）

Problem: Request not going through Access, no JWT header

Solution: Access Worker through Access URL, not direct

*.workers.dev

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

问题: 请求未通过Access转发，缺少JWT头

解决方案: 通过Access URL访问Worker，而非直接访问

*.workers.dev

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

Error #3: Invalid Team Name (15 min saved)

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

Problem: Hardcoded or wrong team name causes "Invalid issuer"

Solution: Use environment variables

typescript

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

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

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

解决方案: 使用环境变量

typescript

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

// ❌ 错误写法
cloudflareAccess({ domain: 'my-team.cloudflareaccess.com' })

Errors #4-8 (Quick Reference)

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

#	Error	Solution
4	Key cache race	Use `@hono/cloudflare-access` (auto-caches)
5	Wrong service token headers	Use `CF-Access-Client-Id/Secret` (not `Authorization` )
6	Token expiration (401 after 1 hr)	Handle gracefully, redirect to login
7	Overlapping policies	Use most specific paths
8	Dev/prod mismatch	Use environment-specific configs

📄 Full error details:

references/common-errors.md

(~2.5 hours saved per implementation)

编号	错误类型	解决方案
4	密钥缓存竞争	使用 `@hono/cloudflare-access` （自动缓存）
5	服务令牌请求头错误	使用 `CF-Access-Client-Id/Secret` （而非 `Authorization` ）
6	令牌过期（1小时后返回401）	优雅处理过期，重定向至登录页
7	策略重叠	使用最具体的路径配置
8	开发/生产环境配置不匹配	使用环境专属配置

📄 完整错误详情:

references/common-errors.md

（每次集成约节省2.5小时）

Templates

模板列表

Template	Purpose
`hono-basic-setup.ts`	Standard Hono + Access integration
`jwt-validation-manual.ts`	Manual JWT verification with Web Crypto
`service-token-auth.ts`	Service token patterns
`cors-access.ts`	CORS + Access (correct ordering)
`multi-tenant.ts`	Multi-tenant architecture
`wrangler.jsonc`	Complete Wrangler configuration
`.env.example`	Environment variable template
`types.ts`	TypeScript definitions

模板	用途
`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类型定义

Scripts

脚本列表

Script	Usage
`test-access-jwt.sh`	`./test-access-jwt.sh <jwt-token>` - Decode and validate JWT
`create-service-token.sh`	`./create-service-token.sh [name]` - Service token setup guide

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

Use Cases

应用场景示例

Use Case	Template	Key Point
Admin Dashboard	`hono-basic-setup.ts`	Email domain policy
API Authentication	`hono-basic-setup.ts`	Mixed user/service policy
SPA + API	`cors-access.ts`	CORS before Access!
CI/CD Pipeline	`service-token-auth.ts`	Service token in secrets
Multi-Tenant SaaS	`multi-tenant.ts`	D1 tenant config

📄 Detailed use cases:

references/use-cases.md

场景	使用模板	核心要点
管理后台	`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

When to Load References

参考文档加载时机

Reference File	Load When...
`references/quick-start.md`	Step-by-step setup for new users, first-time integration
`references/common-errors.md`	Debugging auth issues, prevention patterns (includes all 8 errors)
`references/jwt-payload-structure.md`	Accessing JWT claims, user vs service token
`references/service-tokens-guide.md`	Setting up machine-to-machine auth
`references/access-policy-setup.md`	Dashboard configuration, policy creation
`references/use-cases.md`	Detailed implementation for specific scenarios
`references/value-proposition.md`	Token efficiency metrics, workflow guidance, production validation

参考文件	加载场景
`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`	令牌效率指标、工作流指导、生产环境验证

Package Versions

依赖包版本

Package	Version
@hono/cloudflare-access	0.3.1
hono	4.10.7
@cloudflare/workers-types	4.20251126.0

Verified: 2025-12-14 | Token Savings: ~58% | Production Tested: ✅

包	版本
@hono/cloudflare-access	0.3.1
hono	4.10.7
@cloudflare/workers-types	4.20251126.0

验证日期: 2025-12-14 | 令牌消耗节省: ~58% | 生产环境测试: ✅

When NOT to Use

不适用场景

This skill is for Cloudflare Workers with Cloudflare Access. Do not use for:

❌ Cloudflare Pages (use

@cloudflare/pages-plugin-cloudflare-access

instead)

❌ Non-Cloudflare platforms
❌ Custom JWT auth (not Access)
❌ Auth.js or other auth libraries
❌ Self-hosted authentication

For those, use appropriate skills or libraries.

本技能方案仅适用于Cloudflare Workers搭配Cloudflare Access的场景。请勿用于：

❌ Cloudflare Pages（请使用

@cloudflare/pages-plugin-cloudflare-access

）

❌ 非Cloudflare平台
❌ 自定义JWT身份验证（非Access颁发）
❌ Auth.js或其他身份验证库
❌ 自托管身份验证系统

以上场景请使用对应的技能方案或库。

Additional Resources

额外资源

Cloudflare Documentation:

Packages:

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: ✅

Cloudflare官方文档:

依赖包:

控制台:

Zero Trust控制台

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