configuring-sso-and-scim

配置 SSO 和 SCIM

为 CockroachDB 配置单点登录（SSO）和 SCIM 2.0 预配，涵盖以下四个不同层面：

1. Cloud Console SSO — 为 CockroachDB Cloud Web 控制台配置 SAML 或 OIDC
2. DB Console SSO — 为 DB Console Web UI 配置 OIDC（仅限 Advanced/Enterprise）
3. SQL/Cluster SSO — 为 SQL 客户端连接配置基于 JWT 或 LDAP/AD 的身份验证
4. SCIM 2.0 — 在 Cloud Console 上自动预配用户

先决条件

• Console SSO/SCIM： 组织管理员权限 + ccloud CLI
• DB Console/SQL SSO： 集群管理员角色 + Advanced 或 Enterprise 计划（Standard/Basic 不支持 DB Console SSO）
• LDAP/AD： 仅限自托管（CockroachDB Cloud 不提供此功能）
• SCIM 2.0： 需要 Enterprise 计划

配置决策

继续之前，请确定用户需要配置哪些层面。询问用户需要启用以下哪些选项，然后仅执行下文相关的部分。

决策 1 — Cloud Console SSO：

• SAML： 适用于已有 SAML 基础设施的企业 IdP（Okta、Azure AD、PingOne）
• OIDC： 设置更简单，原生支持 Google Workspace 和现代 IdP
• 跳过： 不需要

决策 2 — DB Console SSO：

• 启用（OIDC）： 为 DB Console Web UI 启用 SSO。需要 Advanced 或 Enterprise 计划；Standard 或 Basic 计划不支持
• 跳过： 不需要或计划不支持

决策 3 — SQL/Cluster SSO 方法：

• 基于 JWT： 使用 JWT 令牌为 SQL 客户端连接进行身份验证的云原生方案。适用于 CockroachDB Cloud 和自托管集群
• LDAP/AD： 通过 Active Directory 或 OpenLDAP 直接进行目录身份验证。仅限自托管（CockroachDB Cloud 不提供此功能）
• 跳过： 不需要

决策 4 — SCIM 2.0 预配：

• 启用： 自动管理 IdP 与 Cloud Console 之间的用户生命周期（创建/更新/停用）。需要 Enterprise 计划
• 跳过： 手动管理 Cloud Console 用户

步骤

第 1 部分：Cloud Console SSO

Cloud Console SSO 可为 CockroachDB Cloud Web 控制台启用 SAML 或 OIDC 身份验证。

1.1 检查当前 SSO 配置

在 Cloud Console UI 中检查 SSO 状态（Organization Settings > Authentication）。

1.2a 配置 SAML SSO

如果用户在决策 1 中选择了 SAML，请按照本节操作。

1. 在 Cloud Console 中前往 Organization Settings > Authentication
2. 选择 SAML 作为 SSO 提供方类型
3. 配置 SAML 连接：
   • 输入 IdP 元数据 URL 或上传元数据 XML
   • 将 CockroachDB Cloud 的 ACS URL 和 Entity ID 复制到 IdP 中
   • 将 IdP 属性映射到 CockroachDB Cloud 用户字段（电子邮件、姓名）
4. 在 IdP 中创建 SAML 2.0 应用：
   • 将 Single sign-on URL 设置为 CockroachDB Cloud ACS URL
   • 将 Audience URI (SP Entity ID) 设置为 CockroachDB Cloud Entity ID
   • 将 Name ID format 设置为 Email Address
   • 映射属性：email、firstName、lastName
5. 在 IdP 中将用户或组分配给 SAML 应用

有关特定 IdP 的 SAML 配置说明（Okta、Azure AD），请参阅配置步骤参考。

1.2b 配置 OIDC SSO

如果用户在决策 1 中选择了 OIDC，请按照本节操作。

1. 在 Cloud Console 中导航到 Organization Settings > Authentication
2. 选择 OIDC 作为 SSO 提供商类型
3. 配置 OIDC 连接：
   • 输入 IdP 提供的 OIDC 发现 URL（例如，https://accounts.google.com/.well-known/openid-configuration）
   • 输入 IdP 提供的 Client ID 和 Client Secret
   • 在 IdP 中将重定向 URI 配置为指向 CockroachDB Cloud
