Microsoft Entra ID を使用した SCIM プロビジョニング

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

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

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

https://api.clickhouse.cloud/v1/organizations/<your-org-id>/scim

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

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

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

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

<scim-key>:<scim-secret>

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

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 の概要を開き、左側のメニューの Manage で Enterprise applications を選択します。ClickHouse Cloud の SAML SSO を設定した際に作成したアプリケーションを開きます。

エンタープライズ アプリケーションをまだ作成していない場合は、まず SAML SSO セットアップガイド に従ってください。SAML ベースの SSO では、同じエンタープライズ アプリケーションをシングルサインオンと 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 エンドポイントに対してテスト呼び出しを行い、成功通知が表示されます。失敗した場合は、トラブルシューティングを参照してください。

Save をクリックします。

認証情報を保存したら、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 側で無視されます。

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

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

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

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

Save をクリックします。

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

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

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

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

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

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

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

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