设置仪表板 SSO

Cloudflare 为所有使用自定义电子邮件域登录的客户提供单点登录 (SSO)。通过创建 Cloudflare SSO 连接器，您可以使用所选身份提供商 (IdP) 对 Cloudflare 仪表板强制执行 SSO。SSO 将对您电子邮件域中的每个用户强制执行。

可用性

Cloudflare 仪表板 SSO 对所有套餐免费可用。

	Free	Pro	Business	Enterprise
Availability	Yes	Yes	Yes	Yes

前提条件

您必须控制您的电子邮件域，并能够添加 TXT 记录进行验证。
- 不允许使用 @gmail.com 等公共电子邮件提供商。
- 该电子邮件域的每个用户必须是您组织的员工。例如，不允许使用 @harvard.edu 等大学域，因为它们包含学生电子邮件。
您必须是超级管理员，并能够访问 Cloudflare API。
必须创建具有任何订阅层级（包括 Free）的 Cloudflare Zero Trust 组织。要设置 Cloudflare Zero Trust 组织，请参阅创建 Cloudflare Zero Trust 组织。

1. 设置 IdP

按照详细说明将 IdP 添加到 Cloudflare Zero Trust。

配置 IdP 后，请确保还测试您的 IdP。

2. 在 Cloudflare 注册 SSO 域名

在 Cloudflare One 中配置 IdP 后，转到 Members（成员） 页面管理 SSO 连接器。

Go to Members ↗

如果步骤 1 成功，将出现添加新 SSO 域名的按钮。选择该按钮开始添加新 SSO 域名的流程。

输入您的电子邮件域并选择 Create（创建） 进入验证步骤。

在已设置环境变量 CLOUDFLARE_API_TOKEN 为具有 SSO Connector Edit 权限的用户或账户 API 令牌的命令行终端中，运行以下命令创建 SSO 连接器。将 {account_id} 替换为您的账户 ID，将 {domain} 替换为您的电子邮件域。

cURL commandbash

curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/sso_connectors" \
  --request POST \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --json '{"email_domain":"{domain}"}'

{
	"success": true,
	"errors": [],
	"messages": [],
	"result": {
		"id": "c3ebcba5c20b42f73e111110d0be67d",
		"enabled": false,
		"email_domain": "cool.cats",
		"verification": {
			"code": "cloudflare_dashboard_sso=111111111",
			"status": "pending"
		},
		"created_on": "2025-09-05T20:35:34Z"
	}
}

3. 验证域名所有权

如果您暂时无法更改 DNS 记录，可以选择稍后验证。可以从列表中该连接器的操作菜单手动触发验证流程。

复制验证代码，并在 DNS 配置中创建包含该值的 TXT 记录。记录必须包含所有文本，包括 cloudflare_dashboard_sso= 前缀。

Cloudflare 将自动轮询此 DNS 记录，直到找到或两天内超时。

如果验证流程因超时而失败，可以通过选择列表中该连接器的操作菜单中的 Begin verification（开始验证） 手动重新启动轮询。

复制验证代码（例如 cloudflare_dashboard_sso=1111111），并在 DNS 配置中创建包含该值的 TXT 记录。要测试 DNS 记录是否正确配置，可以使用 dig 命令查询您的电子邮件域：

dig cool.cats TXT +short

"cloudflare_dashboard_sso=111111111"

TXT 记录必须包含 cloudflare_dashboard_sso= 前缀以及数字代码。

Cloudflare 将自动轮询此 DNS 记录，直到找到或两天内超时。如果验证因超时而失败，可以通过运行以下命令手动重新启动轮询：

cURL commandbash

curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/sso_connectors/{sso_connector_id}/begin_verification" \
  --request POST \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

验证流程完成或超时后，您将收到包含验证结果的电子邮件通知。

4. 启用仪表板 SSO

验证流程完成并成功验证域名所有权后，您可以启用连接器。

属于不同账户的已启用连接器关联的域名，在旧账户上禁用之前，无法在新账户上启用。

通过选择列表中该连接器 Actions 菜单中的 Enable（启用） 来启用连接器。

通过运行以下命令启用连接器——再次将 {account_id} 替换为您的账户 ID，并将 {sso_connector_id} 替换为从前一次调用响应的 id 字段获得的值。

cURL commandbash

curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/sso_connectors/{sso_connector_id}" \
  --request PATCH \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --json '{"enabled": true}'

在强制执行前测试 IdP

在为域名启用 SSO 之前，验证身份提供商配置是否正确：

在 Cloudflare 仪表板 ↗中，转到 Zero Trust > Integrations（集成） > Identity providers（身份提供商）。
找到您的 IdP 并选择 Test（测试）。
确认测试返回成功的身份验证结果。

如果测试失败，在启用 SSO 连接器之前，请根据身份提供商设置说明审查 IdP 配置。

排除 IdP 错误

如果在 IdP 设置或测试期间遇到错误，联系支持时请提供以下信息：

IdP 测试返回的错误消息。
在仪表板运行 IdP 测试时捕获的已清理 HAR 文件。

限制

Cloudflare 仪表板 SSO 不支持：

使用加号地址的电子邮件用户，例如 [email protected]。如果您有此类用户添加到 Cloudflare 组织，他们将无法使用 SSO 登录。
向 Zero Trust SSO 应用程序添加与 SSO 域名策略不匹配的单独基于电子邮件的策略。
多个 Zero Trust 域名策略。如果需要另一个域名策略，可以创建另一个 SSO 连接器。这将在 SSO 应用程序中为该新域名创建第二个策略。
删除自动生成的 Zero Trust allow email domain 策略。如果删除此策略，您组织的管理员将无法访问 Cloudflare 仪表板。

IdP 发起的 SSO

Cloudflare 仪表板 SSO 支持 IdP 发起的登录，可通过身份提供商 (IdP) 进行配置。

目前 Okta 有分步指南，支持自定义 SSO endpoint 的其他身份提供商也可以进行类似配置。

Okta

使用 Cloudflare Zero Trust 和 Okta 配置身份提供商 (IdP) 发起的单点登录 (SSO) 会话。

前提条件

在 Cloudflare 仪表板 ↗中，转到 Zero Trust > Access controls（访问控制） > Applications（应用程序） > 选择您的 SSO App（SSO 应用）。
选择 Configure（配置） 访问应用程序设置。
在 Basic Information（基本信息） 部分，复制 SSO Endpoint URL（SSO 端点 URL） 和 Access Entity ID or Issuer（Access 实体 ID 或颁发者）。IdP 设置需要这些值。

将 Okta 配置为 IdP

登录 Okta Admin Dashboard ↗，转到 Applications（应用程序） > Applications（应用程序）。
选择 Create App Integration（创建应用集成） 启动新的 SAML 集成以处理 IdP 发起的 SSO 流程。请注意，这是第二个独立的 Cloudflare-Okta 集成，与 Zero Trust 的 IdP 集成分开创建。
在弹出窗口中选择 SAML 2.0 并选择 Next（下一步）。
输入应用名称并选择 Next（下一步）。
在 Single Sign-On URL（单点登录 URL） 字段中，粘贴之前复制的 SSO Endpoint URL（SSO 端点 URL）。
在 Audience URI (SP Entity ID)（受众 URI（SP 实体 ID）） 字段中，粘贴之前复制的 Access Entity ID or Issuer（Access 实体 ID 或颁发者）。
将 Name ID Format（名称 ID 格式） 设置为 EmailAddress。
将 Application Username（应用程序用户名） 设置为 Email。
选择 Next（下一步） > Finish（完成） 保存集成。
转到 Okta User Dashboard，找到新应用磁贴并选择它以验证 SSO 流程，从而测试集成。

（可选）使用即时身份验证强制执行单一 IdP 登录

如果您仅使用一个 IdP（例如 Okta）进行 Cloudflare SSO，并希望用户跳过身份提供商选择提示：

在 Cloudflare 仪表板 ↗中，转到 Zero Trust > Access controls（访问控制） > Applications（应用程序） > 选择您的 SSO App（SSO 应用）。
转到 Authentication（身份验证）。
禁用 Accept all available identity providers（接受所有可用的身份提供程序），确保仅选择 Okta 作为登录方法。
启用 Apply instant authentication（应用即时身份验证），允许用户跳过身份提供商选择。

绕过仪表板 SSO

本节介绍在无法使用 SSO 登录时如何恢复对 Cloudflare 仪表板的访问。

选项 1：添加备用 IdP

