CREATE USER

Создаёт учётные записи пользователей. Синтаксис:

CREATE USER [IF NOT EXISTS | OR REPLACE] name1 [, name2 [,...]] [ON CLUSTER cluster_name]
    [{VALID UNTIL datetime | VALID FOR interval}]
    [NOT IDENTIFIED | IDENTIFIED {[WITH {plaintext_password | sha256_password | sha256_hash | double_sha1_password | double_sha1_hash}] BY {'password' | 'hash'}} | WITH NO_PASSWORD | {WITH ldap SERVER 'server_name'} | {WITH kerberos [REALM 'realm']} | {WITH ssl_certificate CN 'common_name' | SAN 'TYPE:subject_alt_name'} | {WITH ssh_key BY KEY 'public_key' TYPE 'ssh-rsa|...'} | {WITH http SERVER 'server_name' [SCHEME 'Basic']} [{VALID UNTIL datetime | VALID FOR interval}] [GRANTS (privilege ON object [,...])]
    [, {[{plaintext_password | sha256_password | sha256_hash | ...}] BY {'password' | 'hash'}} | {ldap SERVER 'server_name'} | {...} | ... [,...]]]
    [HOST {LOCAL | NAME 'name' | REGEXP 'name_regexp' | IP 'address' | LIKE 'pattern'} [,...] | ANY | NONE]
    [IN access_storage_type]
    [ROLE role [,...]]
    [DEFAULT ROLE role [,...]]
    [DEFAULT DATABASE database | NONE]
    [GRANTEES {user | role | ANY | NONE} [,...] [EXCEPT {user | role} [,...]]]
    [SETTINGS variable [= value] [MIN [=] min_value] [MAX [=] max_value] [READONLY | WRITABLE] | PROFILE 'profile_name'] [,...]

Предложение ON CLUSTER позволяет создавать пользователей в кластере, см. Distributed DDL.

Идентификация

Существует несколько способов идентификации пользователя:

IDENTIFIED WITH no_password
IDENTIFIED WITH plaintext_password BY 'qwerty'
IDENTIFIED WITH sha256_password BY 'qwerty' or IDENTIFIED BY 'password'
IDENTIFIED WITH sha256_hash BY 'hash' or IDENTIFIED WITH sha256_hash BY 'hash' SALT 'salt'
IDENTIFIED WITH double_sha1_password BY 'qwerty'
IDENTIFIED WITH double_sha1_hash BY 'hash'
IDENTIFIED WITH bcrypt_password BY 'qwerty'
IDENTIFIED WITH bcrypt_hash BY 'hash'
IDENTIFIED WITH ldap SERVER 'server_name'
IDENTIFIED WITH kerberos or IDENTIFIED WITH kerberos REALM 'realm'
IDENTIFIED WITH ssl_certificate CN 'mysite.com:user'
IDENTIFIED WITH ssh_key BY KEY 'public_key' TYPE 'ssh-rsa', KEY 'another_public_key' TYPE 'ssh-ed25519'
IDENTIFIED WITH http SERVER 'http_server' or IDENTIFIED WITH http SERVER 'http_server' SCHEME 'basic'
IDENTIFIED BY 'qwerty'

Требования к сложности паролей можно изменить в config.xml. Ниже приведен пример конфигурации, в которой требуется, чтобы пароль был длиной не менее 12 символов и содержал 1 цифру. Для каждого правила сложности пароля требуется регулярное выражение для проверки паролей и описание правила.

<clickhouse>
    <password_complexity>
        <rule>
            <pattern>.{12}</pattern>
            <message>be at least 12 characters long</message>
        </rule>
        <rule>
            <pattern>\p{N}</pattern>
            <message>contain at least 1 numeric character</message>
        </rule>
    </password_complexity>
</clickhouse>

В ClickHouse Cloud по умолчанию пароли должны соответствовать следующим требованиям к сложности:

Длина — не менее 12 символов
Содержать как минимум 1 цифру
Содержать как минимум 1 заглавную букву
Содержать как минимум 1 строчную букву
Содержать как минимум 1 специальный символ

Примеры

Следующее имя пользователя — name1, и для него не требуется пароль, что, очевидно, не дает почти никакой защиты:
CREATE USER name1 NOT IDENTIFIED

Чтобы указать пароль в открытом виде:

CREATE USER name2 IDENTIFIED WITH plaintext_password BY 'my_password'

Пароль хранится в текстовом SQL-файле в /var/lib/clickhouse/access, поэтому использовать plaintext_password — не лучшая идея. Вместо этого лучше использовать sha256_password, как показано ниже…