4. 在 IdP 中创建 OIDC/OAuth 2.0 应用：
   • 将 Sign-in redirect URI 设置为 CockroachDB Cloud 的重定向 URI
   • 授予以下作用域：openid、profile、email
5. 在 IdP 中将用户或群组分配给 OIDC 应用

请参阅 配置步骤参考，了解特定 IdP 的 OIDC 说明（Okta、Azure AD、Google Workspace）。

1.3 测试 SSO 登录

1. 打开新的浏览器会话（或无痕窗口）
2. 导航到 CockroachDB Cloud Console 登录页面
3. 选择 Sign in with SSO
4. 确认重定向到 IdP，完成身份验证，然后重定向回 Cloud Console

1.4 强制使用 SSO（禁用密码登录）

确认 SSO 正常工作后：

1. 导航到 Organization Settings > Authentication
2. 启用 Require SSO，以禁用基于密码的登录
3. 确认存在一个紧急备用管理员账号（请参阅安全注意事项）

第 2 部分：DB Console SSO（OIDC）

此操作仅为 DB Console Web UI 配置 SSO，不适用于 SQL 客户端连接。 SQL 客户端 SSO 需在第 3 部分（JWT）或第 4 部分（LDAP/AD）中单独配置。

前提条件： 需要 Advanced 或 Enterprise 计划。Standard 或 Basic 计划不提供 DB Console SSO。

DB Console SSO 使用 OIDC 对登录 CockroachDB DB Console Web 界面的用户进行身份验证。

2.1 检查当前 DB Console SSO 配置

SHOW CLUSTER SETTING server.oidc_authentication.enabled;
SHOW CLUSTER SETTING server.oidc_authentication.provider_url;
SHOW CLUSTER SETTING server.oidc_authentication.client_id;

2.2 配置 DB Console SSO

-- Enable OIDC authentication for the DB Console
SET CLUSTER SETTING server.oidc_authentication.enabled = true;

-- Set the OIDC provider URL (your IdP's discovery endpoint)
SET CLUSTER SETTING server.oidc_authentication.provider_url = 'https://your-idp.example.com';

-- Set the client ID registered in your IdP
SET CLUSTER SETTING server.oidc_authentication.client_id = '<client-id>';

-- Set the client secret
SET CLUSTER SETTING server.oidc_authentication.client_secret = '<client-secret>';

-- Configure the claim field used for username mapping
SET CLUSTER SETTING server.oidc_authentication.claim_json_key = 'email';

-- Configure the principal regex (extract username from claim)
SET CLUSTER SETTING server.oidc_authentication.principal_regex = '^([^@]+)';

请参阅 配置步骤参考，了解特定 IdP 的 DB Console SSO 设置说明（Okta、Azure AD）。

2.3 测试 DB Console SSO

1. 在浏览器中打开 DB Console URL
2. 点击 Log in with OIDC
3. 使用 IdP 进行身份验证
4. 确认已登录 DB Console

第 3 部分：SQL/集群 SSO（JWT）

SQL/集群 SSO 使用来自 IdP 的 JWT 令牌对 SQL 客户端连接进行身份验证。这与 DB Console SSO（第 2 部分）相互独立 — 它用于验证 cockroach sql 和应用程序连接，而非 Web UI。

3.1 检查当前 JWT SSO 配置

SHOW CLUSTER SETTING server.jwt_authentication.enabled;
SHOW CLUSTER SETTING server.jwt_authentication.issuers.configuration;
SHOW CLUSTER SETTING server.jwt_authentication.jwks_auto_fetch.enabled;

3.2 配置 JWT 身份验证

-- Enable JWT authentication for SQL connections
SET CLUSTER SETTING server.jwt_authentication.enabled = true;

-- Configure the JWT issuer(s)
-- Format: JSON object with issuer URL and audience
SET CLUSTER SETTING server.jwt_authentication.issuers.configuration = '{
  "issuers": [
    {
      "issuer": "https://your-idp.example.com",
      "audience": "<client-id>"
    }
  ]
}';

