Back to Details

cloudflare-access-troubleshoot

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Troubleshoot Cloudflare Access Authentication Skill

Cloudflare Access认证问题排查Skill

Systematic diagnosis and resolution of Cloudflare Access authentication issues including Google OAuth errors and access policy problems.
系统诊断并解决Cloudflare Access认证问题，包括Google OAuth错误和访问策略问题。

Quick Start

快速开始

Quick diagnostics for Access issues:
bash
undefined
Access问题快速诊断：
bash
undefined

Check allowed emails configured

检查已配置的允许邮箱

grep ACCESS_ALLOWED_EMAIL /home/dawiddutoit/projects/network/.env
grep ACCESS_ALLOWED_EMAIL /home/dawiddutoit/projects/network/.env

Verify Google OAuth credentials set

验证Google OAuth凭证已设置

grep GOOGLE_OAUTH /home/dawiddutoit/projects/network/.env
grep GOOGLE_OAUTH /home/dawiddutoit/projects/network/.env

Check if Google domains are whitelisted in Pi-hole

检查Google域名是否在Pi-hole中被白名单放行

docker exec pihole pihole -q accounts.google.com docker exec pihole pihole -q login.google.com
docker exec pihole pihole -q accounts.google.com docker exec pihole pihole -q login.google.com

Apply Google whitelist (fixes CookieMismatch)

应用Google白名单（修复CookieMismatch错误）

/home/dawiddutoit/projects/network/scripts/setup-google-whitelist.sh
undefined
/home/dawiddutoit/projects/network/scripts/setup-google-whitelist.sh
undefined

Table of Contents

目录

  1. When to Use This Skill
  2. What This Skill Does
  3. Instructions
    • 3.1 Verify Google OAuth Configuration
    • 3.2 Check Allowed Email Configuration
    • 3.3 Verify Pi-hole Whitelist
    • 3.4 Test Google OAuth Consent Screen
    • 3.5 Check Access Policy in Dashboard
    • 3.6 Verify Redirect URI Configuration
    • 3.7 Apply Fix
  4. Supporting Files
  5. Expected Outcomes
  6. Requirements
  7. Red Flags to Avoid
  1. 适用场景
  2. 功能说明
  3. 操作步骤
    • 3.1 验证Google OAuth配置
    • 3.2 检查允许邮箱配置
    • 3.3 验证Pi-hole白名单
    • 3.4 测试Google OAuth授权界面
    • 3.5 检查控制台中的访问策略
    • 3.6 验证重定向URI配置
    • 3.7 应用修复方案
  4. 支持文件
  5. 预期结果
  6. 前置要求
  7. 注意事项

When to Use This Skill

适用场景

Explicit Triggers:
  • "Access denied"
  • "OAuth not working"
  • "Login loop"
  • "CookieMismatch error"
  • "Can only be used within organization"
  • "Fix Cloudflare Access"
Implicit Triggers:
  • Google login succeeds but then shows "Access Denied"
  • Redirected back to login after successful Google authentication
  • Browser stuck in authentication loop
  • "This app is not verified" but can't proceed
Debugging Triggers:
  • "Why am I denied after login?"
  • "Why is authentication not working?"
  • "How to fix Google OAuth errors?"
明确触发条件：
  • "访问被拒绝"
  • "OAuth无法工作"
  • "登录循环"
  • "CookieMismatch错误"
  • "仅可在其组织内使用"
  • "修复Cloudflare Access"
隐含触发场景：
  • Google登录成功后显示"访问被拒绝"
  • Google认证成功后被重定向回登录页
  • 浏览器陷入认证循环
  • 显示"此应用未验证"但无法继续
调试触发问题：
  • "为什么登录后被拒绝访问？"
  • "为什么认证无法工作？"
  • "如何修复Google OAuth错误？"

What This Skill Does

