服务令牌 · Cloudflare One docs

您可以向自动化系统提供服务令牌（service tokens），以针对您的 Cloudflare One 策略进行身份验证。Cloudflare Access 会生成由 Client ID 和 Client Secret 组成的服务令牌。自动化系统或应用程序随后可以使用这些值访问受 Access 保护的应用程序。

本节介绍如何创建、续订和撤销服务令牌。

创建服务令牌

在 Cloudflare 仪表板 ↗中，前往 Zero Trust > Access controls（访问控制） > Service credentials（服务凭据） > Service Tokens（服务令牌）。
选择 Create Service Token（创建服务令牌）。
为服务令牌命名。该名称便于您在日志中识别与令牌相关的事件，并可单独撤销令牌。
选择 Service Token Duration（服务令牌有效期）。这将设置令牌的到期日期。
选择 Generate token（生成令牌）。您将看到为服务令牌生成的 Client ID 和 Client Secret，以及各自的请求头。
复制 Client Secret。

注意
这是 Cloudflare Access 唯一一次显示 Client Secret。如果您丢失了 Client Secret，必须生成一个新的服务令牌。

向 Access Service Tokens 端点发出 POST 请求：

Required API token permissions

At least one of the following token permissions is required:

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_id

terraform 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
		})
	}

您现在可以配置您的 Access 应用程序和设备注册权限以接受此服务令牌。请确保将策略操作设置为 Service Auth；否则，Access 将提示进行身份提供商登录。

将您的服务连接到 Access

初始请求

要使用您的服务令牌对 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

如果服务令牌有效，Access 会以 CF_Authorization cookie 的形式生成一个针对该应用程序的 JWT。可以使用此 Cookie 对后续请求进行身份验证。

使用单个标头进行身份验证

作为 CF-Access-Client-Id 和 CF-Access-Client-Secret 标头对的替代方法，您可以配置自托管 Access 应用程序以在单个 HTTP 标头中接受服务令牌。这对于对仅支持在请求中发送一个自定义标头（例如 Authorization 标头）的 SaaS 服务进行身份验证非常有用。

要使用单个标头进行身份验证：

获取您现有的 Access 应用程序配置：
Required API token permissions

At least one of the following token permissions is required:
- Access: Apps and Policies Write
- Access: 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 请求返回的所有字段。
Required API token permissions

At least one of the following token permissions is required:
- 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

后续请求

在使用服务令牌对应用程序完成身份验证之后，请将生成的 CF_Authorization cookie 添加到所有后续请求的标头中：

curl -H "cookie: CF_Authorization=<CF_AUTHORIZATION_COOKIE>" https://app.example.com

如果您更喜欢使用原始标头，请将该值作为 cf-access-token 发送：

curl -H "cf-access-token: <CF_AUTHORIZATION_COOKIE>" https://app.example.com

在 JWT 过期之前，使用此 Cookie 的所有请求都将成功。

续订服务令牌

服务令牌会根据您创建令牌时选择的令牌持续时间到期。

在 Cloudflare 仪表板 ↗中，转到 Zero Trust > Access controls（访问控制）> Service credentials（服务凭据）> Service Tokens（服务令牌）。
找到您要续订的令牌。
要将令牌的寿命延长一年，请选择 Refresh（刷新）。
要将令牌的寿命延长一年以上：
1. 选择 Edit（编辑）。
2. 选择新的 Service Token Duration（服务令牌持续时间）。
3. 选择 Save（保存）。到期日期将延长所选的时间量。

要将令牌的寿命延长一年，请对续订服务令牌端点发出 POST 请求：

Required API token permissions

At least one of the following token permissions is required:

Access: Service Tokens Write

Refresh a service tokenbash

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

Update a service tokenbash

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

撤销服务令牌

如果您需要在令牌过期前撤销访问权限，请删除该令牌。依赖于已删除服务令牌的服务将无法再访问您的应用程序。

在 Cloudflare 仪表板 ↗中，转到 Zero Trust > Access controls（访问控制）> Service credentials（服务凭据）> Service Tokens（服务令牌）。
选择 **Delete（删除）**您需要撤销的令牌。

Make a DELETE request to the Delete a service token endpoint:

Required API token permissions

At least one of the following token permissions is required:

Access: Service Tokens Write

Delete a service tokenbash

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

Who is it for?

Access customers who want to receive a notification when their service token is about to expire.

Other options / filters

None.

Included with

Purchase of Access

What should you do if you receive one?

Extend the expiration date of the service token. For more details, refer to Renew your service token.

要配置服务令牌到期警报：

在 Cloudflare 仪表板 ↗中，转到 **Notifications（通知）**页面。 Go to Notifications ↗
选择 Add（添加）。
选择 Expiring Access Service Token（即将过期的 Access 服务令牌）。
输入警报的名称和可选描述。
（可选）为通知电子邮件添加其他收件人。
选择 Save（保存）。

您的警报已设置，现在显示在 **Notifications（通知）**页面上。