> ## 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

현재 사용자의 토큰을 생성합니다. 서버가 임의의 시크릿을 생성해 현재 사용자에게 추가 [인증 메서드](/ko/reference/statements/create/user#identification)로 등록하고, 이를 쿼리 결과로 반환합니다. 이 시크릿은 이 쿼리에서만 확인할 수 있으며, 해시된 형태로 저장되므로 이후에는 복구할 수 없습니다.

구문:

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

이는 동일한 [`VALID UNTIL`](/ko/reference/statements/create/user#valid-until-clause) 및
[`GRANTS`](/ko/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 ...` SQL 문도 실행할 수 있습니다.

## 결과

이 쿼리는 두 개의 컬럼으로 구성된 행 하나를 반환합니다:

| 컬럼 | 유형 | 설명 |
| - | - | - |
| `token` | `String` | 생성된 시크릿입니다. |
| `valid_until` | `DateTime64(0)` | 토큰이 만료되는 시점입니다. `0`은 만료되지 않음을 의미하며, [`system.users`](/ko/reference/system-tables/users)의 `valid_until` 컬럼과 동일한 인코딩입니다. |

별도의 포맷 없이 시크릿 값만 얻으려면 `FORMAT TSVRaw`로 조회하십시오:

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

이 시크릿은 길이가 32자이며 암호학적으로 안전한 난수 소스에서 생성되므로,
[비밀번호 복잡성 규칙](/ko/reference/statements/create/user#identification)을 검사할 필요가 없으며 실제로 검사하지도 않습니다.
해당 규칙은 사람이 직접 정한 비밀번호를 제약하기 위해 존재합니다.

## VALID UNTIL 및 VALID FOR 절

토큰의 수명을 제한합니다. [`CREATE USER`](/ko/reference/statements/create/user#valid-until-clause)의 인증 메서드에 사용되는 동일한 이름의 절과 정확히 같은 방식으로 동작합니다. `VALID UNTIL`은 절대 날짜와 시간을 지정하고, `VALID FOR`는 [인터벌](/ko/reference/data-types/special-data-types/interval)을 지정하며, 이 값은 쿼리가 실행되는 시점의 현재 시간에 더해집니다.

두 절을 모두 지정하지 않으면 토큰은 [`create_token_default_ttl_seconds`](/ko/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` 절](/ko/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`](/ko/reference/statements/show#show-create-user)의 출력에 (`VALID UNTIL` 및 `GRANTS` 절과 함께, 시크릿은 제외하고) 표시되며, [`system.users`](/ko/reference/system-tables/users) 테이블의 `auth_type`, `auth_params`, `auth_grants` 컬럼에도 나타납니다.

개별 토큰 하나만 삭제하는 SQL 문은 없습니다. 사용자의 모든 토큰을 취소하려면 `ALTER USER <name> IDENTIFIED WITH ...` 등으로 인증 메서드를 대체하거나, `ALTER USER <name> RESET AUTHENTICATION METHODS TO NEW`를 사용해 가장 최근에 추가된 것만 남기십시오. 한 사용자가 동시에 보유할 수 있는 인증 메서드의 개수는 `max_authentication_methods_per_user` 서버 설정으로 제한됩니다.

시크릿은 쿼리 자체가 생성하고 저장하므로, 결과가 클라이언트에 전달되지 못한 `CREATE TOKEN`(행을 전송하는 도중 연결이 끊기거나, 클라이언트가 열 수 없는 `INTO OUTFILE`을 지정한 경우)은 아무도 사용할 수 없으면서 위 제한에는 계속 포함되는 인증 메서드를 남깁니다. 그런 시크릿은 아무도 보유하지 않으며, 쿼리가 실행되는 동안에만 존재합니다. 사용할 수 없는 포맷을 `FORMAT` 절에 지정한 경우를 포함해, 실행 전에 거부된 쿼리는 아무것도 추가하지 않습니다.

`CREATE TOKEN`은 `ON CLUSTER` 절을 지원하지 않습니다. 액세스 엔터티가 로컬에 저장되는 클러스터 전체에서 토큰이 동작하도록 하려면 복제된 액세스 스토리지를 사용하거나, 모든 노드에서 이에 상응하는 `ALTER USER ... ADD IDENTIFIED WITH sha256_hash` 문을 실행하십시오.

## 보안 고려 사항

`VALID UNTIL`과 `GRANTS`는 해당 토큰으로 인증하는 세션을 제한합니다. 그러나 그 세션이 남긴 결과물까지 제한하지는 않습니다.

* 데드라인은 세션이 토큰으로 인증하는 시점에 검사됩니다. 이미 열려 있는 세션이나 이미 실행 중인 쿼리는 토큰이 만료되어도 중단되지 않습니다.
* 세션이 생성한 모든 것은 토큰보다 오래 남으며, 스스로 동작하는 객체는 계속 그 작업을 이어갑니다. 즉, 토큰이 만료된 지 한참 후에도
  [갱신 가능 구체화 뷰](/ko/reference/statements/create/view#refreshable-materialized-view)는 계속 갱신되고,
  [`Kafka`](/ko/reference/engines/table-engines/integrations/kafka),
  [`RabbitMQ`](/ko/reference/engines/table-engines/integrations/rabbitmq),
  [`NATS`](/ko/reference/engines/table-engines/integrations/nats),
  [`S3Queue`](/ko/reference/engines/table-engines/integrations/s3queue)와 같은 스트리밍 테이블 엔진에 연결된 materialized view는 계속 데이터를 소비하며,
  [`LIFETIME`](/ko/reference/statements/create/dictionary/lifetime)이 설정된 딕셔너리는 계속 다시 로드됩니다. 뷰는 이러한 작업을
  [`DEFINER`](/ko/reference/statements/create/view#sql_security)의 권한으로 수행하며, 기본값은 해당 뷰를 생성한 사용자입니다. 즉, 토큰의 `GRANTS` 절이 남겨준 권한이 아니라 그 사용자의 전체 권한이 사용됩니다.

따라서 테이블, 뷰 또는 딕셔너리를 생성할 수 있는 토큰은 실질적으로 두 가지 제한을 모두 넘어설 수 있습니다. 데드라인 이후에도 계속 실행되면서, 사용자 권한으로 토큰 자체에는 허용되지 않았던 작업을 수행하는 지속적인 작업을 남길 수 있기 때문입니다. 토큰에는 애플리케이션에 필요한 권한, 즉 대개 지정된 테이블에 대한 `SELECT`와 `INSERT`만 부여하십시오. 그리고 이러한 제한이 실제로 유지되어야 한다면 `CREATE TABLE`, `CREATE VIEW`, `CREATE DICTIONARY` 및 `ACCESS MANAGEMENT` 권한은 `GRANTS` 절에서 제외하십시오.

`GRANTS` 절이 있는 토큰으로 인증한 세션은 토큰을 전혀 발급할 수 없습니다. 이러한 세션에서는 기존 사용자에게 인증 메서드를 추가하는 작업이 거부됩니다. 새 인증 메서드의 `GRANTS` 절은 로그인 시 해당 메서드를 생성한 세션의 접근 권한이 아니라 사용자의 접근 권한과 교집합으로 계산되므로, 그렇지 않다면 제한을 넓히는 수단이 될 수 있기 때문입니다.