-- Enable automatic JWKS fetching (recommended)
SET CLUSTER SETTING server.jwt_authentication.jwks_auto_fetch.enabled = true;

-- Configure the claim used for SQL username mapping
SET CLUSTER SETTING server.jwt_authentication.claim = 'email';

请参阅 配置步骤参考，了解特定 IdP 的 JWT 配置说明（Okta、Azure AD、Google）。

3.3 配置身份映射

将 IdP 身份（例如，电子邮件地址）映射到 SQL 用户名：

-- Map [email protected] -> user (strip domain)
SET CLUSTER SETTING server.identity_map.configuration = '
crdb /^(.*)@example\.com$ \1
';

3.4 启用自动用户预配（可选）

当用户首次通过 JWT 进行身份验证时，自动预配 SQL 用户：

SET CLUSTER SETTING security.provisioning.jwt.enabled = true;

启用后，对于已通过 JWT 身份验证但尚无账号的用户，系统会自动创建 SQL 用户。

3.5 测试 SQL/集群 SSO

# Obtain a JWT token from your IdP (method varies by IdP)
# Then connect using the token as the password with JWT auth enabled
cockroach sql --url "postgresql://<username>@<cluster-host>:26257/defaultdb?sslmode=verify-full&options=--crdb:jwt_auth_enabled=true" --external-io-implicit-credentials

JWT 令牌将作为密码传递。--crdb:jwt_auth_enabled=true 连接选项会告知 CockroachDB 将密码视为 JWT 令牌。

-- Verify the connection
SELECT current_user();

第 4 部分：LDAP/AD 身份验证

LDAP/AD 身份验证会直接通过 LDAP 目录（Active Directory 或 OpenLDAP）验证 SQL 凭据。仅适用于可自托管环境 — CockroachDB Cloud 不提供此功能。

警告 — HBA 按顺序匹配，命中即停止： HBA 规则按从上到下的顺序进行评估。系统使用第一个匹配的规则。类似 host all all all ldap ... 的规则会匹配来自所有地址的所有用户，并阻止任何用户回退到密码验证。始终将 LDAP 规则限定为特定用户或角色，以避免管理员账号被锁定。

4.1 检查当前 HBA 配置

SHOW CLUSTER SETTING server.host_based_authentication.configuration;

4.2 通过 HBA 配置 LDAP 身份验证

LDAP 身份验证通过 HBA（基于主机的身份验证）规则进行配置。始终将 LDAP 规则限定到特定数据库或用户——切勿使用 host all all all ldap。

-- Configure HBA for LDAP authentication scoped to specific users
-- The 'root' user and other admin users keep password auth
SET CLUSTER SETTING server.host_based_authentication.configuration = '
host all root all password
host all admin_user all password
host all all all ldap "ldapserver=ldap.example.com" "ldapport=389" "ldapbasedn=dc=example,dc=com" "ldapsearchattribute=uid" "ldapsearchfilter=(objectClass=inetOrgPerson)" "ldapbinddn=cn=readonly,dc=example,dc=com" "ldapbindpasswd=<bind-password>"
host all all all password
';

LDAP HBA 关键参数：

• ldapserver — LDAP 服务主机名
• ldapport — LDAP 服务端口（LDAP 使用 389，LDAPS 使用 636）
• ldapbasedn — 用户搜索的基础 DN
• ldapsearchattribute — 与 SQL 用户名匹配的属性（例如，OpenLDAP 使用 uid，AD 使用 sAMAccountName）
• ldapsearchfilter — **必需。**用于缩小用户搜索范围的 LDAP 筛选器（例如，(objectClass=inetOrgPerson)）
• ldapbinddn — 用于 LDAP 绑定/搜索的服务账户 DN
• ldapbindpasswd — 绑定 DN 服务账户的密码

**重要：**每个 HBA 选项都必须写成 "key=value"（整个 key=value 对放在一组引号中）。

有关 Active Directory、OpenLDAP、组映射和 LDAPS 示例，请参阅配置步骤参考。

4.3 在生产环境中使用 LDAPS（TLS）

在生产环境中，始终使用 LDAPS（通过端口 636 的 TLS 加密 LDAP），以加密传输中的凭据。请勿使用 ldaptls=1——此选项不受支持。请改用端口 636，并配置自定义 CA 证书：

