Back to Details

cloudflare-service-token-setup

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Service Token Setup Skill

Service Token 配置指南

Complete workflow for creating and managing Cloudflare Access service tokens for automated infrastructure verification and non-human access.
本指南提供创建和管理Cloudflare Access服务令牌的完整流程，用于自动化基础设施验证和非人类访问场景。

Quick Start

快速开始

Quick service token setup:
bash
undefined
快速配置服务令牌：
bash
undefined

1. Create service token via Cloudflare dashboard

1. Create service token via Cloudflare dashboard

Go to: https://one.dash.cloudflare.com → Access → Service Auth → Create Service Token

Go to: https://one.dash.cloudflare.com → Access → Service Auth → Create Service Token

Name: "Infrastructure Automation"

Name: "Infrastructure Automation"

Duration: 1 year

Duration: 1 year

2. Add credentials to .env

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

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

4. Use helper script for testing

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

Table of Contents

目录

  1. When to Use This Skill
  2. What This Skill Does
  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
  5. Expected Outcomes
  6. Requirements
  7. Red Flags to Avoid
  1. 适用场景
  2. 功能说明
  3. 操作步骤
    • 3.1 服务令牌与OAuth的区别
    • 3.2 通过控制台创建服务令牌
    • 3.3 将凭证添加至.env
    • 3.4 测试服务令牌访问权限
    • 3.5 使用辅助脚本验证
    • 3.6 吊销或轮换服务令牌
    • 3.7 监控服务令牌使用情况
  4. 相关文件
  5. 预期结果
  6. 前提条件
  7. 注意事项

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?"
明确触发场景：
  • "创建服务令牌"
  • "配置自动化访问权限"
  • "无需OAuth验证服务"
  • "自动化监控"
  • "非人类访问"
隐含触发场景：
  • 需要以编程方式测试服务
  • 搭建监控脚本
  • CI/CD流程需要验证部署结果
  • 需与Claude共享验证结果
  • 需要绕过Google OAuth实现自动化
调试触发场景：
  • "如何无需浏览器测试服务？"
  • "如何实现自动化验证？"
  • "服务令牌与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
  1. 概念讲解 - 明确服务令牌与Google OAuth的适用场景
  2. 令牌创建 - 指导通过Cloudflare控制台创建令牌
  3. 凭证存储 - 将令牌安全存储至.env文件
  4. 访问测试 - 验证令牌可访问受保护服务
  5. 辅助脚本 - 演示如何使用cf-service-token.sh进行测试
  6. 令牌吊销 - 演示如何吊销/轮换泄露的令牌
  7. 使用监控 - 演示如何在Access日志中查看令牌使用情况

Instructions

操作步骤

3.1 Understanding Service Tokens vs OAuth

3.1 服务令牌与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 CaseMethod
Automated health checksService Token
CI/CD deployment verificationService Token
Monitoring scriptsService Token
Sharing verification with ClaudeService Token
Human web browser accessGoogle OAuth
Interactive service useGoogle OAuth
Key difference: Service tokens automatically bypass all Cloudflare Access policies - no additional configuration needed.
服务令牌（非人类访问）：
  • 适用于自动化流程、脚本、监控系统
  • 绕过Google OAuth验证要求
  • 可与curl、脚本、CI/CD配合使用
  • 长期有效（数月/数年）
  • 无需用户会话
Google OAuth（人类访问）：
  • 适用于人类通过浏览器访问
  • 需要Google账户登录
  • 基于会话（默认24小时）
  • 支持多因素认证
适用场景对比：
场景方式
自动化健康检查服务令牌
CI/CD部署验证服务令牌
监控脚本服务令牌
与Claude共享验证结果服务令牌
人类浏览器访问Google OAuth
交互式服务使用Google OAuth
核心区别： 服务令牌会自动绕过所有Cloudflare Access策略 - 无需额外配置。

3.2 Create Service Token via Dashboard

