configuring-sso-and-scim

用途

该技能用于为 CockroachDB 配置单点登录（SSO）与 SCIM 2.0 用户自动预配，覆盖四个相互独立的层面：

• Cloud Console SSO：为 CockroachDB Cloud Web 控制台配置 SAML 或 OIDC 认证。
• DB Console SSO：为 DB Console Web UI 配置 OIDC 认证（仅 Advanced/Enterprise 计划）。
• SQL/集群 SSO：为 SQL 客户端连接配置基于 JWT 或 LDAP/AD 的认证。
• SCIM 2.0：在 Cloud Console 上实现用户自动预配与取消预配。

主要能力

• 支持 Cloud Console 的 SAML 与 OIDC 两种 SSO 方式，包含 IdP 元数据、ACS URL、Entity ID、属性映射等配置。
• 支持 DB Console 的 OIDC 认证，通过集群设置启用并配置 provider URL、client ID/secret、claim 字段与 principal 正则。
• 支持 SQL/集群的 JWT 认证，可配置 issuer、audience、JWKS 自动获取、claim 映射与身份映射。
• 支持 LDAP/AD 认证，通过 HBA 规则配置，包含 LDAP 服务器、端口、base DN、搜索属性、搜索过滤器、绑定 DN 与密码等参数。
• 支持 LDAP 组到 SQL 角色的映射，通过 ldapgrouplistfilter 参数实现。
• 支持 JWT 与 LDAP 的自动用户预配（security.provisioning.jwt.enabled / security.provisioning.ldap.enabled）。
• 支持 SCIM 2.0 端点启用与 IdP 侧预配集成配置。
• 提供各层的测试方法与常见故障排查指引。

使用方式

技能首先要求用户确认需要配置哪些层面（Decision 1 至 Decision 4），然后仅执行相关部分：

• Part 1：Cloud Console SSO（SAML 或 OIDC），包含检查当前配置、配置连接、测试登录、强制 SSO。
• Part 2：DB Console SSO（OIDC），通过 SHOW/SET CLUSTER SETTING 命令配置。
• Part 3：SQL/集群 SSO（JWT），配置 JWT 认证、身份映射、自动用户预配并测试。
• Part 4：LDAP/AD 认证，通过 HBA 规则配置，包含 LDAPS 与组映射。
• Part 5：SCIM 2.0，在 Cloud Console 启用端点并在 IdP 配置预配。

配置过程中涉及具体命令与参数，例如：

SET CLUSTER SETTING server.oidc_authentication.enabled = true;
SET CLUSTER SETTING server.jwt_authentication.enabled = true;
SET CLUSTER SETTING security.provisioning.jwt.enabled = true;
SET CLUSTER SETTING security.provisioning.ldap.enabled = true;

LDAP HBA 配置示例：

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
';

JWT 连接测试示例：

cockroach sql --url "postgresql://<username>@<cluster-host>:26257/defaultdb?sslmode=verify-full&options=--crdb:jwt_auth_enabled=true" --external-io-implicit-credentials

适用场景

• 企业需要将 CockroachDB Cloud 控制台接入现有 IdP（如 Okta、Azure AD、PingOne、Google Workspace）实现 SSO。
• 需要为 DB Console Web UI 启用 OIDC 登录（需 Advanced 或 Enterprise 计划）。
• 需要为 SQL 客户端连接启用 JWT 或 LDAP/AD 认证。
• 需要基于 LDAP/AD 组自动映射 SQL 角色。
• 需要通过 SCIM 2.0 实现用户生命周期自动化管理（需 Enterprise 计划）。

限制

• DB Console SSO 仅支持 Advanced 或 Enterprise 计划，Standard/Basic 计划不可用。
• LDAP/AD 认证仅支持自托管集群，CockroachDB Cloud 不可用。
• SCIM 2.0 需要 Enterprise 计划。
• LDAPS 生产环境应使用端口 636，不支持 ldaptls=1 选项。
• HBA 规则采用首个匹配生效，需将 LDAP 规则限定到特定用户或角色，避免锁定管理员账户。
• CockroachDB 使用 Go 正则语法，不支持 lookahead/lookbehind。
• 强制 SSO 前必须创建并测试 break-glass 管理员账户，否则 IdP 故障时可能无法登录。
• ccloud CLI 当前不提供 SCIM 配置命令，SCIM 需通过 Cloud Console UI 配置。
• 部分 IdP 特定配置步骤需参考外部配置步骤参考文档，本资料未提供具体内容。