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/access-policy-setup.md
View on GitHub# Cloudflare Access Policy Setup Guide
Complete guide to configuring Cloudflare Zero Trust Access policies for protecting Worker applications.
---
## Overview
Cloudflare Access protects your applications by requiring authentication before users can access them. This guide walks through creating and configuring Access policies from scratch.
**What You'll Learn**:
- Creating Access applications
- Configuring authentication policies
- Setting up identity providers
- Testing and troubleshooting
---
## Prerequisites
1. **Cloudflare Account** with Zero Trust enabled
2. **Custom Domain** pointed to your Worker
3. **Worker Application** deployed
4. **Identity Provider** (optional but recommended)
---
## Step 1: Enable Zero Trust
### First-Time Setup
1. Go to https://one.dash.cloudflare.com/
2. Select your account
3. Navigate to **Zero Trust** (left sidebar)
4. If first time, click **"Get Started"**
5. Choose a **team name** (e.g., "acme-corp")
- This becomes your Access domain: `acme-corp.cloudflareaccess.com`
- **IMPORTANT**: Cannot be changed later!
### Team Name Best Practices
- Use company/organization name
- Lowercase, no spaces
- Hyphen-separated words
- Short and memorable
- Examples: `acme`, `acme-corp`, `acme-prod`
---
## Step 2: Configure Identity Provider (Optional)
Identity providers add organization-specific authentication. Without one, Access uses one-time PIN codes via email.
### Supported Providers
- **Azure AD / Entra ID** (Microsoft 365)
- **Google Workspace**
- **Okta**
- **GitHub**
- **Generic OIDC**
- **Generic SAML**
### Adding Azure AD (Example)
1. **In Azure**:
- Azure Portal > Azure Active Directory > App Registrations
- New Registration
- Name: "Cloudflare Access"
- Redirect URI: `https://<team>.cloudflareaccess.com/cdn-cgi/access/callback`
- Copy **Application (client) ID**
- Create **Client Secret**, copy value
2. **In Cloudflare**:
- Zero Trust > Settings > Authentication
- Login Methods > Add new
- Select **Azure AD**
- Enter:
- Name: "Azure AD"
- Application ID: (from Azure)
- Client Secret: (from Azure)
- Directory (tenant) ID: (from Azure)
- Save
3. **Test**:
- Click **"Test"** button
- Should redirect to Microsoft login
- Success message after authentication
### Adding Google Workspace (Example)
1. **In Google Cloud Console**:
- Create new OAuth 2.0 Client ID
- Type: Web application
- Authorized redirect URI: `https://<team>.cloudflareaccess.com/cdn-cgi/access/callback`
- Copy **Client ID** and **Client Secret**
2. **In Cloudflare**:
- Zero Trust > Settings > Authentication
- Add new > Google Workspace
- Enter Client ID and Secret
- (Optional) Restrict to specific domain
3. **Test**:
- Test button should open Google login
---
## Step 3: Create Access Application
### Basic Setup
1. **Navigate to Applications**:
- Zero Trust > Access > Applications
- Click **"Add an application"**
2. **Choose Application Type**:
- Select **"Self-hosted"**
- (Not SaaS or Warp)
3. **Configure Application**:
**Application Name**: Descriptive name
```
Example: "API Dashboard"
```
**Session Duration**: How long users stay logged in
```
Options: 1 hour, 12 hours, 24 hours, 30 days
Recommended: 24 hours for user apps, 1 hour for admin panels
```
**Application Domain**: Your Worker's domain
```
Examples:
- api.example.com
- dashboard.example.com
- *.example.com (wildcard)
```
**Path** (optional): Specific URL path
```
Examples:
- /admin (protect only admin routes)
- /api (protect only API routes)
- / (protect entire domain)
```
4. **Copy Application Audience (AUD)**:
- After creating, copy the **Application Audience** tag
- Example: `abc123def456ghi789jkl012mno345pqr678stu901vwx234yz`
- You'll need this for your Worker configuration
---
## Step 4: Create Access Policy
Policies define **who** can access your application.
### Policy Structure
```
┌─────────────┐
│ Include │ ← Who gets access (required)
├─────────────┤
│ Require │ ← Additional requirements (optional)
├─────────────┤
│ Exclude │ ← Who is explicitly denied (optional)
└─────────────┘
```
**Logic**: `(Include AND Require) AND NOT Exclude`
### Creating a Policy
1. **Add Policy**:
- In your application, click **"Add a policy"**
2. **Policy Name**: Descriptive name
```
Examples:
- "Employees Only"
- "Admin Access"
- "API Access - All Users"
```
3. **Decision**: Allow or Block
```
- Allow: Grant access if rules match
- Block: Deny access (for deny-lists)
```
### Example Policies
#### Example 1: Email Domain
**Use Case**: Only company employees
**Policy**:
```
Include:
Emails ending in: @company.com
```
**Result**: Only users with `@company.com` emails can access.
---
#### Example 2: Specific Emails
**Use Case**: Small team, specific users
**Policy**:
```
Include:
Emails:
- alice@example.com
- bob@example.com
- charlie@example.com
```
---
#### Example 3: Group Membership
**Use Case**: Only developers (requires IdP with groups)
**Policy**:
```
Include:
Emails ending in: @company.com
Require:
Groups: developers
```
**Result**: Must be company employee AND in "developers" group.
---
#### Example 4: Multiple Groups (OR logic)
**Use Case**: Developers or Admins
**Policy 1**:
```
Name: Developers
Include:
Emails ending in: @company.com
Groups: developers
```
**Policy 2**:
```
Name: Admins
Include:
Emails ending in: @company.com
Groups: admin
```
**Result**: Multiple policies create OR logic (either developers OR admins).
---
#### Example 5: Service Tokens
**Use Case**: Backend service + users
**Policy**:
```
Include:
Emails ending in: @company.com
Service Auth: backend-service-token
```
**Result**: Both company employees AND the service token can access.
---
#### Example 6: Country Restriction
**Use Case**: Geo-fencing
**Policy**:
```
Include:
Emails ending in: @company.com
Require:
Country: United States, Canada, United Kingdom
```
**Result**: Company employees only from specified countries.
---
#### Example 7: IP Whitelist
**Use Case**: VPN or office network required
**Policy**:
```
Include:
Emails ending in: @company.com
Require:
IP ranges:
- 203.0.113.0/24
- 198.51.100.0/24
```
**Result**: Must be company employee AND on specified IP ranges.
---
### Policy Selector Options
**Include/Require/Exclude Options**:
- **Emails** - Specific email addresses
- **Emails ending in** - Domain-based (e.g., `@company.com`)
- **Email domains** - Multiple domains
- **Everyone** - Allow all (not recommended for production!)
- **IP ranges** - CIDR notation
- **Country** - ISO country codes
- **Valid certificate** - mTLS authentication
- **Common Name** - Certificate CN field
- **Service Auth** - Service tokens
- **Groups** - IdP groups (requires IdP)
- **GitHub Organization** - GitHub org membership
- **Azure Groups** - Azure AD groups
- **Okta Groups** - Okta groups
- **SAML Groups** - Generic SAML groups
---
## Step 5: Configure Worker Domain
### DNS Setup
Your custom domain must point to your Worker for Access to work.
**Option 1: Workers Custom Domain**:
1. In Cloudflare Dashboard (not Zero Trust):
- Workers & Pages > Your Worker
- Settings > Triggers > Custom Domains
- Add Custom Domain: `api.example.com`
- Cloudflare handles DNS automatically
**Option 2: Manual DNS + Route**:
1. Add DNS record:
```
Type: AAAA
Name: api
Content: 100:: (IPv6 placeholder)
Proxy: Enabled (orange cloud)
```
2. Add Worker route:
```
Route: api.example.com/*
Worker: your-worker-name
```
---
## Step 6: Configure Worker Code
### Environment Variables
**wrangler.jsonc**:
```jsonc
{
"name": "my-worker",
"vars": {
"ACCESS_TEAM_DOMAIN": "acme-corp.cloudflareaccess.com",
"ACCESS_AUD": "abc123def456ghi789jkl012mno345pqr678stu901vwx234yz"
}
}
```
### Worker Code (Hono)
```typescript
import { Hono } from 'hono'
import { cloudflareAccess } from '@hono/cloudflare-access'
type Env = {
ACCESS_TEAM_DOMAIN: string
ACCESS_AUD: string
}
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}!`)
})
export default app
```
### Deploy
```bash
npx wrangler deploy
```
---
## Step 7: Test Access
### Manual Testing
1. **Open Protected URL**:
```
https://api.example.com/admin/dashboard
```
2. **Expect Redirect**:
- Redirected to `https://acme-corp.cloudflareaccess.com/...`
- Shows login page or IdP login
3. **Authenticate**:
- Enter email (or login via IdP)
- Receive verification code (if using email)
- Or complete IdP authentication
4. **Access Granted**:
- Redirected back to `https://api.example.com/admin/dashboard`
- Session cookie set (`CF_Authorization`)
- Page loads successfully
### Testing with curl
```bash
# Get Access login page
curl -I https://api.example.com/admin/dashboard
# Should return 302 redirect to cloudflareaccess.com
# Test with service token
curl -H "CF-Access-Client-Id: abc123.access" \
-H "CF-Access-Client-Secret: your-secret" \
https://api.example.com/admin/dashboard
# Should return 200 with content
```
---
## Step 8: Monitor Access Logs
### Viewing Logs
1. **Navigate to Logs**:
- Zero Trust > Logs > Access
2. **Log Details**:
- Timestamp
- User email
- Application name
- Action (login, allowed, blocked)
- Country, IP address
- User agent
3. **Filter Logs**:
- By application
- By user
- By action (allowed/blocked)
- By date range
### Audit Trail
Access logs provide:
- Who accessed what, when
- Failed authentication attempts
- Service token usage
- Policy changes
**Retention**: 180 days (6 months)
---
## Common Configurations
### Configuration 1: Public Frontend + Protected API
**Setup**:
- Frontend: `www.example.com` (public, no Access)
- API: `api.example.com` (protected with Access)
**Access Application**:
```
Application Domain: api.example.com
Path: /
Policy: Emails ending in @company.com
```
**Worker**: CORS configured to allow `www.example.com`
---
### Configuration 2: Admin Panel Only
**Setup**:
- Public site: `example.com/*` (no Access)
- Admin panel: `example.com/admin/*` (protected)
**Access Application**:
```
Application Domain: example.com
Path: /admin
Policy:
Include: Emails ending in @company.com
Require: Groups - admin
```
---
### Configuration 3: Multi-Environment
**Development**:
```
Application: dev-api.example.com
Policy: Everyone (or specific test emails)
Session Duration: 30 days (convenience)
```
**Staging**:
```
Application: staging-api.example.com
Policy: Emails ending in @company.com
Session Duration: 24 hours
```
**Production**:
```
Application: api.example.com
Policy:
Include: Emails ending in @company.com
Require: Groups - production-access
Session Duration: 12 hours
```
---
## Troubleshooting
### Problem: Infinite Redirect Loop
**Symptoms**:
- Browser keeps redirecting between app and Access
- Never able to login
**Causes**:
- Worker not validating JWT properly
- CORS issues blocking cookies
- Incorrect Access domain configuration
**Solutions**:
1. Check Worker validates `CF-Access-JWT-Assertion` header
2. Ensure CORS allows credentials
3. Verify `ACCESS_TEAM_DOMAIN` matches Access configuration
---
### Problem: "Access Denied"
**Symptoms**:
- User can login but gets "Access Denied" message
**Causes**:
- User doesn't meet policy requirements
- Policy misconfigured
- IdP groups not syncing
**Solutions**:
1. Check Access logs to see why denied
2. Verify user meets all policy criteria
3. Test policy with "Test policy" feature
4. Check IdP group membership
---
### Problem: Service Token Not Working
**Symptoms**:
- Service token returns 401
**Causes**:
- Service token not added to policy
- Wrong header names
- Token expired
**Solutions**:
1. Verify token is in policy's "Service Auth" section
2. Use correct headers: `CF-Access-Client-Id`, `CF-Access-Client-Secret`
3. Check token hasn't expired in dashboard
---
## Best Practices
### Security
1. **Use Identity Provider** - Better security than email OTP
2. **Require MFA** - Enable in IdP settings
3. **Short Session Duration** - 12-24 hours for sensitive apps
4. **Group-Based Access** - Use IdP groups, not individual emails
5. **Regular Audits** - Review Access logs monthly
### Performance
1. **Minimize Policies** - Fewer policies = faster evaluation
2. **Use Wildcards** - `*.example.com` instead of multiple apps
3. **Cache Friendly** - Access adds session cookies that cache well
### Maintenance
1. **Document Policies** - Note why each policy exists
2. **Review Access** - Quarterly review who has access
3. **Rotate Service Tokens** - Every 3-6 months
4. **Test After Changes** - Always test policy changes
5. **Separate Environments** - Different Access apps for dev/staging/prod
---
## Resources
- [Cloudflare Access Policies](https://developers.cloudflare.com/cloudflare-one/policies/access/)
- [Access Applications](https://developers.cloudflare.com/cloudflare-one/applications/)
- [Identity Providers](https://developers.cloudflare.com/cloudflare-one/identity/)
- [Access Logs](https://developers.cloudflare.com/cloudflare-one/insights/logs/)
---
**Last Updated**: 2025-10-28
**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 |