-- Configure the LDAP CA certificate for TLS verification
SET CLUSTER SETTING server.ldap_authentication.domain.custom_ca = '-----BEGIN CERTIFICATE-----
<your-ldap-ca-certificate-pem>
-----END CERTIFICATE-----';

-- Set HBA to use LDAPS (port 636)
SET CLUSTER SETTING server.host_based_authentication.configuration = '
host all root all password
host all admin_user all password
host all all all ldap "ldapserver=ldap.example.com" "ldapport=636" "ldapbasedn=dc=example,dc=com" "ldapsearchattribute=uid" "ldapsearchfilter=(objectClass=inetOrgPerson)" "ldapbinddn=cn=readonly,dc=example,dc=com" "ldapbindpasswd=<bind-password>"
host all all all password
';

4.4 配置 LDAP 组到角色的映射

LDAP 组映射会根据 LDAP/AD 组成员身份分配 CockroachDB SQL 角色。组映射通过 ldapgrouplistfilter HBA 参数配置，而不是通过集群设置配置。

-- HBA with group-to-role mapping
SET CLUSTER SETTING server.host_based_authentication.configuration = '
host all root all password
host all admin_user all password
host all all all ldap "ldapserver=ad.corp.example.com" "ldapport=636" "ldapbasedn=ou=Users,dc=corp,dc=example,dc=com" "ldapsearchattribute=sAMAccountName" "ldapsearchfilter=(objectClass=user)" "ldapbinddn=cn=crdb-svc,ou=ServiceAccounts,dc=corp,dc=example,dc=com" "ldapbindpasswd=<service-account-password>" "ldapgrouplistfilter=(&(objectClass=group)(member={{.User.DN}}))"
host all all all password
';

LDAP 组 CN 会直接映射到 SQL 角色名称。该角色必须已在 CockroachDB 中创建：

CREATE ROLE IF NOT EXISTS db_admins;
GRANT admin TO db_admins;

4.5 启用自动用户预配（可选）

当 SQL 用户首次通过 LDAP 进行身份验证时，自动预配该用户：

SET CLUSTER SETTING security.provisioning.ldap.enabled = true;

4.6 测试 LDAP 身份验证

# Test with an LDAP user credential
cockroach sql --url "postgresql://<ldap-username>:<ldap-password>@<cluster-host>:26257/defaultdb?sslmode=verify-full"

-- Verify the user connected successfully
SELECT current_user();

-- If group mapping is enabled, verify role grants
SHOW GRANTS FOR <ldap-username>;

第 5 部分：Cloud Console 上的 SCIM 2.0

如果用户不需要自动用户预配，或者没有 Enterprise 计划，请跳过本节。

SCIM 2.0 可在 Cloud Console 上自动预配和取消预配用户，并将用户生命周期与 IdP 同步。

5.1 检查当前 SCIM 配置

在 Cloud Console UI（Organization Settings > Authentication > SCIM）中检查 SCIM 状态。ccloud CLI 目前不提供 SCIM 配置命令。

5.2 启用 SCIM 端点

1. 在 Cloud Console 中导航至 Organization Settings > Authentication > SCIM
2. 启用 SCIM 2.0 端点
3. 复制用于 IdP 配置的 SCIM 基础 URL 和 Bearer 令牌

5.3 为 SCIM 配置 IdP

在 IdP（Okta、Azure AD 等）中：

1. 添加新的 SCIM 预配集成
2. 输入第 5.2 步中的 SCIM 基础 URL
3. 输入用于身份验证的 Bearer 令牌
4. 配置预配操作：
   • 创建用户 — 在 CockroachDB Cloud 中创建新的 IdP 用户
   • 更新用户属性 — 同步姓名和电子邮件地址的更改
   • 停用用户 — 在 CockroachDB Cloud 中停用已从 IdP 移除的用户
5. 将用户或组分配到 SCIM 集成

有关特定 IdP 的 SCIM 设置，请参阅配置步骤参考。

5.4 验证 SCIM 预配

1. 在 IdP 中创建测试用户，并将其分配到 SCIM 集成
2. 检查 Cloud Console——几分钟内应该会显示该用户
3. 从 IdP 的 SCIM 分配中移除测试用户
4. 确认该用户已在 Cloud Console 中停用

