> ## 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.

# Okta での SCIM プロビジョニング

> Okta と ClickHouse Cloud 間で SCIM プロビジョニング を設定する方法

Enterpriseプランの機能

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

ClickHouse Cloud は、ユーザーとグループのライフサイクルを自動管理するための SCIM 2.0 (System for Cross-domain Identity Management) をサポートしています。IDプロバイダーに接続すると、ClickHouse Cloud アプリケーションに割り当てたすべてのユーザーが、適切なロールで組織内に自動的に作成されます。プロファイルの更新も自動的に反映され、IdP からユーザーを削除すると、そのユーザーのアクセス権も削除されます。手動で招待したり、不要なアカウントが残ったりすることはありません。

このガイドでは、**Okta** を使用して SCIM プロビジョニングをエンドツーエンドで設定する手順を説明します。ClickHouse Cloud の SCIM エンドポイントは SCIM 2.0 (RFC 7644) に準拠しています。Okta は Basic Auth を使用して認証します。本ガイドでもこの方式を使用します。IDプロバイダーが Microsoft Entra ID の場合は、代わりに [Entra ID での SCIM プロビジョニング](https://clickhouse.com/docs/ja/products/cloud/guides/security/cloud-access-management/scim-setup-entra.md) ガイドに従ってください。

## 始める前に

必要なもの:

* ClickHouse Cloud の組織で **Admin** ロールを持っていること。
* IdP と ClickHouse Cloud の間で [SAML SSO](https://clickhouse.com/docs/ja/products/cloud/guides/security/cloud-access-management/saml-sso-setup.md) がすでに設定済みであること。SCIM でユーザーアカウントは作成されますが、それらのアカウントは SAML 経由でサインインするため、まず SSO が正常に動作している必要があります。
* Okta テナントに対するスーパー管理者権限があり、アプリケーションのインストールと Provisioning の設定を行えること。
* 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 SSO フローを使用して ClickHouse Cloud にサインインします。
5. プロファイルやグループの変更、Okta での無効化は、自動的に ClickHouse Cloud に反映されます。

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

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

組織管理者として **ClickHouse Cloud Console** にサインインし、**組織設定 → SAML and SCIM settings → SCIM Configuration** を開きます。

![組織設定で SCIM 設定タブに移動する](https://mintcdn.com/private-7c7dfe99/zhhfCE__w-UVvpQP/images/cloud/security/scim-okta/scim-okta-01.webp?fit=max\&auto=format\&n=zhhfCE__w-UVvpQP\&q=85\&s=35eada6dd3b923c7d8fe71645ead97a8)

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

![Enable SCIM を切り替える](https://mintcdn.com/private-7c7dfe99/zhhfCE__w-UVvpQP/images/cloud/security/scim-okta/scim-okta-02.webp?fit=max\&auto=format\&n=zhhfCE__w-UVvpQP\&q=85\&s=94c88b975e7b709b5a1ecb155925868f)

次の形式の **SCIM エンドポイント URL** が生成されます。

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

これをコピーしてください。後で Okta に貼り付けます。

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

`Create an API key` セクションで有効期限を選択します。

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

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

![新しい SCIM API key を生成する](https://mintcdn.com/private-7c7dfe99/zhhfCE__w-UVvpQP/images/cloud/security/scim-okta/scim-okta-07.webp?fit=max\&auto=format\&n=zhhfCE__w-UVvpQP\&q=85\&s=6c88d690ff90f8c993caeab0c7425eff)

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

SCIM Configuration パネルで **Map roles in "Users and roles"** をクリックします (または **Users and roles → Roles** から直接移動します)。

SCIM グループは名前に基づいて ClickHouse Cloud のロールに紐付けられます。あわせて次のルールに注意してください。

* **SCIM グループを定義済みのシステムロールにマップすることはできません。** SCIM マッピングが適用されるのはカスタムロールのみです。SCIM 経由でシステムレベルの権限を公開する必要がある場合は、必要な権限をまとめたカスタムロールを作成してください。
* **名前が一致すると自動的にリンクされます。** カスタムロールが受信した SCIM グループと同じ名前であれば、ClickHouse Cloud が自動的に紐付けます。手動マッピングは不要です。
* **グループ名とは異なるロール名を使うには**、まず使用したいロール名でカスタムロールを作成し、その後、そのロールが紐付けられる SCIM グループ名を **SCIM group** フィールドに設定してください。
* **未マップのグループは新しいロールを作成します。** Okta が、既存のロール名と一致せず、どのロールの `SCIM group` フィールドからも参照されていないグループをプッシュすると、ClickHouse Cloud はそのグループ名で新しいカスタムロールを作成します。その後、そのロールに必要な権限を付与できます。

## Okta で ClickHouse Cloud アプリケーションを設定する

**1. Okta で ClickHouse Cloud アプリケーションを開く**

**Okta Admin Console** で **Applications → Applications** に移動し、ClickHouse Cloud の SAML SSO 設定時に作成したアプリケーションを検索して開きます。

まだ SAML アプリケーションを作成していない場合は、先に [SAML SSO setup guide](https://clickhouse.com/docs/ja/products/cloud/guides/security/cloud-access-management/saml-sso-setup.md) に従ってください。SCIM プロビジョニングは同じアプリケーションで設定します。

**General** タブで **App Settings** セクションを見つけて `Edit` をクリックします。**Provisioning** で `SCIM` を選択し、`Save` をクリックします。

![Okta アプリケーション設定でプロビジョニングモードを SCIM に設定する](https://mintcdn.com/private-7c7dfe99/zhhfCE__w-UVvpQP/images/cloud/security/scim-okta/scim-okta-03.webp?fit=max\&auto=format\&n=zhhfCE__w-UVvpQP\&q=85\&s=8ec4d887b1923fcacf6ce5a00a6e41b1)

これで、アプリケーションに **Provisioning** タブが表示されます。

![アプリケーションに Provisioning タブが表示された状態](https://mintcdn.com/private-7c7dfe99/zhhfCE__w-UVvpQP/images/cloud/security/scim-okta/scim-okta-05.webp?fit=max\&auto=format\&n=zhhfCE__w-UVvpQP\&q=85\&s=987c43c94bcab41923eea98b31d9d555)

**2. Okta を SCIM エンドポイントに接続する**

アプリケーションの **Provisioning** タブを開き、`Edit` をクリックします。フォームに必要事項を入力します。

* **SCIM connector base URL** — 先ほどの SCIM エンドポイント URL。
* **Unique identifier field for users** — `userName`。
* **Supported provisioning actions** — 次の項目をすべて選択します。
  * Import New Users and Profile Updates
  * Push New Users
  * Push Profile Updates
  * Push Groups
  * Import Groups
* **Authentication Mode** — `Basic Auth`。
  * **Username** — SCIM トークンのキー (`scim_` で始まります) 。
  * **Password** — SCIM トークンのシークレット。

    ![SCIM コネクタ URL を入力し、一意識別子を userName に設定する](https://mintcdn.com/private-7c7dfe99/zhhfCE__w-UVvpQP/images/cloud/security/scim-okta/scim-okta-06.webp?fit=max\&auto=format\&n=zhhfCE__w-UVvpQP\&q=85\&s=24367e1a32c9681b00042a64eb121248)

    ![SCIM 認証用の API 認証情報を入力する](https://mintcdn.com/private-7c7dfe99/zhhfCE__w-UVvpQP/images/cloud/security/scim-okta/scim-okta-08.webp?fit=max\&auto=format\&n=zhhfCE__w-UVvpQP\&q=85\&s=1d2d5089b5d3ef62d6216ed50ba18b9d)

`Test Connector Configuration` をクリックします。緑色の確認メッセージが表示されるはずです。失敗した場合は、[Troubleshooting](#troubleshooting) に進んでください。

![SCIM 接続をテストする](https://mintcdn.com/private-7c7dfe99/zhhfCE__w-UVvpQP/images/cloud/security/scim-okta/scim-okta-09.webp?fit=max\&auto=format\&n=zhhfCE__w-UVvpQP\&q=85\&s=0541ae42f2283eefdf7b6bff85a8be57)

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

**3. Provisioning の動作を設定する**

引き続き **Provisioning** タブで、左側のサイドバーにある `To App` をクリックします。`Edit` をクリックし、以下を有効にします。

| 設定 | 操作 | 内容 |
| - | - | - |
| Create Users | 有効化 | Okta で割り当てられると、ClickHouse Cloud に新しいユーザーを作成します |
| Update User Attributes | 有効化 | プロファイルの変更 (名前、メールアドレスなど) を自動的に同期します |
| Deactivate Users | 有効化 | Okta で割り当て解除または無効化されると、ClickHouse Cloud からユーザーを削除します |
| Sync Password | 無効化 | 使用しません — サインインはパスワードではなく SAML 経由で行われます |

![ユーザー向けの SCIM Provisioning アクションを有効にする](https://mintcdn.com/private-7c7dfe99/zhhfCE__w-UVvpQP/images/cloud/security/scim-okta/scim-okta-10.webp?fit=max\&auto=format\&n=zhhfCE__w-UVvpQP\&q=85\&s=3c72af6b959cda980108c967fc5f42b1)

`Save` をクリックし、アプリケーションの **Sign On** / **Provisioning** タブに戻って、設定が反映されていることを確認します。

![Provisioning の設定を保存して Sign On タブに戻る](https://mintcdn.com/private-7c7dfe99/zhhfCE__w-UVvpQP/images/cloud/security/scim-okta/scim-okta-10b.webp?fit=max\&auto=format\&n=zhhfCE__w-UVvpQP\&q=85\&s=c903f1e0b610c511c3b531d7a1357969)

**4. ユーザー属性をマッピングする**

Okta と ClickHouse Cloud で、どのユーザーフィールドを対応付けるか一致している必要があります。**Provisioning** タブで `To App` をクリックし、アプリケーションの **Attribute Mappings** を確認してください。通常は Okta SAML アプリケーションのデフォルト設定で問題ありませんが、以下の表を確認してください。

| Okta 属性 | ClickHouse Cloud (SCIM) 属性 | 必須 |
| - | - | - |
| `userName` | `userName` | **はい** — 一意の識別子およびプライマリメールとして使用されます |
| `email` (primary) | `emails[primary].value` | **はい** — `userName` と一致している必要があります |
| `firstName` | `name.givenName` | 推奨 |
| `lastName` | `name.familyName` | 推奨 |
| `displayName` | `displayName` | 推奨 — ClickHouse Cloud UI に表示されます |
| `externalId` | `externalId` | 推奨 — 照合時の精度向上に役立ちます |

department、manager、location などの任意の属性を追加できます。ClickHouse Cloud はこれらをユーザープロファイルに保存しますが、現時点では権限には使用しません。SCIM 標準セットに含まれない属性は、ClickHouse Cloud 側で無視されます。

> [!WARNING]
>
> **メールアドレスの大文字・小文字は重要です**
>
> Okta の `userName` と `email` で大文字・小文字が一致していることを確認してください。ClickHouse Cloud はメールアドレスを小文字に正規化するため、2 つのフィールドに不一致があるとテストに失敗することがあります。

**5. グループをプッシュしてユーザーを割り当てる**

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

**Okta でグループを作成します。** 先ほど設定した各ロールマッピングに対して、**表示名が完全に一致する** Okta グループを作成するか、既存のグループを特定します。たとえば、マッピングが `ClickHouse-Admins → Admin` であれば、Okta で `ClickHouse-Admins` という名前のグループを作成します。

![Okta で新しいグループを作成する](https://mintcdn.com/private-7c7dfe99/zhhfCE__w-UVvpQP/images/cloud/security/scim-okta/scim-okta-13.webp?fit=max\&auto=format\&n=zhhfCE__w-UVvpQP\&q=85\&s=f559beb7d4e4ece1e3412eca4ba00a71)

作成したグループを開き、`Assign people` をクリックしてメンバーを追加します。

![グループの Assign people をクリックする](https://mintcdn.com/private-7c7dfe99/zhhfCE__w-UVvpQP/images/cloud/security/scim-okta/scim-okta-14.webp?fit=max\&auto=format\&n=zhhfCE__w-UVvpQP\&q=85\&s=1d2199478dec60a933e0ea25becac48e)

![ユーザーをグループに割り当てる](https://mintcdn.com/private-7c7dfe99/zhhfCE__w-UVvpQP/images/cloud/security/scim-okta/scim-okta-15.webp?fit=max\&auto=format\&n=zhhfCE__w-UVvpQP\&q=85\&s=d02c4a2ca4e28a14311346599c84762b)

次に、ロールのメンバーシップとアプリへのアクセスを同期した状態に保つため、同じグループに SCIM アプリケーションも割り当てます。

![アプリケーションをグループに割り当てる](https://mintcdn.com/private-7c7dfe99/zhhfCE__w-UVvpQP/images/cloud/security/scim-okta/scim-okta-16.webp?fit=max\&auto=format\&n=zhhfCE__w-UVvpQP\&q=85\&s=46778fe178dd37672cbab15954c89470)

**グループをプッシュします。** アプリケーションの **Provisioning** タブで `Push Groups → Find groups by name` をクリックし、グループを検索して `Save` をクリックします。これを各ロールグループに対して繰り返します。プロビジョニングが完了すると、それぞれの **Push Status** は **Active (Pushed)** と表示されるはずです。

![アプリケーションの Push Groups タブで名前による Group Push を設定する](https://mintcdn.com/private-7c7dfe99/zhhfCE__w-UVvpQP/images/cloud/security/scim-okta/scim-okta-17.webp?fit=max\&auto=format\&n=zhhfCE__w-UVvpQP\&q=85\&s=aec2acb66665086a779764270f7ab5ed)

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

* **グループ経由 (推奨) 。** 先ほどプッシュした Okta グループにユーザーを追加します。ユーザーは ClickHouse Cloud にプロビジョニングされ、対応するロールが自動的に割り当てられます。
* **直接。** アプリケーションの **Assignments** タブで、`Assign → Assign to People` をクリックし、個別のユーザーを選択します。プッシュ済みのグループにも所属していない場合、ユーザーは **Default role** でプロビジョニングされます。

継続的な管理では、グループベースの割り当てのほうが簡潔です。誰かのロールが変わっても、更新するのはグループのメンバーシップだけで済みます。

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

Provisioning の設定が完了したら、ClickHouse Cloud Console の **Settings → Users and roles** に戻り、同期されたユーザーが想定どおりのロールで表示されていることを確認します。

![Users and roles でユーザー同期を確認](https://mintcdn.com/private-7c7dfe99/zhhfCE__w-UVvpQP/images/cloud/security/scim-okta/scim-okta-18.webp?fit=max\&auto=format\&n=zhhfCE__w-UVvpQP\&q=85\&s=a2dd21b10258bc2896e603f0c91ac15e)

チーム全体を割り当てる**前に**、1～2 人のテストユーザーでこの簡単なテスト計画を実施してください。各手順は数秒以内に成功するはずです。成功しない場合は、Okta の Tasks キューと [Troubleshooting](#troubleshooting) セクションを確認してください。

| # | Okta での操作 | ClickHouse Cloud での期待される結果 |
| - | - | - |
| 1 | テストユーザーを `ClickHouse-Admins` Okta グループに追加する | ユーザーが **Settings → Members** にロール **Admin** で表示される |
| 2 | テストユーザーが SSO 経由で ClickHouse Cloud にサインインする | 管理者権限を持った状態でダッシュボードが表示される |
| 3 | Okta でユーザーの名を更新する | 更新後の名前が数秒以内に **Members** に表示される |
| 4 | ユーザーを `ClickHouse-Admins` から `ClickHouse-Read-only` に移動する | ユーザーのロールが **Read-only** に変わる |
| 5 | アプリケーションからユーザーの割り当てを解除する (または Okta で無効化する) | ユーザーが組織から削除され、その後のサインインは失敗する |

いずれかの手順が失敗した場合は、先に進む前に根本原因を解消してください。問題はそのままにすると、症状が連鎖的に悪化することがよくあります。

> [!TIP]
>
> **Okta で SCIM エラーを確認する場所**
>
> SCIM エラーは、対象アプリケーションで絞り込んだ **Reports → System Log** と、アプリケーションの **Provisioning → View Logs** 画面に表示されます。ClickHouse Cloud から返されたエラーメッセージはそのまま表示されるため、まずはそこを確認してください。

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

### トークンは定期的にローテーションしてください

SCIMトークンのローテーションを忘れないよう、カレンダーにリマインダーを設定してください。推奨頻度は12か月ごと、またはそのトークンを把握していた管理者が退職した場合は直ちに実施することです。ClickHouse Cloud では、プロビジョニングを止めずにローテーションできるよう、組織ごとに2つのアクティブなトークンを利用できます。

### 直接割り当てではなく、グループを使ってください

アプリケーションにユーザーを直接割り当てることもできますが、すぐに監査しづらくなります。Okta のグループ経由で割り当てれば、アクセスレビューやロール変更を1か所で管理できます。

### 監査ログを確認してください

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

### 適切なデフォルトロールを設定してください。

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

### SCIM と手動招待を同時に使わないでください

SCIM を有効にしたら、メンバーシップは Okta 経由で管理し、同じユーザーに手動招待を送らないでください。両方を混在させると、どちらを正とすべきかが不明確になり、重複が発生することがあります。

### 失敗したプロビジョニングタスクを監視してください

Okta は失敗したプロビジョニング呼び出しを再試行しますが、最終的には **Tasks** キューに保留します。このキューを IT チームが普段監視しているダッシュボードに追加するか、Okta の webhook やメールアラートを使って、継続的な失敗を検知してください。

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

> [accordion] Okta で "Test connector configuration" が失敗する
>
> * ClickHouse Cloud Console で SCIM が**有効**になっていることを確認します。
> * Okta の**base URL** が、Cloud Console に表示されている SCIM エンドポイント URL と完全に一致していることを確認します。組織 ID が正しい必要があります。
> * **トークンのキーとシークレット**が、前後に空白を含まず貼り付けられていることを確認します。
> * トークンをローテーションした場合は、以前の組み合わせではなく、**新しい**キーとシークレットを使用していることを確認します。

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

> [accordion] メンバー一覧に重複ユーザーが表示される
>
> 通常は、Okta と過去の手動招待との間でメールアドレスの大文字小文字が一致していないことが原因です。Members 一覧から重複したユーザーを削除し、その後 Okta でそのユーザーの割り当てを解除してから再割り当てし、あらためてプロビジョニングしてください。

> [accordion] グループのプッシュが "displayName not recognised" で失敗する
>
> Okta のグループ名が、ClickHouse Cloud で設定されているマッピングと一致していません。Okta のグループ名を変更するか、SCIM Configuration パネル (または **Users and roles → Roles**) から **Map roles in "Users and roles"** にマッピングを追加してください。

> [accordion] 無効化されたユーザーが引き続きメンバーとして表示される
>
> Okta で無効化が反映されるまで最大 1 分かかることがあります。数分経ってもユーザーが引き続きメンバーとして表示される場合は、Okta の **Provisioning → View Logs** で無効化タスクのエラーを確認してください。

> [accordion] SCIM トークンをローテーションしたら Okta が失敗するようになった
>
> Okta で**同じ SCIM アプリケーション**の認証情報を更新したことを確認してください。更新後、`Test Connector Configuration` をクリックして確認します。プロビジョニングが正常な状態に戻ったら、ClickHouse Cloud Console で古いトークンを取り消します。

> [accordion] SCIM トークンを紛失した
>
> トークンは復元できません。ClickHouse Cloud Console の **組織設定 → SAML and SCIM settings → SCIM Configuration** で、紛失したトークンを取り消して新しいものを生成し、その後 Okta の認証情報を更新してください。

## よくある質問

> [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] SCIM は Microsoft Entra ID、OneLogin、またはその他の SCIM 2.0 IdP で動作しますか？
>
> Microsoft Entra ID もサポートされています — [Entra ID による SCIM プロビジョニング](https://clickhouse.com/docs/ja/products/cloud/guides/security/cloud-access-management/scim-setup-entra.md) を参照してください。エンドポイントは SCIM 2.0 (RFC 7644) に準拠しており、Basic Auth (Okta で使用) または Bearer token (Entra ID で使用) のいずれかを受け付けます。これらのいずれかの方法で認証できる場合、その他の SCIM 2.0 IdP も実際には動作する可能性がありますが、現時点でテスト済みかつサポート対象なのは Okta と Entra ID です。

> [accordion] Okta での変更はどれくらいで ClickHouse Cloud に反映されますか？
>
> ほとんどの操作は数秒以内に反映されます。大量の変更 (大規模なグループのプッシュ) は、規模によってはさらに時間がかかることがありますが、一時的なエラーに対しては Okta が自動的に再試行します。

> [accordion] 1 つの Okta テナントから複数の ClickHouse Cloud 組織をプロビジョニングできますか？
>
> はい — 組織ごとに、それぞれ専用の SCIM エンドポイント URL とトークンを使ってアプリケーションを 1 つずつインストールしてください。必要に応じて、同じ Okta グループを各アプリケーションに push できます。

> [accordion] 行き詰まった場合は、どこでサポートを受けられますか？
>
> ClickHouse Cloud Console の **Help → Contact support** からサポートチケットを作成し、次の情報を含めてください。
>
> * 組織 ID
> * Okta アプリケーション ID
> * Okta のログにある、失敗したタスクまたはテストのスクリーンショット