Самый распространенный вариант — использовать пароль, хешированный с помощью SHA-256. ClickHouse сам вычислит хеш пароля, если указать IDENTIFIED WITH sha256_password. Например:
CREATE USER name3 IDENTIFIED WITH sha256_password BY 'my_password'
Пользователь name3 теперь может входить с паролем my_password, но сам пароль хранится в виде хеша, показанного выше. В /var/lib/clickhouse/access будет создан следующий SQL-файл, который выполняется при запуске сервера:
/var/lib/clickhouse/access $ cat 3843f510-6ebd-a52d-72ac-e021686d8a93.sql ATTACH USER name3 IDENTIFIED WITH sha256_hash BY '0C268556C1680BEF0640AAC1E7187566704208398DA31F03D18C74F5C5BE5053' SALT '4FB16307F5E10048196966DD7E6876AE53DE6A1D1F625488482C75F14A5097C7';

Если у вас уже есть хеш-значение и соответствующее значение соли для имени пользователя, можно использовать IDENTIFIED WITH sha256_hash BY 'hash' или IDENTIFIED WITH sha256_hash BY 'hash' SALT 'salt'. При идентификации с помощью sha256_hash и SALT хеш должен вычисляться из конкатенации ‘password’ и ‘salt’.

double_sha1_password обычно не требуется, но бывает полезен при работе с клиентами, которым он нужен (например, через интерфейс MySQL):
CREATE USER name4 IDENTIFIED WITH double_sha1_password BY 'my_password'
ClickHouse генерирует и выполняет следующий запрос:
CREATE USER name4 IDENTIFIED WITH double_sha1_hash BY 'CCD3A959D6A004B9C3807B728BC2E55B67E10518'
bcrypt_password — самый безопасный вариант хранения паролей. Он использует алгоритм bcrypt, устойчивый к атакам методом перебора, даже если хеш пароля был скомпрометирован.
CREATE USER name5 IDENTIFIED WITH bcrypt_password BY 'my_password'
При использовании этого метода длина пароля ограничена 72 символами. Параметр bcrypt work factor, который определяет объем вычислений и время, необходимые для вычисления хеша и проверки пароля, можно изменить в конфигурации сервера:
<bcrypt_workfactor>12</bcrypt_workfactor>
Значение work factor должно быть в диапазоне от 4 до 31, по умолчанию — 12.

Для приложений с высокочастотной аутентификацией рассмотрите альтернативные методы аутентификации из-за вычислительных затрат bcrypt при более высоких значениях work factor.

Тип пароля также можно не указывать:
CREATE USER name6 IDENTIFIED BY 'my_password'
В этом случае ClickHouse будет использовать тип пароля по умолчанию, указанный в конфигурации сервера:
<default_password_type>sha256_password</default_password_type>
Доступные типы паролей: plaintext_password, sha256_password, double_sha1_password.

Можно указать несколько методов аутентификации:

CREATE USER user1 IDENTIFIED WITH plaintext_password by '1', bcrypt_password by '2', plaintext_password by '3''

Примечания:

Более старые версии ClickHouse могут не поддерживать синтаксис для нескольких методов аутентификации. Поэтому, если на сервере ClickHouse есть такие пользователи, а затем сервер понижают до версии, где эта возможность не поддерживается, такие пользователи станут непригодны к использованию, а некоторые операции, связанные с пользователями, перестанут работать. Чтобы корректно понизить версию, перед этим необходимо настроить всех пользователей так, чтобы у каждого был только один метод аутентификации. Если же версия сервера была понижена без соблюдения этой процедуры, некорректных пользователей следует удалить.
no_password не может использоваться вместе с другими методами аутентификации из соображений безопасности. Поэтому указать no_password можно только в том случае, если это единственный метод аутентификации в запросе.

Хост пользователя

Хост пользователя — это хост, с которого может быть установлено соединение с сервером ClickHouse. Хост можно указать в секции запроса HOST следующими способами:

HOST IP 'ip_address_or_subnetwork' — Пользователь может подключаться к серверу ClickHouse только с указанного IP-адреса или из подсети. Примеры: HOST IP '192.168.0.0/16', HOST IP '2001:DB8::/32'. Для использования в рабочей среде указывайте только элементы HOST IP (IP-адреса и их маски), поскольку использование host и host_regexp может вызывать дополнительную задержку.
HOST ANY — Пользователь может подключаться откуда угодно. Это вариант по умолчанию.
HOST LOCAL — Пользователь может подключаться только локально.
HOST NAME 'fqdn' — Хост пользователя можно указать в виде FQDN. Например, HOST NAME 'mysite.com'.
HOST REGEXP 'regexp' — При указании хостов пользователя можно использовать pcre регулярные выражения. Например, HOST REGEXP '.*\.mysite\.com'.
HOST LIKE 'template' — Позволяет использовать оператор LIKE для фильтрации хостов пользователя. Например, HOST LIKE '%' эквивалентно HOST ANY, а HOST LIKE '%.mysite.com' фильтрует все хосты в домене mysite.com.

