/cloudflare-zero-trust-access

name: cloudflare-zero-trust-access
description: "Cloudflare Zero Trust Access authentication for Workers. Use for JWT validation, service tokens, CORS, or encountering preflight blocking, cache race conditions, missing JWT headers."
license: MIT
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
metadata:
  version: "1.0.0"
  category: authentication
  framework: hono
  platform: cloudflare-workers
  package_versions:
    "@hono/cloudflare-access": "0.3.1"
    "hono": "4.12.12"
    "@cloudflare/workers-types": "4.20260408.0"
  errors_prevented: 8
  token_savings: "58%"
  time_savings: "2.5 hours"
  production_tested: true
  last_verified: "2025-10-28"
  keywords:
    - Cloudflare Access
    - Zero Trust
    - Cloudflare Zero Trust Access
    - Access authentication
    - JWT validation
    - access jwt
    - service tokens
    - hono cloudflare access
    - hono-cloudflare-access middleware
    - workers authentication
    - protect worker routes
    - admin authentication
    - access policy
    - identity providers
    - azure ad access
    - google workspace access
    - okta access
    - github access
    - rbac cloudflare
    - geographic restrictions
    - multi-tenant access
    - cors access
    - CORS preflight blocked
    - JWT header missing
    - access key cache
    - team mismatch
    - access claims

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.clou