> ## 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 (System for Cross-domain Identity Management) をサポートしています。ID プロバイダー に接続すると、ClickHouse Cloud のエンタープライズアプリケーションに割り当てたすべてのユーザーが適切なロールで組織内に自動的に作成され、プロファイルの更新も自動的に反映されます。また、IdP からユーザーを削除すると、そのユーザーのアクセス権も削除されます。手動での招待や孤立したアカウントは不要です。

このガイドでは、**Microsoft Entra ID** (旧 Azure Active Directory) で SCIM プロビジョニングをエンドツーエンドで設定する手順を説明します。ClickHouse Cloud の SCIM エンドポイント は、SCIM 2.0 (RFC 7644) に準拠しています。Entra ID は、ClickHouse Cloud Console で生成した SCIM token key と secret を組み合わせた長期間有効な bearer token を使用して、エンドポイント に対して認証します。

<Tip>
  **Okta を使用していますか？**

  ID プロバイダー が Okta の場合は、[Okta での SCIM プロビジョニング](/docs/ja/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 SSO](/docs/ja/products/cloud/guides/security/cloud-access-management/saml-sso-setup) がすでに設定されていること。SCIM でユーザーアカウントが作成され、それらのアカウントは SAML 経由でサインインするため、事前に SSO が機能している必要があります。
* エンタープライズアプリケーションの Provisioning を設定する権限を持つ、少なくとも **Application Administrator** (または **Cloud Application Administrator**) ロールが割り当てられた **Microsoft Entra 管理センター**へのアクセス。
* SCIM 経由で割り当てるロールのリスト (例: Admins、Developers、Read-only) 。事前に決定してください。Entra ID で対応するグループを作成します。

<div id="how-scim-works">
  ## SCIM と ClickHouse Cloud の連携の仕組み
</div>

1. Entra ID の管理者が、ユーザーを直接、またはグループを介して ClickHouse Cloud のエンタープライズアプリケーションに割り当てます。
2. Entra ID のプロビジョニングサービスが、生成した Bearer token を使用して認証を行い、HTTPS 経由で ClickHouse Cloud の SCIM エンドポイント を呼び出します。
3. ClickHouse Cloud は組織内にユーザーを作成し、Entra ID のグループメンバーシップに基づいてロールを割り当てます。
4. ユーザーは、既存の SAML SSO フローを介して ClickHouse Cloud にサインインします。
5. Entra ID でのプロファイル、グループの変更、およびアカウントの無効化は、ClickHouse Cloud に自動的に反映されます。

<div id="configure-clickhouse-cloud">
  ## ClickHouse Cloud 組織で SCIM を設定する
</div>

