Back to Details

cloudflare-access-setup

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Cloudflare Access Setup Skill

Cloudflare Access 配置技能

Configure Cloudflare Access with Google OAuth to protect services with secure authentication.
配置基于Google OAuth的Cloudflare Access，为服务提供安全认证保护。

Quick Start

快速开始

To set up Cloudflare Access authentication:
bash
undefined
要设置Cloudflare Access认证：
bash
undefined

1. Verify prerequisites

1. Verify prerequisites

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

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

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

3. Run automated setup

3. Run automated setup

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

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

配置完成后，访问https://pihole.temet.ai进行测试，你应该会看到Google登录界面。

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
  1. 何时使用此技能
  2. 此技能的功能
  3. 操作说明
    • 3.1 检查前置条件
    • 3.2 配置Google OAuth（如需）
    • 3.3 运行自动化配置
    • 3.4 验证应用是否创建成功
    • 3.5 测试认证流程
    • 3.6 访问监控
  4. 支持文件
  5. 预期结果
  6. 集成点
  7. 要求
  8. 注意事项

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"
明确触发场景：
  • "Set up Cloudflare Access"
  • "Configure Google OAuth for access"
  • "Protect my services with authentication"
  • "Enable remote access authentication"
  • "Run cf-access-setup"
隐含触发场景：
  • 配置需要保护的新服务
  • 首次基础设施搭建
  • 向domains.toml添加新服务后
调试触发场景：
  • "访问服务时显示Access Denied"
  • "Google登录无法正常工作"
  • "无法远程访问pihole"
  • "OAuth重定向错误"
  • "会话过期错误"

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
  1. 检查前置条件 - 检查.env文件中是否存在OAuth凭据
  2. 指导OAuth配置 - 若缺少凭据，提供Google Console的配置步骤
  3. 运行自动化脚本 - 执行cf-access-setup.sh完成所有配置
  4. 创建应用 - 为所有受保护服务创建Access应用
  5. 配置策略 - 为授权用户创建允许访问的策略
  6. 测试认证 - 验证Google登录流程是否正常
  7. 提供监控功能 - 显示访问日志的URL以进行审计追踪

Instructions

操作说明

3.1 Verify Prerequisites

3.1 检查前置条件

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.
检查所需的环境变量：
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"
若有任何变量缺失，请继续3.2步骤；否则跳过至3.3步骤。

3.2 Configure Google OAuth (if needed)

3.2 配置Google OAuth（如需）

Guide the user through Google Console setup:
Step 1: Access Google Cloud Console
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>
ACCESS_ALLOWED_EMAIL=your-email@domain.com
引导用户完成Google Console的配置步骤：
步骤1：访问Google Cloud Console
步骤2：创建OAuth同意屏幕（首次配置时）
  • 用户类型：Internal（仅限组织内部）或External（适用于个人Gmail账号）
  • 应用名称："Cloudflare Access - Home Network"
  • 支持邮箱：你的邮箱地址
  • 开发者联系信息：你的邮箱地址
步骤3：创建OAuth Client ID
  • 点击「Create Credentials」→「OAuth client ID」
  • 应用类型：Web application
  • 名称："Cloudflare Access - Home Network"
  • 授权重定向URI：
    https://temetai.cloudflareaccess.com/cdn-cgi/access/callback
  • 点击「Create」
步骤4：更新.env文件
bash
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

3.3 运行自动化配置

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)
执行配置脚本：
bash
cd /home/dawiddutoit/projects/network && ./scripts/cf-access-setup.sh setup
该脚本将完成以下操作：
  1. 验证所有前置条件
  2. 配置Google OAuth身份提供商
  3. 为受保护服务创建Access应用
  4. 为授权用户创建允许访问的策略
  5. 为webhook创建绕过认证的策略
受保护的服务：
  • pihole.temet.ai
  • jaeger.temet.ai
  • langfuse.temet.ai
  • sprinkler.temet.ai
  • ha.temet.ai
  • temet.ai（根域名）
绕过认证的服务：
  • webhook.temet.ai（无需认证，供GitHub使用）

3.4 Verify Applications Created

3.4 验证应用是否创建成功

List all configured applications:
bash
./scripts/cf-access-setup.sh list
Expected output shows all services with App IDs and session durations.
列出所有已配置的应用：
bash
./scripts/cf-access-setup.sh list
预期输出应显示所有服务的App ID和会话时长。

3.5 Test Authentication Flow