3.2 通过控制台创建服务令牌

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.
步骤1：进入服务认证页面
  1. 访问：https://one.dash.cloudflare.com
  2. 导航至：Access → Service Auth → Service Tokens
  3. 点击：Create Service Token
步骤2：配置令牌
  • 名称： 
    Infrastructure Automation
    （或其他描述性名称）
  • 有效期： 1年（按需设置）
  • 建议： 使用具有描述性的名称，如「CI/CD流水线」或「健康监控」
步骤3：保存凭证
创建完成后，Cloudflare会显示：
  • Client ID： 
    8f0eb3c52a7236fc952d9b11cd67b960.access
  • Client Secret： 
    63b34062dbca3405521196952ba4d155...
    （长十六进制字符串）
⚠️ 重要提示： Client Secret仅会显示一次，请立即复制保存.
步骤4：复制凭证
复制两个值 - 下一步将添加至.env文件.

3.3 Add Credentials to .env

3.3 将凭证添加至.env

Add service token credentials to project .env file:
bash
undefined
将服务令牌凭证添加至项目的.env文件：
bash
undefined

Navigate to project directory

Navigate to project directory

cd /home/dawiddutoit/projects/network
cd /home/dawiddutoit/projects/network

Add credentials to .env

Add credentials to .env

cat >> .env << 'EOF'
cat >> .env << 'EOF'

Cloudflare Access Service Token (for automation)

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.
CF_SERVICE_TOKEN_CLIENT_ID="your-client-id.access" CF_SERVICE_TOKEN_CLIENT_SECRET="your-client-secret-here" EOF

**替换值**为控制台获取的实际凭证.

**验证凭证已添加：**

```bash
grep CF_SERVICE_TOKEN /home/dawiddutoit/projects/network/.env
预期输出：
CF_SERVICE_TOKEN_CLIENT_ID="8f0eb3c52a7236fc952d9b11cd67b960.access"
CF_SERVICE_TOKEN_CLIENT_SECRET="63b34062dbca3405521196952ba4d155de00f59e52d0fa23d0a7f3de66696c6c"
安全说明： .env已添加至.gitignore，因此凭证不会被提交至代码仓库.

3.4 Test Service Token Access

3.4 测试服务令牌访问权限

Test with curl directly:
bash
undefined
直接使用curl测试：
bash
undefined

Load environment variables

Load environment variables

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

Test single service

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

**预期结果：**
HTTP/2 200 server: Caddy ...

**测试多个服务：**

```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
成功标识：
  • HTTP 200：服务可访问且正常运行
  • HTTP 502：服务令牌有效，但后端服务故障
  • HTTP 403：服务令牌无效或已过期

3.5 Use Helper Script for Verification

3.5 使用辅助脚本验证

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
项目包含辅助脚本，便于测试：
测试单个服务：
bash
/home/dawiddutoit/projects/network/scripts/cf-service-token.sh test jaeger.temet.ai
预期输出：
Testing jaeger.temet.ai...
✓ Service token accepted (HTTP 200)
查看完整响应：
bash
/home/dawiddutoit/projects/network/scripts/cf-service-token.sh test jaeger.temet.ai --verbose
显示完整的HTTP响应和头部信息.
列出所有服务令牌：
bash
/home/dawiddutoit/projects/network/scripts/cf-service-token.sh list
显示Cloudflare账户中配置的所有服务令牌.
测试所有已配置服务：
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

3.6 吊销或轮换服务令牌

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
undefined
吊销场景：
  • 令牌泄露或暴露
  • 令牌不再需要
  • 定期安全轮换（建议每年一次）
通过控制台吊销：
  1. 访问：https://one.dash.cloudflare.com
  2. 导航至：Access → Service Auth → Service Tokens
  3. 通过名称查找令牌："Infrastructure Automation"
  4. 点击垃圾桶图标 → Delete
  5. 确认删除
通过脚本吊销：
bash
undefined

List tokens to get ID

List tokens to get ID

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

Delete by ID

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
/home/dawiddutoit/projects/network/scripts/cf-service-token.sh delete <token-id>

**吊销后操作：**

