cloudflare-service-token-setup

What this skill does

# Service Token Setup Skill

Complete workflow for creating and managing Cloudflare Access service tokens for automated infrastructure verification and non-human access.

## Quick Start

Quick service token setup:

```bash
# 1. Create service token via Cloudflare dashboard
# Go to: https://one.dash.cloudflare.com → Access → Service Auth → Create Service Token
# Name: "Infrastructure Automation"
# Duration: 1 year

# 2. Add credentials to .env
echo "CF_SERVICE_TOKEN_CLIENT_ID=your-client-id.access" >> /home/dawiddutoit/projects/network/.env
echo "CF_SERVICE_TOKEN_CLIENT_SECRET=your-client-secret" >> /home/dawiddutoit/projects/network/.env

# 3. Test service token
source /home/dawiddutoit/projects/network/.env
curl -H "CF-Access-Client-Id: ${CF_SERVICE_TOKEN_CLIENT_ID}" \
     -H "CF-Access-Client-Secret: ${CF_SERVICE_TOKEN_CLIENT_SECRET}" \
     https://jaeger.temet.ai

# 4. Use helper script for testing
/home/dawiddutoit/projects/network/scripts/cf-service-token.sh test jaeger.temet.ai
```

## 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 Understanding Service Tokens vs OAuth
   - 3.2 Create Service Token via Dashboard
   - 3.3 Add Credentials to .env
   - 3.4 Test Service Token Access
   - 3.5 Use Helper Script for Verification
   - 3.6 Revoke or Rotate Service Token
   - 3.7 Monitor Service Token Usage