功能说明

  1. Checks OAuth Config - Verifies Google OAuth credentials are set
  2. Validates Emails - Confirms allowed emails are configured
  3. Checks Whitelist - Verifies Pi-hole not blocking Google domains
  4. Tests Consent - Validates Google OAuth consent screen configuration
  5. Reviews Policy - Checks Access policy in Cloudflare dashboard
  6. Verifies Redirect - Confirms redirect URI matches team name
  7. Provides Fix - Gives specific commands to resolve the issue
  1. 检查OAuth配置 - 验证Google OAuth凭证已设置
  2. 验证邮箱配置 - 确认允许邮箱已正确配置
  3. 检查白名单 - 验证Pi-hole未拦截Google域名
  4. 测试授权界面 - 验证Google OAuth授权界面配置
  5. 检查访问策略 - 在Cloudflare控制台中检查Access策略
  6. 验证重定向URI - 确认重定向URI与团队名称匹配
  7. 提供修复方案 - 给出解决问题的具体命令

Instructions

操作步骤

3.1 Verify Google OAuth Configuration

3.1 验证Google OAuth配置

Check OAuth credentials are set:
bash
undefined
检查OAuth凭证是否已设置：
bash
undefined

Check OAuth Client ID

检查OAuth客户端ID

grep GOOGLE_OAUTH_CLIENT_ID /home/dawiddutoit/projects/network/.env
grep GOOGLE_OAUTH_CLIENT_ID /home/dawiddutoit/projects/network/.env

Check OAuth Client Secret

检查OAuth客户端密钥

grep GOOGLE_OAUTH_CLIENT_SECRET /home/dawiddutoit/projects/network/.env

Expected: Both should show values (not empty)

**If missing:**

1. Go to Google Cloud Console: https://console.cloud.google.com/apis/credentials
2. Create OAuth 2.0 Client ID if needed:
   - Application type: Web application
   - Authorized redirect URIs: `https://<TEAM_NAME>.cloudflareaccess.com/cdn-cgi/access/callback`
3. Copy Client ID and Client Secret
4. Add to .env:
```bash
GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"
  1. Re-run Cloudflare Access setup:
bash
/home/dawiddutoit/projects/network/scripts/cf-access-setup.sh setup
grep GOOGLE_OAUTH_CLIENT_SECRET /home/dawiddutoit/projects/network/.env

预期结果：两者均显示有效值（非空）

**如果缺失：**

1. 访问Google Cloud Console：https://console.cloud.google.com/apis/credentials
2. 若需要，创建OAuth 2.0客户端ID：
   - 应用类型：Web应用
   - 授权重定向URI：`https://<TEAM_NAME>.cloudflareaccess.com/cdn-cgi/access/callback`
3. 复制客户端ID和客户端密钥
4. 添加到.env文件：
```bash
GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"
  1. 重新运行Cloudflare Access设置：
bash
/home/dawiddutoit/projects/network/scripts/cf-access-setup.sh setup

3.2 Check Allowed Email Configuration

3.2 检查允许邮箱配置

Verify emails are configured:
bash
grep ACCESS_ALLOWED_EMAIL /home/dawiddutoit/projects/network/.env
Expected: Shows comma-separated list of allowed email addresses
If missing or incorrect:
  1. Edit .env:
bash
nano /home/dawiddutoit/projects/network/.env
  1. Add or update:
bash
ACCESS_ALLOWED_EMAIL="your.email@gmail.com,other@gmail.com"
  1. Update Access policies:
bash
/home/dawiddutoit/projects/network/scripts/update-access-emails.sh
Common mistake: Email in policy doesn't match Google account used for login.
验证邮箱已配置：
bash
grep ACCESS_ALLOWED_EMAIL /home/dawiddutoit/projects/network/.env
预期结果：显示逗号分隔的允许邮箱列表
如果缺失或不正确：
  1. 编辑.env文件：
bash
nano /home/dawiddutoit/projects/network/.env
  1. 添加或更新：
bash
ACCESS_ALLOWED_EMAIL="your.email@gmail.com,other@gmail.com"
  1. 更新Access策略：
bash
/home/dawiddutoit/projects/network/scripts/update-access-emails.sh
常见错误： 策略中的邮箱与登录使用的Google账户不匹配。

3.3 Verify Pi-hole Whitelist

3.3 验证Pi-hole白名单

Pi-hole must allow Google domains for OAuth to work:
Check if Google domains are whitelisted:
bash
undefined
Pi-hole必须允许Google域名才能使OAuth正常工作：
检查Google域名是否被白名单放行：
bash
undefined

Check essential auth domains

检查核心认证域名

docker exec pihole pihole -q accounts.google.com docker exec pihole pihole -q login.google.com docker exec pihole pihole -q id.google.com docker exec pihole pihole -q doubleclick.net

Expected: Each shows "Exact whitelist match"

**If blocked or not whitelisted:**

Apply Google/YouTube whitelist (automatic via docker-compose.yml pihole-init service):
```bash
/home/dawiddutoit/projects/network/scripts/setup-google-whitelist.sh
Whitelisted domains include:
  • Authentication: 
    accounts.google.com
    , 
    login.google.com
    , 
    id.google.com
  • Cookie sync: 
    doubleclick.net
    , 
    google-analytics.com
    , 
    googlesyndication.com
  • YouTube: 
    youtube.com
    , 
    googlevideo.com
    , 
    ytimg.com
  • OAuth/API: 
    googleapis.com
    , 
    gstatic.com
    , 
    googleusercontent.com
