> ## 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 プロビジョニングを設定する方法

Enterpriseプランの機能

SCIM は Enterpriseプランで利用できます。アップグレードするには、Cloud Console のプランページにアクセスしてください。

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 プロビジョニング](https://clickhouse.com/docs/ja/products/cloud/guides/security/cloud-access-management/scim-setup.md) ガイドに従ってください。ClickHouse Cloud 側の設定は同じで、異なるのは IdP の設定のみです。

## 始める前に

必要なもの:

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

## SCIM と ClickHouse Cloud の連携の仕組み

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 に自動的に反映されます。

## ClickHouse Cloud 組織で SCIM を設定する

**1. SCIM を有効にする**

組織の管理者として **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** として貼り付けます。

**2. SCIM アクセストークンを生成する**

`Generate new key` セクションで、有効期限を選択します。

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

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

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

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

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

**3. ロールマッピングを定義する**

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 はそのグループ名で新しいカスタムロールを作成します。その後、必要な権限を付与できます。

## Microsoft Entra ID でプロビジョニングを設定する

**1. ClickHouse Cloud Enterprise アプリケーションを開きます**

**Microsoft Entra ID** の概要を開き、左側のメニューの **Manage** で **Enterprise applications** を選択します。ClickHouse Cloud の SAML SSO を設定した際に作成したアプリケーションを開きます。

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

**2. プロビジョニング モードと認証情報を設定する**

アプリケーションの左側のサイドバーで、**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` をクリックします。

**3. 属性マッピングを設定する**

認証情報を保存したら、**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` をマッピングしてください。

以下の行はデフォルトでマッピングされています。各項目が正しく設定されていることを確認してください。

| 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 つのフィールド間で大文字・小文字が一致しないと、プロビジョニングが失敗する可能性があります。

**4. Provisioning の適用範囲を設定する**

**Settings** セクションを展開します。

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

`Save` をクリックします。

**5. グループとユーザーの割り当て**

ここでロールが自動的に適用されます。

**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 に作成され、表示名に基づいて対応するロールに関連付けられます。

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

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

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

**6. プロビジョニングを有効にする**

**Provisioning** に戻り、**Provisioning Status** を `On` に設定して、`Save` をクリックします。

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

## インテグレーションをテストする

プロビジョニングをオンにしたら、次のサイクルを待たずに **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 から返されたエラーがそのまま表示されます。まずはここを確認してください。

## 本番環境のベストプラクティス

### トークンを定期的にローテーションする

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

### 直接割り当てではなくグループを使用する

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

### 監査ログを確認する

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

### 適切なデフォルトロールを設定する

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

### SCIM と手動招待を併用しない

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

### Provisioning サイクルを考慮する

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

## トラブルシューティング

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

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

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

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

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

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

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

> [accordion] SCIM トークンを紛失した
>
> トークンは復元できません。ClickHouse Cloud Console の **組織設定 → SAML and SCIM settings → SCIM Configuration** で、紛失したトークンを取り消して新しいトークンを生成し、Entra ID の **Secret Token** を更新します。

## よくある質問

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

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

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

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

> [accordion] 困った場合はどこでサポートを受けられますか？
>
> ClickHouse Cloud Console の **Help → Contact support** からサポートチケットを作成し、次の情報を含めてください。
>
> * 組織 ID
> * Entra ID エンタープライズアプリケーションの名前 (およびオブジェクト ID)
> * **Provisioning → View provisioning logs** にある失敗したエントリのスクリーンショット