如果 SSO IdP 提供商出现问题，您可以使用 API 添加备用 IdP。以下示例展示如何添加 Cloudflare One-time PIN 作为登录方法：

添加一次性 PIN 登录：

Required API token permissions

At least one of the following token permissions is required:

Access: Organizations, Identity Providers, and Groups Write

Add an Access identity providerbash

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/access/identity_providers" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"type": "onetimepin",
		"config": {}
	}'

获取 dash_sso Access 应用程序的 id。可以使用 jq ↗ 快速找到正确的应用程序：

cURL commandbash

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/access/apps" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  | jq '.result[] | select(.type == "dash_sso")'

   {
   	"id": "3537a672-e4d8-4d89-aab9-26cb622918a1",
   	"uid": "3537a672-e4d8-4d89-aab9-26cb622918a1",
   	"type": "dash_sso",
   	"name": "SSO App"
   	// ...
   }

使用上面获得的 id，更新 SSO App 以接受所有身份提供商。为避免覆盖现有配置，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/3537a672-e4d8-4d89-aab9-26cb622918a1" \
	--request PUT \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"id": "3537a672-e4d8-4d89-aab9-26cb622918a1",
		"uid": "3537a672-e4d8-4d89-aab9-26cb622918a1",
		"type": "dash_sso",
		"name": "SSO App",
		"allowed_idps": []
	}'

用户现在可以选择使用一次性 PIN 登录。

选项 2：禁用仪表板 SSO

导航到 Members（成员） 页面。

Go to Members ↗

转到 Settings（设置）。
选择列表中 SSO 连接器的操作菜单并选择 Disable（禁用）。
输入连接器的域名并点击确认以完成禁用操作。

以下 API 调用将禁用账户的 SSO 强制执行。此操作只能由具有 SSO connectors edit 角色或 Super Administrators 的 API 令牌执行。

获取 SSO 连接器 id：

cURL commandbash

curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/sso_connectors" \
  --request GET \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

   {
   	"result": [
   		{
   			"id": "d616ac82cc7f87153112d75a711c5c3c",
   			"email_domain": "cool.cats",
   			"enabled": true
   			// ...
   		}
   	],
   	"success": true,
   	"errors": [],
   	"messages": []
   }

禁用 SSO 连接器：

cURL commandbash

curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/sso_connectors/{connector_id}" \
  --request PATCH \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --json '{
    "enabled": false
  }'

   {
   	"result": [
   		{
   			"id": "d616ac82cc7f87153112d75a711c5c3c",
   			"email_domain": "cool.cats",
   			"enabled": false
   			// ...
   		}
   	],
   	"success": true,
   	"errors": [],
   	"messages": []
   }

用户现在可以使用 Cloudflare 账户电子邮件和密码登录。如果用户没有密码，可以在登录页面使用忘记密码方法创建密码。

更改 Zero Trust 团队名称

Cloudflare 不允许在创建 SSO 连接器时更改团队名称。要更改团队名称，必须禁用并删除 SSO 连接器。

导航到 Members（成员） 页面。

Go to Members ↗

转到 Settings（设置）。
禁用所有 SSO 连接器。
删除所有 SSO 连接器。

获取账户的所有 SSO 连接器。

cURL commandbash

curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/sso_connectors" \
  --request GET \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

使用上一步中每个连接器的 id 禁用任何活动的 SSO 连接器。

cURL commandbash

curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/sso_connectors/{connector_id}" \
  --request PATCH \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --json '{
    "enabled": false
  }'

使用上一步中每个连接器的 id 删除所有 SSO 连接器。

cURL commandbash

curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/sso_connectors/{connector_id}" \
  --request DELETE \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

在 Cloudflare 仪表板 ↗中，转到 Zero Trust > Reusable components（可重用组件） > Custom pages（自定义页面）。
在 Team domain（团队域名） 下，选择 Edit（编辑） 输入新团队名称。选择 Save（保存）。
在身份提供商中，使用新团队名称更新 Cloudflare 集成。例如，如果您使用 SAML IdP，需要更新 Single Sign-on URL 和 Entity ID 为 https://<new-team-name>.cloudflareaccess.com/cdn-cgi/access/callback。
使用在 Cloudflare 注册 SSO 域名中的步骤重新创建已删除的 SSO 连接器。
重新创建 SSO 连接器后，按照验证和启用步骤操作。