> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 Microsoft Entra ID 配置 SCIM 预配

> 如何在 Microsoft Entra ID 和 ClickHouse Cloud 之间配置 SCIM 预配

export const EnterprisePlanFeatureBadge = ({feature = '此功能', support = false, linking_verb_are = false}) => {
  return <div className="enterprisePlanFeatureContainer">
            <div className="enterprisePlanFeatureBadge">
                Enterprise 计划功能
            </div>
            <div>
                <p>{feature} {linking_verb_are ? '可在' : '可在'} Enterprise 计划中使用。{support ? `请联系支持团队以启用此功能。` : '如需升级，请前往 Cloud Console 的套餐页面。'}</p>
            </div>
        </div>;
};

<EnterprisePlanFeatureBadge feature="SCIM" />

ClickHouse Cloud 支持 SCIM 2.0 (跨域身份管理系统) ，可自动管理用户和组的生命周期。连接身份提供商后，您分配给 ClickHouse Cloud 应用的每位用户都会自动在组织中创建，并获得相应角色；profile 更新会自动同步；从 IdP 中移除用户也会撤销其访问权限——无需手动邀请，也不会留下孤立账户。

本指南将介绍如何使用 **Microsoft Entra ID** (原 Azure Active Directory) 端到端配置 SCIM 预配。ClickHouse Cloud 的 SCIM 端点遵循 SCIM 2.0 (RFC 7644) 。Entra ID 使用长期有效的 Bearer 令牌对该端点进行身份验证；该令牌由您在 ClickHouse Cloud 控制台中生成的 SCIM 令牌密钥和机密值组合而成。

<Tip>
  **使用 Okta？**

  如果您的身份提供商是 Okta，请参阅[使用 Okta 进行 SCIM 预配](/docs/zh/products/cloud/guides/security/cloud-access-management/scim-setup)指南。ClickHouse Cloud 端的配置完全相同；仅 IdP 配置有所不同。
</Tip>

<div id="before-you-begin">
  ## 开始之前
</div>

您需要：

* 在您的 ClickHouse Cloud 组织中拥有 **Admin** 角色。
* 已在 Entra ID 与 ClickHouse Cloud 之间配置 [SAML 单点登录](/docs/zh/products/cloud/guides/security/cloud-access-management/saml-sso-setup)。SCIM 会创建用户账户；这些账户通过 SAML 登录，因此必须先确保 SSO 正常运行。
* 有权访问 **Microsoft Entra 管理中心**，且至少拥有 **Application Administrator** (或 **Cloud Application Administrator**) 角色，并具有为企业应用程序配置预配的权限。
* 要通过 SCIM 分配的角色列表 (例如：Admins、Developers、只读) 。请提前确定此列表，因为您需要在 Entra ID 中创建对应的组。

<div id="how-scim-works">
  ## SCIM 如何与 ClickHouse Cloud 配合使用
</div>

1. Entra ID 中的管理员可直接或通过群组将用户分配给 ClickHouse Cloud 企业应用程序。
2. Entra ID 的预配服务通过 HTTPS 调用 ClickHouse Cloud SCIM 端点，并使用您生成的 Bearer 令牌进行身份验证。
3. ClickHouse Cloud 会在您的组织中创建用户，并根据其 Entra ID 群组成员身份分配角色。
4. 用户通过您现有的 SAML 单点登录流程登录 ClickHouse Cloud。
5. Entra ID 中的 profile、群组变更和停用会自动同步到 ClickHouse Cloud。

<div id="configure-clickhouse-cloud">
  ## 在 ClickHouse Cloud 组织中配置 SCIM
</div>

