跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

服务令牌

最后更新 查看 MarkdownAgent 设置

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

本节介绍如何创建、轮换、续订、禁用和撤销服务令牌。您还可以配置 Access,以自动管理不活动的服务令牌。

创建服务令牌

  1. 在 Cloudflare 仪表板 ↗中,前往 Zero Trust > Access controls(访问控制) > Service credentials(服务凭据) > Service Tokens(服务令牌)。

  2. 选择 Create Service Token(创建服务令牌)。

  3. 为服务令牌命名。该名称便于您在日志中识别与令牌相关的事件,并可单独撤销令牌。

  4. 选择 Service Token Duration(服务令牌有效期)。这将设置令牌的到期日期。

  5. 选择 Generate token(生成令牌)。您将看到为服务令牌生成的 Client ID 和 Client Secret,以及各自的请求头。

  6. 复制 Client Secret。

  1. 向 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"
    	}'
  2. 复制响应中返回的 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
    }
  1. 向您的 cloudflare_api_token ↗ 添加以下权限:

    • Access: Service Tokens Write
  2. 配置 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
    	}
    }
  3. 获取服务令牌的 Client ID 和 Client Secret:

    示例:输出到 CLI

    1. 将 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
      }
    2. 应用配置:
      terraform apply
    3. 读取 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 将提示进行身份提供商登录。

Client Secret 格式

自 2026 年 8 月 26 日起,新的服务令牌 Client Secret 使用 cfast_[40 alphanumeric characters][8-character checksum] 格式。前缀和校验和便于凭据扫描工具识别这些密钥。

现有 Client Secret 使用 64 个字符的十六进制格式。这些密钥可继续使用,无需轮换。两种格式使用相同的 Client ID 和身份验证标头。

将您的服务连接到 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

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

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

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

  1. 获取您现有的 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"
  2. 使用您要用于服务令牌身份验证的标头名称发出 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"
    	}'
  3. 将标头添加到任何 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_Authorization cookie。
  • 身份验证成功后,Access 不会向客户端返回 CF_Authorization cookie。后续请求应继续使用服务令牌标头。
  • 已识别服务令牌的失败请求会出现在 Access 身份验证日志中。Access 会记录已过期或已禁用的令牌、不正确的 Client Secret,以及未经该应用程序授权的令牌。格式错误的标头或未知的 Client ID 不会被记录。

在 2026-10-05 当天或之后创建的 Zero Trust 组织默认开启严格服务令牌身份验证,且无法关闭。Cloudflare 建议现有组织也开启此设置。

  1. 在 Cloudflare 仪表板 ↗中,转到 Zero Trust > Access controls(访问控制)> Access settings(Access 设置)。

    前往 Access settings(Access 设置) ↗
  2. 在 Manage service tokens(管理服务令牌) 下,开启 Strict service token authentication(严格服务令牌身份验证)。

  3. 在确认对话框中,选择 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 撤销旧密钥。

  1. 在 Cloudflare 仪表板 ↗中,转到 Zero Trust > Access controls(访问控制)> Service credentials(服务凭据)> Service Tokens(服务令牌)。

    前往  ↗
  2. 找到该令牌,选择三点菜单 > Rotate secret(轮换密钥)。

  3. 在 Keep the current secret valid for(当前密钥保持有效) 中,选择 Access 应何时撤销当前密钥。可用宽限期从一小时到 30 天不等。若要在轮换时立即撤销,请选择 Revoke immediately(立即撤销)。

  4. 选择 Rotate(轮换)。

  5. 复制新的 Client Secret,并在宽限期结束前更新您的服务。

向轮换服务令牌端点发出 POST 请求。将 previous_client_secret_expires_at 设置为 RFC 3339 时间戳,表示旧密钥应过期的时间:

Rotate a service tokenbash
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。

续订服务令牌

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

  1. 在 Cloudflare 仪表板 ↗中,转到 Zero Trust > Access controls(访问控制)> Service credentials(服务凭据)> Service Tokens(服务令牌)。
  2. 找到您要续订的令牌。
  3. 要将令牌的寿命延长一年,请选择 Refresh(刷新)。
  4. 要将令牌的寿命延长一年以上:
    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
	}
}

管理不活动的服务令牌

您可以配置 Access,自动禁用或删除不再使用的服务令牌。该设置适用于 Zero Trust 账户中的所有服务令牌。

当以下条件全部满足时,Access 会将服务令牌视为不活动:

  • 在配置的不活动期限内,该令牌未成功向 Access 应用程序进行身份验证。
  • 该令牌的创建时间早于配置的不活动期限。
  • 该令牌未被 Access 策略规则直接引用。

不活动期限可设置为 30 到 365 天之间的整数。已禁用的令牌仍会保留在账户中,可以再次开启。已删除的令牌无法恢复。

  1. 在 Cloudflare 仪表板 ↗中,转到 Zero Trust > Access controls(访问控制)> Access settings(Access 设置)。

    前往 Access settings(Access 设置) ↗
  2. 在 Manage service tokens(管理服务令牌) 下,开启 Automatically clean up inactive service tokens(自动清理不活动的服务令牌)。

  3. 输入 30 到 365 天的 Inactivity period(不活动期限)。

  4. 选择 Access 应禁用还是删除不活动的令牌。

  5. 选择 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 会保留该令牌,以便稍后再次开启。

关闭令牌还会使轮换宽限期内的旧密钥立即失效。

  1. 在 Cloudflare 仪表板 ↗中,转到 Zero Trust > Access controls(访问控制)> Service credentials(服务凭据)> Service Tokens(服务令牌)。

    前往  ↗
  2. 找到该令牌并选择三点菜单。

  3. 要停止该令牌进行身份验证,选择 Disable token(禁用令牌) > Disable(禁用)。

  4. 要恢复身份验证,选择 Enable token(启用令牌) > Enable(启用)。

向更新服务令牌端点发出 PUT 请求。将 enabled 设置为 false 以关闭该令牌:

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 '{
		"name": "<TOKEN_NAME>",
		"enabled": false
	}'

要再次开启该令牌,将 enabled 设置为 true。

撤销服务令牌

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

  1. 在 Cloudflare 仪表板 ↗中,转到 Zero Trust > Access controls(访问控制)> Service credentials(服务凭据)> Service Tokens(服务令牌)。
  2. 选择 Delete(删除) 您需要撤销的令牌。

向删除服务令牌端点发送 DELETE 请求:

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

适用对象

希望在服务令牌即将过期时收到通知的 Access 客户。

其他选项/筛选条件

无。

包含于

已购买 Access

收到通知后应如何处理?

延长服务令牌的过期日期。有关详细信息,请参阅续订服务令牌。

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

  1. 在 Cloudflare 仪表板 ↗中,转到 Notifications(通知) 页面。 前往 Notifications(通知) ↗
  2. 选择 Add(添加)。
  3. 选择 Expiring Access Service Token(即将过期的 Access 服务令牌)。
  4. 输入警报的名称和可选描述。
  5. (可选)为通知电子邮件添加其他收件人。
  6. 选择 Save(保存)。

您的警报已设置,现在显示在 Notifications(通知) 页面上。

这篇文档对您有帮助吗?