<Steps>
  <Step title="SCIM を有効にする" id="enable-scim-provisioning">
    組織の管理者として **ClickHouse Cloud Console** にサインインし、**組織設定 → SAML and SCIM settings → SCIM Configuration** を開きます。

    `Enable SCIM` をクリックします。SAML SSO を接続すると SCIM のロックが解除されます。オプションがグレーアウトされている場合は、先に SAML の設定を完了してください。

    次の形式の **SCIM endpoint URL** が生成されます。

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

    コピーしておきます。後で Entra ID の **Tenant URL** として貼り付けます。
  </Step>

  <Step title="SCIM アクセストークンを生成する" id="generate-scim-token">
    `Generate new key` セクションで、有効期限を選択します。

    <Tip>
      **ローテーションを計画する**

      有効期限は 12 か月に設定し、カレンダーにリマインダーを追加することをお勧めします。ClickHouse Cloud では一度に最大 2 つの SCIM トークンを有効にできるため、ダウンタイムなしでローテーションできます。新しいトークンを生成し、Entra ID 側を切り替え、プロビジョニングが引き続き機能することを確認した後、古いトークンを取り消します。
    </Tip>

    `Generate new key` をクリックします。トークンは、キー (`scim_` で始まる) とシークレットとして **一度だけ** 表示されます。すぐに両方をコピーし、安全なシークレットマネージャーに保存してください。後から取得することはできません。紛失した場合は、トークンを取り消して新しいトークンを生成してください。

    Entra ID 用に、キーとシークレットを次の形式の単一の Bearer token に結合します。

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

    具体的には、`scim_` で始まるトークンの**キー**、コロン、トークンの**シークレット**を、スペースを入れずに連結します。Entra ID は、すべてのリクエストでこの値を `Authorization: Bearer` ヘッダーとして送信します。
  </Step>

  <Step title="ロールマッピングを定義する" id="define-role-mapping">
    SCIM Configuration パネルで **Map roles in "Users and roles"** をクリックします (または **Users and roles → 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 SSO を設定した際に作成したアプリケーションを開きます。

    エンタープライズ アプリケーションをまだ作成していない場合は、まず [SAML SSO セットアップガイド](/docs/ja/products/cloud/guides/security/cloud-access-management/saml-sso-setup#azure-enterprise-app) に従ってください。SAML ベースの SSO では、同じエンタープライズ アプリケーションをシングルサインオンと SCIM プロビジョニングの両方に使用します。
  </Step>

  <Step title="プロビジョニング モードと認証情報を設定する" id="connect-entra-scim">
    アプリケーションの左側のサイドバーで、**Provisioning** を選択し、`Get started` (または `Provisioning` → `Edit provisioning`) をクリックします。

    **Provisioning Mode** を `Automatic` に設定します。**Admin Credentials** で、以下の項目を入力します。

    * **Tenant URL** — ClickHouse Cloud Console の 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">
    認証情報を保存したら、**Mappings** セクションを展開します。Entra ID には次の 2 つのマッピングセットが表示されます。

    * **Provision Microsoft Entra ID Users**
    * **Provision Microsoft Entra ID Groups**

    **Provision Microsoft Entra ID Users** を開き、属性マッピングが ClickHouse Cloud の要件に合っていることを確認します。

    デフォルトでは、Entra ID は `userPrincipalName` を `userName` にマッピングします。**重要なのは、`userName` の値の取得元が、ユーザーが SAML SSO でサインインする際に使用するメールアドレスと同じメールアドレスを持つ属性であることです**。特定の属性名である必要はありません。一部のテナントでは `userPrincipalName` がすでにそのメールアドレスであるため、変更は不要です。一方、メールアドレスが `mail` に格納されている場合は、`mail` を `userName` の取得元にするようマッピングを編集します。取得元を変更するには、`userName` の行をクリックし、**Source attribute** を正しい属性に設定して保存します。

    `userName` がプライマリの照合属性となるよう、**Matching precedence** を設定します。サポートされていないマッピングは削除できます。SCIM の標準セット以外の項目は ClickHouse Cloud 側で無視されます。

    <Warning>
      **SAML SSO で使用するメールアドレスと一致させる**

      `userName` に渡される値は、各ユーザーが SAML SSO 経由でサインインする際に使用するメールアドレスと**必ず**一致している必要があります。SCIM はアカウントを作成し、SAML はそのアカウントを認証します。そのため、SCIM の `userName` と SAML アサーションのメールアドレスが一致しない場合、サインイン時に SAML により、SCIM で管理されない別の新規ユーザーが作成され、未管理の重複アカウントが残ります。SAML configuration が送信するメールアドレスと同じメールアドレスを持つ属性 (`userPrincipalName`、`mail`、またはその他) から `userName` をマッピングしてください。
    </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`                       | **はい** — deactivation を制御します     |

    **Provision Microsoft Entra ID Groups** を開き、`displayName` が `displayName` に、`members` が `members` にマッピングされていることを確認します。グループの表示名は、ClickHouse Cloud のロールへのバインドに使用されます。

    <Warning>
      **メールアドレスの大文字・小文字は重要です**

      `userName` に渡される値とプライマリメールアドレスに渡される値では、大文字・小文字が一致していることを確認してください。ClickHouse Cloud はメールアドレスを小文字に正規化します。2 つのフィールド間で大文字・小文字が一致しないと、プロビジョニングが失敗する可能性があります。
    </Warning>
  </Step>

  <Step title="Provisioning の適用範囲を設定する" id="configure-provisioning-behavior">
    **Settings** セクションを展開します。

    * **Scope** を `Sync only assigned users and groups` に設定します。これにより、プロビジョニングの対象が、次のステップでアプリケーションに明示的に割り当てるユーザーとグループに限定されます。
    * **Provisioning Status** は、テストユーザーを割り当てた後にオンにするため、現時点では `Off` のままにします。

    `Save` をクリックします。
  </Step>

  <Step title="グループとユーザーの割り当て" id="push-groups-and-assign-users">
    ここでロールが自動的に適用されます。

    **Entra ID でグループを作成します。** 先ほど設定した各ロールマッピングについて、**表示名が完全に同じ** Entra ID グループを作成または特定します。たとえば、マッピングが `ClickHouse-Admins → Admin` の場合は、Entra ID で `ClickHouse-Admins` というグループを作成します。

    **グループをアプリケーションに割り当てます。** エンタープライズ アプリケーションで、**Users and groups → Add user/group** に移動し、ロールグループを選択して割り当てます。各ロールグループについて繰り返します。アプリケーションのプロビジョニング スコープは *assigned users and groups* に設定されているため、プロビジョニングされるのはこれらのグループとそのメンバーのみです。

    <Note>
      **グループのプロビジョニングには適切な Entra ID ライセンスが必要です**

      メンバーだけでなくグループ自体をプロビジョニングするには、Microsoft Entra ID P1 以上が必要です。グループのプロビジョニングでは、グループ自体が ClickHouse Cloud に作成され、表示名に基づいて対応するロールに関連付けられます。
    </Note>

    **ユーザーを割り当てます。** 次の 2 つの方法があります。

    * **グループ経由 (推奨) 。** アプリケーションに割り当てた Entra ID グループにユーザーを追加します。ユーザーは ClickHouse Cloud にプロビジョニングされ、対応するロールが自動的に割り当てられます。
    * **直接割り当て。** **Users and groups** で個々のユーザーをアプリケーションに割り当てます。割り当て済みグループのメンバーでもある場合を除き、ユーザーは **Default role** でプロビジョニングされます。

    グループベースの割り当てのほうが、継続的な管理には適しています。誰かのロールが変更された場合は、グループメンバーシップを更新するだけです。
  </Step>

  <Step title="プロビジョニングを有効にする" id="turn-on-provisioning">
    **Provisioning** に戻り、**Provisioning Status** を `On` に設定して、`Save` をクリックします。

    Entra ID は定期的に (約 40 分ごと) プロビジョニングを実行します。テストなどで特定のユーザーをすぐにプロビジョニングするには、**Provisioning → Provision on demand** でユーザーを検索し、プロビジョニングを 1 回実行します。
  </Step>
</Steps>

<div id="test-the-integration">
  ## インテグレーションをテストする
</div>

プロビジョニングをオンにしたら、次のサイクルを待たずに **Provision on demand** を使用して、テストユーザーを 1 ～ 2 人ただちにプッシュします。次に、ClickHouse Cloud Console の **Settings → Users and roles** に戻り、同期されたユーザーが想定どおりのロールで表示されていることを確認します。

チーム全体を割り当てる**前に**、1 ～ 2 人のテストユーザーを使って、この簡単なテスト計画を実施してください。手順が反映されない場合は、**Provision on demand** を使用して同期を強制してから、[トラブルシューティング](#troubleshooting) セクションを確認してください。

| # | Entra ID での操作                                                        | ClickHouse Cloud での想定結果                            |
| - | -------------------------------------------------------------------- | -------------------------------------------------- |
| 1 | テストユーザーを `ClickHouse-Admins` グループに追加し、**Provision on demand** を実行する  | ユーザーが **Settings → Members** に **Admin** ロールで表示される |
| 2 | テストユーザーが SSO 経由で ClickHouse Cloud にサインインする                           | 管理者権限でダッシュボードが表示される                                |
| 3 | Entra ID でユーザーの名を更新し、再プロビジョニングする                                     | 更新された名前が **Members** に表示される                        |
| 4 | ユーザーを `ClickHouse-Admins` から `ClickHouse-Read-only` に移動し、再プロビジョニングする | ロールが **Read-only** に変更される                          |
| 5 | アプリケーションからユーザーの割り当てを解除する (または Entra ID でアカウントを無効化する)                 | ユーザーが組織から削除され、以降のサインインは失敗する                        |

いずれかの手順に失敗した場合は、続行する前に根本原因を解決してください。通常、問題は連鎖的に悪化します。

<Tip>
  **Entra ID で SCIM エラーを確認する場所**

  SCIM エラーは、アプリケーションの **Provisioning → View provisioning logs** 画面に表示されます (**Identity → Monitoring & health → Provisioning logs** からも確認できます) 。各エントリには、リクエスト、ターゲット、および ClickHouse Cloud から返されたエラーがそのまま表示されます。まずはここを確認してください。
</Tip>

<div id="best-practices">
  ## 本番環境のベストプラクティス
</div>

<div id="rotate-tokens">
  ### トークンを定期的にローテーションする
</div>

SCIM トークンのローテーションをカレンダーに登録してください。推奨頻度は12か月ごと、またはトークンを知っている管理者が退職した場合は直ちに行うことです。ClickHouse Cloud では、プロビジョニングを中断せずにローテーションできるよう、組織ごとに2つのアクティブなトークンを利用できます。新しいトークンを生成し、Entra ID の **Secret Token** を更新して **Test Connection** で確認した後、古いトークンを取り消してください。

<div id="use-groups">
  ### 直接割り当てではなくグループを使用する
</div>

ユーザーをアプリケーションに直接割り当てることもできますが、すぐに監査が難しくなります。Entra ID グループを介して割り当てを管理すれば、アクセスレビューやロールの変更を一元的に行えます。

<div id="review-audit-log">
  ### 監査ログを確認する
</div>

ユーザーの作成、無効化、プロファイルの更新など、すべての SCIM アクションは ClickHouse Cloud の監査ログに記録されます。[監査ログ](/docs/ja/products/cloud/reference/security/audit-logging)を参照してください。特に大規模なプロビジョニングが行われた後は、定期的にログを確認してください。

<div id="default-role">
  ### 適切なデフォルトロールを設定する
</div>

Entra ID ユーザーがアプリケーションに割り当てられていても、割り当て済みのグループに属していない場合は、**Default role** で作成されます。ユーザーが最低限の操作を行える、最も制限の厳しいロールを選択してください。これにより、設定ミスがあっても安全に失敗します。

<div id="avoid-manual-invites">
  ### SCIM と手動招待を併用しない
</div>

SCIM を有効にしたら、メンバーシップは Entra ID で管理し、同じユーザーに手動招待を送らないでください。両方を併用すると、どちらが信頼できる情報源なのかが不明確になり、重複が発生する可能性があります。

<div id="account-for-provisioning-cycle">
  ### Provisioning サイクルを考慮する
</div>

Entra ID は約 40 分ごとの周期で同期するため、通常の変更はすぐには反映されません。変更をすぐに反映する必要がある場合は **Provision on demand** を使用し、継続的に発生する失敗については **Provisioning logs** を監視してください。

<div id="troubleshooting">
  ## トラブルシューティング
</div>

<AccordionGroup>
  <Accordion title="Entra ID で「Test connection」が失敗する" id="test-credentials-fails">
    * ClickHouse Cloud Console で SCIM が**有効**になっていることを確認します。
    * Entra ID の **Tenant URL** が Cloud Console に表示されている SCIM エンドポイント URL と完全に一致していることを確認します。組織 ID が正しく設定されている必要があります。
    * **Secret Token** が `<scim-key>:<scim-secret>` の形式であることを確認します。`scim_` で始まるキー、コロン、シークレットの順に指定します。先頭または末尾に空白を含めず、`Bearer` プレフィックスも付けないでください (Entra ID により自動的に追加されます) 。
    * トークンをローテーションした場合は、以前のペアではなく、**新しい**キーとシークレットを使用していることを確認します。
  </Accordion>

  <Accordion title="ユーザーは作成されるが権限がない" id="users-no-permissions">
    * 想定するロールについて、**Map roles in "Users and roles"** に行を追加していることを確認します。
    * Entra ID のグループ名が、マッピング内の SCIM グループ名と、大文字・小文字やハイフンも含めて**完全に**一致していることを確認します。
    * 意図的に一部のユーザーをグループなしでプロビジョニングする場合は、**Default role** が設定されていることを確認します。
  </Accordion>

  <Accordion title="ユーザーまたはグループがまったくプロビジョニングされない" id="nothing-provisioning">
    * **Provisioning Status** が `On` になっていることを確認します。
    * **Scope** が `Sync only assigned users and groups` に設定され、ユーザーまたはグループが **Users and groups** で実際にアプリケーションに割り当てられていることを確認します。
    * プロビジョニングサイクルは約40分ごとに実行されます。個別のユーザーをすぐにテストするには、**Provision on demand** を使用します。
    * メンバーだけでなくグループ自体をプロビジョニングするには、Microsoft Entra ID P1 以上が必要です。
  </Accordion>

  <Accordion title="メンバーリストに重複したユーザーが表示される" id="duplicate-user">
    通常、Entra ID と以前の手動招待でメールアドレスの大文字・小文字が一致していないことが原因です。Members リストから重複したユーザーを削除し、Entra ID でそのユーザーの割り当てを解除してから再度割り当てます (または **Provision on demand** を再実行します) 。
  </Accordion>

  <Accordion title="グループのプロビジョニングが名前の不一致で失敗する" id="group-display-name">
    Entra ID のグループ表示名が、ClickHouse Cloud で設定されているマッピングと一致していません。Entra ID グループの名前を変更するか、SCIM Configuration パネルの **Map roles in "Users and roles"** でマッピングを追加します (または **Users and roles → Roles** から追加します) 。
  </Accordion>

  <Accordion title="無効化されたユーザーがメンバーとして表示され続ける" id="deactivated-users-remaining">
    無効化は次のプロビジョニングサイクルで反映されます。すぐに反映させるには、そのユーザーに対して **Provision on demand** を使用します。その後もユーザーがメンバーとして残っている場合は、**Provisioning → View provisioning logs** で無効化操作に関するエラーを確認します。
  </Accordion>

  <Accordion title="SCIM トークンをローテーションした後、Entra ID が失敗するようになった" id="token-rotation-issue">
    Entra ID の正しいエンタープライズアプリケーションで、`<scim-key>:<scim-secret>` 形式の **Secret Token** を更新したことを確認します。更新後、`Test Connection` をクリックして確認します。プロビジョニングが正常な状態に戻ったら、ClickHouse Cloud Console で古いトークンを取り消します。
  </Accordion>

  <Accordion title="SCIM トークンを紛失した" id="lost-token">
    トークンは復元できません。ClickHouse Cloud Console の **組織設定 → SAML and SCIM settings → SCIM Configuration** で、紛失したトークンを取り消して新しいトークンを生成し、Entra ID の **Secret Token** を更新します。
  </Accordion>
</AccordionGroup>

<div id="faq">
  ## よくある質問
</div>

<AccordionGroup>
  <Accordion title="SCIM を使用するには、事前に SAML SSO が必要ですか？">
    はい。SCIM はユーザーアカウントを作成しますが、ClickHouse Cloud では SAML を使用して認証されます。まず [SAML SSO](/docs/ja/products/cloud/guides/security/cloud-access-management/saml-sso-setup) を設定してください。
  </Accordion>

  <Accordion title="SAML と SCIM に同じエンタープライズアプリケーションを使用できますか？">
    はい。SAML ベースの SSO では、1 つの Entra ID エンタープライズアプリケーションでシングルサインオンと SCIM プロビジョニングの両方を処理できます。
  </Accordion>

  <Accordion title="Secret Token が key:secret 形式なのはなぜですか？">
    Entra ID は、Secret Token を `Authorization: Bearer` ヘッダーとして送信して認証します。ClickHouse Cloud の SCIM エンドポイントでは、ベアラー値として、トークンキーとシークレットをコロンで連結した値を想定しています。
  </Accordion>

  <Accordion title="Entra ID での変更はどのくらいで ClickHouse Cloud に反映されますか？">
    Entra ID は約 40 分ごとのサイクルでプロビジョニングを実行します。すぐに更新するには、対象ユーザーに対して **Provision on demand** を使用してください。
  </Accordion>

  <Accordion title="困った場合はどこでサポートを受けられますか？">
    ClickHouse Cloud Console の **Help → Contact support** からサポートチケットを作成し、次の情報を含めてください。

    * 組織 ID
    * Entra ID エンタープライズアプリケーションの名前 (およびオブジェクト ID)
    * **Provisioning → View provisioning logs** にある失敗したエントリのスクリーンショット
  </Accordion>
</AccordionGroup>