<Steps>
  <Step title="启用 SCIM" id="enable-scim-provisioning">
    以组织管理员身份登录 **ClickHouse Cloud 控制台**，然后依次打开 **组织设置 → SAML 和 SCIM 设置 → SCIM 配置**。

    点击 `Enable SCIM`。连接 SAML 单点登录后即可启用 SCIM；如果该选项显示为灰色，请先完成 SAML 设置。

    系统会生成一个 **SCIM endpoint URL**，格式如下：

    ```plaintext theme={null}
    https://api.clickhouse.cloud/v1/organizations/<your-org-id>/scim
    ```

    复制该 URL，稍后需将其作为 **租户 URL** 粘贴到 Entra ID 中。
  </Step>

  <Step title="生成 SCIM 访问令牌" id="generate-scim-token">
    找到 `Generate new key` 部分并选择过期日期。

    <Tip>
      **规划轮换**

      建议将有效期设为 12 个月，并添加日历提醒。ClickHouse Cloud 最多可同时启用两个 SCIM 令牌，因此可以在不中断服务的情况下进行轮换：生成新令牌，将 Entra ID 切换为使用新令牌，确认预配仍可正常运行，然后撤销旧令牌。
    </Tip>

    点击 `Generate new key`。令牌仅显示**一次**，由密钥 (以 `scim_` 为前缀) 和机密值组成。请立即复制两者并存储在安全的密钥管理器中，之后将无法再次获取。如果遗失，请撤销该令牌并生成新令牌。

    您需要将密钥和机密值合并为单个 Bearer 令牌，供 Entra ID 使用，格式如下：

    ```plaintext theme={null}
    <scim-key>:<scim-secret>
    ```

    具体来说，令牌**密钥** (以 `scim_` 开头) 后接一个冒号，再接令牌**机密值**，中间不留空格。Entra ID 会在每个请求中通过 `Authorization: Bearer` 请求头发送此值。
  </Step>

  <Step title="定义角色映射" id="define-role-mapping">
    在 SCIM 配置面板中，点击 **Map roles in "用户和角色"** (或直接依次进入 **用户和角色 → Roles**) 。

    SCIM 组会按名称绑定到 ClickHouse Cloud 角色，请注意以下规则：

    * **无法将 SCIM 组映射到预定义的系统角色。** SCIM 映射仅适用于自定义角色。如果需要通过 SCIM 提供系统级能力，请创建一个包含所需权限的自定义角色。
    * **同名会自动关联。** 如果自定义角色与传入的 SCIM 组同名，ClickHouse Cloud 会自动将两者关联，无需手动映射。
    * **若要使用与组名不同的角色名称**，请使用所需角色名称创建自定义角色，然后将其 **SCIM group** 字段设置为要绑定的 SCIM 组名称。
    * **未映射的组会创建新角色。** 如果 Entra ID 推送的组既不匹配现有角色名称，也未被任何角色的 `SCIM group` 字段引用，ClickHouse Cloud 会使用该组名称创建新的自定义角色。之后您可以为其授予所需权限。
  </Step>
</Steps>

<div id="configure-entra">
  ## 在 Microsoft Entra ID 中配置预配
</div>