Ещё один способ указать хост — использовать синтаксис @ после имени пользователя. Примеры:

CREATE USER mira@'127.0.0.1' — Эквивалентно синтаксису HOST IP.
CREATE USER mira@'localhost' — Эквивалентно синтаксису HOST LOCAL.
CREATE USER mira@'192.168.%.%' — Эквивалентно синтаксису HOST LIKE.

ClickHouse рассматривает user_name@'address' как имя пользователя целиком. Таким образом, технически можно создать нескольких пользователей с одним и тем же user_name и разными конструкциями после @. Однако мы не рекомендуем этого делать.

Предложение VALID UNTIL

Позволяет указать дату истечения срока действия и, при необходимости, время для метода аутентификации. В качестве параметра принимает строку. Для даты и времени рекомендуется использовать формат YYYY-MM-DD [hh:mm:ss] [timezone], где [timezone] должен быть числовым смещением, например +09:00, или одним из значений UTC, GMT, Z, MSK, MSD; именованные зоны IANA, такие как Asia/Tokyo, не распознаются (см. примечание ниже). По умолчанию этот параметр равен 'infinity'. Допустимый диапазон срока действия — от 1900-01-01 00:00:00 UTC до 9999-12-31 09:59:59 UTC — последнего момента, который остаётся в пределах 9999 года в любом часовом поясе. Поэтому сохранённый момент никогда не ограничивается при отображении. Срок действия в прошлом означает, что учётные данные уже истекли. Сроки до 1970-01-01 00:00:01 UTC принимаются только как маркер «уже истекло»: они приводятся к минимальному истёкшему моменту — одной секунде после эпохи Unix (1970-01-01 00:00:01 UTC). Поэтому SHOW CREATE USER выводит этот момент вместо указанного вами срока. Сроки, начиная с этого момента, сохраняются без изменений. Срок действия хранится как абсолютный момент, но SHOW CREATE USER и system.users отображают его в часовом поясе сервера или сеанса. Поэтому один и тот же сохранённый момент выглядит по-разному на серверах с разными настройками: например, указанный выше приведённый истёкший момент отображается как 1970-01-01 00:00:01 на сервере в UTC и как 1970-01-01 14:00:01 на сервере в Pacific/Kiritimati. При проверке всегда используется сохранённый момент, а не его отображение. Расположение предложения определяет, к каким методам аутентификации оно применяется:

Перед предложением IDENTIFIED (или если запрос вообще не указывает метод аутентификации): срок действия устанавливается на уровне пользователя и применяется ко всем его методам аутентификации.
После метода аутентификации: срок действия применяется только к этому методу. Поэтому предложение, указанное после всего списка IDENTIFIED, относится только к последнему методу, а предыдущие методы остаются бессрочными.

Примеры:

CREATE USER name1 VALID UNTIL '2025-01-01'
CREATE USER name1 VALID UNTIL '2025-01-01 12:00:00 UTC'
CREATE USER name1 VALID UNTIL '2025-01-01 12:00:00 +09:00'
CREATE USER name1 VALID UNTIL 'infinity'
CREATE USER name1 VALID UNTIL '2025-01-01' IDENTIFIED WITH plaintext_password BY 'password_1', bcrypt_password BY 'password_2' — срок действия на уровне пользователя применяется к обоим методам.
CREATE USER name1 IDENTIFIED WITH plaintext_password BY 'no_expiration', bcrypt_password BY 'expiration_set' VALID UNTIL '2025-01-01' — срок действия применяется только к методу bcrypt_password; срок действия plaintext_password не ограничен.

Строка даты и времени разбирается с помощью parseDateTimeBestEffort, который распознаёт только токены часового пояса UTC, GMT, Z, MSK, MSD и числовые смещения, например +09:00 или -05:00. Именованные часовые пояса IANA, такие как Asia/Tokyo или Europe/London, не поддерживаются. Кроме того, фиксированное смещение не эквивалентно зоне IANA для регионов, где используется переход на летнее время, поэтому для конкретной кодируемой даты необходимо вычислить правильное смещение.

Предложение VALID FOR