After whitelisting:
  1. Clear browser cache and cookies for Google domains
  2. Flush DNS cache on client device
  3. Restart browser completely
  4. Try authentication again
docker exec pihole pihole -q accounts.google.com docker exec pihole pihole -q login.google.com docker exec pihole pihole -q id.google.com docker exec pihole pihole -q doubleclick.net

预期结果：每个域名均显示"Exact whitelist match"

**如果被拦截或未被白名单放行：**

应用Google/YouTube白名单（通过docker-compose.yml中的pihole-init服务自动执行）：
```bash
/home/dawiddutoit/projects/network/scripts/setup-google-whitelist.sh
白名单包含的域名：
  • 认证类：
    accounts.google.com
    , 
    login.google.com
    , 
    id.google.com
  • Cookie同步类：
    doubleclick.net
    , 
    google-analytics.com
    , 
    googlesyndication.com
  • YouTube类：
    youtube.com
    , 
    googlevideo.com
    , 
    ytimg.com
  • OAuth/API类：
    googleapis.com
    , 
    gstatic.com
    , 
    googleusercontent.com
白名单配置后：
  1. 清除浏览器中Google域名的缓存和Cookie
  2. 刷新客户端设备的DNS缓存
  3. 完全重启浏览器
  4. 再次尝试认证

3.4 Test Google OAuth Consent Screen

3.4 测试Google OAuth授权界面

Verify OAuth consent screen configuration:
  1. Go to: https://console.cloud.google.com/apis/credentials/consent
  2. Check "Publishing status"
Common issue: "Can only be used within its organization"
Cause: OAuth consent screen set to "Internal" but using personal Gmail account
Fix:
  1. Click "Edit App"
  2. Change "User Type" from "Internal" to "External"
  3. Save and continue through wizard
  4. Status should show "In production" or "Testing"
If using External + Testing mode:
  • Add test users in "Test users" section
  • Must include all ACCESS_ALLOWED_EMAIL addresses
验证OAuth授权界面配置：
  1. 访问：https://console.cloud.google.com/apis/credentials/consent
  2. 检查"发布状态"
常见问题："仅可在其组织内使用"
原因： OAuth授权界面设置为"内部"但使用个人Gmail账户
修复方案：
  1. 点击"编辑应用"
  2. 将"用户类型"从"内部"更改为"外部"
  3. 保存并完成向导流程
  4. 状态应显示为"已发布"或"测试中"
如果使用外部+测试模式：
  • 在"测试用户"部分添加测试用户
  • 必须包含所有ACCESS_ALLOWED_EMAIL中的地址

3.5 Check Access Policy in Dashboard

3.5 检查控制台中的访问策略

Verify policy in Cloudflare Zero Trust:
  1. Go to: https://one.dash.cloudflare.com
  2. Navigate to: Access → Applications
  3. Find your application (e.g., "Pi-hole Access")
  4. Click "Edit" → "Policies"
Verify policy settings:
  • Action: "Allow"
  • Include rule: "Emails" with your email addresses
  • Or: "Emails ending in" with your domain
Common issue: Email in policy doesn't match exactly
Example:
  • Policy has: 
    john.doe@gmail.com
  • Login uses: 
    johndoe@gmail.com
  • Result: Access denied (email mismatch)
Fix: Update policy to use correct email addresses:
bash
/home/dawiddutoit/projects/network/scripts/update-access-emails.sh
在Cloudflare Zero Trust中验证策略：
  1. 访问：https://one.dash.cloudflare.com
  2. 导航至：Access → 应用
  3. 找到你的应用（例如："Pi-hole Access"）
  4. 点击"编辑" → "策略"
验证策略设置：
  • 操作："允许"
  • 包含规则："邮箱"并填写你的邮箱地址
  • 或："邮箱后缀"并填写你的域名
常见问题： 策略中的邮箱与登录邮箱不完全匹配
示例：
  • 策略中设置：
    john.doe@gmail.com
  • 登录使用：
    johndoe@gmail.com
  • 结果：访问被拒绝（邮箱不匹配）
修复方案： 更新策略以使用正确的邮箱地址：
bash
/home/dawiddutoit/projects/network/scripts/update-access-emails.sh

3.6 Verify Redirect URI Configuration

3.6 验证重定向URI配置

OAuth redirect URI must match Cloudflare team name:
Check team name:
bash
grep CLOUDFLARE_TEAM_NAME /home/dawiddutoit/projects/network/.env
Verify redirect URI in Google Console:
  1. Go to: https://console.cloud.google.com/apis/credentials
  2. Click your OAuth 2.0 Client ID
  3. Check "Authorized redirect URIs"
Expected:
https://<TEAM_NAME>.cloudflareaccess.com/cdn-cgi/access/callback
If mismatch:
  1. Update redirect URI in Google Console to match team name
  2. Or re-run Access setup to sync:
bash
/home/dawiddutoit/projects/network/scripts/cf-access-setup.sh setup
OAuth重定向URI必须与Cloudflare团队名称匹配：
检查团队名称：
bash
grep CLOUDFLARE_TEAM_NAME /home/dawiddutoit/projects/network/.env
在Google Console中验证重定向URI：
  1. 访问：https://console.cloud.google.com/apis/credentials
  2. 点击你的OAuth 2.0客户端ID
  3. 检查"授权重定向URI"
预期结果：
https://<TEAM_NAME>.cloudflareaccess.com/cdn-cgi/access/callback
如果不匹配：
  1. 在Google Console中更新重定向URI以匹配团队名称
  2. 或重新运行设置脚本进行同步：
bash
/home/dawiddutoit/projects/network/scripts/cf-access-setup.sh setup

3.7 Apply Fix

3.7 应用修复方案

Fix A: Access Denied After Login
Symptoms: Google login succeeds, then immediately shows "Access Denied"
Causes:
  • Email not in ACCESS_ALLOWED_EMAIL
  • Email in policy doesn't match login email
Fix:
bash
undefined
修复方案A：登录后访问被拒绝
症状： Google登录成功后立即显示"访问被拒绝"
原因：
  • 邮箱未在ACCESS_ALLOWED_EMAIL中
  • 策略中的邮箱与登录邮箱不匹配
修复步骤：
bash
undefined

1. Verify email configuration

1. 验证邮箱配置

grep ACCESS_ALLOWED_EMAIL /home/dawiddutoit/projects/network/.env
grep ACCESS_ALLOWED_EMAIL /home/dawiddutoit/projects/network/.env

2. Update if needed

2. 如有需要，更新配置

nano /home/dawiddutoit/projects/network/.env
nano /home/dawiddutoit/projects/network/.env

Add: ACCESS_ALLOWED_EMAIL="correct.email@gmail.com"

添加：ACCESS_ALLOWED_EMAIL="correct.email@gmail.com"

3. Update Access policies

3. 更新Access策略

/home/dawiddutoit/projects/network/scripts/update-access-emails.sh
/home/dawiddutoit/projects/network/scripts/update-access-emails.sh

4. Clear browser cookies

4. 清除浏览器Cookie

Browser → Settings → Privacy → Clear browsing data → Cookies (*.cloudflareaccess.com)

浏览器 → 设置 → 隐私 → 清除浏览数据 → Cookie（*.cloudflareaccess.com）

5. Try again in incognito window

5. 在无痕窗口中重试


**Fix B: Login Loop**

**Symptoms:** Redirected back to login after successful authentication

**Causes:**
- Browser cookies blocked or cleared
- Pi-hole blocking Google domains
- Redirect URI mismatch

**Fix:**
```bash

