cloudflare-zero-trust-access

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

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

Use Web Crypto API for custom validation logic.

When to Use:

• Not using Hono framework
• Need custom validation beyond standard checks
• Want full control over JWT verification

Template: templates/jwt-validation-manual.ts

Key Functions:

// Validate JWT signature and claims
async function validateAccessJWT(
  token: string,
  env: Env
): Promise<AccessJWTPayload> {
  // 1. Decode header to get kid
  // 2. Fetch public keys (with caching)
  // 3. Verify signature using Web Crypto API
  // 4. Validate aud, exp, iss
  // 5. Return payload
}

Complexity: ~100 lines Dependencies: None (uses Web Crypto API)

Pattern 3: Service Token Authentication

Use service tokens for machine-to-machine auth.

When to Use:

• Backend services calling your Worker API
• CI/CD pipelines
• Automated scripts and cron jobs
• No interactive login needed

Template: templates/service-token-auth.ts

Client Side (sending request):

const response = await fetch('https://api.example.com/data', {
  headers: {
    'CF-Access-Client-Id': env.SERVICE_TOKEN_ID,
    'CF-Access-Client-Secret': env.SERVICE_TOKEN_SECRET,
  },
})

Server Side (Worker):

// Same validation as user JWTs - middleware handles both
app.use('/api/*', cloudflareAccess({
  domain: (c) => c.env.ACCESS_TEAM_DOMAIN
}))

app.get('/api/data', (c) => {
  const payload = c.get('accessPayload')

  // Detect service token vs user
  const isService = !payload.email && payload.common_name

  return c.json({
    authenticated_by: isService ? 'service-token' : 'user',
    identifier: payload.email || payload.common_name,
  })
})

Setup Guide: references/service-tokens-guide.md

Pattern 4: CORS + Access

Handle cross-origin requests with Access authentication.

When to Use:

• SPA (React/Vue/Angular) calling protected API
• Frontend and API on different domains
• Cross-origin authenticated requests

Template: templates/cors-access.ts

CRITICAL: CORS middleware MUST come before Access middleware!

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

// ✅ CORRECT ORDER
app.use('*', cors({
  origin: 'https://app.example.com',
  credentials: true, // Allow cookies
}))

app.use('/api/*', cloudflareAccess({
  domain: (c) => c.env.ACCESS_TEAM_DOMAIN
}))

// ❌ WRONG ORDER - WILL FAIL!
// Access blocks OPTIONS preflight requests

Why: OPTIONS preflight requests don't include auth headers. If Access runs first, it blocks them with 401.

Frontend:

fetch('https://api.example.com/api/data', {
  credentials: 'include', // ← Critical!
  method: 'POST',
})

Pattern 5: Multi-Tenant

Different Access configurations per tenant/organization.

When to Use:

• SaaS with organization-level authentication
• Each customer has separate Access team
• White-label applications

Template: templates/multi-tenant.ts

Architecture:

• Tenant config stored in D1 or KV
• Dynamic middleware based on tenant ID
• Tenant ID from subdomain, path, or header

Example:

// Subdomain-based: tenant1.example.com, tenant2.example.com
app.use('/app/*', async (c, next) => {
  const tenantId = getTenantFromSubdomain(c.req.url)
  const tenant = await getTenantConfig(tenantId, c.env.DB)

  // Apply tenant-specific Access
  return cloudflareAccess({
    domain: tenant.access_team_domain
  })(c, next)
})

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' })

Error #4: Key Cache Race (20 min saved)

Problem: First request fails, subsequent work

Solution: Use @hono/cloudflare-access (handles caching automatically)

Error #5: Service Token Headers (10 min saved)

Problem: Wrong header names, token doesn't work

Solution: Use exact header names:

// ✅ Correct
'CF-Access-Client-Id': '...'
'CF-Access-Client-Secret': '...'

// ❌ Wrong
'Authorization': 'Bearer ...'

Error #6: Token Expiration (10 min saved)

Problem: Users suddenly get 401 after 1 hour

Solution: Handle gracefully, redirect to login

if (error.message.includes('expired')) {
  return c.json({ error: 'Session expired', code: 'TOKEN_EXPIRED' }, 401)
}

Error #7: Multiple Policies (30 min saved)

Problem: Overlapping Access applications ca