4. [Supporting Files](#4-supporting-files)
5. [Expected Outcomes](#5-expected-outcomes)
6. [Requirements](#6-requirements)
7. [Red Flags to Avoid](#7-red-flags-to-avoid)

## When to Use This Skill

**Explicit Triggers:**
- "Create service token"
- "Setup automation access"
- "Verify services without OAuth"
- "Automated monitoring"
- "Non-human access"

**Implicit Triggers:**
- Need to test services programmatically
- Setting up monitoring scripts
- CI/CD needs to verify deployments
- Want to share verification results with Claude
- Need to bypass Google OAuth for automation

**Debugging Triggers:**
- "How do I test services without browser?"
- "How to automate verification?"
- "What's the difference between service tokens and OAuth?"

## What This Skill Does

1. **Explains Tokens** - Clarifies service tokens vs Google OAuth use cases
2. **Creates Token** - Guides through Cloudflare dashboard token creation
3. **Stores Credentials** - Adds token to .env securely
4. **Tests Access** - Verifies token works for protected services
5. **Helper Script** - Shows how to use cf-service-token.sh for testing
6. **Revokes Token** - Shows how to revoke/rotate compromised tokens
7. **Monitors Usage** - Shows how to view token usage in Access logs

## Instructions

### 3.1 Understanding Service Tokens vs OAuth

**Service Tokens (Non-Human Access):**
- For automation, scripts, monitoring systems
- Bypasses Google OAuth requirement
- Works with curl, scripts, CI/CD
- Long-lived (months/years)
- No user session required

**Google OAuth (Human Access):**
- For humans accessing via web browser
- Requires Google account login
- Session-based (24 hours default)
- Multi-factor authentication support

**When to use each:**

| Use Case | Method |
|----------|--------|
| Automated health checks | Service Token |
| CI/CD deployment verification | Service Token |
| Monitoring scripts | Service Token |
| Sharing verification with Claude | Service Token |
| Human web browser access | Google OAuth |
| Interactive service use | Google OAuth |

**Key difference:** Service tokens **automatically bypass** all Cloudflare Access policies - no additional configuration needed.

### 3.2 Create Service Token via Dashboard

**Step 1: Navigate to Service Auth**

1. Go to: https://one.dash.cloudflare.com
2. Navigate to: **Access** → **Service Auth** → **Service Tokens**
3. Click: **Create Service Token**

**Step 2: Configure Token**

- **Name:** `Infrastructure Automation` (or descriptive name)
- **Duration:** 1 year (or as needed)
- **Recommended:** Use descriptive names like "CI/CD Pipeline" or "Health Monitoring"

**Step 3: Save Credentials**

After creation, Cloudflare shows:
- **Client ID:** `8f0eb3c52a7236fc952d9b11cd67b960.access`
- **Client Secret:** `63b34062dbca3405521196952ba4d155...` (long hex string)

⚠️ **IMPORTANT:** Client secret is shown **only once**. Copy it immediately.

**Step 4: Copy Credentials**

Copy both values - you'll add them to .env in the next step.

### 3.3 Add Credentials to .env

Add service token credentials to project .env file:

```bash
# Navigate to project directory
cd /home/dawiddutoit/projects/network

# Add credentials to .env
cat >> .env << 'EOF'

# Cloudflare Access Service Token (for automation)
CF_SERVICE_TOKEN_CLIENT_ID="your-client-id.access"
CF_SERVICE_TOKEN_CLIENT_SECRET="your-client-secret-here"
EOF
```

**Replace values** with actual credentials from dashboard.

**Verify credentials added:**

```bash
grep CF_SERVICE_TOKEN /home/dawiddutoit/projects/network/.env
```

Expected output:
```
CF_SERVICE_TOKEN_CLIENT_ID="8f0eb3c52a7236fc952d9b11cd67b960.access"
CF_SERVICE_TOKEN_CLIENT_SECRET="63b34062dbca3405521196952ba4d155de00f59e52d0fa23d0a7f3de66696c6c"
```

**Security note:** .env is already in .gitignore, so credentials won't be committed.

### 3.4 Test Service Token Access

**Test with curl directly:**

```bash
# Load environment variables
source /home/dawiddutoit/projects/network/.env

# Test single service
curl -I \
  -H "CF-Access-Client-Id: ${CF_SERVICE_TOKEN_CLIENT_ID}" \
  -H "CF-Access-Client-Secret: ${CF_SERVICE_TOKEN_CLIENT_SECRET}" \
  https://jaeger.temet.ai
```

**Expected result:**
```
HTTP/2 200
server: Caddy
...
```

**Test multiple services:**

```bash
source /home/dawiddutoit/projects/network/.env

for service in pihole jaeger langfuse ha sprinkler code webhook; do
  echo "Testing ${service}.temet.ai..."
  status=$(curl -s -o /dev/null -w "%{http_code}" \
    -H "CF-Access-Client-Id: ${CF_SERVICE_TOKEN_CLIENT_ID}" \
    -H "CF-Access-Client-Secret: ${CF_SERVICE_TOKEN_CLIENT_SECRET}" \
    "https://${service}.temet.ai")

  echo "  Status: HTTP $status"
  echo
done
```

**Success indicators:**
- HTTP 200: Service accessible and working
- HTTP 502: Service token working but backend down
- HTTP 403: Service token invalid or expired

### 3.5 Use Helper Script for Verification

The project includes a helper script for easier testing:

**Test single service:**

```bash
/home/dawiddutoit/projects/network/scripts/cf-service-token.sh test jaeger.temet.ai
```

Expected output:
```
Testing jaeger.temet.ai...
✓ Service token accepted (HTTP 200)
```

**Test with full response:**

```bash
/home/dawiddutoit/projects/network/scripts/cf-service-token.sh test jaeger.temet.ai --verbose
```

Shows complete HTTP response and headers.

**List all service tokens:**

```bash
/home/dawiddutoit/projects/network/scripts/cf-service-token.sh list
```

Shows all service tokens configured in your Cloudflare account.

**Test all configured services:**

```bash
for domain in pihole jaeger langfuse ha sprinkler code webhook; do
  /home/dawiddutoit/projects/network/scripts/cf-service-token.sh test ${domain}.temet.ai
done
```

### 3.6 Revoke or Rotate Service Token

**When to revoke:**
- Token compromised or exposed
- Token no longer needed
- Regular security rotation (annually recommended)

**Revoke via Dashboard:**

1. Go to: https://one.dash.cloudflare.com
2. Navigate to: **Access** → **Service Auth** → **Service Tokens**
3. Find token by name: "Infrastructure Automation"
4. Click trash icon → **Delete**
5. Confirm deletion

**Revoke via Script:**

```bash
# List tokens to get ID
/home/dawiddutoit/projects/network/scripts/cf-service-token.sh list

# Delete by ID
/home/dawiddutoit/projects/network/scripts/cf-service-token.sh delete <token-id>
```

**After revocation:**

1. Remove credentials from .env:
```bash
nano /home/dawiddutoit/projects/network/.env
# Delete CF_SERVICE_TOKEN_CLIENT_ID and CF_SERVICE_TOKEN_CLIENT_SECRET lines
```

2.