**修复方案B：登录循环**

**症状：** 认证成功后被重定向回登录页

**原因：**
- 浏览器Cookie被拦截或清除
- Pi-hole拦截Google域名
- 重定向URI不匹配

**修复步骤：**
```bash

1. Apply Google whitelist

1. 应用Google白名单

/home/dawiddutoit/projects/network/scripts/setup-google-whitelist.sh
/home/dawiddutoit/projects/network/scripts/setup-google-whitelist.sh

2. Clear all browser data

2. 清除所有浏览器数据

Clear cache, cookies, and site data completely

完全清除缓存、Cookie和站点数据

3. Flush DNS cache

3. 刷新DNS缓存

sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder # macOS sudo systemd-resolve --flush-caches # Linux
sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder # macOS sudo systemd-resolve --flush-caches # Linux

4. Restart browser completely

4. 完全重启浏览器

5. Try incognito window

5. 尝试使用无痕窗口


**Fix C: CookieMismatch Error**

**Symptoms:** Error message about cookie mismatch during OAuth

**Cause:** Pi-hole blocking Google cookie sync domains

**Fix:**
```bash

**修复方案C：CookieMismatch错误**

**症状：** OAuth过程中出现Cookie不匹配的错误提示

**原因：** Pi-hole拦截Google Cookie同步域名

