您可以向自动化系统提供服务令牌(service tokens),以针对您的 Cloudflare One 策略进行身份验证。Cloudflare Access 会生成由 Client ID 和 Client Secret 组成的服务令牌。自动化系统或应用程序随后可以使用这些值访问受 Access 保护的应用程序。
本节介绍如何创建、轮换、续订、禁用和撤销服务令牌。您还可以配置 Access,以自动管理不活动的服务令牌。
-
在 Cloudflare 仪表板 ↗中,前往 Zero Trust > Access controls(访问控制) > Service credentials(服务凭据) > Service Tokens(服务令牌)。
-
选择 Create Service Token(创建服务令牌)。
-
为服务令牌命名。该名称便于您在日志中识别与令牌相关的事件,并可单独撤销令牌。
-
选择 Service Token Duration(服务令牌有效期)。这将设置令牌的到期日期。
-
选择 Generate token(生成令牌)。您将看到为服务令牌生成的 Client ID 和 Client Secret,以及各自的请求头。
-
复制 Client Secret。
-
向 Access Service Tokens 端点发出
POST请求:
At least one of the following token permissions is required:Required API token permissions
Access: Service Tokens Write
Create a service tokenbash curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/access/service_tokens" \ --request POST \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "name": "CI/CD token", "duration": "8760h" }' -
复制响应中返回的
client_id和client_secret值。Responsejson "result": { "client_id": "88bf3b6d86161464f6509f7219099e57.access", "client_secret": "bdd31cbc4dec990953e39163fbbb194c93313ca9f0a6e420346af9d326b1d2a5", "created_at": "2025-09-25T22:26:26Z", "expires_at": "2026-09-25T22:26:26Z", "id": "3537a672-e4d8-4d89-aab9-26cb622918a1", "name": "CI/CD token", "updated_at": "2025-09-25T22:26:26Z", "duration": "8760h", "client_secret_version": 1 }
-
向您的
cloudflare_api_token↗ 添加以下权限:Access: Service Tokens Write
-
配置
cloudflare_zero_trust_access_service_token↗ 资源:resource "cloudflare_zero_trust_access_service_token" "example_service_token" { account_id = var.cloudflare_account_id name = "Example service token" duration = "8760h" lifecycle { create_before_destroy = true } } -
获取服务令牌的 Client ID 和 Client Secret:
示例:输出到 CLI
- 将 Client ID 和 Client Secret 输出到 Terraform 状态文件:
output "example_service_token_client_id" { value = cloudflare_zero_trust_access_service_token.example_service_token.client_id } output "example_service_token_client_secret" { value = cloudflare_zero_trust_access_service_token.example_service_token.client_secret sensitive = true } - 应用配置:
terraform apply - 读取 Client ID 和 Client Secret:
terraform output -raw example_service_token_client_idterraform output -raw example_service_token_client_secret
示例:存储在 HashiCorp Vault 中
resource "vault_generic_secret" "example_service_token" { path = "kv/cloudflare/example_service_token" data_json = jsonencode({ "CLIENT_ID" = cloudflare_access_service_token.example_service_token.client_id "CLIENT_SECRET" = cloudflare_access_service_token.example_service_token.client_secret }) } - 将 Client ID 和 Client Secret 输出到 Terraform 状态文件:
您现在可以配置您的 Access 应用程序和设备注册权限以接受此服务令牌。请确保将策略操作设置为 Service Auth;否则,Access 将提示进行身份提供商登录。
自 2026 年 8 月 26 日起,新的服务令牌 Client Secret 使用 cfast_[40 alphanumeric characters][8-character checksum] 格式。前缀和校验和便于凭据扫描工具识别这些密钥。
现有 Client Secret 使用 64 个字符的十六进制格式。这些密钥可继续使用,无需轮换。两种格式使用相同的 Client ID 和身份验证标头。
要使用您的服务令牌对 Access 应用程序进行身份验证,请将以下内容添加到任何 HTTP 请求的标头中:
CF-Access-Client-Id: <CLIENT_ID>
CF-Access-Client-Secret: <CLIENT_SECRET>
例如,
curl -H "CF-Access-Client-Id: <CLIENT_ID>" -H "CF-Access-Client-Secret: <CLIENT_SECRET>" https://app.example.com作为 CF-Access-Client-Id 和 CF-Access-Client-Secret 标头对的替代方法,您可以配置自托管 Access 应用程序以在单个 HTTP 标头中接受服务令牌。这对于对仅支持在请求中发送一个自定义标头(例如 Authorization 标头)的 SaaS 服务进行身份验证非常有用。
要使用单个标头进行身份验证:
-
获取您现有的 Access 应用程序配置:
At least one of the following token permissions is required:Required API token permissions
Access: Apps and Policies WriteAccess: Apps and Policies Read
Get an Access applicationbash curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/access/apps/$APP_ID" \ --request GET \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" -
使用您要用于服务令牌身份验证的标头名称发出
PUT请求。为避免覆盖您现有的配置,PUT请求主体应包含上一个GET请求返回的所有字段。
At least one of the following token permissions is required:Required API token permissions
Access: Apps and Policies Write
Update an Access applicationbash curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/access/apps/$APP_ID" \ --request PUT \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "domain": "app.example.com", "type": "self_hosted", "read_service_tokens_from_header": "Authorization" }' -
将标头添加到任何 HTTP 请求。例如,
curl -H "Authorization: {\"cf-access-client-id\": \"<CLIENT_ID>\", \"cf-access-client-secret\": \"<CLIENT_SECRET>\"}" https://app.example.com
严格服务令牌身份验证是一项 Zero Trust 组织设置,用于对使用服务令牌发出的请求应用一致的行为。开启该设置后,Access 会按如下方式处理带有服务令牌标头的请求:
- 如果身份验证或授权失败,Access 始终返回
401或403,而不是以302将客户端重定向到登录页面。 - 只有 Service Auth 策略可以授权该请求。Access 会忽略 Allow 策略,以及随请求发送的任何
CF_Authorizationcookie。 - 身份验证成功后,Access 不会向客户端返回
CF_Authorizationcookie。后续请求应继续使用服务令牌标头。 - 已识别服务令牌的失败请求会出现在 Access 身份验证日志中。Access 会记录已过期或已禁用的令牌、不正确的 Client Secret,以及未经该应用程序授权的令牌。格式错误的标头或未知的 Client ID 不会被记录。
在 2026-10-05 当天或之后创建的 Zero Trust 组织默认开启严格服务令牌身份验证,且无法关闭。Cloudflare 建议现有组织也开启此设置。
-
在 Cloudflare 仪表板 ↗中,转到 Zero Trust > Access controls(访问控制)> Access settings(Access 设置)。
前往 Access settings(Access 设置) ↗ -
在 Manage service tokens(管理服务令牌) 下,开启 Strict service token authentication(严格服务令牌身份验证)。
-
在确认对话框中,选择 Enable(启用)。
要关闭严格服务令牌身份验证,请关闭该设置并选择 Disable(禁用)。
向更新 Zero Trust 组织端点发送 PATCH 请求:
curl "https://api.cloudflare.com/client/v4/accounts/%7Baccount_id%7D/access/organizations" \
--request PATCH \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--json '{
"strict_service_token_auth": true
}'要关闭严格服务令牌身份验证,将 strict_service_token_auth 设置为 false。
当怀疑密钥已泄露,或作为定期凭据轮换的一部分时,请轮换服务令牌密钥。Client ID 保持不变,但 Access 会生成新的 Client Secret。
您可以设置宽限期,在此期间两个密钥均有效。使用此宽限期更新您的服务,然后再由 Access 撤销旧密钥。
-
在 Cloudflare 仪表板 ↗中,转到 Zero Trust > Access controls(访问控制)> Service credentials(服务凭据)> Service Tokens(服务令牌)。
前往 ↗ -
找到该令牌,选择三点菜单 > Rotate secret(轮换密钥)。
-
在 Keep the current secret valid for(当前密钥保持有效) 中,选择 Access 应何时撤销当前密钥。可用宽限期从一小时到 30 天不等。若要在轮换时立即撤销,请选择 Revoke immediately(立即撤销)。
-
选择 Rotate(轮换)。
-
复制新的 Client Secret,并在宽限期结束前更新您的服务。
向轮换服务令牌端点发出 POST 请求。将 previous_client_secret_expires_at 设置为 RFC 3339 时间戳,表示旧密钥应过期的时间:
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/access/service_tokens/$SERVICE_TOKEN_ID/rotate" \
--request POST \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--json '{
"previous_client_secret_expires_at": "2030-01-01T00:00:00Z"
}'要立即撤销旧密钥,请从请求中省略 previous_client_secret_expires_at。
服务令牌会根据您创建令牌时选择的令牌持续时间到期。
- 在 Cloudflare 仪表板 ↗中,转到 Zero Trust > Access controls(访问控制)> Service credentials(服务凭据)> Service Tokens(服务令牌)。
- 找到您要续订的令牌。
- 要将令牌的寿命延长一年,请选择 Refresh(刷新)。
- 要将令牌的寿命延长一年以上:
- 选择 Edit(编辑)。
- 选择新的 Service Token Duration(服务令牌持续时间)。
- 选择 Save(保存)。到期日期将延长所选的时间量。
要将令牌的寿命延长一年,请对续订服务令牌端点发出 POST 请求:
Required API token permissions
At least one of the following token permissions is required:Access: Service Tokens Write
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/access/service_tokens/$SERVICE_TOKEN_ID/refresh" \
--request POST \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"要以自定义时长延长令牌生命周期,请向 Update a service token 端点发送带有新 duration 的 PUT 请求:
Required API token permissions
At least one of the following token permissions is required:Access: Service Tokens Write
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/access/service_tokens/$SERVICE_TOKEN_ID" \
--request PUT \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--json '{
"duration": "17520h"
}'要续订服务令牌,请更新 cloudflare_zero_trust_access_service_token ↗ 资源上的 duration 属性并应用更改。Cloudflare 将相对于更新时间重置过期时间。
resource "cloudflare_zero_trust_access_service_token" "example_service_token" {
account_id = var.cloudflare_account_id
name = "Example service token"
duration = "17520h"
lifecycle {
create_before_destroy = true
}
}您可以配置 Access,自动禁用或删除不再使用的服务令牌。该设置适用于 Zero Trust 账户中的所有服务令牌。
当以下条件全部满足时,Access 会将服务令牌视为不活动:
- 在配置的不活动期限内,该令牌未成功向 Access 应用程序进行身份验证。
- 该令牌的创建时间早于配置的不活动期限。
- 该令牌未被 Access 策略规则直接引用。
不活动期限可设置为 30 到 365 天之间的整数。已禁用的令牌仍会保留在账户中,可以再次开启。已删除的令牌无法恢复。
-
在 Cloudflare 仪表板 ↗中,转到 Zero Trust > Access controls(访问控制)> Access settings(Access 设置)。
前往 Access settings(Access 设置) ↗ -
在 Manage service tokens(管理服务令牌) 下,开启 Automatically clean up inactive service tokens(自动清理不活动的服务令牌)。
-
输入 30 到 365 天的 Inactivity period(不活动期限)。
-
选择 Access 应禁用还是删除不活动的令牌。
-
选择 Save(保存)。
发送 PATCH 请求以更新您的 Zero Trust 组织。将 action 设置为 disable 或 delete:
curl "https://api.cloudflare.com/client/v4/accounts/%7Baccount_id%7D/access/organizations" \
--request PATCH \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--json '{
"service_token_inactivity": {
"enabled": true,
"inactivity_threshold_days": 90,
"action": "disable"
}
}'要停止自动清理,将 enabled 设置为 false。
清理会在后台逐步运行。符合条件的令牌可能不会立即被禁用或删除。
关闭服务令牌可暂时阻止其进行身份验证。Access 会保留该令牌,以便稍后再次开启。
关闭令牌还会使轮换宽限期内的旧密钥立即失效。
-
在 Cloudflare 仪表板 ↗中,转到 Zero Trust > Access controls(访问控制)> Service credentials(服务凭据)> Service Tokens(服务令牌)。
前往 ↗ -
找到该令牌并选择三点菜单。
-
要停止该令牌进行身份验证,选择 Disable token(禁用令牌) > Disable(禁用)。
-
要恢复身份验证,选择 Enable token(启用令牌) > Enable(启用)。
向更新服务令牌端点发出 PUT 请求。将 enabled 设置为 false 以关闭该令牌:
Required API token permissions
At least one of the following token permissions is required:Access: Service Tokens Write
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/access/service_tokens/$SERVICE_TOKEN_ID" \
--request PUT \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--json '{
"name": "<TOKEN_NAME>",
"enabled": false
}'要再次开启该令牌,将 enabled 设置为 true。
如果您需要在令牌过期前撤销访问权限,请删除该令牌。依赖于已删除服务令牌的服务将无法再访问您的应用程序。
- 在 Cloudflare 仪表板 ↗中,转到 Zero Trust > Access controls(访问控制)> Service credentials(服务凭据)> Service Tokens(服务令牌)。
- 选择 Delete(删除) 您需要撤销的令牌。
向删除服务令牌端点发送 DELETE 请求:
Required API token permissions
At least one of the following token permissions is required:Access: Service Tokens Write
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/access/service_tokens/$SERVICE_TOKEN_ID" \
--request DELETE \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"要撤销服务令牌,请从您的配置中删除 cloudflare_zero_trust_access_service_token ↗ 资源并运行 terraform apply,或将该资源作为销毁目标:
terraform destroy -target=cloudflare_zero_trust_access_service_token.example_service_token可以配置警报,在服务令牌过期前一周发出通知,以便管理员调用令牌刷新。
Expiring Access Service Token Alert
适用对象希望在服务令牌即将过期时收到通知的 Access 客户。
其他选项/筛选条件无。
包含于已购买 Access
收到通知后应如何处理?延长服务令牌的过期日期。有关详细信息,请参阅续订服务令牌。
要配置服务令牌到期警报:
- 在 Cloudflare 仪表板 ↗中,转到 Notifications(通知) 页面。 前往 Notifications(通知) ↗
- 选择 Add(添加)。
- 选择 Expiring Access Service Token(即将过期的 Access 服务令牌)。
- 输入警报的名称和可选描述。
- (可选)为通知电子邮件添加其他收件人。
- 选择 Save(保存)。
您的警报已设置,现在显示在 Notifications(通知) 页面上。