SuperAPI AI 工具集

cloudflare-zero-trust-access

安全与审计

查看项目

更新于 10-15 22:33

技能介绍

用途:为 Cloudflare Workers 应用接入 Cloudflare Access 认证(Zero Trust),在应用层完成身份验证,无需自建认证基础设施。Access 位于应用之前校验用户,认证后签发 JWT,由 Worker 校验。

主要能力:支持多种集成模式。一、Hono 中间件(推荐):使用 @hono/cloudflare-access 一行接入,自动校验 JWT、缓存公钥(1 小时 TTL),并具 TypeScript 类型安全。示例:app.use('/admin/*', cloudflareAccess({ domain: (c) => c.env.ACCESS_TEAM_DOMAIN })),通过 c.get('accessPayload') 获取 email。配置在 wrangler.jsonc 中设置 ACCESS_TEAM_DOMAIN 与 ACCESS_AUD。二、手动 JWT 校验:适用于非 Hono 场景,约 100 行,使用 Web Crypto API。三、服务令牌认证:用于 CI/CD、后端服务、cron 等无交互登录场景,客户端发送 CF-Access-Client-Id 与 CF-Access-Client-Secret 头,服务端同一中间件兼容。四、CORS + Access:用于 SPA 调用受保护 API,关键点是 CORS 中间件必须放在 Access 中间件之前,否则 OPTIONS 预检因无认证头被返回 401。五、多租户:租户配置存于 D1/KV,按请求动态选择中间件。

适用场景:保护 Worker 路由、管理后台、API 认证、基于角色或组权限、地域限制、机器间认证、多租户 SaaS、SPA + API 组合。

使用方式与限制:提供 templates/ 下多个模板(如 hono-basic-setup.ts、jwt-validation-manual.ts、service-token-auth.ts、cors-access.ts、multi-tenant.ts)及 wrangler.jsonc、.env.example、types.ts;脚本 test-access-jwt.sh 与 create-service-token.sh。依赖版本:@hono/cloudflare-access 0.3.1、hono 4.12.12、@cloudflare/workers-types 4.20260408.0。该技能仅适用于 Cloudflare Workers 搭配 Cloudflare Access;不适用于 Cloudflare Pages(应改用 @cloudflare/pages-plugin-cloudflare-access)、非 Cloudflare 平台、自定义 JWT 认证、Auth.js 以及自托管认证。资料称可防范 8 类常见错误,如 CORS 预检被拦截、缺少 JWT 头、团队名无效、密钥缓存竞争、服务令牌头错误、令牌过期、策略重叠、开发生产配置不一致。