Предложение VALID FOR — удобное сокращение для VALID UNTIL. Вместо абсолютных даты и времени оно принимает интервал, а срок действия вычисляется как текущее время плюс этот интервал в момент выполнения запроса. Затем результат сохраняется в формате VALID UNTIL, поэтому SHOW CREATE USER всегда отображает вычисленный абсолютный срок действия. Его можно использовать везде, где допустимо VALID UNTIL, и к нему применяются те же правила размещения: перед IDENTIFIED (или при отсутствии метода аутентификации) это срок действия на уровне пользователя, применяемый ко всем методам, а после метода аутентификации — только к этому методу. Срок действия хранится и контролируется с точностью до секунды, поэтому интервалы с точностью менее секунды (NANOSECOND, MICROSECOND, MILLISECOND) не допускаются; наименьшая допустимая единица — SECOND. Отрицательный интервал можно использовать, чтобы пометить учётные данные как уже истёкшие; если вычисленный срок действия приходится на время до 1970-01-01 00:00:01 UTC, он приводится к этому минимальному истёкшему моменту, который затем отображается в SHOW CREATE USER — в часовом поясе сервера или сеанса, как описано для VALID UNTIL. Примеры:

CREATE USER name1 VALID FOR INTERVAL 1 DAY
CREATE USER name1 VALID FOR INTERVAL 3 MONTH
CREATE USER name1 VALID FOR INTERVAL 1 DAY + INTERVAL 12 HOUR
CREATE USER name1 VALID FOR INTERVAL 30 DAY IDENTIFIED WITH plaintext_password BY 'password_1', bcrypt_password BY 'password_2' — срок действия на уровне пользователя применяется к обоим методам.
CREATE USER name1 IDENTIFIED WITH plaintext_password BY 'no_expiration', bcrypt_password BY 'expiration_set' VALID FOR INTERVAL 30 DAY — срок действия применяется только к методу bcrypt_password; срок действия plaintext_password не ограничен.

Предложение GRANTS

Позволяет ограничить права доступа, доступные сеансу, аутентифицированному с помощью определенного метода аутентификации. Принимает заключенный в скобки список привилегий в той же форме, что и оператор GRANT. Предложение указывается после метода аутентификации (после его предложения VALID UNTIL, если оно есть) и применяется только к этому методу. Когда пользователь входит в систему с таким методом аутентификации, права доступа сеанса представляют собой пересечение прав доступа пользователя (включая права, полученные через предоставленные роли) и привилегий, указанных в предложении. Предложение никогда не добавляет прав доступа: если указанная привилегия не выдана пользователю, сеанс ее не получает. Сеансы, аутентифицированные таким методом, также не могут выдавать привилегии (GRANT OPTION никогда не сохраняется при пересечении) или администрировать роли. Администрирование ролей включает не только создание, изменение, удаление, выдачу и отзыв ролей, но и изменение ролей, активируемых для пользователя по умолчанию (SET DEFAULT ROLE и ALTER USER ... DEFAULT ROLE), что также отклоняется. EXECUTE AS меняет субъект сеанса, поэтому оператор, выполняемый от имени другого пользователя, ограничивается пересечением прав доступа целевого пользователя и указанных привилегий, а не правами пользователя, выполнившего вход. Само ограничение никогда не снимается, а выполнение от имени другого пользователя требует, чтобы IMPERSONATE ON target было как выдано пользователю, так и указано в предложении, поэтому ограниченные учетные данные никогда не могут предоставить больше возможностей, чем неограниченные учетные данные того же пользователя. Это удобный способ создавать токены для приложений: дополнительные учетные данные с датой истечения срока действия и ограниченным набором привилегий, привязанные к пользователю. Они отображаются в system.query_log и system.processes как этот пользователь, перестают работать при его удалении и теряют права доступа, когда пользователь их теряет.

Принудительная проверка выполняется только на инициаторе. Ограничение GRANTS метода аутентификации и срок действия VALID UNTIL применяются только на узле, который получает запрос (инициаторе). Они не распространяются на другие узлы кластера, поэтому не полагайтесь на это предложение для ограничения выполнения во всем кластере. На удаленных узлах сохраняется обычная область действия ролей. Предложение также недоступно в users.xml. Кэш результатов запросов является общим для всех методов аутентификации пользователя: записи в нем изолируются по пользователю и ролям, а попадание в кэш не перепроверяется относительно GRANTS метода, с которым был аутентифицирован сеанс.

Примеры:

CREATE USER name1 IDENTIFIED BY 'qwerty' GRANTS (SELECT ON db.*)
ALTER USER name1 ADD IDENTIFIED WITH plaintext_password BY 'app_token' VALID UNTIL '2026-12-31' GRANTS (SELECT ON db.table, INSERT ON db.table)

