secondsky/claude-skills / plugins/cloudflare-zero-trust-access/skills/cloudflare-zero-trust-access
cloudflare-zero-trust-access
VerifiedCloudflare Zero Trust Access authentication for Workers. Use for JWT validation, service tokens, CORS, or encountering preflight blocking, cache race conditions, missing JWT headers.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.1 KB |
| references/access-policy-setup.md | markdown | 13.5 KB |
| references/common-errors.md | markdown | 15.1 KB |
| references/jwt-payload-structure.md | markdown | 12.8 KB |
| references/quick-start.md | markdown | 1.8 KB |
| references/service-tokens-guide.md | markdown | 15.3 KB |
| references/use-cases.md | markdown | 8.1 KB |
| references/value-proposition.md | markdown | 1.6 KB |
| scripts/create-service-token.shexecutable | script | 8.3 KB |
| scripts/test-access-jwt.shexecutable | script | 10.8 KB |
| templates/.env.example | other | 4.2 KB |
| templates/cors-access.ts | script | 8.1 KB |
| templates/hono-basic-setup.ts | script | 3.8 KB |
| templates/jwt-validation-manual.ts | script | 6.6 KB |
| templates/multi-tenant.ts | script | 10.1 KB |
| templates/service-token-auth.ts | script | 7.5 KB |
| templates/types.ts | script | 8.5 KB |
| templates/wrangler.jsonc | other | 3.9 KB |
references/jwt-payload-structure.md
View on GitHub# Cloudflare Access JWT Payload Structure
This document provides detailed information about the structure of JWT tokens issued by Cloudflare Access, including differences between user authentication and service tokens.
---
## Overview
Cloudflare Access issues JWT (JSON Web Token) tokens after successful authentication. These tokens are included in the `CF-Access-JWT-Assertion` header on all requests that pass through Access.
**Token Lifetime**: Default 1 hour (configurable in Access policy)
**Token Format**: Standard JWT with header, payload, and signature
```
header.payload.signature
```
---
## User Authentication JWT
### Complete Example
```json
{
"email": "user@example.com",
"country": "US",
"groups": ["developers", "admin"],
"type": "app",
"aud": [
"abc123def456ghi789jkl012mno345pqr678stu901vwx234yz"
],
"exp": 1730995200,
"iat": 1730991600,
"iss": "https://your-team.cloudflareaccess.com",
"sub": "user-id-from-identity-provider",
"nonce": "random-nonce-value"
}
```
### Field Descriptions
#### `email` (string, required)
The authenticated user's email address.
**Example**: `"user@example.com"`
**Use Cases**:
- Display username in UI
- Check email domain for authorization
- Log user activity
- Personalize content
**Code Example**:
```typescript
const accessPayload = c.get('accessPayload')
const userEmail = accessPayload.email
// Check email domain
if (!userEmail.endsWith('@company.com')) {
return c.json({ error: 'Only company emails allowed' }, 403)
}
```
---
#### `country` (string, optional)
User's country code in ISO 3166-1 alpha-2 format.
**Example**: `"US"`, `"GB"`, `"AU"`, `"CA"`
**Note**: Only populated if geo-location is enabled in Access policy.
**Use Cases**:
- Geographic restrictions
- Compliance requirements (GDPR, data residency)
- Analytics and logging
- Content localization
**Code Example**:
```typescript
// Restrict access to specific countries
const allowedCountries = ['US', 'CA', 'GB', 'AU']
if (accessPayload.country && !allowedCountries.includes(accessPayload.country)) {
return c.json({ error: 'Access restricted in your region' }, 403)
}
```
---
#### `groups` (string[], optional)
Array of group names the user belongs to, provided by the identity provider.
**Example**: `["developers", "admin", "sales"]`
**Note**: Only populated when using identity providers that support groups (Azure AD, Okta, Google Workspace, etc.)
**Use Cases**:
- Role-based access control (RBAC)
- Feature flags
- Team-specific functionality
- Admin panels
**Code Example**:
```typescript
// Check if user is admin
const isAdmin = accessPayload.groups?.includes('admin') ?? false
if (isAdmin) {
// Show admin features
} else {
// Regular user view
}
```
---
#### `type` (string, optional)
Type of authentication.
**Values**:
- `"app"` - Application access (most common)
**Example**: `"app"`
---
#### `aud` (string[], required)
Application Audience - identifies which Access application issued this token.
**Example**: `["abc123def456ghi789jkl012mno345pqr678stu901vwx234yz"]`
**CRITICAL**: Always validate this matches your application's expected AUD tag.
**Finding Your AUD**:
1. Go to Zero Trust Dashboard
2. Access > Applications
3. Click on your application
4. Copy the "Application Audience" value
**Code Example**:
```typescript
// Validate audience
if (!payload.aud.includes(env.ACCESS_AUD)) {
throw new Error(`Invalid audience. Expected ${env.ACCESS_AUD}`)
}
```
**Security Note**: Validating `aud` prevents token reuse across different applications.
---
#### `exp` (number, required)
Expiration time as Unix timestamp (seconds since epoch).
**Example**: `1730995200` (2025-10-28 12:00:00 UTC)
**Default Lifespan**: 1 hour from `iat`
**Use Cases**:
- Validate token hasn't expired
- Calculate remaining session time
- Trigger re-authentication
**Code Example**:
```typescript
function isTokenExpired(payload: AccessJWTPayload): boolean {
const nowSeconds = Math.floor(Date.now() / 1000)
return payload.exp < nowSeconds
}
function getTimeToExpiration(payload: AccessJWTPayload): number {
const nowSeconds = Math.floor(Date.now() / 1000)
return Math.max(0, payload.exp - nowSeconds)
}
// Usage
if (isTokenExpired(accessPayload)) {
return c.json({ error: 'Session expired' }, 401)
}
const ttl = getTimeToExpiration(accessPayload)
console.log(`Session expires in ${ttl} seconds`)
```
---
#### `iat` (number, required)
Issued At time as Unix timestamp (seconds since epoch).
**Example**: `1730991600` (2025-10-28 11:00:00 UTC)
**Use Cases**:
- Calculate token age
- Logging and auditing
- Reject tokens issued before a certain time (e.g., after password reset)
**Code Example**:
```typescript
const tokenAge = Math.floor(Date.now() / 1000) - payload.iat
console.log(`Token issued ${tokenAge} seconds ago`)
```
---
#### `iss` (string, required)
Issuer - the Access team domain that issued this token.
**Example**: `"https://your-team.cloudflareaccess.com"`
**Format**: Always includes `https://` prefix
**Validation**:
```typescript
const expectedIssuer = `https://${env.ACCESS_TEAM_DOMAIN}`
if (payload.iss !== expectedIssuer) {
throw new Error(`Invalid issuer. Expected ${expectedIssuer}, got ${payload.iss}`)
}
```
**Security Note**: Validating `iss` prevents tokens from other Access teams being used.
---
#### `sub` (string, required)
Subject - unique user identifier from the identity provider.
**Example**: `"user-id-from-identity-provider"`
**Format**: Varies by identity provider
- Azure AD: GUID
- Google: Numeric ID
- Okta: User ID
**Use Cases**:
- Unique user identification (more stable than email)
- Link user data across systems
- Audit logs
**Code Example**:
```typescript
// Use sub as unique identifier instead of email
// (email can change, sub typically doesn't)
const userId = accessPayload.sub
await db.prepare('SELECT * FROM users WHERE idp_sub = ?')
.bind(userId)
.first()
```
---
#### `nonce` (string, optional)
Random nonce value for OIDC flow.
**Example**: `"random-nonce-value"`
**Use Case**: Typically used internally by Access, not needed for application logic.
---
## Service Token JWT
Service tokens have a **different structure** than user JWTs.
### Complete Example
```json
{
"common_name": "my-backend-service",
"aud": [
"abc123def456ghi789jkl012mno345pqr678stu901vwx234yz"
],
"exp": 1730995200,
"iat": 1730991600,
"iss": "https://your-team.cloudflareaccess.com",
"sub": "",
"type": "app"
}
```
### Key Differences from User JWT
| Field | User JWT | Service Token JWT |
|-------|----------|-------------------|
| `email` | ✅ Present | ❌ Not present |
| `common_name` | ❌ Not present | ✅ Present (token name) |
| `sub` | Populated with user ID | Empty string `""` |
| `groups` | May be present | Never present |
| `country` | May be present | Never present |
### Field Descriptions
#### `common_name` (string, required for service tokens)
The name of the service token as configured in the Access dashboard.
**Example**: `"my-backend-service"`
**Use Cases**:
- Identify which service made the request
- Service-specific logic
- Logging and monitoring
**Code Example**:
```typescript
// Detect service token vs user authentication
function isServiceToken(payload: any): boolean {
return !!payload.common_name && !payload.email
}
// Handle differently based on auth type
if (isServiceToken(accessPayload)) {
console.log(`Service request from: ${accessPayload.common_name}`)
} else {
console.log(`User request from: ${accessPayload.email}`)
}
```
---
#### `sub` (string, empty for service tokens)
Always an empty string for service tokens.
**Example**: `""`
**Note**: This is a reliable way to differentiate service tokens from user JWTs.
---
## TypeScript Type Definitions
### User JWT Type
```typescript
interface AccessJWTPayload {
email: string
country?: string
groups?: string[]
type?: string
aud: string[]
exp: number
iat: number
iss: string
sub: string
nonce?: string
[key: string]: any // Custom claims
}
```
### Service Token JWT Type
```typescript
interface ServiceTokenJWTPayload {
common_name: string
aud: string[]
exp: number
iat: number
iss: string
sub: string // Always empty ""
type?: string
[key: string]: any
}
```
### Type Guards
```typescript
// Check if user (not service token)
function isUserJWT(payload: any): payload is AccessJWTPayload {
return 'email' in payload && !!payload.email
}
// Check if service token
function isServiceTokenJWT(payload: any): payload is ServiceTokenJWTPayload {
return 'common_name' in payload && !!payload.common_name
}
// Usage
if (isUserJWT(accessPayload)) {
console.log(`User: ${accessPayload.email}`)
} else if (isServiceTokenJWT(accessPayload)) {
console.log(`Service: ${accessPayload.common_name}`)
}
```
---
## JWT Header Structure
The JWT header contains metadata about the token.
### Example
```json
{
"alg": "RS256",
"kid": "abc123",
"typ": "JWT"
}
```
### Fields
#### `alg` (string)
Algorithm used to sign the token.
**Value**: Always `"RS256"` (RSA with SHA-256)
#### `kid` (string)
Key ID - identifies which public key to use for signature verification.
**Example**: `"abc123"`
**Use**: Match this with the `kid` in the public keys response from:
```
https://<team>.cloudflareaccess.com/cdn-cgi/access/certs
```
#### `typ` (string)
Token type.
**Value**: `"JWT"`
---
## Custom Claims
Access allows adding custom claims through your identity provider configuration.
### Example with Custom Claims
```json
{
"email": "user@example.com",
"groups": ["admin"],
"aud": ["..."],
"exp": 1730995200,
"iat": 1730991600,
"iss": "https://your-team.cloudflareaccess.com",
"sub": "user-123",
// Custom claims
"department": "Engineering",
"employee_id": "EMP-456",
"role": "Senior Developer",
"clearance_level": 3
}
```
### Accessing Custom Claims
```typescript
interface CustomAccessPayload extends AccessJWTPayload {
department?: string
employee_id?: string
role?: string
clearance_level?: number
}
const payload = c.get('accessPayload') as CustomAccessPayload
if (payload.clearance_level && payload.clearance_level >= 3) {
// Grant access to sensitive resources
}
```
---
## Common Patterns
### Pattern 1: Extract User Identifier
```typescript
function getUserIdentifier(payload: any): string {
// For user JWT: use email
if (payload.email) {
return payload.email
}
// For service token: use common_name
if (payload.common_name) {
return payload.common_name
}
// Fallback: use sub
return payload.sub || 'unknown'
}
```
### Pattern 2: Role-Based Access Control
```typescript
function hasRole(payload: AccessJWTPayload, requiredRole: string): boolean {
return payload.groups?.includes(requiredRole) ?? false
}
// Usage
if (!hasRole(accessPayload, 'admin')) {
return c.json({ error: 'Admin access required' }, 403)
}
```
### Pattern 3: Geographic Restrictions
```typescript
const RESTRICTED_COUNTRIES = ['CN', 'RU', 'KP']
function isCountryAllowed(payload: AccessJWTPayload): boolean {
if (!payload.country) {
return true // Allow if country not provided
}
return !RESTRICTED_COUNTRIES.includes(payload.country)
}
```
### Pattern 4: Token Validation
```typescript
function validateAccessToken(
payload: AccessJWTPayload,
env: Env
): { valid: boolean; error?: string } {
// Check expiration
const nowSeconds = Math.floor(Date.now() / 1000)
if (payload.exp < nowSeconds) {
return { valid: false, error: 'Token expired' }
}
// Check audience
if (!payload.aud.includes(env.ACCESS_AUD)) {
return { valid: false, error: 'Invalid audience' }
}
// Check issuer
const expectedIssuer = `https://${env.ACCESS_TEAM_DOMAIN}`
if (payload.iss !== expectedIssuer) {
return { valid: false, error: 'Invalid issuer' }
}
return { valid: true }
}
```
---
## Debugging Tips
### Decode JWT in Browser Console
```javascript
// Paste JWT token
const token = 'eyJhbGciOiJS...'
// Decode payload
const [header, payload, signature] = token.split('.')
const decodedPayload = JSON.parse(atob(payload.replace(/-/g, '+').replace(/_/g, '/')))
console.log(decodedPayload)
```
### Log JWT in Worker (Development Only!)
```typescript
// ⚠️ DEVELOPMENT ONLY - DO NOT LOG IN PRODUCTION
if (env.ENVIRONMENT === 'development') {
const jwtToken = c.req.header('CF-Access-JWT-Assertion')
console.log('JWT Token:', jwtToken)
const [, payloadB64] = jwtToken.split('.')
const payload = JSON.parse(atob(payloadB64.replace(/-/g, '+').replace(/_/g, '/')))
console.log('Decoded Payload:', payload)
}
```
---
## Resources
- [JWT Specification (RFC 7519)](https://datatracker.ietf.org/doc/html/rfc7519)
- [Cloudflare Access JWT Validation](https://developers.cloudflare.com/cloudflare-one/identity/authorization-cookie/validating-json/)
- [JWT.io Debugger](https://jwt.io/) - Decode and validate JWTs
---
**Last Updated**: 2025-10-28
**JWT Format**: RS256
**Cloudflare Docs**: ✅ Verified
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |