name: cloudflare-access-setup description: | Configures Cloudflare Access authentication with Google OAuth for protected services. Use when you need to set up authentication, configure Google OAuth, protect services with Cloudflare Access, enable remote access security, or troubleshoot Access issues. Triggers on "setup cloudflare access", "configure access authentication", "enable google oauth", "protect services", "fix access denied", "add users to access", or "why can't I login remotely". Works with cf-access-setup.sh, .env OAuth credentials, and Cloudflare Zero Trust dashboard. allowed-tools:

• Read
• Bash
• Grep
• Glob

Cloudflare Access Setup Skill

Configure Cloudflare Access with Google OAuth to protect services with secure authentication.

Quick Start

To set up Cloudflare Access authentication:

# 1. Verify prerequisites
./scripts/cf-access-setup.sh list

# 2. If OAuth credentials missing, configure .env first (see Section 3.2)

# 3. Run automated setup
./scripts/cf-access-setup.sh setup

After setup, test by visiting https://pihole.temet.ai - you should see Google login.

Table of Contents

1. When to Use This Skill
2. What This Skill Does
3. Instructions
   • 3.1 Verify Prerequisites
   • 3.2 Configure Google OAuth (if needed)
   • 3.3 Run Automated Setup
   • 3.4 Verify Applications Created
   • 3.5 Test Authentication Flow
   • 3.6 Access Monitoring
4. Supporting Files
5. Expected Outcomes
6. Integration Points
7. Requirements
8. Red Flags to Avoid

When to Use This Skill

Explicit Triggers:

• "Set up Cloudflare Access"
• "Configure Google OAuth for access"
• "Protect my services with authentication"
• "Enable remote access authentication"
• "Run cf-access-setup"

Implicit Triggers:

• Setting up a new service that needs protection
• First-time infrastructure setup
• After adding new services to domains.toml

Debugging Triggers:

• "I get Access Denied when accessing services"
• "Google login isn't working"
• "Can't access pihole remotely"
• "OAuth redirect error"
• "Session expired errors"

What This Skill Does

1. Verifies Prerequisites - Checks OAuth credentials exist in .env
2. Guides OAuth Setup - Provides Google Console instructions if credentials missing
3. Runs Automation - Executes cf-access-setup.sh to configure everything
4. Creates Applications - Sets up Access apps for all protected services
5. Configures Policies - Creates allow policies for authorized users
6. Tests Authentication - Verifies Google login flow works
7. Provides Monitoring - Shows access logs URL for audit trail

Instructions

3.1 Verify Prerequisites

Check required environment variables:

cd /home/dawiddutoit/projects/network && source .env && echo "Checking OAuth credentials..."
[ -n "$GOOGLE_OAUTH_CLIENT_ID" ] && echo "GOOGLE_OAUTH_CLIENT_ID: Set" || echo "GOOGLE_OAUTH_CLIENT_ID: MISSING"
[ -n "$GOOGLE_OAUTH_CLIENT_SECRET" ] && echo "GOOGLE_OAUTH_CLIENT_SECRET: Set" || echo "GOOGLE_OAUTH_CLIENT_SECRET: MISSING"
[ -n "$ACCESS_ALLOWED_EMAIL" ] && echo "ACCESS_ALLOWED_EMAIL: $ACCESS_ALLOWED_EMAIL" || echo "ACCESS_ALLOWED_EMAIL: MISSING"
[ -n "$CLOUDFLARE_ACCESS_API_TOKEN" ] && echo "CLOUDFLARE_ACCESS_API_TOKEN: Set" || echo "CLOUDFLARE_ACCESS_API_TOKEN: MISSING"

If any are missing, proceed to 3.2. Otherwise, skip to 3.3.

3.2 Configure Google OAuth (if needed)

Guide the user through Google Console setup:

Step 1: Access Google Cloud Console

• URL: https://console.cloud.google.com/apis/credentials
• Sign in with the Google Workspace account (e.g., dawiddutoit@temet.ai)

Step 2: Create OAuth Consent Screen (if first time)

• User Type: Internal (for organization only) or External (for personal Gmail)
• App name: "Cloudflare Access - Home Network"
• Support email: Your email
• Developer contact: Your email

Step 3: Create OAuth Client ID

• Click "Create Credentials" -> "OAuth client ID"
• Application type: Web application
• Name: "Cloudflare Access - Home Network"
• Authorized redirect URI: https://temetai.cloudflareaccess.com/cdn-cgi/access/callback
• Click "Create"

Step 4: Update .env