故障排除

SSO 锁定恢复

如果已强制启用 SSO，而 IdP 不可用或配置错误：

1. **使用应急账户：**使用预先配置的基于密码的管理员账户登录
2. **禁用 SSO 强制要求：**导航至 Organization Settings > Authentication，并禁用“Require SSO”
3. **如果没有应急账户：**联系 CockroachDB Cloud 支持，请求为组织禁用 SSO 强制要求

**预防措施：**在强制启用 SSO 之前，务必创建并测试应急管理员账户。

JWT 身份验证错误

“ERROR: JWT authentication: invalid token”

• 验证 server.jwt_authentication.issuers.configuration 中的 JWT 颁发者配置
• 检查 JWT 令牌是否已过期
• 验证 server.jwt_authentication.jwks_auto_fetch.enabled 是否为 true
• 检查令牌内容：echo '<token>' | cut -d. -f2 | base64 -d | jq .
• 验证令牌中的 aud（受众）声明是否与配置的受众匹配

“ERROR: JWT authentication: issuer not configured”

• 令牌中的颁发者 URL 与 server.jwt_authentication.issuers.configuration 不匹配
• 重新检查颁发者 URL 是否完全一致（末尾的斜杠也有影响）

DB Console OIDC 错误

“OIDC: unable to match principal”

• server.oidc_authentication.principal_regex 与令牌中的声明值不匹配
• 使用实际声明值测试正则表达式：

SHOW CLUSTER SETTING server.oidc_authentication.principal_regex;
-- Common patterns:
-- Email -> username (strip domain): '^([^@]+)'
-- Full email as username: '^(.+)$'

不接受复杂正则表达式：

• CockroachDB 使用 Go 的 regexp 语法（不支持前瞻和后顾）
• 在 https://regex101.com/ 上使用 “Golang” 模式进行测试

LDAP 身份验证错误

“ERROR: LDAP authentication: unable to bind”

• 验证 ldapbinddn 和 ldapbindpasswd 是否正确
• 检查绑定服务帐户是否具有用户搜索基准的读取权限
• 使用以下命令进行测试：ldapsearch -H ldap://ldap.example.com -D "cn=readonly,dc=example,dc=com" -W -b "dc=example,dc=com" "(uid=testuser)"

“ERROR: LDAP authentication: user not found”

• 验证 ldapbasedn 是否包含用户所在的 OU
• 检查 ldapsearchattribute 是否与登录属性匹配（OpenLDAP 使用 uid，AD 使用 sAMAccountName）
• 检查是否设置了 ldapsearchfilter——如果未设置，LDAP 用户搜索将失败

LDAP 锁定——所有用户均被阻止

• 如果类似 host all all all ldap ... 的过于宽泛的 HBA 规则排在第一条，且 LDAP 服务无法访问，或者 LDAP 配置有误，就会发生此问题
• 修复方法： 确保在任何 ldap 规则之前，为 root 和管理员用户设置明确的 password 规则
• 恢复方法： 使用客户端证书身份验证以 root 身份连接（可绕过 HBA），然后修复 HBA 配置

无法访问 LDAP 服务

• 验证 CockroachDB 节点与 LDAP 服务之间的网络连接
• 对于 LDAPS，确保通过 server.ldap_authentication.domain.custom_ca 配置了 CA 证书
• 检查端口 389（LDAP）或 636（LDAPS）的防火墙规则

Azure AD / Entra ID 特定问题

令牌受众不匹配：

• Azure AD 令牌包含一个必须与配置的受众匹配的 aud 声明
• 对于 JWT SQL SSO：确保 server.jwt_authentication.issuers.configuration 中的受众匹配
• 对于 DB Console OIDC：确保 server.oidc_authentication.client_id 匹配

多租户与单租户：

• 对于单租户：使用 https://login.microsoftonline.com/<tenant-id>/v2.0 作为颁发者
• 对于多租户：使用 https://login.microsoftonline.com/common/v2.0（需要额外验证）

缺少 ldapsearchfilter