**修复步骤：**
```bash

Apply Google whitelist

应用Google白名单

/home/dawiddutoit/projects/network/scripts/setup-google-whitelist.sh
/home/dawiddutoit/projects/network/scripts/setup-google-whitelist.sh

Verify domains whitelisted

验证域名已被白名单放行

docker exec pihole pihole -q doubleclick.net docker exec pihole pihole -q google-analytics.com
docker exec pihole pihole -q doubleclick.net docker exec pihole pihole -q google-analytics.com

Clear browser cookies

清除浏览器Cookie

Browser → Settings → Clear browsing data

浏览器 → 设置 → 清除浏览数据

Try again

重试


**Fix D: "Can only be used within its organization"**

**Symptoms:** Error message when trying to authenticate

**Cause:** OAuth consent screen set to "Internal" with personal Gmail

**Fix:**
1. Go to: https://console.cloud.google.com/apis/credentials/consent
2. Click "Edit App"
3. Change "User Type" from "Internal" to "External"
4. Click "Save and Continue" through wizard
5. Publish app if needed
6. Try authentication again

**Fix E: OAuth Redirect Failure**

**Symptoms:** Redirect fails or goes to wrong URL

**Cause:** Redirect URI doesn't match team name

**Fix:**
```bash

**修复方案D："仅可在其组织内使用"错误**

**症状：** 认证时出现该错误提示

**原因：** OAuth授权界面设置为"内部"但使用个人Gmail账户

**修复步骤：**
1. 访问：https://console.cloud.google.com/apis/credentials/consent
2. 点击"编辑应用"
3. 将"用户类型"从"内部"更改为"外部"
4. 点击"保存并继续"完成向导
5. 如有需要，发布应用
6. 再次尝试认证

**修复方案E：OAuth重定向失败**

**症状：** 重定向失败或跳转到错误URL

**原因：** 重定向URI与团队名称不匹配

