cloudflare-zero-trust-access

What this skill does

# 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**:
```typescript
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`):
```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**:
```typescript
// 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):
```typescript
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):
```typescript
// 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!

```typescript
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**:
```javascript
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**:
```typescript
// 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
```typescript
// ✅ 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
```typescript
// ✅ 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:
```typescript
// ✅ 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
```typescript
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 c