> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-vortex-format.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Token に関するドキュメント

# CREATE TOKEN

現在のユーザーのトークンを作成します。サーバーはランダムなシークレットを生成し、それを追加の[認証方式](/ja/reference/statements/create/user#identification)として現在のユーザーに追加したうえで、クエリの結果として返します。このシークレットが表示されるのはこのクエリのときのみです。ハッシュ化されて保存されるため、後から復元することはできません。

構文:

```sql theme={null}
CREATE TOKEN
    [{VALID UNTIL datetime | VALID FOR interval}]
    [GRANTS (privilege ON object [,...])]
```

これは、同じ [`VALID UNTIL`](/ja/reference/statements/create/user#valid-until-clause) 句および
[`GRANTS`](/ja/reference/statements/create/user#grants-clause) 句を指定した `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行を返します:

| カラム | Type | Description |
| - | - | - |
| `token` | `String` | 生成されたシークレット。 |
| `valid_until` | `DateTime64(0)` | トークンの有効期限。`0` は有効期限がないことを意味し、[`system.users`](/ja/reference/system-tables/users) の `valid_until` カラムと同じエンコーディングです。 |

フォーマットを適用せずにシークレットを取得するには、`FORMAT TSVRaw` を指定して SELECT します:

```sql theme={null}
CREATE TOKEN VALID FOR INTERVAL 30 DAY GRANTS (SELECT ON db.*) FORMAT TSVRaw
```

このシークレットは32文字の長さで、暗号学的に安全な乱数ソースから生成されるため、[パスワードの複雑性ルール](/ja/reference/statements/create/user#identification)によるチェックを受ける必要はなく、実際にチェックもされません。これらのルールは、人間が選んだパスワードを制約するために存在しています。

## VALID UNTIL 句と VALID FOR 句

トークンの有効期間を制限します。これらは [`CREATE USER`](/ja/reference/statements/create/user#valid-until-clause) における認証方式の対応する句とまったく同じように動作します。`VALID UNTIL` には絶対的な日付と時刻を指定し、`VALID FOR` には [interval](/ja/reference/data-types/special-data-types/interval) を指定します。指定した interval は、クエリ実行時の現在時刻に加算されます。

いずれの句も指定しない場合、トークンの有効期間は [`create_token_default_ttl_seconds`](/ja/reference/settings/session-settings/create) に従い、デフォルトでは 30 分です。つまり、より長い有効期間を明示的に指定しないトークンは短命ということになります。有効期限のないトークンを作成するには、この設定を `0` にするか、`VALID UNTIL 'infinity'` と記述してください。

例:

* `CREATE TOKEN VALID UNTIL '2026-12-31'`
* `CREATE TOKEN VALID FOR INTERVAL 30 DAY`
* `CREATE TOKEN VALID UNTIL 'infinity'`

## GRANTS 句

トークンで認証されたセッションのアクセス権を、列挙された権限との積集合に制限します。動作は [`CREATE USER` の `GRANTS` 句](/ja/reference/statements/create/user#grants-clause)と完全に同じで、その制限事項も引き継ぎます。特に、この制限はクエリを受け取ったノードでのみ適用され、クラスターの他のノードには伝播しません。この句によってアクセス権が追加されることはありません。ユーザーに付与されていない権限は、トークンでも使用不可のままです。この句を指定しない場合、トークンはユーザーのすべてのアクセス権を持ちます。

例:

* `CREATE TOKEN GRANTS (SELECT ON db.table)`
* `CREATE TOKEN VALID FOR INTERVAL 90 DAY GRANTS (SELECT ON db.table, INSERT ON db.table)`

この制限も有効期限も、トークンのセッションが残したものには適用されません。[セキュリティ上の考慮事項](#security-considerations)を参照してください。

## トークンの管理

トークンはユーザーの認証方式の一つであるため、[`SHOW CREATE USER`](/ja/reference/statements/show#show-create-user) (`VALID UNTIL` 句および `GRANTS` 句とともに、ただしシークレットは除く) や、[`system.users`](/ja/reference/system-tables/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](/ja/reference/statements/create/view#refreshable-materialized-view) はリフレッシュを続け、
  [`Kafka`](/ja/reference/engines/table-engines/integrations/kafka)、
  [`RabbitMQ`](/ja/reference/engines/table-engines/integrations/rabbitmq)、
  [`NATS`](/ja/reference/engines/table-engines/integrations/nats)、
  [`S3Queue`](/ja/reference/engines/table-engines/integrations/s3queue) などのストリーミングテーブルエンジンにアタッチされた materialized view は消費を続け、
  [`LIFETIME`](/ja/reference/statements/create/dictionary/lifetime) を持つ Dictionary はリロードを続けます。トークンの有効期限が切れてからずっと後でも同様です。VIEW はこれらの処理を自身の
  [`DEFINER`](/ja/reference/statements/create/view#sql_security) の権限で実行します。DEFINER はデフォルトではその VIEW を作成したユーザーであり、トークンの `GRANTS` 句によって絞り込まれた権限ではなく、そのユーザーの全権限が用いられます。

したがって、テーブル、VIEW、Dictionary の作成を許可されたトークンは、実質的にこの両方の制限を越えられてしまいます。デッドラインを過ぎても動作し続ける永続的なジョブを残し、トークン自体には許可されていなかった処理をユーザーの権限で実行させられるからです。トークンには、アプリケーションが必要とするものだけ (通常は指定したテーブルに対する `SELECT` と `INSERT`) を付与してください。制限を確実に機能させたい場合は、`CREATE TABLE`、`CREATE VIEW`、`CREATE DICTIONARY` および `ACCESS MANAGEMENT` の権限を `GRANTS` 句に含めないでください。

`GRANTS` 句を持つトークンで認証したセッションは、トークンを一切発行できません。そのようなセッションからは、既存のユーザーへの認証方式の追加が拒否されます。新しい認証方式の `GRANTS` 句は、ログイン時にユーザーのアクセス権との積集合が取られるのであり、その認証方式を作成したセッションのアクセス権とではありません。これを許せば、制限を広げる抜け道になってしまうためです。