始める前に
以下のものが必要です。- Enterprise プランの組織と、ClickHouse バージョン 26.4 以降で稼働しているサービス。
-
JWT プロバイダーを追加するための、対象サービスに対する
control-plane:service:manageアクセス許可を持つ ClickHouse Cloud ロール (例: 管理者 または サービス管理者) 。 - Cloud Application Administrator 以上のロールを持つ、Microsoft Entra admin center へのアクセス権。
- 個々のユーザーではなくグループをアプリロールに割り当てる場合は、Microsoft Entra ID P1 または P2。
-
セットアップをテストするための Azure CLI (
az) とclickhouse-client。 -
Entra ID 経由で付与する ClickHouse ロールの一覧。各ロールは、同じ名前の Entra ID アプリロールとして作成します。このガイドでは次の 2 つを使用します。
仕組み
- ClickHouse Cloud サービスを表すアプリケーションを Entra ID に登録し、ClickHouse ロールごとにアプリロールを 1 つずつ定義します。
- Entra ID のユーザー、グループ、アプリケーションを、それらのアプリロールに割り当てます。
- ユーザーが Azure CLI または
clickhouse-client --loginでサインインするか、アプリケーションがクライアント認証情報グラントを使用します。Entra ID は v2.0 アクセストークンを発行します。このトークンのaudclaim にはアプリケーション (クライアント) ID が設定され、rolesclaim には呼び出し元に割り当てられたアプリロールが列挙されます。 - ClickHouse Cloud は Entra ID の公開鍵を使用してトークンの署名を検証し、
issおよびaudclaim を確認したうえで、rolesclaim で指定された ClickHouse ロールの権限を持つ一時ユーザーを作成します。ただし、この権限はdefaultユーザーの権限が上限となります。
Entra ID に ClickHouse を登録する
1
アプリの登録を作成する
Microsoft Entra 管理センターで App registrations を開き、New registration を選択します。
- Name: 表示名を入力します。例:
clickhouse-cloud-production - Supported account types: シングルテナントを選択します。ポータルのバージョンによって、このオプションは Single tenant only または Accounts in this organizational directory only と表示されます。
- Redirect URI: 空欄のままにします。ユーザーはリダイレクト URI を使用しないデバイスコードフローでサインインします。
- Application (client) ID (以下
<CLIENT_ID>) 。トークンのaudclaim になります。 - Directory (tenant) ID (以下
<TENANT_ID>) 。発行元および JWKS URL の一部として使用されます。
2
v2.0 アクセストークンをリクエストする
デフォルトでは、Entra ID は v1.0 のアクセストークンを発行し、その発行元は
https://sts.windows.net/<TENANT_ID>/ です。代わりに v2.0 トークンを受け取るようにアプリケーションを設定してください。v2.0 トークンの発行元は https://login.microsoftonline.com/<TENANT_ID>/v2.0 で、aud claim は常にクライアント ID になります。アプリの登録で Manifest を開き、アクセストークンのバージョンを 2 に設定して 保存 を選択します。プロパティ名は、エディターに表示されるマニフェストのフォーマットによって異なります。- Microsoft Graph フォーマット:
apiセクション内のrequestedAccessTokenVersion - Azure AD Graph フォーマット: 下のスクリーンショットのとおり、top-level の
accessTokenAcceptedVersion
3
API を公開する
Expose an API を開きます。
-
Application ID URI の横にある Add を選択し、デフォルト値
api://<CLIENT_ID>のまま保存します。クライアントはこの URI を使用して ClickHouse 用のトークンをリクエストします。なお、この設定によって v2.0 トークンのaudclaim が変わることはなく、値はクライアント ID のままです。 -
Add a scope を選択し、フォームに入力します。このスコープは、ユーザーがサインインする際にリクエストされます。アプリケーション自身として認証するアプリケーションでは使用されません。
5
アプリロールを作成する
各アプリロールは、1つのClickHouseロールに対応します。アプリロールの Value はトークンの
roles claimに含まれる値であり、大文字・小文字の区別も含めてClickHouseロールの名前と完全に一致している必要があります。App roles を開き、ClickHouseロールごとに Create app role を選択します。次の例では、ClickHouseロール名を値とする3つのアプリロールを定義しています。
6
割り当てを必須にする
デフォルトでは、tenant 内のすべてのユーザーがアプリケーションのトークンを取得できます。トークンの取得をアプリロールに割り当てたユーザー、グループ、アプリケーションのみに制限するには、Enterprise applications を開いてアプリ登録と同じ名前のアプリケーションを選択し、Properties を開きます。次に、Assignment required? を Yes に設定して Save を選択します。
7
ユーザーとグループをアプリのロールに割り当てる
同じエンタープライズアプリケーションで Users and groups を開き、Add user/group を選択します。ユーザーまたはグループを選び、アプリロールを選択してから Assign を選択します。この手順を、ユーザーまたはグループごとに繰り返します。直接またはグループ経由で複数のアプリロールが割り当てられているユーザーの場合、
roles claim にはそれらすべてのロールが含まれます。グループをアプリロールに割り当てるには、Microsoft Entra ID P1 または P2 が必要です。ネストされたグループはサポートされていません。アプリロールが付与されるのは、割り当てられたグループの直接のメンバーのみです。
ClickHouse で対応するロールを作成する
SQL コンソールなどからdefault ユーザーとしてサービスに接続し、アプリロールの値ごとにロールを作成します。
- ロール名は case-sensitive であり、アプリロールの値と一致している必要があります。
- ClickHouse は、
rolesclaim に含まれる名前のうち、サービス上の既存のロールと一致しないものを無視します。 - ClickHouse Cloud における JWTプロバイダーの権限上限は
defaultユーザーです。ロールの権限のうちdefaultユーザーが持たないものは、ClickHouse によってすべて削除されます。
Entra ID を JWTプロバイダーとして追加する
JWTプロバイダーを追加する の手順に従い、次の値を入力します。ユーザーとして接続する
アプリ登録で取得した値とサービスホスト名を、シェル変数として設定します。Azure CLI トークンを渡す
Azure CLI でサインインして ClickHouse アプリケーション用のアクセストークンをリクエストし、--jwt で clickhouse-client に渡します。
--login を使用してください。
clickhouse-client でサインインする
clickhouse-client は OAuth 2.0 デバイスコードフローを単独で実行でき、session 中にトークンを更新することもできます。
offline_access を必ず含めておいてください。これにより Entra ID がリフレッシュトークンを返すようになり、クライアントはこれを使ってアクセストークンを更新します。含めない場合は、アクセストークンの有効期限が切れるたびにサインインし直す必要があります。
アプリケーションとして接続する
ETL ジョブやバックエンドサービスなどのアプリケーションは、OAuth 2.0 のクライアント資格情報グラントを使用して、アプリケーション自身として認証します。アプリケーションに付与するアプリロールでは、メンバーの種類として Applications が許可されている必要があります。- App registrations で、ワークロード専用のアプリケーションを別途登録します。Certificates & secrets で、クライアントシークレットを作成するか、証明書をアップロードします。以下のコマンドでは、ワークロードのクライアント ID とシークレットをそれぞれ
<WORKLOAD_CLIENT_ID>、<WORKLOAD_CLIENT_SECRET>と表記します。 - ワークロードのアプリ登録で API permissions を開き、Add a permission を選択します。APIs my organization uses で ClickHouse アプリケーションを探して Application permissions を選択し、ワークロードに必要なアプリロールを選んで Add permissions を選択します。
- Grant admin consent を選択して、アプリロールをワークロードに割り当てます。
確認
接続後、session のアイデンティティと権限を確認します。
ClickHouse は、ロールそのものを一時ユーザーに付与するわけではありません。トークンで指定されたロールの権限を収集し、
default ユーザーの権限との積集合を求めたうえで、その結果をユーザーに直接付与します。そのため、SHOW CURRENT ROLES は行を返しません。
ユーザートークンの場合、Entra ID は sub に、ユーザーとアプリケーションの組み合わせごとに一意な不透明な識別子を設定します。これはユーザーのメールアドレスやオブジェクト ID ではありません。
ベストプラクティス
個々のユーザーではなくグループを割り当てる
各アプリロールに Entra ID グループを 1 つずつ割り当て、アクセスの付与や取り消しはグループのメンバーを変更して行います。こうしておけば、チームにメンバーが加わったり抜けたりしても、アプリケーションを編集する必要はありません。環境ごとに個別のアプリ登録を使用する
トークンのaud claim には、発行元のアプリ登録のクライアント ID が含まれます。本番環境とステージング環境で個別のアプリ登録を使用すれば、一方の環境向けに発行されたトークンでもう一方の環境に認証することはできません。
ロールの変更は次に発行されるトークンから反映される
Entra ID は、トークンの発行時にroles claim を書き込みます。そのため、ユーザーのアプリロールの割り当てを変更しても、変更が反映されるのはユーザーが新しいトークンを取得した時点です。発行済みのトークンは、有効期限が切れるまで変更前のロールを保持します。Azure CLI を使用している場合は、az logout と az login を実行すると、新しいトークンをすぐに取得できます。
トラブルシューティング
トークンが拒否され、発行元が https://sts.windows.net で始まっている
トークンが拒否され、発行元が https://sts.windows.net で始まっている
Entra ID が v1.0 トークンを発行しています。v2.0 アクセストークンを要求する の手順に従ってアプリケーションのマニフェストで
requestedAccessTokenVersion を 2 に設定し、トークンを再取得してください。オーディエンスが原因でトークンが拒否される
オーディエンスが原因でトークンが拒否される
- ClickHouse Cloud のプロバイダーの Audience には、
api://<CLIENT_ID>ではなくクライアント ID を指定する必要があります。 - ClickHouse アプリケーション向けのトークンを要求しているか確認してください。
--resourceを指定しないと、az account get-access-tokenは Azure Resource Manager 向けのトークンを返します。
Entra ID が AADSTS65001 を返す、または同意を求められる
Entra ID が AADSTS65001 を返す、または同意を求められる
クライアントアプリケーションが
access_as_application スコープに対して事前承認されていません。ユーザーのサインイン用にクライアントアプリケーションを承認する の手順に従い、Expose an API → Authorized client applications にそのクライアント ID を追加してください。Entra ID が AADSTS50105 または AADSTS501051 を返す
Entra ID が AADSTS50105 または AADSTS501051 を返す
Assignment required? が Yes に設定されているにもかかわらず、ユーザーまたはアプリケーションが ClickHouse アプリケーションに割り当てられていません。ユーザー、そのユーザーが所属するグループ、またはアプリケーションをアプリロールに割り当ててください。グループを割り当てた場合は、ユーザーがそのグループの直接のメンバーになっていることを確認してください。
認証は成功するが、クエリが ACCESS_DENIED で失敗する
認証は成功するが、クエリが ACCESS_DENIED で失敗する
一時ユーザーに、クエリの実行に必要な権限がありません。次の点を確認してください。
- プロバイダーの Roles claim が
rolesに設定されていること。 - トークンに
rolesクレームが含まれていること。呼び出し元がアプリロールなしでアプリケーションに割り当てられている場合、このクレームは含まれません。 rolesクレームの各値が、サービス上の既存の ClickHouse ロールと大文字・小文字まで一致していること。- ロールに付与した権限を
defaultユーザーが保持していること。
クレームマッピングポリシーの設定後にトークンが拒否される
クレームマッピングポリシーの設定後にトークンが拒否される
アプリケーションにクレームマッピングポリシーやカスタム署名キーを設定している場合、Entra ID はテナントの JWKS に含まれないキーでトークンに署名します。プロバイダーの JWKS URL を
https://login.microsoftonline.com/<TENANT_ID>/discovery/v2.0/keys?appid=<CLIENT_ID> に設定してください。関連項目
- JWT認証のセットアップ: クラウドコンソールでJWTプロバイダーを追加、更新、削除する方法について説明します。
- JWT認証: トークンのクレーム、一時ユーザー、クライアントでの使用方法について説明します。