jackspace/claudeskillz/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 cause conflicts

Solution: Use most specific paths, avoid overlaps

Error #8: Dev/Prod Mismatch (15 min saved)

Problem: Code works in dev, fails in prod

Solution: Environment-specific configs

{
  "env": {
    "dev": {
      "vars": { "ACCESS_TEAM_DOMAIN": "dev-team.cloudflareaccess.com" }
    },
    "production": {
      "vars": { "ACCESS_TEAM_DOMAIN": "prod-team.cloudflareaccess.com" }
    }
  }
}

Total Time Saved: ~2.5 hours per implementation

Templates

Core Templates

1. `hono-basic-setup.ts` - Standard Hono + Access integration

• Public and protected routes
• User info access
• Error handling

1. `jwt-validation-manual.ts` - Manual JWT verification

• Web Crypto API usage
• Key caching
• Full validation logic

1. `service-token-auth.ts` - Service token patterns

• Client and server examples
• Service vs user detection
• Best practices

1. `cors-access.ts` - CORS + Access integration

• Correct middleware ordering
• Frontend examples (fetch, axios)
• Troubleshooting guide

1. `multi-tenant.ts` - Multi-tenant architecture

• Subdomain, path, header strategies
• D1 tenant config
• Dynamic middleware

Configuration Templates

1. `wrangler.jsonc` - Complete Wrangler configuration

• Environment variables
• Bindings (D1, KV, R2)
• Dev/staging/production environments

1. `.env.example` - Environment variable template

• Required: ACCESS_TEAM_DOMAIN, ACCESS_AUD
• Optional: Service tokens, CORS config
• Setup instructions

1. `types.ts` - TypeScript definitions

• AccessJWTPayload interface
• ServiceTokenJWTPayload interface
• Type guards and helpers

Reference Documentation

Comprehensive guides in references/:

1. `common-errors.md` (~800 words)

• All 8 errors with solutions
• Error → Symptom → Cause → Solution → Prevention
• Source links and time savings

1. `jwt-payload-structure.md` (~1,200 words)

• Complete JWT field reference
• User vs service token differences
• Type definitions and examples

1. `service-tokens-guide.md` (~1,100 words)

• Creating service tokens
• Adding to policies
• Use cases (CI/CD, microservices, cron)
• Rotation best practices

1. `access-policy-setup.md` (~1,400 words)

• Dashboard configuration steps
• Policy examples
• Identity provider setup
• Testing and troubleshooting

Helper Scripts

Located in scripts/:

1. `test-access-jwt.sh` - JWT testing tool

• Decodes JWT header and payload
• Fetches public keys
• Validates signature and claims
• Usage: ./test-access-jwt.sh <jwt-token>

1. `create-service-token.sh` - Service token setup guide

• Interactive setup instructions
• Code examples (curl, Node.js, Python, GitHub Actions)
• Best practices checklist
• Usage: ./create-service-token.sh [token-name]

Quick Start

1. Install Package

npm install hono @hono/cloudflare-access

2. Configure Access

Dashboard:

1. Go to Zero Trust > Access > Applications
2. Create application for your Worker domain
3. Create policy (e.g., "Emails ending in @company.com")
4. Copy Application Audience (AUD) tag

wrangler.jsonc:

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

3. Add to Worker

Use templates/hono-basic-setup.ts as starting point:

import { Hono } from 'hono'
import { cloudflareAccess } from '@hono/cloudflare-access'
const app = new Hono<{ Bindings: Env }>()
app.use('/admin/*', cloudflareAccess({
  domain: (c) => c.env.ACCESS_TEAM_DOMAIN
}))
app.get('/admin/dashboard', (c) => {
  const { email } = c.get('accessPayload')
  return c.json({ email })
})
export default app

4. Deploy and Test

npx wrangler deploy

Access: https://your-worker.example.com/admin/dashboard