> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 通过 Okta 进行 SCIM 预配
> 如何在 Okta 与 ClickHouse Cloud 之间设置 SCIM 预配
export const PrivatePreviewBadge = () => {
return
{'Private preview in ClickHouse Cloud'}
;
};
export const EnterprisePlanFeatureBadge = ({feature = 'This feature', support = false, linking_verb_are = false}) => {
return
Enterprise plan feature
{feature} {linking_verb_are ? 'are' : 'is'} available in the Enterprise plan. {support ? `Contact support to enable this feature.` : 'To upgrade, visit the plans page in the cloud console.'}
;
};
export const Image = ({img, alt, size}) => {
return
;
};
SCIM 预配目前处于私有预览阶段。
ClickHouse Cloud 支持 SCIM 2.0 (System for Cross-domain Identity Management，跨域身份管理) ，用于自动化管理用户和组的生命周期。连接到您的身份提供商后，您分配给 ClickHouse Cloud 应用的每位用户都会自动在您的组织中创建，并获得相应的角色；profile 更新也会自动同步；而从您的 IdP 中移除某位用户时，其访问权限也会一并移除——无需手动邀请，也不会留下孤立账户。
本指南将逐步介绍如何使用 **Okta** 端到端设置 SCIM 预配。ClickHouse Cloud 的 SCIM 端点遵循 SCIM 2.0 (RFC 7644) ，但仅支持通过 Basic Auth 进行身份验证，并且 Okta 是我们唯一测试过的身份提供商。其他 SCIM 2.0 IdP 如果支持使用 Basic Auth 进行身份验证，也可能可以正常工作，但目前尚未获得官方支持。
## 开始之前
你需要准备：
* 在你的 ClickHouse Cloud 组织中拥有 **Admin** 角色。
* 已在你的 IdP 与 ClickHouse Cloud 之间配置好 [SAML 单点登录](/zh/cloud/security/saml-setup)。SCIM 会创建用户账户；这些账户通过 SAML 登录，因此必须先确保 SSO 已正常工作。
* 拥有 Okta 租户的超级管理员权限，并具备安装应用和配置预配的权限。
* 一份你希望通过 SCIM 分配的角色列表 (例如：Admins、Developers、Read-only) 。请提前确定这些角色——你需要在 Okta 中创建对应的组。
## SCIM 在 ClickHouse Cloud 中的工作方式
1. Okta 中的管理员将用户直接或通过组分配给 ClickHouse Cloud 应用。
2. Okta 通过 HTTPS 调用 ClickHouse Cloud 的 SCIM 端点，并使用你生成的令牌进行身份验证。
3. ClickHouse Cloud 会在你的组织中创建该用户，并根据 Okta 的组成员身份分配 角色。
4. 用户通过你现有的 SAML 单点登录流程登录 ClickHouse Cloud。
5. 在 Okta 中对用户资料、组以及停用状态所做的更改，会自动同步到 ClickHouse Cloud。
## 在您的 ClickHouse Cloud 组织中配置 SCIM
### 启用 SCIM
以组织管理员身份登录 **ClickHouse Cloud 控制台**，然后打开 **组织设置 → SAML 和 SCIM 设置 → SCIM 配置**。
点击 `Enable SCIM`。连接 SAML 单点登录后，SCIM 才会解锁；如果该选项显示为灰色，请先完成 SAML 设置。
系统会生成一个 **SCIM 端点 URL**，格式如下：
```plaintext theme={null}
https://api.clickhouse.cloud/v1/organizations//scim
```
复制它——稍后您需要将其粘贴到 Okta 中。
### 生成 SCIM 访问令牌
找到 `Create an API key` 部分，并选择过期日期。
**提前规划轮换。** 我们建议将有效期设置为 12 个月，并添加日历提醒。ClickHouse Cloud 最多可同时支持两个处于活动状态的 SCIM 令牌，因此您可以在不停机的情况下完成轮换：生成新令牌，将 Okta 切换到新令牌，确认预配仍正常工作，然后撤销旧令牌。
点击 `Generate key`。该令牌**只会显示一次**，包含一个密钥 (前缀为 `scim_`) 和一个 secret。请立即复制这两项，并将其存储到安全的 secrets manager 中——之后无法再次查看。如果丢失，请撤销该令牌并生成新令牌。
### 定义角色映射
在 SCIM 配置 面板中，点击 **Map roles in "用户和角色"** (或直接进入 **用户和角色 → Roles**) 。
SCIM 组会按名称绑定到 ClickHouse Cloud 角色，但需要注意以下规则：
* **您不能将 SCIM 组映射到预定义的系统角色。** SCIM 映射仅适用于自定义角色。如果您需要通过 SCIM 提供系统级能力，请创建一个包含所需权限的自定义角色。
* **同名会自动关联。** 如果某个自定义角色与传入的 SCIM 组同名，ClickHouse Cloud 会自动将它们关联起来——无需手动映射。
* **如果要使用与组名不同的角色名**，请先用您想要的角色名创建自定义角色，然后将其 **SCIM group** 字段设置为它应绑定的 SCIM 组名称。
* **未映射的组会创建新角色。** 如果 Okta 推送了一个组，而该组既不匹配现有角色名称，也未被任何角色的 `SCIM group` 字段引用，ClickHouse Cloud 会使用该组名称创建一个新的自定义角色。随后，您可以为其授予所需权限。
## 在 Okta 中配置 ClickHouse Cloud 应用
### 在 Okta 中打开您的 ClickHouse Cloud 应用
在 **Okta Admin Console** 中，前往 **Applications → Applications**，搜索您在为 ClickHouse Cloud 配置 SAML 单点登录时创建的应用。打开它。
如果您尚未创建该 SAML 应用，请先参考 [SAML SSO 设置指南](/zh/cloud/security/saml-setup)——SCIM 预配也是在同一个应用中配置的。
在 **General** 选项卡中，找到 **App Settings** 部分并点击 `Edit`。在 **Provisioning** 下选择 `SCIM`，然后点击 `Save`。
现在，该应用会显示一个 **Provisioning** 选项卡。
### 将 Okta 连接到 SCIM 端点
打开应用的 **Provisioning** 选项卡，然后点击 `Edit`。填写表单：
* **SCIM connector base URL** — 前面步骤中的 SCIM 端点 URL。
* **Unique identifier field for users** — `userName`。
* **Supported provisioning actions** — 选择以下所有项：
* 导入新用户和个人资料更新
* 推送新用户
* 推送个人资料更新
* 推送组
* 导入组
* **Authentication Mode** — `Basic Auth`。
* **Username** — SCIM 令牌 **key** (以 `scim_` 开头) 。
* **Password** — SCIM 令牌 **secret**。
点击 `Test Connector Configuration`。你应会看到绿色的确认提示。如果失败，请跳转到[故障排查](#troubleshooting)。
点击 `Save`。
### 配置预配行为
仍在 **Provisioning** 选项卡中，点击左侧边栏中的 `To App`。点击 `Edit` 并启用：
| 设置 | 操作 | 作用 |
| ---------------------- | ------- | --------------------------------------------- |
| Create Users | Enable | 在 Okta 中分配给应用时，在 ClickHouse Cloud 中创建新用户 |
| Update User Attributes | Enable | 自动同步 profile 变更 (姓名、电子邮件等) |
| Deactivate Users | Enable | 当用户在 Okta 中被取消分配或停用时，将其从 ClickHouse Cloud 中移除 |
| Sync Password | Disable | 不使用——登录通过 SAML 完成，而不是通过密码 |
点击 `Save`，然后返回该应用的 **Sign On** / **Provisioning** 选项卡，确认这些设置已生效。
### 映射用户属性
Okta 和 ClickHouse Cloud 需要就用户字段的对应关系保持一致。在 **Provisioning** 选项卡中，点击 `To App`，然后检查你的应用的 **Attribute Mappings**。Okta SAML 应用的默认设置通常就可以满足需求——请核对下表：
| Okta attribute | ClickHouse Cloud (SCIM) attribute | Required |
| ----------------- | --------------------------------- | ------------------------------ |
| `userName` | `userName` | **是** — 用作唯一标识符和主电子邮箱 |
| `email` (primary) | `emails[primary].value` | **是** — 必须与 `userName`` `一致 |
| `firstName` | `name.givenName` | 推荐 |
| `lastName` | `name.familyName` | 推荐 |
| `displayName` | `displayName` | 推荐 — 显示在 ClickHouse Cloud UI 中 |
| `externalId` | `externalId` | 推荐 — 可提高匹配校验时的准确性 |
你还可以添加部门、主管和位置等可选属性——ClickHouse Cloud 会将它们存储在用户资料中，但目前不会将其用于权限控制。任何不属于 SCIM 标准集的属性都会在 ClickHouse Cloud 端被忽略。
**电子邮箱大小写很重要。** 请确保 Okta 中的 `userName` 和 `email` 使用完全相同的大小写。ClickHouse Cloud 会将电子邮箱规范化为小写；如果这两个字段的大小写不一致，可能会导致测试失败。
### 推送组并分配用户
角色就是在这里自动应用的。
**在 Okta 中创建组。** 对于你之前设置的每个角色映射，在 Okta 中创建或确认一个**显示名称完全一致**的组。例如，如果你的映射是 `ClickHouse-Admins → Admin`，就在 Okta 中创建一个名为 `ClickHouse-Admins` 的组。
打开你刚创建的组，然后点击 `Assign people`，将成员添加到该组。
然后将 SCIM 应用也分配给同一个组，这样角色成员关系和应用访问权限就能保持同步。
**推送这些组。** 在应用的 **Provisioning** 选项卡中，点击 `Push Groups → Find groups by name`，搜索你的组，然后点击 `Save`。对每个角色组重复此操作。预配完成后，每个组的 **Push Status** 都应显示为 **Active (Pushed)**。
**分配用户。** 你有两种方式：
* **通过组 (推荐) 。** 将用户添加到你刚刚推送的 Okta 组中。他们会被预配到 ClickHouse Cloud，并自动分配相应角色。
* **直接分配。** 在应用的 **Assignments** 选项卡中，点击 `Assign → Assign to People` 并选择单个用户。除非他们同时属于某个已推送的组，否则会按 **Default role** 进行预配。
基于组的分配更便于长期管理——当某人的角色发生变化时，你只需要更新组成员关系。
## 测试集成
配置好预配后，返回 ClickHouse Cloud 控制台中的 **设置 → 用户和角色**，确认已同步的用户已经出现，并且具备预期的角色。
在将其分配给整个团队**之前**，先用一到两个测试用户执行这份简短的测试计划。每一步都应在几秒内成功；如果没有，请检查 Okta 的 Tasks 队列以及[故障排查](#troubleshooting)部分。
| # | 在 Okta 中的操作 | 在 ClickHouse Cloud 中的预期结果 |
| - | ---------------------------------------------------- | ---------------------------------- |
| 1 | 将一个测试用户添加到 `ClickHouse-Admins` Okta 组 | 用户会出现在 **设置 → 成员** 中，角色为 **Admin** |
| 2 | 测试用户通过 SSO 登录 ClickHouse Cloud | 用户会进入仪表板，并拥有管理员访问权限 |
| 3 | 在 Okta 中更新该用户的名 | 更新后的名称会在几秒内显示在 **成员** 中 |
| 4 | 将该用户从 `ClickHouse-Admins` 移动到 `ClickHouse-Read-only` | 其角色会变为 **只读** |
| 5 | 取消该用户对应用的分配 (或在 Okta 中停用该用户) | 用户会从组织中移除；后续登录尝试将失败 |
如果任何一步失败，请先解决根本问题后再继续——这些症状通常会连带放大。
**在 Okta 中哪里查看 SCIM 错误。** SCIM 错误会显示在 **Reports → System Log** 中 (按你的应用过滤) ，以及该应用的 **Provisioning → View Logs** 页面中。ClickHouse Cloud 返回的错误消息会原样显示——先从这里查起。
## 生产环境最佳实践
**定期轮换令牌。** 为 SCIM 令牌轮换设置日历提醒。建议周期：每 12 个月一次；或者只要有知晓该令牌的管理员离开公司，就立即轮换。ClickHouse Cloud 允许每个组织同时保留两个有效令牌，正是为了让你在轮换时不影响预配。
**使用组，而不是直接分配。** 直接将用户分配给应用程序虽然可行，但很快就会难以审计。通过 Okta 组来管理分配，意味着访问审查和角色变更都可以在同一个地方完成。
**查看审计日志。** 每一次 SCIM 操作——创建用户、停用用户、更新 profile——都会记录在 ClickHouse Cloud 审计日志中。请参阅 [Audit logging](/zh/cloud/security/audit-logging)。应定期检查日志，尤其是在大规模预配之后。
**设置合理的默认角色。** 如果某个 Okta 用户被分配给应用程序，但不在任何已推送的组中，系统就会使用 **默认角色** 创建该用户。请选择限制最严格、但仍能让用户完成*一些*操作的角色，这样即使配置有误，也能以更安全的方式失败。
**避免同时使用 SCIM 和手动邀请。** 一旦启用 SCIM，就应通过 Okta 管理成员关系——不要再向同一批用户发送手动邀请。混用这两种方式会让“谁才是事实来源”变得模糊，并且可能产生重复项。
**监控失败的预配任务。** Okta 会重试失败的预配调用，但最终会将它们放入 **Tasks** 队列。把这个队列加入你的 IT 团队已在监控的仪表盘，或者使用 Okta 的 webhook 或电子邮件告警来标记持续发生的故障。
## 故障排查
### Okta 中“测试连接器配置”失败
* 确认已在 ClickHouse Cloud 控制台中**启用** SCIM。
* 确认 Okta 中的 **base URL** 与 Cloud 控制台中显示的 SCIM 端点 URL 完全一致——组织 ID 必须正确。
* 确认粘贴的 **token key and secret** 前后没有多余空白字符。
* 如果你已轮换令牌，请确保使用的是**新的** key 和 secret，而不是之前那一对。
### 用户已创建，但没有任何权限
* 检查你是否已在 **“用户和角色”中的“映射角色”** 下，为所需角色添加了一行。
* 检查 Okta 组名是否与映射中的 SCIM 组名**完全**一致，包括大小写和连字符。
* 如果你的设计本来就会为部分用户预配而不分配任何组，请确认已设置 **默认角色**。
### 成员列表中有重复用户
这通常是因为 Okta 与之前的手动邀请使用了大小写不一致的电子邮件地址。请从 Members 列表中删除重复项，然后在 Okta 中先取消分配该用户，再重新分配，以重新完成预配。
### 组推送失败，并提示“displayName not recognised”
Okta 中的组名与 ClickHouse Cloud 中已配置的映射不一致。请重命名 Okta 组，或在 SCIM 配置 面板的 **Map roles in "用户和角色"** 下添加映射 (也可通过 **用户和角色 → Roles** 添加) 。
### 已停用的用户仍显示为成员
Okta 传播停用状态最多可能需要一分钟。如果几分钟后该用户仍然显示为成员，请检查 Okta 的 **Provisioning → View Logs**，查看停用任务是否报错。
### 我轮换了 SCIM 令牌，现在 Okta 无法正常工作
请检查你是否在 Okta 的**同一个 SCIM 应用**中更新了凭据。更新后，点击 `Test Connector Configuration` 进行确认。待预配状态恢复为绿色后，再到 ClickHouse Cloud 控制台中撤销旧令牌。
### 我把 SCIM 令牌弄丢了
令牌无法找回。请在 ClickHouse Cloud 控制台的 **组织设置 → SAML 和 SCIM 设置 → SCIM 配置** 中撤销丢失的令牌并生成新令牌，然后更新 Okta 中的凭据。
## 常见问题
**在使用 SCIM 之前，是否需要先配置 SAML 单点登录？**
是的。SCIM 会创建用户账户，但 ClickHouse Cloud 通过 SAML 对这些账户进行身份验证。请先设置 [SAML 单点登录](/zh/cloud/security/saml-setup)。
**SCIM 能否与 Microsoft Entra ID、OneLogin 或其他 SCIM 2.0 IdP 配合使用？**
官方来说，不能——目前我们只测试并支持 Okta 这一种 IdP。该端点遵循 SCIM 2.0 (RFC 7644) ，但身份验证仅支持 Basic Auth，因此任何无法通过 Basic Auth 进行身份验证的 IdP 都无法使用。其他支持 Basic Auth 的 SCIM 2.0 IdP 在实际使用中可能可行，但我们不作任何保证。
**Okta 中的更改多久会显示在 ClickHouse Cloud 中？**
大多数操作会在几秒内同步完成。批量更改 (大型组推送) 可能会因规模而需要更长时间，不过 Okta 会在出现瞬时错误时自动重试。
**能否通过单个 Okta 租户为多个 ClickHouse Cloud 组织开通配置？**
可以——每个组织分别安装一次应用，并为其配置各自的 SCIM 端点 URL 和令牌。根据需要将相同的 Okta 组推送到每个应用即可。
**如果遇到问题，我该在哪里寻求帮助？**
请在 ClickHouse Cloud 控制台中提交支持工单 (**Help → Contact support**) ，并附上：
* 你的组织 ID，
* 你的 Okta 应用 ID，以及
* Okta 日志中失败任务或测试的截图。