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) ヘッダークレームも必須です。
その他の認識済みクレーム
オプションのクレーム
トークン、ヘッダー、ペイロードの例
一時ユーザーの動作
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 は、上限として設定された参照ロールまたはユーザーが保持するアクセス権の集合です。トークンが要求した権限のうち、この上限を超えるものは、通知されることなく破棄されます。
トークンの新しさ
iat (発行時刻) クレームを追跡します。保存済みの値と同じか、それより古い iat を持つトークンが提示された場合、サーバーはクレームを再評価せず、既存の一時ユーザーを再利用します。これにより、古いトークンによってユーザーの権限が引き下げられるのを防ぎます。
有効期間とガベージコレクション
valid_until (exp から導出) が過ぎると、バックグラウンドのガベージコレクション タスクによって削除されます。GC の間隔は、gc_interval パラメータ (デフォルト: 5 分) で制御されます。
GC の実行間では、期限切れのユーザーが system.users に表示されたままになることがありますが、認証はできなくなります。
永続的なアクセス割り当て
指定した アイデンティティ のユーザー名と UUID は、ユーザーが有効な間、
system.users の name カラムと id カラムで確認できます。ALTER USER は読み取り専用のため、JWTユーザーには直接使用できないことに注意してください。設定プロファイル、クォータ、またはポリシーを割り当てるには、上記のとおり ALTER SETTINGS PROFILE、ALTER QUOTA、または ALTER ROW POLICY ステートメントを使用してください。
一般ユーザーとの違い
SQL SECURITY DEFINER を使用するビュー
SQL SECURITY DEFINER を指定してビューを作成すると、サーバーはそのビューの定義者として機能する永続的なシャドウコピーを自動的に作成します。このシャドウユーザーには、次の特性があります。
- 名前は
<original_jwt_username>:definer NO_AUTHENTICATIONが設定される (ログインには使用できません)- ビュー作成時点で、元の JWT ユーザーと同じアクセス権を保持する
クライアントの利用
トークンを直接渡す
clickhouse-client で --jwt フラグを指定します。
--jwt フラグは --user と同時に使用できません。--jwt を指定した場合、ユーザー名はトークンから取得されます。HTTP インターフェイス
Authorization ヘッダーに指定して送信します：
OAuth2 デバイスコードログイン
clickhouse-client は、--login フラグによる対話型の OAuth2 デバイスコードフローをサポートしています。ClickHouse Cloud エンドポイントでは、ClickHouse 固有の JWT を取得するためのトークン交換がクライアントによって自動的に行われます。トークンはセッション中に透過的に更新されます。新しいトークンを取得すると、クライアントは自動的に再接続します。
ClickHouse Cloud 組み込み JWT 認証器
clickhouse-client の --login フローで使用される、あらかじめ定義された JWT 認証器が用意されています。この認証器は次のように設定されています。
この組み込み認証器の権限上限は、
default_role ロールおよび default ユーザーに設定されています。つまり、JWT ユーザーの実効権限はこの 2 つが持つ権限との積集合になるため、トークンによって default_role と default に許可されている範囲を超えて権限を昇格させることはできません。
この認証器を使用するために、追加の設定は必要ありません。サービスの作成時に自動的にプロビジョニングされます。
サービスで JWT 認証を有効にする
サーバー間通信
トラブルシューティング
- アクセス権が付与されていない: 参照先のロールまたはユーザーに、必要な権限が付与されていない可能性があります。
clickhouse:rolesで参照しているロールが存在し、適切な権限が含まれていることを確認してください。 - トークンが拒否される: トークン内の
iss、aud、および署名アルゴリズムが、JWT プロバイダーの想定と一致していることを確認してください。JWKS を使用している場合は、トークンのkidがプロバイダーのキーセット内のキーと一致していることを確認してください。 - クエリの間にユーザーが消える: 一時ユーザーは、トークンの有効期限が切れると削除されます。長時間のセッションでは、トークンの更新をサポートするクライアント (例:
--loginモード) を使用してください。 CREATE USER ... IDENTIFIED WITH jwtが失敗する: これは想定どおりです。JWT ユーザーは DDL では作成できません。管理は完全にトークンのライフサイクルに委ねられます。