**修复步骤：**
```bash

1. Get team name

1. 获取团队名称

grep CLOUDFLARE_TEAM_NAME /home/dawiddutoit/projects/network/.env
grep CLOUDFLARE_TEAM_NAME /home/dawiddutoit/projects/network/.env

2. Update redirect URI in Google Console

2. 在Google Console中更新重定向URI

Go to: https://console.cloud.google.com/apis/credentials

访问：https://console.cloud.google.com/apis/credentials

Update to: https://<TEAM_NAME>.cloudflareaccess.com/cdn-cgi/access/callback

更新为：https://<TEAM_NAME>.cloudflareaccess.com/cdn-cgi/access/callback

3. Or re-run setup to sync

3. 或重新运行设置脚本进行同步

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

Supporting Files

支持文件

FilePurpose
references/reference.md
Google OAuth setup details, Access policy configuration
examples/examples.md
Example configurations, common error scenarios
文件用途
references/reference.md
Google OAuth设置详情、Access策略配置
examples/examples.md
示例配置、常见错误场景

Expected Outcomes

预期结果

Success:
  • Google OAuth login succeeds
  • User redirected to protected service
  • Access granted without "Access Denied"
  • Session persists (no login loops)
Partial Success:
  • Login works but shows "not verified" warning (cosmetic, can proceed)
  • Authentication works in incognito but not regular browser (clear cookies)
Failure Indicators:
  • Access Denied after successful Google login
  • Login loops continuously
  • CookieMismatch errors persist
  • "Can only be used within organization" error
  • Redirect to wrong URL
成功：
  • Google OAuth登录成功
  • 用户被重定向到受保护的服务
  • 无"访问被拒绝"提示，成功获得访问权限
  • 会话保持有效（无登录循环）
部分成功：
  • 登录成功但显示"未验证"警告（仅外观问题，可继续）
  • 在无痕窗口中认证正常但普通浏览器中异常（清除Cookie即可）
失败标识：
  • Google登录成功后仍显示访问被拒绝
  • 持续陷入登录循环
  • CookieMismatch错误仍存在
  • "仅可在其组织内使用"错误
  • 跳转到错误URL

Requirements

前置要求

  • Cloudflare Zero Trust account with Access configured
  • Google Cloud Console project with OAuth 2.0 credentials
  • Valid ACCESS_ALLOWED_EMAIL in .env
  • Pi-hole with Google domains whitelisted
  • Browser with cookies enabled
  • 已配置Access的Cloudflare Zero Trust账户
  • 拥有OAuth 2.0凭证的Google Cloud Console项目
  • .env文件中存在有效的ACCESS_ALLOWED_EMAIL
  • 已将Google域名白名单放行的Pi-hole
  • 启用Cookie的浏览器

Red Flags to Avoid

注意事项

  • Do not use "Internal" OAuth consent screen with personal Gmail accounts
  • Do not block Google domains in Pi-hole (breaks OAuth)
  • Do not skip clearing browser cookies after configuration changes
  • Do not use email wildcards if specific emails intended (security risk)
  • Do not test in same browser session (use incognito window)
  • Do not forget to update both .env and Access policies
  • Do not commit OAuth credentials to git
  • 不要对个人Gmail账户使用"内部"OAuth授权界面
  • 不要在Pi-hole中拦截Google域名（会导致OAuth失效）
  • 配置变更后不要跳过清除浏览器Cookie的步骤
  • 如果需要指定特定邮箱，不要使用邮箱通配符（存在安全风险）
  • 不要在同一会话中测试（使用无痕窗口）
  • 不要忘记同时更新.env和Access策略
  • 不要将OAuth凭证提交到git

Notes

备注

  • Google whitelist is automatically applied via pihole-init service in docker-compose.yml
  • Access policies support wildcards: 
    *@yourdomain.com
  • Session duration default: 24 hours (configurable in Access policy)
  • OAuth consent screen can show "not verified" warning (safe to proceed if you trust app)
  • Redirect URI is case-sensitive and must exactly match team name
  • Clear cookies for 
    *.cloudflareaccess.com
    domain when troubleshooting
  • Test authentication in incognito window to avoid cached sessions
  • View Access logs: https://one.dash.cloudflare.com → Logs → Access
  • Google白名单通过docker-compose.yml中的pihole-init服务自动应用
  • Access策略支持通配符：
    *@yourdomain.com
  • 默认会话时长：24小时（可在Access策略中配置）
  • OAuth授权界面可能显示"未验证"警告（如果信任该应用，可安全继续）
  • 重定向URI区分大小写，必须与团队名称完全匹配
  • 排查问题时清除
    *.cloudflareaccess.com
    域名的Cookie
  • 使用无痕窗口测试认证以避免缓存会话的影响
  • 查看Access日志：https://one.dash.cloudflare.com → 日志 → Access