CREATE TOKEN

Token에 대한 문서

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

구문:

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

이는 동일한 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 ... SQL 문도 실행할 수 있습니다.

​

결과

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

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

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

CREATE TOKEN VALID FOR INTERVAL 30 DAY GRANTS (SELECT ON db.*) FORMAT TSVRaw

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

​

VALID UNTIL 및 VALID FOR 절

토큰의 수명을 제한합니다. CREATE USER의 인증 메서드에 사용되는 동일한 이름의 절과 정확히 같은 방식으로 동작합니다. VALID UNTIL은 절대 날짜와 시간을 지정하고, VALID FOR는 인터벌을 지정하며, 이 값은 쿼리가 실행되는 시점의 현재 시간에 더해집니다.

두 절을 모두 지정하지 않으면 토큰은 create_token_default_ttl_seconds에 지정된 기간 동안 유지되며, 기본값은 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 절과 정확히 동일하게 동작하며, 그 제약 사항까지 그대로 적용됩니다. 특히 이 제한은 쿼리를 수신한 노드에서만 적용되며 클러스터의 다른 노드로는 전파되지 않습니다. 이 절은 접근 권한을 추가하지 않습니다. 즉, 사용자에게 부여되지 않은 권한은 토큰에서도 사용할 수 없습니다. 이 절을 지정하지 않으면 토큰은 해당 사용자의 모든 접근 권한을 갖습니다.

예시:

• 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 컬럼에도 나타납니다.

개별 토큰 하나만 삭제하는 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는 해당 토큰으로 인증하는 세션을 제한합니다. 그러나 그 세션이 남긴 결과물까지 제한하지는 않습니다.

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

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

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