如果 LDAP 身份验证失败并提示“user not found”，但用户确实存在于目录中，请检查 HBA 规则中是否包含 ldapsearchfilter。此参数为必需项；如果未设置，LDAP 搜索可能会静默失败或不返回任何结果。

安全注意事项

SSO 配置错误可能导致用户无法登录。 如果强制启用 SSO 后，IdP 宕机或配置错误，则无人能够登录。

缓解措施 — 紧急备用账户：

1. 强制启用 SSO 前，确保至少有一个组织管理员账户使用密码身份验证
2. 将紧急备用账户凭据记录在安全保险库中（例如，1Password、HashiCorp Vault）
3. 定期测试紧急备用账户，确保其仍可正常使用
4. 对于 SQL SSO（JWT 或 LDAP），至少保留一个使用密码身份验证的 SQL 用户作为备用

HBA 规则按顺序匹配，首条匹配规则生效 — 有锁定账户的风险： HBA 规则按从上到下的顺序进行评估。首条匹配的规则生效。这意味着：

• 如果将 host all all all ldap ... 设为第一条规则，则会强制所有用户通过 LDAP 进行身份验证，包括 root
• 如果 LDAP 服务器宕机，所有身份验证都会失败（包括管理员访问）
• 务必将 root 和管理员用户的密码规则放在 LDAP 规则之前

危险配置示例：

# DANGEROUS — locks out root if LDAP is unavailable
host all all all ldap ...
host all all all password

安全配置：

# SAFE — root and admins always have password fallback
host all root all password
host all admin_user all password
host all all all ldap ...
host all all all password

SCIM 风险：

• 大规模停用账户： 如果 IdP 中意外移除了 SCIM 分配，所有已预配用户都可能被停用。全面启用前，请先从小范围的用户组开始。
• 属性映射错误： 属性映射不正确可能会创建名称或电子邮件地址错误的用户。请先用单个用户进行测试。

LDAP/AD 风险：

• LDAP 服务器不可用会阻止身份验证： 如果 LDAP 服务器宕机，通过 LDAP 进行身份验证的用户将无法连接。务必为管理员用户保留基于密码的备用 HBA 规则。
• LDAP 绑定使用受限的服务账户： ldapbinddn 账户应仅具有最低限度的只读权限。切勿使用域管理员账户。
• 未使用 LDAPS 会导致凭据泄露： 未启用 TLS 的 LDAP 会以明文传输密码。生产环境中务必使用 LDAPS（端口 636），并配置 server.ldap_authentication.domain.custom_ca。

回滚

禁用 Cloud Console SSO 强制要求

1. 使用紧急备用管理员账户登录
2. 前往 组织设置 > 身份验证
3. 禁用 Require SSO，以重新启用密码登录

禁用 DB Console SSO（OIDC）

SET CLUSTER SETTING server.oidc_authentication.enabled = false;

禁用 SQL/集群 SSO（JWT）

SET CLUSTER SETTING server.jwt_authentication.enabled = false;

禁用 LDAP/AD 身份验证

-- Revert HBA to password-only authentication
SET CLUSTER SETTING server.host_based_authentication.configuration = '
host all all all password
';

禁用自动用户预配

-- Disable JWT auto-provisioning
SET CLUSTER SETTING security.provisioning.jwt.enabled = false;

-- Disable LDAP auto-provisioning
SET CLUSTER SETTING security.provisioning.ldap.enabled = false;

禁用 SCIM

1. 前往 组织设置 > 身份验证 > SCIM
2. 禁用 SCIM 端点
3. 从 IdP 中移除 SCIM 集成

移除身份映射

SET CLUSTER SETTING server.identity_map.configuration = '';

参考资料

技能参考：

• IdP 配置步骤

相关技能：

• auditing-cloud-cluster-security — 执行完整的安全态势审计
• enforcing-password-policies — 通过强化密码策略作为 SSO 的替代方案
• managing-tls-certificates — 使用基于证书的身份验证作为 SSO 的替代方案

CockroachDB 官方文档：

• Cloud Console SSO
• DB Console SSO
• 集群 SSO（JWT）
• SCIM 预配
• 集群设置
• HBA 配置
• JWT 身份验证
• LDAP 身份验证
• 身份验证参考