1. 从.env中移除凭证：
```bash
nano /home/dawiddutoit/projects/network/.env

Delete CF_SERVICE_TOKEN_CLIENT_ID and CF_SERVICE_TOKEN_CLIENT_SECRET lines

删除CF_SERVICE_TOKEN_CLIENT_ID和CF_SERVICE_TOKEN_CLIENT_SECRET行


2. If rotating (not removing), create new token and update .env with new credentials.

**Token rotation workflow:**

```bash

2. 若为轮换（而非移除），创建新令牌并更新.env中的凭证.

**令牌轮换流程：**

```bash

1. Create new token via dashboard

1. Create new token via dashboard

2. Add new credentials to .env (with new_ prefix temporarily)

2. Add new credentials to .env (with new_ prefix temporarily)

echo "CF_SERVICE_TOKEN_CLIENT_ID_NEW=new-client-id.access" >> .env echo "CF_SERVICE_TOKEN_CLIENT_SECRET_NEW=new-secret" >> .env
echo "CF_SERVICE_TOKEN_CLIENT_ID_NEW=new-client-id.access" >> .env echo "CF_SERVICE_TOKEN_CLIENT_SECRET_NEW=new-secret" >> .env

3. Test new token works

3. Test new token works

source .env curl -H "CF-Access-Client-Id: ${CF_SERVICE_TOKEN_CLIENT_ID_NEW}"
-H "CF-Access-Client-Secret: ${CF_SERVICE_TOKEN_CLIENT_SECRET_NEW}"
https://jaeger.temet.ai
source .env curl -H "CF-Access-Client-Id: ${CF_SERVICE_TOKEN_CLIENT_ID_NEW}"
-H "CF-Access-Client-Secret: ${CF_SERVICE_TOKEN_CLIENT_SECRET_NEW}"
https://jaeger.temet.ai

4. If working, replace old with new in .env

4. If working, replace old with new in .env

nano .env # Remove old credentials, rename new_ to remove suffix
nano .env # Remove old credentials, rename new_ to remove suffix

5. Revoke old token via dashboard

5. Revoke old token via dashboard

undefined
undefined

3.7 Monitor Service Token Usage

3.7 监控服务令牌使用情况

View service token access logs:
Via Cloudflare Dashboard:
  1. Go to: https://one.dash.cloudflare.com
  2. Navigate to: Logs → Access
  3. Filter by: Authentication method → Service token
  4. View:
    • Timestamp of access
    • Service accessed
    • Token name used
    • Source IP
    • Success/failure
Log retention: 30 days (free plan) to 6 months (enterprise)
Monitoring for suspicious activity:
  • Unexpected IPs accessing services
  • High frequency of requests (potential abuse)
  • 403 errors (token may be expired/revoked)
Alerts setup (optional):
Set up Cloudflare Notifications:
  1. Go to: Account → Notifications
  2. Create alert for: Access events
  3. Trigger: Service token authentication failures
查看服务令牌访问日志：
通过Cloudflare控制台：
  1. 访问：https://one.dash.cloudflare.com
  2. 导航至：Logs → Access
  3. 筛选条件：Authentication method → Service token
  4. 查看内容：
    • 访问时间戳
    • 访问的服务
    • 使用的令牌名称
    • 源IP
    • 访问成功/失败状态
日志保留时长： 免费计划30天，企业计划最长6个月
可疑活动监控：
  • 非预期IP访问服务
  • 请求频率过高（可能存在滥用）
  • 403错误（令牌可能已过期/吊销）
告警设置（可选）：
配置Cloudflare通知：
  1. 访问：Account → Notifications
  2. 创建告警：Access事件
  3. 触发条件：服务令牌认证失败

Supporting Files

相关文件

FilePurpose
references/reference.md
Service token architecture, security best practices, API details
scripts/test-service-token.sh
Automated testing script for all services
examples/examples.md
Example use cases, monitoring scripts, CI/CD integration
文件用途
references/reference.md
服务令牌架构、安全最佳实践、API详情
scripts/test-service-token.sh
所有服务的自动化测试脚本
examples/examples.md
示例用例、监控脚本、CI/CD集成示例

Expected Outcomes

预期结果

Success:
  • Service token created in Cloudflare dashboard
  • Credentials stored securely in .env
  • Token bypasses OAuth for protected services
  • HTTP 200 responses for accessible services
  • Helper script works for verification
  • Can share verification results with Claude
Partial Success:
  • Token created but not tested (complete step 3.4)
  • Some services return 502 (backend issue, not auth issue)
Failure Indicators:
  • HTTP 403 responses (token invalid or not configured)
  • Token not found in dashboard
  • Credentials not in .env
  • Helper script fails with "missing credentials"
成功：
  • 已在Cloudflare控制台创建服务令牌
  • 凭证已安全存储至.env
  • 令牌可绕过OAuth访问受保护服务
  • 可访问服务返回HTTP 200响应
  • 辅助脚本可正常进行验证
  • 可与Claude共享验证结果
部分成功：
  • 已创建令牌但未完成测试（执行步骤3.4）
  • 部分服务返回502（后端服务故障，非认证问题）
失败标识：
  • 返回HTTP 403响应（令牌无效或未配置）
  • 控制台中未找到令牌
  • 凭证未添加至.env
  • 辅助脚本提示「缺少凭证」错误

Requirements

前提条件

  • Cloudflare Zero Trust account with Access configured
  • Admin access to Cloudflare dashboard
  • .env file with write permissions
  • curl installed for testing
  • Existing Cloudflare Access applications configured
  • 已配置Access的Cloudflare Zero Trust账户
  • Cloudflare控制台管理员权限
  • .env文件可写权限
  • 已安装curl用于测试
  • 已配置Cloudflare Access应用

Red Flags to Avoid

注意事项

  • Do not treat service tokens like passwords (they are powerful credentials)
  • Do not share service tokens publicly or commit to git
  • Do not create unlimited tokens (1-2 per use case is sufficient)
  • Do not skip saving client secret immediately (shown only once)
  • Do not use service tokens for human browser access (use OAuth)
  • Do not forget to revoke tokens when no longer needed
  • Do not ignore 403 errors (indicates auth failure, not backend issue)
  • 请勿将服务令牌视为普通密码（它们是高权限凭证）
  • 请勿公开分享服务令牌或提交至git
  • 请勿创建过多令牌（每个场景1-2个即可）
  • 请勿忘记立即保存Client Secret（仅显示一次）
  • 请勿将服务令牌用于人类浏览器访问（使用OAuth）
  • 令牌不再需要时请勿忘记吊销
  • 请勿忽略403错误（表示认证失败，非后端问题）

Notes

备注

  • Service tokens automatically bypass Cloudflare Access policies (no policy configuration needed)
  • Token duration options: 1 day, 1 week, 1 month, 6 months, 1 year, no expiry
  • Recommended duration: 1 year with annual rotation
  • Service tokens work for all Access-protected applications automatically
  • No limit on number of service tokens per account
  • Revoked tokens fail immediately (no grace period)
  • Service tokens don't support MFA (they bypass all human authentication)
  • Use separate tokens for different systems (easier to revoke if compromised)
  • Monitor Access logs regularly for unusual service token activity
  • cf-service-token.sh script location: 
    scripts/cf-service-token.sh
  • 服务令牌会自动绕过Cloudflare Access策略（无需配置额外策略）
  • 令牌有效期选项：1天、1周、1个月、6个月、1年、永久
  • 推荐有效期：1年，每年轮换一次
  • 服务令牌可自动访问所有受Access保护的应用
  • 账户中服务令牌数量无限制
  • 吊销的令牌立即失效（无宽限期）
  • 服务令牌不支持MFA（会绕过所有人类认证）
  • 为不同系统使用独立令牌（泄露后便于吊销）
  • 定期查看Access日志，监控服务令牌异常活动
  • cf-service-token.sh脚本路径:
    scripts/cf-service-token.sh