cloudflare-zero-trust-access

Imported from secondsky/claude-skills (plugins/cloudflare-zero-trust-access/skills/cloudflare-zero-trust-access/SKILL.md). Install upstream with npx skills add secondsky/claude-skills --skill cloudflare-zero-trust-access. Copyright stays with the author (MIT).

Cloudflare Zero Trust Access Skill

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

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

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

Integration Patterns

📖 New to Cloudflare Access? Load references/quick-start.md for step-by-step setup instructions (15-20 minutes).

Pattern 1: Hono Middleware (Recommended)

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:

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

{
  "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

Pattern 2: Manual JWT Validation

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

Template: templates/jwt-validation-manual.ts (~100 lines, uses Web Crypto API)

Pattern 3: Service Token Authentication

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

Pattern 4: CORS + Access

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

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

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

Pattern 5: Multi-Tenant

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

Common Errors Prevented

This skill prevents 8 documented errors. Full details: references/common-errors.md

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

Problem: OPTIONS requests return 401, breaking CORS

Solution: CORS middleware BEFORE Access middleware

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

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

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

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

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

Solution: Use environment variables

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

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

Errors #4-8 (Quick Reference)

📄 Full error details: references/common-errors.md (~2.5 hours saved per implementation)

Templates

Scripts

Use Cases

📄 Detailed use cases: references/use-cases.md

When to Load References

Package Versions

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

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.

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