GOOGLE_OAUTH_CLIENT_ID=<client-id>.apps.googleusercontent.com
GOOGLE_OAUTH_CLIENT_SECRET=<client-secret>
ACCESS_ALLOWED_EMAIL=your-email@domain.com

3.3 Run Automated Setup

Execute the setup script:

cd /home/dawiddutoit/projects/network && ./scripts/cf-access-setup.sh setup

The script will:

1. Verify all prerequisites
2. Configure Google OAuth identity provider
3. Create Access applications for protected services
4. Create allow policies for authorized users
5. Create bypass policy for webhook

Protected Services:

• pihole.temet.ai
• jaeger.temet.ai
• langfuse.temet.ai
• sprinkler.temet.ai
• ha.temet.ai
• temet.ai (root)

Bypass Service:

• webhook.temet.ai (no auth for GitHub)

3.4 Verify Applications Created

List all configured applications:

./scripts/cf-access-setup.sh list

Expected output shows all services with App IDs and session durations.

3.5 Test Authentication Flow

Manual Test:

1. Open incognito/private browser window
2. Navigate to: https://pihole.temet.ai
3. Expected: Redirect to Cloudflare Access login page
4. Click "Google" to authenticate
5. Sign in with authorized email
6. After authentication: Access to Pi-hole admin

CLI Test (webhook bypass):

curl -I https://webhook.temet.ai/hooks/health
# Should return HTTP response without authentication

Verify unauthorized access blocked:

• Try accessing with different Google account
• Should see "Access Denied" message

3.6 Access Monitoring

Access Logs Dashboard: https://one.dash.cloudflare.com -> Logs -> Access

View information:

• Who accessed which service
• Timestamp of access attempts
• Allow/deny decisions
• Source IP addresses

Quick command to show dashboard URL:

echo "Access Logs: https://one.dash.cloudflare.com"
echo "Navigate to: Logs -> Access"

Supporting Files

Expected Outcomes

Success:

• Google OAuth identity provider configured
• Access applications created for all protected services
• Allow policies set for authorized email(s)
• Bypass policy configured for webhook
• Authentication flow working (Google login redirects)
• Access logs visible in Cloudflare dashboard

Partial Success:

• Applications created but OAuth not working (check redirect URI)
• Some services missing (re-run setup - idempotent)

Failure Indicators:

• "Missing GOOGLE_OAUTH_CLIENT_ID" -> Configure .env first
• "Missing CLOUDFLARE_ACCESS_API_TOKEN" -> Create API token
• API errors -> Check token permissions
• Redirect loop -> Clear cookies and retry

Integration Points

Cloudflare Tunnel:

• Access works with existing tunnel configuration
• Tunnel routes traffic, Access provides authentication layer

domains.toml:

• Services with require_auth = true should have Access applications
• Run after adding new services: ./scripts/cf-access-setup.sh setup

manage-domains.sh:

• Automatically syncs Access applications via sync-cloudflare-access.py
• Use ./scripts/manage-domains.sh apply for full sync

Requirements

Environment Variables (in .env):

• GOOGLE_OAUTH_CLIENT_ID - From Google Console
• GOOGLE_OAUTH_CLIENT_SECRET - From Google Console
• ACCESS_ALLOWED_EMAIL - Email(s) to authorize
• CLOUDFLARE_ACCESS_API_TOKEN - API token with Zero Trust permissions
• CLOUDFLARE_ACCOUNT_ID - Cloudflare account ID
• CLOUDFLARE_TEAM_NAME - Zero Trust team name

API Token Permissions:

• Account -> Zero Trust -> Edit
• Account -> Access: Apps and Policies -> Edit
• Account -> Access: Organizations, Identity Providers, and Groups -> Edit

Tools:

• Bash (for running setup script)
• Read (for checking .env and script output)

Red Flags to Avoid

• Do not run setup without verifying OAuth credentials exist
• Do not use wrong redirect URI (must match exactly)
• Do not set consent screen to "Internal" if using personal Gmail accounts
• Do not delete webhook bypass policy (breaks GitHub deployments)
• Do not forget to test in incognito (cached sessions cause confusion)
• Do not skip verifying applications were created
• Do not ignore "Access Denied" errors (check allowed emails)
• Do not expose API tokens in logs or output

Notes

• Setup script is idempotent - safe to run multiple times
• OAuth redirect URI must be exactly: https://temetai.cloudflareaccess.com/cdn-cgi/access/callback
• Session duration is 24 hours by default
• Multiple emails can be authorized: ACCESS_ALLOWED_EMAIL="email1@domain.com,email2@domain.com"
• Local network access bypasses Cloudflare Access (only remote access requires auth)
• Pi-hole may block Google domains needed for OAuth - whitelist if issues occur