CREATE USER ... IDENTIFIED WITH jwt ステートメントは存在せず、これを実行しようとすると例外が発生します。JWT ユーザーは、トークンのライフサイクルによって管理されます。
認証フローは次のとおりです。
- クライアントは、サポートされているいずれかの転送メカニズム (HTTP
Authorization: Bearerヘッダー、TCP ネイティブプロトコル、または gRPC のjwtフィールド) を介して署名付き JWT を提示します。 - ClickHouse はトークンの署名を検証します。
- 必須のクレーム (
exp、iat、iss、sub、aud) が検証されます。 clickhouse:grantsおよびclickhouse:rolesのトークンクレームから導出されたアクセス権と権限上限の積集合に基づいて、メモリ内に一時ユーザーが作成されます。- トークンの有効期限が切れると、バックグラウンドのガベージコレクションタスクによってそのユーザーは削除されます。
JWKS ベースの鍵解決を使用する場合は、
kid (key ID) ヘッダークレームも必須です。
iss、sub、aud のクレーム から計算される決定論的な UUID が割り当てられます。この UUID はログインをまたいでも 変わりません。異なるトークンで何度ログインしても、issuer、subject、audience が同じであれば、常に同じ UUID が割り当てられます。
一方、ユーザー名は 変動 します。次のように構成されます。
<claims_hash> は、iss、sub、aud のクレームと、clickhouse:roles および clickhouse:grants のクレームから導出されるハッシュです。iss と aud のクレームは このハッシュを通じてのみ 反映され、表示されるユーザー名のプレフィックスには直接埋め込まれなくなりました。これにより、iss/aud が長く不透明な IdP の URL (たとえば Microsoft Entra や Okta) であっても、名前を簡潔で読みやすく保ちつつ、異なる (iss, sub, aud) の組み合わせと、異なる clickhouse:roles / clickhouse:grants のセットが、それぞれ異なる安定した名前に対応することが保証されます。ハッシュに反映されないクレーム (たとえば iat、exp、nbf、または無関係なカスタムクレーム) は、ユーザー名を変更しません。
<claims_hash> の部分は、clickhouse:roles または clickhouse:grants のクレームが変更されるたびに変化します。つまり、同じアイデンティティであっても、ロールまたは権限セットが異なるトークンでは、生成されるユーザー名も異なります。
有効なアクセス権は次のように算出されます。
permission_limit は、上限として設定された参照ロールまたはユーザーが保持するアクセス権の集合です。トークンが要求した権限のうち、この上限を超えるものは、通知されることなく破棄されます。
ClickHouse は、安定した各アイデンティティについて、直近に認証されたトークンの iat (発行時刻) クレームを追跡します。保存済みの値と同じか、それより古い iat を持つトークンが提示された場合、サーバーはクレームを再評価せず、既存の一時ユーザーを再利用します。これにより、古いトークンによってユーザーの権限が引き下げられるのを防ぎます。
一時ユーザーは、トークンが最初に認証されたときに作成され、valid_until (exp から導出) が過ぎると、バックグラウンドのガベージコレクション タスクによって削除されます。GC の間隔は、gc_interval パラメータ (デフォルト: 5 分) で制御されます。
GC の実行間では、期限切れのユーザーが system.users に表示されたままになることがありますが、認証はできなくなります。
UUID は変わらないため、SQLステートメントを使用して、設定プロファイル、クォータ、行ポリシー、カラムのマスキングポリシーを JWT ユーザーに割り当てることができます。これらの割り当てはアクセス制御ストレージ (ディスク上または ZooKeeper 内) に永続的に保存され、トークンの有効期限切れや再認証後も維持されます。
ユーザーは現在のユーザー名で参照してください:
指定した アイデンティティ のユーザー名と UUID は、ユーザーが有効な間、
system.users の name カラムと id カラムで確認できます。ALTER USER は読み取り専用のため、JWTユーザーには直接使用できないことに注意してください。設定プロファイル、クォータ、またはポリシーを割り当てるには、上記のとおり ALTER SETTINGS PROFILE、ALTER QUOTA、または ALTER ROW POLICY ステートメントを使用してください。
一時ユーザーである JWT ユーザーが
SQL SECURITY DEFINER を指定してビューを作成すると、サーバーはそのビューの定義者として機能する永続的なシャドウコピーを自動的に作成します。このシャドウユーザーには、次の特性があります。
- 名前は
<original_jwt_username>:definer NO_AUTHENTICATIONが設定される (ログインには使用できません)- ビュー作成時点で、元の JWT ユーザーと同じアクセス権を保持する
clickhouse-client で --jwt フラグを指定します。
--jwt フラグは --user と同時に使用できません。--jwt を指定した場合、ユーザー名はトークンから取得されます。Authorization ヘッダーに指定して送信します:
OAuth2 デバイスコードによるログイン
clickhouse-client は、--login フラグにより、対話型の OAuth 2.0 デバイス認可グラント (RFC 8628) をサポートしています。
ClickHouse Cloud のエンドポイントに接続する際に --oauth-* オプションを指定しない場合、クライアントは ClickHouse Cloud の IdP でログインし、トークン交換を自動的に実行して ClickHouse 固有の JWT を取得します。トークンは session 中に透過的にリフレッシュされ、新しいトークンを取得すると、クライアントは自動的に再接続します。
--oauth-url に指定します。--oauth-* オプションをいずれか 1 つでも指定すると、ClickHouse Cloud のホストに対してもカスタム IdP フローが使用されます (たとえば、サービスで カスタム identity provider による JWT認証 が有効になっている場合など) 。クライアントは、発行元 の /.well-known/openid-configuration (および関連する OAuth メタデータ URL) から device_authorization_endpoint と token_endpoint を自動検出します。grant_types_supported が存在する場合は、urn:ietf:params:oauth:grant-type:device_code が含まれている必要があります。検出に失敗するとクライアントはエラーを報告するため、メタデータが使用できない場合は --oauth-device-uri と --oauth-token-uri の両方を明示的に指定してください。
ログイン時、クライアントは短い verification_uri と user_code (RFC 8628) を出力します。IdP が verification_uri_complete も返す場合は、そのショートカット URL が出力されてブラウザで開かれます。さらに qrencode ツールが利用可能であれば、端末上に QR コードとしても表示されます。ClickHouse Cloud の IdP では、verification_uri_complete と user_code のみが出力されます。コンフィデンシャルクライアントでは、--oauth-client-secret を --oauth-client-auth basic|post と組み合わせて指定できます。
clickhouse:roles 永続ボリューム要求) によって決まります。ClickHouse Cloud でこのフローを利用する際に必要な Entra ID アプリケーションの設定については、Microsoft Entra ID による JWT認証 を参照してください。
すべての ClickHouse Cloud サービスには、SQL Console と clickhouse-client の --login フローで使用される、あらかじめ定義された JWT 認証器が用意されています。この認証器は次のように設定されています。
この組み込み認証器の権限上限は、
default_role ロールおよび default ユーザーに設定されています。つまり、JWT ユーザーの実効権限はこの 2 つが持つ権限との積集合になるため、トークンによって default_role と default に許可されている範囲を超えて権限を昇格させることはできません。
この認証器を使用するために、追加の設定は必要ありません。サービスの作成時に自動的にプロビジョニングされます。
組み込みの 認証器 に加えて、独自の identity provider (Microsoft Entra や Okta など) が発行する JWT を受け入れるよう、ClickHouse Cloud サービスを設定できます。この機能は、ClickHouse バージョン 26.4 以降を実行するサービスでは Enterprise プランで利用できます。Cloud Console の Settings → Security → JWT認証 からご自身で設定できます。手順については JWT認証 setup を、Entra ID のエンドツーエンドのセットアップについては JWT認証 with Microsoft Entra ID を参照してください。各プロバイダーは、以下によって定義されます。
クエリが別の分片またはレプリカに転送される際、JWTトークンはサーバー間プロトコルにも含まれます。リモートノードはそのトークンを独自に再認証し、独自の一時ユーザーを作成します。
- アクセス権が付与されていない: 参照先のロールまたはユーザーに、必要な権限が付与されていない可能性があります。
clickhouse:rolesで参照しているロールが存在し、適切な権限が含まれていることを確認してください。 - トークンが拒否される: トークン内の
iss、aud、および署名アルゴリズムが、JWT プロバイダーの想定と一致していることを確認してください。JWKS を使用している場合は、トークンのkidがプロバイダーのキーセット内のキーと一致していることを確認してください。 - クエリの間にユーザーが消える: 一時ユーザーは、トークンの有効期限が切れると削除されます。長時間のセッションでは、トークンの更新をサポートするクライアント (例:
--loginモード) を使用してください。 CREATE USER ... IDENTIFIED WITH jwtが失敗する: これは想定どおりです。JWT ユーザーは DDL では作成できません。管理は完全にトークンのライフサイクルに委ねられます。