VALID UNTIL 句および
GRANTS 句を指定した ALTER USER <current user> ADD IDENTIFIED WITH sha256_password BY '<random secret>' の短縮形であり、トークンは現在のユーザーの通常のパスワードと同じように動作します。
- トークンはユーザーに紐づきます。
system.query_logおよびsystem.processesにはそのユーザーとして表示され、ユーザーが削除されると使用できなくなり、ユーザーがアクセス権を失えばトークンもアクセス権を失います。 VALID UNTILまたはVALID FORで有効期間を、GRANTSで権限を制限できます。- パスワードを受け付けるあらゆる認証メカニズムで使用できます。たとえば、HTTP インターフェイスの
passwordパラメータやclickhouse-clientの--passwordオプションなどです。
CREATE TOKEN 権限、または現在のユーザーに対する ALTER USER 権限が必要です。
これが独立した権限になっているのは、トークンが属するアカウントのセキュリティレベルを低下させるためです。ハードウェアキーや証明書で認証されたユーザーであっても、トークンを使えば同じアカウントに対して長期間有効なパスワードを作成できてしまいます。同じ権限で、同等の
ALTER USER <current user> ADD IDENTIFIED ... ステートメントも実行できます。
結果
このクエリは、2つのカラムを持つ1行を返します:
フォーマットを適用せずにシークレットを取得するには、
FORMAT TSVRaw を指定して SELECT します:
VALID UNTIL 句と VALID FOR 句
トークンの有効期間を制限します。これらはCREATE USER における認証方式の対応する句とまったく同じように動作します。VALID UNTIL には絶対的な日付と時刻を指定し、VALID FOR には interval を指定します。指定した interval は、クエリ実行時の現在時刻に加算されます。
いずれの句も指定しない場合、トークンの有効期間は create_token_default_ttl_seconds に従い、デフォルトでは 30 分です。つまり、より長い有効期間を明示的に指定しないトークンは短命ということになります。有効期限のないトークンを作成するには、この設定を 0 にするか、VALID UNTIL 'infinity' と記述してください。
例:
CREATE TOKEN VALID UNTIL '2026-12-31'CREATE TOKEN VALID FOR INTERVAL 30 DAYCREATE TOKEN VALID UNTIL 'infinity'
GRANTS 句
トークンで認証されたセッションのアクセス権を、列挙された権限との積集合に制限します。動作はCREATE USER の GRANTS 句と完全に同じで、その制限事項も引き継ぎます。特に、この制限はクエリを受け取ったノードでのみ適用され、クラスターの他のノードには伝播しません。この句によってアクセス権が追加されることはありません。ユーザーに付与されていない権限は、トークンでも使用不可のままです。この句を指定しない場合、トークンはユーザーのすべてのアクセス権を持ちます。
例:
CREATE TOKEN GRANTS (SELECT ON db.table)CREATE TOKEN VALID FOR INTERVAL 90 DAY GRANTS (SELECT ON db.table, INSERT ON db.table)
トークンの管理
トークンはユーザーの認証方式の一つであるため、SHOW CREATE USER (VALID UNTIL 句および GRANTS 句とともに、ただしシークレットは除く) や、system.users テーブルの auth_type、auth_params、auth_grants カラムに表示されます。
個々のトークンだけを削除するステートメントはありません。あるユーザーのすべてのトークンを取り消すには、ALTER USER <name> IDENTIFIED WITH ... などで認証方式を置き換えるか、ALTER USER <name> RESET AUTHENTICATION METHODS TO NEW を使用して最後に追加された認証方式のみを残してください。1 人のユーザーが同時に保持できる認証方式の数は、サーバー設定 max_authentication_methods_per_user によって制限されます。
シークレットはクエリ自体によって生成・保存されます。そのため、結果がクライアントに届かなかった CREATE TOKEN (行の送信中に接続が切断された場合や、クライアントが開けない INTO OUTFILE を指定した場合など) では、誰も使用できないにもかかわらず上限にはカウントされる認証方式が残ってしまいます。このシークレットは誰も保持しておらず、クエリの実行中にのみ存在します。なお、実行前に拒否されたクエリ (FORMAT 句で使用できないフォーマットを指定した場合を含む) では、認証方式は追加されません。
CREATE TOKEN は ON CLUSTER 句をサポートしていません。アクセスエンティティがローカルに保存されているクラスター全体でトークンを機能させるには、レプリケーションされたアクセスストレージを使用するか、同等の ALTER USER ... ADD IDENTIFIED WITH sha256_hash ステートメントをすべてのノードで実行してください。
セキュリティ上の考慮事項
VALID UNTIL と GRANTS が制約するのは、トークンで認証するセッションであり、そのセッションが残したものまでは制約しません。
- デッドラインがチェックされるのは、セッションがトークンで認証する時点です。すでに開いているセッションや、すでに実行中のクエリは、トークンの有効期限が切れても中断されません。
- セッションが作成したものはすべてトークンより長く存続し、自律的に動作するオブジェクトは動作を続けます。すなわち、
リフレッシャブルmaterialized view はリフレッシュを続け、
Kafka、RabbitMQ、NATS、S3Queueなどのストリーミングテーブルエンジンにアタッチされた materialized view は消費を続け、LIFETIMEを持つ Dictionary はリロードを続けます。トークンの有効期限が切れてからずっと後でも同様です。VIEW はこれらの処理を自身のDEFINERの権限で実行します。DEFINER はデフォルトではその VIEW を作成したユーザーであり、トークンのGRANTS句によって絞り込まれた権限ではなく、そのユーザーの全権限が用いられます。
SELECT と INSERT) を付与してください。制限を確実に機能させたい場合は、CREATE TABLE、CREATE VIEW、CREATE DICTIONARY および ACCESS MANAGEMENT の権限を GRANTS 句に含めないでください。
GRANTS 句を持つトークンで認証したセッションは、トークンを一切発行できません。そのようなセッションからは、既存のユーザーへの認証方式の追加が拒否されます。新しい認証方式の GRANTS 句は、ログイン時にユーザーのアクセス権との積集合が取られるのであり、その認証方式を作成したセッションのアクセス権とではありません。これを許せば、制限を広げる抜け道になってしまうためです。