<Steps>
  <Step title="打开您的 ClickHouse Cloud Enterprise 应用" id="open-clickhouse-cloud-app">
    打开 **Microsoft Entra ID** 的概述页，然后在左侧菜单的 **Manage** 下选择 **Enterprise applications**。打开你在为 ClickHouse Cloud 配置 SAML 单点登录时创建的应用程序。

    如果尚未创建企业应用程序，请先按照 [SAML 单点登录设置指南](/docs/zh/products/cloud/guides/security/cloud-access-management/saml-sso-setup#azure-enterprise-app) 进行操作 — 使用基于 SAML 的单点登录时，单点登录和 SCIM provisioning 共用同一个企业应用程序。
  </Step>

  <Step title="设置预配模式和凭据" id="connect-entra-scim">
    在应用的左侧边栏中，选择 **Provisioning**，然后点击 `Get started` (或选择 `Provisioning` → `Edit provisioning`) 。

    将 **Provisioning Mode** 设置为 `Automatic`。在 **Admin Credentials** 下填写：

    * **Tenant URL** — ClickHouse Cloud 控制台中的 SCIM 端点 URL (即 `.../scim` URL) 。
    * **Secret Token** — 用冒号连接的 SCIM 凭据，格式为 `<scim-key>:<scim-secret>`。Entra ID 会将其作为 `Authorization: Bearer` 请求头发送。

    点击 `Test Connection`。Entra ID 会向 SCIM 端点发起测试请求；成功后应会显示通知。如果失败，请参阅[故障排查](#troubleshooting)。

    点击 `Save`。
  </Step>

  <Step title="配置属性映射" id="map-user-attributes">
    保存凭据后，展开 **映射** 部分。Entra ID 会显示两组映射：

    * **预配 Microsoft Entra ID 用户**
    * **预配 Microsoft Entra ID 组**

    打开 **预配 Microsoft Entra ID 用户**，确认属性映射符合 ClickHouse Cloud 的要求。

    默认情况下，Entra ID 会将 `userName` 映射为 `userPrincipalName`。**关键是，`userName` 必须取自包含与用户通过 SAML 单点登录时所用邮箱地址相同的属性**，而非某个特定的属性名称。在某些租户中，`userPrincipalName` 已是该邮箱地址，无需更改；在其他租户中，邮箱地址存储在 `mail` 中，因此需编辑映射，使 `userName` 取自 `mail`。要更改来源，请点击 `userName` 行，将 **源属性** 设置为正确的属性，然后保存。

    设置 **匹配优先级**，使 `userName` 成为主要匹配属性。你可以删除不受支持的映射；SCIM 标准集之外的任何内容都会被 ClickHouse Cloud 忽略。

    <Warning>
      **使用与 SAML 单点登录相同的邮箱地址**

      写入 `userName` 的值**必须**与每位用户通过 SAML 单点登录时使用的邮箱地址一致。SCIM 创建账户，SAML 对其进行身份验证；因此，如果 SCIM `userName` 与 SAML 断言'中的邮箱地址不一致，SAML 会在用户登录时创建一个不受 SCIM 管理的独立新用户，导致出现重复的未管理账户。请将 `userName` 映射到包含与你的 SAML 配置所发送邮箱地址相同的属性 (`userPrincipalName`、`mail` 或其他属性) 。
    </Warning>

    以下其余行默认已完成映射，请再次确认各项是否正确：

    | Microsoft Entra ID 属性          | ClickHouse Cloud (SCIM) 属性     | 必需                             |
    | ------------------------------ | ------------------------------ | ------------------------------ |
    | `mail`                         | `emails[type eq "work"].value` | **是** — 必须与 `userName` 一致      |
    | `givenName`                    | `name.givenName`               | 建议                             |
    | `surname`                      | `name.familyName`              | 建议                             |
    | `displayName`                  | `displayName`                  | 建议 — 显示在 ClickHouse Cloud UI 中 |
    | `Switch([IsSoftDeleted], ...)` | `active`                       | **是** — 用于停用账户                 |

    打开 **预配 Microsoft Entra ID 组**，确认 `displayName` 映射到 `displayName`，`members` 映射到 `members`——组显示名称用于关联你的 ClickHouse Cloud 角色。

    <Warning>
      **邮箱地址大小写很重要**

      确保写入 `userName` 的值与写入主邮箱地址的值大小写一致。ClickHouse Cloud 会将邮箱地址规范化为小写；两个字段的大小写不一致可能导致预配失败。
    </Warning>
  </Step>

  <Step title="设置预配范围" id="configure-provisioning-behavior">
    展开 **设置** 部分：

    * 将 **范围** 设置为 `仅同步已分配的用户和组`。这样会将预配范围限定为你在下一步中明确分配给该应用的用户和组。
    * 暂时保持 **预配状态** 为 `关闭` — 在分配测试用户后再将其开启。

    点击 `保存`。
  </Step>

  <Step title="分配组和用户" id="push-groups-and-assign-users">
    角色会在此处自动分配。

    **在 Entra ID 中创建组。** 针对之前设置的每个角色映射，创建或找到一个显示名称**完全相同**的 Entra ID 组。例如，如果映射为 `ClickHouse-Admins → Admin`，请在 Entra ID 中创建名为 `ClickHouse-Admins` 的组。

    **将组分配给应用程序。** 在企业应用程序中，依次前往 **用户和组 → 添加用户/组**，选择角色组并进行分配。对每个角色组重复此操作。由于应用程序的预配范围设为*已分配的用户和组*，因此只有这些组 (及其成员) 会被预配。

    <Note>
      **预配组需要相应的 Entra ID 许可证**

      预配组 (而不仅是其成员) 需要 Microsoft Entra ID P1 或更高版本。启用组预配后，组本身会在 ClickHouse Cloud 中创建，并按显示名称绑定到对应的角色。
    </Note>

    **分配用户。** 有两种方式：

    * **通过组 (推荐) 。** 将用户添加到已分配给应用程序的 Entra ID 组中。系统会将其预配到 ClickHouse Cloud，并自动分配对应的角色。
    * **直接分配。** 在 **用户和组** 中将单个用户分配给应用程序。除非其同时属于已分配的组，否则系统会为其预配**默认角色**。

    基于组的分配更便于持续管理：当某人的角色发生变更时，只需更新组成员资格。
  </Step>

  <Step title="启用预配" id="turn-on-provisioning">
    返回 **Provisioning**，将 **Provisioning Status** 设为 `On`，然后点击 `Save`。

    Entra ID 会定期执行预配 (约每 40 分钟一次) 。如需立即预配特定用户 (便于测试) ，请依次选择 **Provisioning → Provision on demand**，搜索该用户，然后执行一次预配操作。
  </Step>
</Steps>

<div id="test-the-integration">
  ## 测试集成
</div>

启用预配后，使用**按需预配**立即推送一两个测试用户，无需等待下一个周期。然后返回 ClickHouse Cloud 控制台中的**设置 → 用户和角色**，确认已同步的用户已出现且角色符合预期。

在为整个团队分配应用之前，请先用一两个测试用户完成这份简短的测试计划。如果某个步骤未生效，请使用**按需预配**强制同步，然后查看[故障排查](#troubleshooting)部分。

| # | Entra ID 中的操作                                            | ClickHouse Cloud 中的预期结果          |
| - | -------------------------------------------------------- | -------------------------------- |
| 1 | 将测试用户添加到 `ClickHouse-Admins` 组并运行**按需预配**                | 用户会以 **Admin** 角色显示在**设置 → 成员**中 |
| 2 | 测试用户通过 SSO 登录 ClickHouse Cloud                           | 用户会进入具有管理员权限的仪表板                 |
| 3 | 在 Entra ID 中更新用户的名字并重新预配                                 | 更新后的名称会显示在**成员**中                |
| 4 | 将用户从 `ClickHouse-Admins` 移至 `ClickHouse-Read-only` 并重新预配 | 用户的角色会变更为**只读**                  |
| 5 | 取消为用户分配该应用程序 (或在 Entra ID 中禁用该账户)                        | 用户会从组织中移除；后续登录尝试将失败              |

如果任何步骤失败，请先解决根本问题再继续——否则问题症状通常会相互叠加。

<Tip>
  **在 Entra ID 中查找 SCIM 错误**

  SCIM 错误会显示在应用程序的**预配 → 查看预配日志**页面中 (也可在**身份 → 监视和运行状况 → 预配日志**下找到) 。每个条目都会原样显示请求、目标以及 ClickHouse Cloud 返回的错误——请从这里开始排查。
</Tip>

<div id="best-practices">
  ## 生产环境最佳实践
</div>

<div id="rotate-tokens">
  ### 定期轮换令牌
</div>

请为 SCIM 令牌轮换设置日历提醒。建议每 12 个月轮换一次；如果知晓该令牌的管理员离职，也应立即轮换。ClickHouse Cloud 特意允许每个组织同时拥有两个有效令牌，因此您可以在不中断预配的情况下完成轮换：生成新令牌，更新 Entra ID 中的 **Secret Token**，通过 **Test Connection** 确认后，再撤销旧令牌。

<div id="use-groups">
  ### 使用组，而非直接分配
</div>

虽然可以直接向应用程序分配用户，但很快就会难以审计。通过 Entra ID 组进行分配，可在一个位置完成访问权限审查和角色变更。

<div id="review-audit-log">
  ### 查看审计日志
</div>

所有 SCIM 操作 (例如创建用户、停用用户和更新 profile) 都会记录在 ClickHouse Cloud 审计日志中。请参阅[审计日志](/docs/zh/products/cloud/reference/security/audit-logging)。请定期查看日志，尤其是在大批量预配操作后。

<div id="default-role">
  ### 设置合理的默认角色
</div>

如果 Entra ID 用户被分配到该应用程序，但不属于任何已分配的组，系统会为其创建用户并赋予**默认角色**。请选择限制最严格但仍允许用户执行*部分操作*的角色，以确保配置错误时能够安全地失败。

<div id="avoid-manual-invites">
  ### 避免同时使用 SCIM 和手动邀请
</div>

启用 SCIM 后，请通过 Entra ID 管理成员资格，不要再向同一用户发送手动邀请。混用这两种方式会造成权威来源不明确，并可能产生重复记录。

<div id="account-for-provisioning-cycle">
  ### 考虑预配周期
</div>

Entra ID 会按固定周期同步 (约每 40 分钟一次) ，因此常规更改不会立即生效。需要让更改立即生效时，请使用 **按需预配**，并监控 **预配日志**，以排查持续发生的故障。

<div id="troubleshooting">
  ## 故障排查
</div>

<AccordionGroup>
  <Accordion title="Entra ID 中“测试连接”失败" id="test-credentials-fails">
    * 确认已在 ClickHouse Cloud 控制台中**启用** SCIM。
    * 确认 Entra ID 中的**租户 URL**与 Cloud 控制台中显示的 SCIM 端点 URL 完全一致——组织 ID 必须正确。
    * 确认**Secret Token**的格式为 `<scim-key>:<scim-secret>`——即以 `scim_` 开头的密钥、一个冒号和机密值。不得包含首尾空白字符，也不得添加 `Bearer` 前缀 (Entra ID 会自动添加) 。
    * 如果您已轮换令牌，请确保使用的是**新**密钥和机密值，而非之前的那一对。
  </Accordion>

  <Accordion title="用户已创建，但没有权限" id="users-no-permissions">
    * 检查是否已在\*\*“用户和角色”中的映射角色\*\*下，为预期角色添加映射行。
    * 检查 Entra ID 组名是否与映射中的 SCIM 组名**完全**一致，包括大小写和连字符。
    * 如果您的设计有意在不将某些用户分配到组的情况下预配他们，请确认已设置**默认角色**。
  </Accordion>

  <Accordion title="用户或组完全未预配" id="nothing-provisioning">
    * 确认**预配状态**为 `On`。
    * 确认**范围**设置为 `仅同步已分配的用户和组`，且用户/组确实已在**用户和组**下分配给该应用程序。
    * 请注意，预配周期大约每 40 分钟运行一次——可使用**按需预配**立即测试单个用户。
    * 预配组本身 (而非仅预配其成员) 需要 Microsoft Entra ID P1 或更高版本。
  </Accordion>

  <Accordion title="成员列表中出现重复用户" id="duplicate-user">
    通常是由于 Entra ID 与之前手动邀请中的电子邮件地址大小写不一致所致。从成员列表中移除重复用户，然后在 Entra ID 中取消分配并重新分配该用户 (或再次运行**按需预配**) ，以重新预配该用户。
  </Accordion>

  <Accordion title="因名称不匹配导致组预配失败" id="group-display-name">
    Entra ID 中的组显示名称与 ClickHouse Cloud 中配置的映射不匹配。请重命名 Entra ID 组，或通过 SCIM 配置面板 (或**用户和角色 → 角色**) 在\*\*“用户和角色”中的映射角色\*\*下添加映射。
  </Accordion>

  <Accordion title="已停用的用户仍显示为成员" id="deactivated-users-remaining">
    停用操作会在下一个预配周期生效。如需立即执行，请对此用户使用**按需预配**。如果之后该用户仍显示为成员，请检查**预配 → 查看预配日志**，确认禁用操作是否报错。
  </Accordion>

  <Accordion title="我轮换了 SCIM 令牌，现在 Entra ID 出现故障" id="token-rotation-issue">
    检查是否已在 Entra ID 中正确的企业应用程序上更新**Secret Token**，其格式应为 `<scim-key>:<scim-secret>`。更新后，单击 `Test Connection` 进行确认。预配恢复正常后，请在 ClickHouse Cloud 控制台中撤销旧令牌。
  </Accordion>

  <Accordion title="我丢失了 SCIM 令牌" id="lost-token">
    令牌无法恢复。在 ClickHouse Cloud 控制台的**组织设置 → SAML 和 SCIM 设置 → SCIM 配置**中，撤销丢失的令牌并生成新令牌，然后在 Entra ID 中更新**Secret Token**。
  </Accordion>
</AccordionGroup>

<div id="faq">
  ## 常见问题
</div>

<AccordionGroup>
  <Accordion title="使用 SCIM 前是否需要先配置 SAML 单点登录？">
    需要。SCIM 用于创建用户账户，而 ClickHouse Cloud 则通过 SAML 对这些账户进行身份验证。请先配置 [SAML 单点登录](/docs/zh/products/cloud/guides/security/cloud-access-management/saml-sso-setup)。
  </Accordion>

  <Accordion title="可以将同一个企业应用程序同时用于 SAML 和 SCIM 吗？">
    可以。使用基于 SAML 的单点登录时，一个 Entra ID 企业应用程序即可同时处理单点登录和 SCIM 预配。
  </Accordion>

  <Accordion title="为什么 Secret Token 的格式为 key:机密值？">
    Entra ID 会通过发送 `Authorization: Bearer` 请求头进行身份验证，其中包含 Secret Token。ClickHouse Cloud 的 SCIM 端点要求 bearer 值为以冒号分隔的标记密钥和机密值。
  </Accordion>

  <Accordion title="Entra ID 中的更改多久会同步到 ClickHouse Cloud？">
    Entra ID 大约每 40 分钟执行一次预配。如需立即更新，请对特定用户使用 **按需预配**。
  </Accordion>

  <Accordion title="遇到问题时，如何获取帮助？">
    请在 ClickHouse Cloud 控制台中通过 **帮助 → 联系支持** 提交支持工单，并附上：

    * 您的组织 ID；
    * 您的 Entra ID 企业应用程序名称 (及对象 ID) ；以及
    * **预配 → 查看预配日志**中失败条目的截图。
  </Accordion>
</AccordionGroup>