3.5 测试认证流程

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
手动测试：
  1. 打开浏览器的隐身/隐私模式
  2. 访问：https://pihole.temet.ai
  3. 预期结果：重定向至Cloudflare Access登录页面
  4. 点击「Google」进行认证
  5. 使用授权邮箱登录
  6. 认证完成后：可访问Pi-hole管理界面
CLI测试（webhook绕过认证）：
bash
curl -I https://webhook.temet.ai/hooks/health

Should return HTTP response without authentication

Should return HTTP response without authentication


**Verify unauthorized access blocked:**
- Try accessing with different Google account
- Should see "Access Denied" message

**验证未授权访问被拦截：**
- 使用其他Google账号尝试访问
- 应显示「Access Denied」提示

3.6 Access Monitoring

3.6 访问监控

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"
访问日志控制台： https://one.dash.cloudflare.com → Logs → Access
可查看的信息：
  • 谁访问了哪个服务
  • 访问尝试的时间戳
  • 允许/拒绝的决策
  • 源IP地址
快速查看控制台URL的命令：
bash
echo "Access Logs: https://one.dash.cloudflare.com"
echo "Navigate to: Logs -> Access"

Supporting Files

支持文件

FilePurpose
references/reference.md
Complete API reference, troubleshooting guide, advanced configuration
examples/examples.md
Common scenarios and configuration examples
文件用途
references/reference.md
完整的API参考、故障排查指南、高级配置说明
examples/examples.md
常见场景和配置示例

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
成功：
  • Google OAuth身份提供商配置完成
  • 为所有受保护服务创建了Access应用
  • 为授权邮箱设置了允许访问的策略
  • 为webhook配置了绕过认证的策略
  • 认证流程正常工作（Google登录重定向功能正常）
  • 可在Cloudflare控制台查看访问日志
部分成功：
  • 应用已创建但OAuth无法正常工作（检查重定向URI）
  • 部分服务未配置（重新运行脚本 - 脚本支持幂等操作）
失败标识：
  • "Missing GOOGLE_OAUTH_CLIENT_ID" → 先配置.env文件
  • "Missing CLOUDFLARE_ACCESS_API_TOKEN" → 创建API令牌
  • API错误 → 检查令牌权限
  • 重定向循环 → 清除Cookie后重试

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
Cloudflare Tunnel：
  • Access可与现有的隧道配置配合使用
  • 隧道负责路由流量，Access提供认证层
domains.toml：
  • 标记为
    require_auth = true
    的服务应创建Access应用
  • 添加新服务后运行：
    ./scripts/cf-access-setup.sh setup
manage-domains.sh：
  • 通过sync-cloudflare-access.py自动同步Access应用
  • 使用
    ./scripts/manage-domains.sh apply
    完成全量同步

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)
环境变量（在.env文件中）：
  • GOOGLE_OAUTH_CLIENT_ID - 来自Google Console
  • GOOGLE_OAUTH_CLIENT_SECRET - 来自Google Console
  • ACCESS_ALLOWED_EMAIL - 授权邮箱地址
  • CLOUDFLARE_ACCESS_API_TOKEN - 拥有Zero Trust权限的API令牌
  • CLOUDFLARE_ACCOUNT_ID - Cloudflare账号ID
  • CLOUDFLARE_TEAM_NAME - Zero Trust团队名称
API令牌权限：
  • Account → Zero Trust → Edit
  • Account → Access: Apps and Policies → Edit
  • Account → Access: Organizations, Identity Providers, and Groups → Edit
工具：
  • Bash（用于运行配置脚本）
  • Read（用于检查.env文件和脚本输出）

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
  • 不要在未验证OAuth凭据存在的情况下运行配置脚本
  • 不要使用错误的重定向URI（必须完全匹配）
  • 若使用个人Gmail账号，不要将同意屏幕设置为「Internal」
  • 不要删除webhook的绕过认证策略（会破坏GitHub部署）
  • 不要忘记在隐身模式下测试（缓存的会话会导致混淆）
  • 不要跳过验证应用是否创建成功的步骤
  • 不要忽略「Access Denied」错误（检查授权邮箱）
  • 不要在日志或输出中暴露API令牌

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
  • 配置脚本支持幂等操作 - 可安全多次运行
  • OAuth重定向URI必须完全为：
    https://temetai.cloudflareaccess.com/cdn-cgi/access/callback
  • 默认会话时长为24小时
  • 可授权多个邮箱：
    ACCESS_ALLOWED_EMAIL="email1@domain.com,email2@domain.com"
  • 本地网络访问可绕过Cloudflare Access（仅远程访问需要认证）
  • Pi-hole可能会阻止OAuth所需的Google域名 - 若出现问题请将其加入白名单