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

2. jwt-validation-manual.ts - Manual JWT verification

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

3. service-token-auth.ts - Service token patterns

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

4. cors-access.ts - CORS + Access integration

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

5. multi-tenant.ts - Multi-tenant architecture

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

Configuration Templates

6. wrangler.jsonc - Complete Wrangler configuration

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

7. .env.example - Environment variable template

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

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

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

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

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

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

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

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

Expected: Redirect to Access login, then back to dashboard after auth.

---

Use Cases

Admin Dashboard Protection

Requirements: Protect admin routes with email authentication

Template: hono-basic-setup.ts

Policy: Emails ending in @company.com

---

API Authentication

Requirements: Protect API, allow public pages

Template: hono-basic-setup.ts + separate routes

Policy: Service tokens + employee emails

---

SPA + Protected API

Requirements: React app calling authenticated API

Template: cors-access.ts

Critical: CORS middleware before Access

---

CI/CD Pipeline

Requirements: GitHub Actions calling Worker API

Template: service-token-auth.ts

Setup: Service token in GitHub Secrets

---

Multi-Tenant SaaS

Requirements: Different Access per organization

Template: multi-tenant.ts

Architecture: Tenant config in D1, dynamic middleware

---

Package Information

Package	Version	Purpose
@hono/cloudflare-access	0.3.1	Hono middleware (recommended)
hono	4.10.3	Web framework
@cloudflare/workers-types	4.20251014.0	TypeScript types

Verified: 2025-10-28

No Node.js Dependencies: All packages use Web Standards APIs, fully compatible with Workers runtime.

---

Token Efficiency

Without Skill: ~5,550 tokens

• Cloudflare docs: 2,500 tokens
• Library docs: 450 tokens
• GitHub issue research: 1,000 tokens
• Manual implementation: 1,600 tokens

With Skill: ~2,300 tokens

• SKILL.md: 1,500 tokens
• Templates: 500 tokens
• Quick setup: 300 tokens

Savings: 3,250 tokens (~58%)

---

Production Testing

Library: @hono/cloudflare-access actively maintained Downloads: ~3,000/week GitHub: Part of Hono middleware collection (10k+ stars)

Production Use: Verified working in commercial projects.

---

Workflow

When user requests Access integration:

1. Assess Pattern: Which integration pattern fits? (Hono middleware, manual, service tokens, CORS, multi-tenant)

2. Check Templates: Copy relevant template from templates/

3. Configure Environment: Set ACCESS_TEAM_DOMAIN and ACCESS_AUD in wrangler.jsonc

4. Setup Dashboard: Guide user through Access policy creation (use references/access-policy-setup.md)

5. Prevent Errors: Apply solutions from references/common-errors.md

6. Test: Deploy and verify authentication flow

---

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