Skip to main content
Создаёт токен для текущего пользователя: сервер генерирует случайный секрет, добавляет его текущему пользователю в качестве дополнительного метода аутентификации и возвращает в результате запроса. Секрет показывается только этим запросом — он хранится в виде хеша, поэтому восстановить его впоследствии невозможно. Синтаксис:
Это сокращённая форма записи ALTER USER <current user> ADD IDENTIFIED WITH sha256_password BY '<random secret>' с теми же секциями VALID UNTIL и GRANTS, поэтому токен ведёт себя как обычный пароль текущего пользователя:
  • он привязан к пользователю — отображается в system.query_log и system.processes как этот пользователь, перестаёт работать при удалении пользователя и теряет права доступа, когда их теряет пользователь;
  • его действие можно ограничить по времени с помощью VALID UNTIL или VALID FOR, а по привилегиям — с помощью GRANTS;
  • его можно использовать с любым механизмом аутентификации, принимающим пароль, например с параметром password HTTP-интерфейса или опцией --password клиента ClickHouse.
Для создания токена требуется привилегия CREATE TOKEN либо привилегия ALTER USER для текущего пользователя. Это отдельная привилегия, поскольку токен понижает уровень безопасности аккаунта, которому принадлежит: пользователь, прошедший аутентификацию с помощью аппаратного ключа или сертификата, может создать долгоживущий пароль для того же аккаунта. Та же привилегия разрешает и эквивалентный оператор ALTER USER <current user> ADD IDENTIFIED ....

​
Результат

Запрос возвращает одну строку с двумя столбцами: Чтобы получить секрет без какого-либо форматирования, выполните запрос с 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

Ограничивает права доступа сеансов, аутентифицированных с помощью токена, пересечением с перечисленными привилегиями. Работает точно так же, как секция GRANTS в CREATE USER, включая те же ограничения — в частности, ограничение применяется на том узле, который получил запрос, и не распространяется на другие узлы кластера. Эта секция GRANTS никогда не добавляет прав доступа: привилегия, не выданная пользователю, остаётся недоступной и для токена. Без этой секции 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, но без секрета), а также в столбцах auth_type, auth_params и auth_grants таблицы system.users. Оператора, удаляющего отдельный токен, не существует. Чтобы отозвать все токены пользователя, замените его методы аутентификации, например с помощью 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 ограничивают сеансы, которые аутентифицируются с помощью токена. Но они не ограничивают то, что эти сеансы оставляют после себя:
  • Срок действия проверяется в момент аутентификации сеанса по токену. Уже открытый сеанс и уже выполняющийся запрос не прерываются, когда срок действия токена истекает.
  • Всё, что создаёт сеанс, живёт дольше токена, а объект, выполняющий работу самостоятельно, продолжает её выполнять: refreshable materialized view продолжает обновляться, materialized view, привязанный к движку потоковой таблицы, такому как Kafka, RabbitMQ, NATS или S3Queue, продолжает читать данные, а словарь с LIFETIME продолжает перезагружаться — ещё долго после того, как срок действия токена истёк. VIEW выполняет эту работу с правами своего DEFINER, которым по умолчанию является пользователь, создавший VIEW, — то есть с полными правами пользователя, а не с теми правами, которые оставила токену секция GRANTS.
Поэтому токен, которому разрешено создавать таблицы, VIEW или словари, на практике способен обойти оба своих ограничения: он может оставить после себя постоянную задачу, которая продолжает работать после истечения срока действия и делает с правами пользователя то, что самому токену не было разрешено. Выдавайте токену только то, что действительно нужно приложению, — обычно SELECT и INSERT на конкретных таблицах — и не включайте CREATE TABLE, CREATE VIEW, CREATE DICTIONARY и привилегии ACCESS MANAGEMENT в его секцию GRANTS, если ограничения должны реально соблюдаться. Сеанс, аутентифицированный токеном с секцией GRANTS, вообще не может выпускать токены: добавление метода аутентификации существующему пользователю для такого сеанса запрещено. Секция GRANTS нового метода аутентификации при входе пересекается с правами доступа пользователя, а не с правами сеанса, создавшего этот метод, иначе это стало бы способом расширить ограничение.
Последнее изменение 26 сентября 2026 г.