Обратите внимание, что ограничение является свойством метода аутентификации и фиксируется в момент входа: изменение предложения с помощью ALTER USER влияет на новые сеансы, а не на уже установленные. Привилегии источников с фильтрами, такие как READ ON S3('s3://bucket/.*'), пока не поддерживаются в предложении: при пересечении фильтр источника сравнивается как непрозрачная строка, поэтому один фильтр нельзя сузить до другого. Такая привилегия отклоняется, а не молча лишается доступа. Предложение поддерживается только для методов аутентификации, учетные данные которых проверяются сервером исключительно локально. Для методов, проверка которых обращается (или, в случае jwt, может обращаться — например, для получения ключей подписи) к внешней системе (ldap, kerberos, http, jwt), предложение отклоняется: когда несколько методов аутентификации принимают одни и те же учетные данные, ограничение применяется путем повторной проверки учетных данных другими методами, а дополнительная проверка внешней системы небезопасна. Поэтому другой метод, принимающий те же учетные данные, мог бы обойти ограничение. Когда одни и те же фактические учетные данные принимаются более чем одним методом аутентификации, при входе применяются ограничения всех этих методов по принципу fail-close: сеанс получает пересечение GRANTS всех совпадающих методов, а срок его действия истекает в наиболее ранний из VALID UNTIL. Наиболее ранний VALID UNTIL имеет приоритет, даже если он уже прошел: вход отклоняется точно так же, как если бы истек срок действия единственного совпавшего метода. Таким образом, истечение срока действия токена никогда не предоставляет общим учетным данным права или срок действия более широкого метода. Эта комбинация проверяется только для методов аутентификации, проверяемых сервером локально, по той же причине, по которой само предложение выше отклоняется для метода с внешней проверкой: повторная проверка учётных данных потребовала бы небезопасного дополнительного обращения к внешней системе. Поэтому, если те же учётные данные также принимаются методом с внешней проверкой (ldap, kerberos, http, jwt) для того же пользователя, его собственный VALID UNTIL не входит в эту комбинацию, а настроенный для него более ранний срок действия не сокращает сеанс, полученный через метод с локальной проверкой.

Предложение GRANTEES

Указывает пользователей или роли, которым этот пользователь может предоставлять привилегии, при условии, что самому этому пользователю также предоставлены все необходимые права доступа с GRANT OPTION. Варианты предложения GRANTEES:

user — Указывает пользователя, которому этот пользователь может предоставлять привилегии.
role — Указывает роль, которой этот пользователь может предоставлять привилегии.
ANY — Этот пользователь может предоставлять привилегии кому угодно. Это значение по умолчанию.
NONE — Этот пользователь не может предоставлять привилегии никому.

Исключить любого пользователя или роль можно с помощью выражения EXCEPT. Например, CREATE USER user1 GRANTEES ANY EXCEPT user2. Это означает, что если пользователю user1 предоставлены какие-либо привилегии с GRANT OPTION, он сможет предоставлять эти привилегии кому угодно, кроме user2.

Примеры

Создайте учётную запись пользователя mira, защищенную паролем qwerty:

CREATE USER mira HOST IP '127.0.0.1' IDENTIFIED WITH sha256_password BY 'qwerty';

mira должна запускать клиентское приложение на хосте, где запущен сервер ClickHouse. Создайте учётную запись пользователя john и назначьте роли:

CREATE USER john ROLE role1, role2;

Создайте учётную запись пользователя john, назначьте роли и сделайте некоторые из них ролями по умолчанию:

CREATE USER john ROLE role1, role2 DEFAULT ROLE role1;

или

CREATE USER john ROLE role1, role2 DEFAULT ROLE ALL EXCEPT role2;

Создайте учётную запись пользователя john и разрешите ему передавать свои привилегии пользователю с учётной записью jack:

CREATE USER john GRANTEES jack;

Используйте параметр запроса, чтобы создать учётную запись пользователя john:

SET param_user=john;
CREATE USER {user:Identifier};

SQL Reference

Data Types

Engines

Functions

Formats

Interfaces

Settings

System Tables

Data Lakes

Идентификация

Примеры

Хост пользователя

Предложение VALID UNTIL

Предложение VALID FOR

Предложение GRANTS

Предложение GRANTEES

Примеры

​Идентификация

​Примеры

​Хост пользователя

​Предложение VALID UNTIL

​Предложение VALID FOR

​Предложение GRANTS

​Предложение GRANTEES

​Примеры

Идентификация

Примеры

Хост пользователя

Предложение VALID UNTIL

Предложение VALID FOR

Предложение GRANTS

Предложение GRANTEES

Примеры