cloudflare-access-setup

What this skill does

# Cloudflare Access Setup Skill

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

## Quick Start

To set up Cloudflare Access authentication:

```bash
# 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](#1-when-to-use-this-skill)
2. [What This Skill Does](#2-what-this-skill-does)
3. [Instructions](#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](#4-supporting-files)
5. [Expected Outcomes](#5-expected-outcomes)
6. [Integration Points](#6-integration-points)
7. [Requirements](#7-requirements)
8. [Red Flags to Avoid](#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:

```bash
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., [email protected])

**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**
```bash
GOOGLE_OAUTH_CLIENT_ID=<client-id>.apps.googleusercontent.com
GOOGLE_OAUTH_CLIENT_SECRET=<client-secret>
[email protected]
```

### 3.3 Run Automated Setup

Execute the setup script:

```bash
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:

```bash
./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):**
```bash
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:**
```bash
echo "Access Logs: https://one.dash.cloudflare.com"
echo "Navigate to: Logs -> Access"
```

## Supporting Files

| File | Purpose |
|------|---------|
| `references/reference.md` | Complete API reference, troubleshooting guide, advanced configuration |
| `examples/examples.md` | Common scenarios and configuration examples |

## 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