Перейти к основному содержанию
Раздел users в файле конфигурации users.xml содержит настройки пользователей.
ClickHouse также поддерживает рабочий процесс, управляемый через SQL для управления пользователями. Рекомендуем использовать именно его.
Структура раздела users: 
<users>
    <!-- Если имя пользователя не указано, используется пользователь 'default'. -->
    <user_name>
        <!-- На уровне users.user_name можно указать ровно один метод аутентификации. Например: -->
        <password></password>
        <!-- Или (взаимоисключающий вариант) -->
        <password_sha256_hex></password_sha256_hex>
 
        <!-- Или (взаимоисключающий вариант) (примечание: несколько SSH-ключей допускается для обратной совместимости) -->
        <ssh_keys>
            <ssh_key>
                <type>ssh-ed25519</type>
                <base64_key>AAAAC3NzaC1lZDI1NTE5AAAAIDNf0r6vRl24Ix3tv2IgPmNPO2ATa2krvt80DdcTatLj</base64_key>
            </ssh_key>
            <ssh_key>
                <type>ecdsa-sha2-nistp256</type>
                <base64_key>AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBNxeV2uN5UY6CUbCzTA1rXfYimKQA5ivNIqxdax4bcMXz4D0nSk2l5E1TkR5mG8EBWtmExSPbcEPJ8V7lyWWbA8=</base64_key>
            </ssh_key>
            <ssh_key>
                <type>ssh-rsa</type>
                <base64_key>AAAAB3NzaC1yc2EAAAADAQABAAABgQCpgqL1SHhPVBOTFlOm0pu+cYBbADzC2jL41sPMawYCJHDyHuq7t+htaVVh2fRgpAPmSEnLEC2d4BEIKMtPK3bfR8plJqVXlLt6Q8t4b1oUlnjb3VPA9P6iGcW7CV1FBkZQEVx8ckOfJ3F+kI5VsrRlEDgiecm/C1VPl0/9M2llW/mPUMaD65cM9nlZgM/hUeBrfxOEqM11gDYxEZm1aRSbZoY4dfdm3vzvpSQ6lrCrkjn3X2aSmaCLcOWJhfBWMovNDB8uiPuw54g3ioZ++qEQMlfxVsqXDGYhXCrsArOVuW/5RbReO79BvXqdssiYShfwo+GhQ0+aLWMIW/jgBkkqx/n7uKLzCMX7b2F+aebRYFh+/QXEj7SnihdVfr9ud6NN3MWzZ1ltfIczlEcFLrLJ1Yq57wW6wXtviWh59WvTWFiPejGjeSjjJyqqB49tKdFVFuBnIU5u/bch2DXVgiAEdQwUrIp1ACoYPq22HFFAYUJrL32y7RxX3PGzuAv3LOc=</base64_key>
            </ssh_key>
        </ssh_keys>

        <!-- Или (взаимоисключающий вариант) для нескольких методов аутентификации: -->
        <auth_methods>
            <method1>
                <password></password>
            </method1>
            <method2>
                <password_sha256_hex></password_sha256_hex>
            </method2>
            <!-- ... -->
            <methodN>
                <!-- ... -->
            </methodN>
        </auth_methods>

        <access_management>0|1</access_management>

        <networks incl="networks" replace="replace">
        </networks>

        <profile>profile_name</profile>

        <quota>default</quota>
        <default_database>default</default_database>
        <databases>
            <database_name>
                <table_name>
                    <filter>expression</filter>
                </table_name>
            </database_name>
        </databases>

        <grants>
            <query>GRANT SELECT ON system.*</query>
        </grants>
    </user_name>
    <!-- Настройки остальных пользователей -->
</users>

​
user_name/password

Пароль можно указать в открытом виде или в виде SHA256 (в шестнадцатеричном формате).
  • Чтобы задать пароль в открытом виде (не рекомендуется), укажите его в элементе password. Например: <password>qwerty</password>. Пароль можно оставить пустым.
  • Чтобы задать пароль с использованием его хэша SHA256, укажите его в элементе password_sha256_hex. Например: <password_sha256_hex>65e84be33532fb784c48129675f9eff3a682b27168c0ea744b2cf58ee02337c5</password_sha256_hex>. Пример генерации пароля в оболочке: 
    PASSWORD=$(base64 < /dev/urandom | head -c8); echo "$PASSWORD"; echo -n "$PASSWORD" | sha256sum | tr -d '-'
    Первая строка результата — пароль. Вторая строка — соответствующий хэш SHA256.
  • Для совместимости с клиентами MySQL пароль можно указать в виде двойного хэша SHA1. Укажите его в элементе password_double_sha1_hex. Например: <password_double_sha1_hex>08b4a0f1de6ad37da17359e592c8d74788a83eb0</password_double_sha1_hex>. Пример генерации пароля в оболочке: 
    PASSWORD=$(base64 < /dev/urandom | head -c8); echo "$PASSWORD"; echo -n "$PASSWORD" | sha1sum | tr -d '-' | xxd -r -p | sha1sum | tr -d '-'
    Первая строка результата — пароль. Вторая строка — соответствующий двойной хэш SHA1.

​
Конфигурация аутентификации TOTP

Time-Based One-Time Password (TOTP) можно использовать для аутентификации пользователей ClickHouse с помощью временных кодов доступа, действующих ограниченное время. Этот метод аутентификации TOTP соответствует стандарту RFC 6238, поэтому он совместим с популярными TOTP-приложениями, такими как Google Authenticator, 1Password и аналогичными инструментами. Его можно настроить через конфигурационный файл users.xml в дополнение к аутентификации по паролю. В управлении доступом через SQL это пока не поддерживается. Для аутентификации с использованием TOTP пользователь должен указать основной пароль вместе с одноразовым паролем, сгенерированным TOTP-приложением, либо через параметр командной строки --one-time-password, либо добавив его к основному паролю через символ ’+’. Например, если основной пароль — some_password, а сгенерированный TOTP-код — 345123, пользователь может указать --password some_password+345123 или --password some_password --one-time-password 345123 при подключении к ClickHouse. Если пароль не указан, clickhouse-client запросит его интерактивно. Чтобы включить аутентификацию TOTP для пользователя, настройте раздел time_based_one_time_password в users.xml. В этом разделе задаются параметры TOTP, такие как секретный ключ, период действия, количество цифр и алгоритм хеширования. Пример 
<clickhouse>
    <!-- ... -->
    <users>
        <my_user>
            <!-- Основная аутентификация на основе пароля: -->
            <password>some_password</password>
            <password_sha256_hex>1464acd6765f91fccd3f5bf4f14ebb7ca69f53af91b0a5790c2bba9d8819417b</password_sha256_hex>
            <!-- ... или любой другой поддерживаемый метод аутентификации ... -->

            <!-- Настройка аутентификации TOTP -->
            <time_based_one_time_password>
                <secret>JBSWY3DPEHPK3PXP</secret>      <!-- Секрет TOTP в кодировке Base32 -->
                <period>30</period>                    <!-- Необязательно: срок действия OTP в секундах -->
                <digits>6</digits>                     <!-- Необязательно: количество цифр в OTP -->
                <algorithm>SHA1</algorithm>            <!-- Необязательно: алгоритм хэширования: SHA1, SHA256, SHA512 -->
            </time_based_one_time_password>
        </my_user>
    </users>
</clickhouse>

Параметры:

- secret — (обязательный) Секретный ключ в кодировке base32, используемый для генерации кодов TOTP.
- period — необязательный. Задаёт срок действия каждого OTP в секундах. Должно быть положительным числом, не превышающим 120. Значение по умолчанию: 30.
- digits — необязательный. Задаёт количество цифр в каждом OTP. Допустимые значения: от 4 до 10. Значение по умолчанию: 6.
- algorithm — необязательный. Определяет алгоритм хэширования для генерации OTP. Поддерживаемые значения: SHA1, SHA256 и SHA512. Значение по умолчанию: SHA1.

Генерация секрета TOTP

Чтобы сгенерировать совместимый с TOTP секрет для использования с ClickHouse, выполните следующую команду в терминале:

```bash
$ base32 -w32 < /dev/urandom | head -1
Эта команда создаст secret, закодированный в base32, который можно добавить в поле secret в users.xml. Чтобы включить TOTP для конкретного пользователя, добавьте в любое существующее поле с паролем (например, password или password_sha256_hex) ещё один раздел time_based_one_time_password. Для генерации QR-кода для секрета TOTP можно использовать утилиту qrencode. 
$ qrencode -t ansiutf8 'otpauth://totp/ClickHouse?issuer=ClickHouse&secret=JBSWY3DPEHPK3PXP'
После настройки TOTP для пользователя одноразовый пароль можно использовать в процессе аутентификации, как описано выше.

​
username/ssh-key

Этот параметр позволяет проходить аутентификацию с помощью SSH-ключей. Если у вас есть SSH-ключ (например, созданный с помощью ssh-keygen), 
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDNf0r6vRl24Ix3tv2IgPmNPO2ATa2krvt80DdcTatLj john@example.com
Ожидается, что элемент ssh_key будет 
<ssh_key>
     <type>ssh-ed25519</type>
     <base64_key>AAAAC3NzaC1lZDI1NTE5AAAAIDNf0r6vRl24Ix3tv2IgPmNPO2ATa2krvt80DdcTatLj</base64_key>
 </ssh_key>
Замените ssh-ed25519 на ssh-rsa или ecdsa-sha2-nistp256, если используете другие поддерживаемые алгоритмы.

​
Несколько методов аутентификации

Для одного пользователя можно настроить несколько методов аутентификации с помощью элемента <auth_methods>. Это позволяет пользователю проходить аутентификацию любым из перечисленных методов — например, у пользователя могут быть и пароль, и учётные данные LDAP, и вход с любым из них будет успешным. Каждый дочерний элемент <auth_methods> представляет собой произвольно именованную обёртку, содержащую ровно один тип аутентификации. Имя обёртки (например, <method1>, <primary>, <a1>) не имеет значения; используется только вложенный элемент аутентификации. Пример: несколько паролей 
<users>
    <my_user>
        <auth_methods>
            <primary>
                <password>password_one</password>
            </primary>
            <secondary>
                <password_sha256_hex>65e84be33532fb784c48129675f9eff3a682b27168c0ea744b2cf58ee02337c5</password_sha256_hex>
            </secondary>
        </auth_methods>
    </my_user>
</users>
Пример: сочетание разных способов аутентификации 
<users>
    <my_user>
        <auth_methods>
            <a1>
                <password>plaintext_pass</password>
            </a1>
            <a2>
                <password_sha256_hex>e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855</password_sha256_hex>
            </a2>
            <a3>
                <ldap>
                    <server>my_ldap_server</server>
                </ldap>
            </a3>
        </auth_methods>
    </my_user>
</users>
В <auth_methods> поддерживаются следующие типы аутентификации:
  • password — пароль в открытом виде
  • password_sha256_hex — хэш пароля SHA256
  • password_scram_sha256_hex — хэш пароля SCRAM-SHA-256
  • password_double_sha1_hex — двойной хэш SHA1 пароля
  • ldap — аутентификация через LDAP-сервер
  • kerberos — аутентификация Kerberos
  • ssl_certificates — аутентификация по SSL-сертификатам
  • ssh_keys — аутентификация по SSH-ключам
  • http_authentication — HTTP-аутентификация
Правила и ограничения:
  • <auth_methods> нельзя использовать вместе с методами аутентификации, заданными на уровне пользователя. Используйте либо один способ, либо другой, но не оба одновременно.
  • <auth_methods> должен содержать как минимум один метод аутентификации.
  • Каждый элемент-обертка внутри <auth_methods> должен содержать ровно один тип аутентификации (за исключением <ssh_keys>, который для обратной совместимости может содержать несколько).
  • TOTP (<time_based_one_time_password>) задается на уровне пользователя (вне <auth_methods>) и применяется ко всем методам на основе пароля в списке. Когда TOTP включен, требуется как минимум один метод на основе пароля.
Пример: auth_methods с TOTP 
<users>
    <my_user>
        <auth_methods>
            <a1>
                <password>my_password</password>
            </a1>
            <a2>
                <ldap>
                    <server>ldap_server_1</server>
                </ldap>
            </a2>
        </auth_methods>
        <time_based_one_time_password>
            <secret>JBSWY3DPEHPK3PXP</secret>
        </time_based_one_time_password>
    </my_user>
</users>
В этом примере проверка TOTP применяется к методу на основе пароля (<password>), а метод LDAP независимо выполняет аутентификацию через внешний server.

​
access_management

Этот параметр включает или отключает использование системы управления доступом и учётными записями, управляемой через SQL, для пользователя. Возможные значения:
  • 0 — Отключено.
  • 1 — Включено.
Значение по умолчанию: 0.

​
привилегии

Этот параметр позволяет предоставить выбранному пользователю любые права. Каждый элемент списка должен быть запросом GRANT без указания получателей привилегий. Пример: 
<user1>
    <grants>
        <query>GRANT SHOW ON *.*</query>
        <query>GRANT CREATE ON *.* WITH GRANT OPTION</query>
        <query>GRANT SELECT ON system.*</query>
    </grants>
</user1>
Этот параметр нельзя указывать одновременно с настройками dictionaries, access_management, named_collection_control, show_named_collections_secrets и allow_databases.

​
user_name/networks

Список сетей, из которых пользователь может подключаться к серверу ClickHouse. Каждый элемент списка может иметь одну из следующих форм:
  • <ip> — IP-адрес или маска сети. Примеры: 213.180.204.3, 10.0.0.1/8, 10.0.0.1/255.255.255.0, 2a02:6b8::3, 2a02:6b8::3/64, 2a02:6b8::3/ffff:ffff:ffff:ffff::.
  • <host> — Имя хоста. Пример: example01.host.ru. Для проверки доступа выполняется DNS-запрос, и все возвращённые IP-адреса сравниваются с адресом клиента.
  • <host_regexp> — Регулярное выражение для имён хостов. Пример: ^example\d\d-\d\d-\d\.host\.ru$ Для проверки доступа для адреса клиента выполняется DNS PTR-запрос, после чего применяется указанное регулярное выражение. Затем для результатов PTR-запроса выполняется ещё один DNS-запрос, и все полученные адреса сравниваются с адресом клиента. Настоятельно рекомендуем, чтобы регулярное выражение оканчивалось символом $.
Все результаты DNS-запросов кэшируются до перезапуска сервера. Примеры Чтобы открыть доступ для пользователя из любой сети, укажите: 
<ip>::/0</ip>
Открывать доступ из любой сети небезопасно, если у вас не настроен должным образом брандмауэр или server не подключен к Интернету напрямую.
Чтобы открыть доступ только с localhost, укажите: 
<ip>::1</ip>
<ip>127.0.0.1</ip>

​
user_name/profile

Пользователю можно назначить профиль настроек. Профили настроек задаются в отдельном разделе файла users.xml. Подробнее см. в разделе Профили настроек.

​
user_name/quota

Квоты позволяют отслеживать и ограничивать использование ресурсов за определенный период времени. Квоты настраиваются в разделе quotas файла конфигурации users.xml. Вы можете назначить пользователю набор квот. Подробное описание настройки квот см. в разделе Quotas.

​
user_name/databases

В этом разделе можно ограничить строки, которые ClickHouse возвращает для запросов SELECT, выполняемых текущим пользователем, тем самым реализовав базовую защиту на уровне строк. Пример Следующая конфигурация задаёт, что пользователь user1 может видеть в результатах запросов SELECT только строки из table1, в которых значение поля id равно 1000. 
<user1>
    <databases>
        <database_name>
            <table1>
                <filter>id = 1000</filter>
            </table1>
        </database_name>
    </databases>
</user1>
filter может быть любым выражением, результатом которого является значение типа UInt8. Обычно оно содержит сравнения и логические операторы. Строки из database_name.table1, для которых результат filter равен 0, не возвращаются этому пользователю. Такая фильтрация несовместима с операциями PREWHERE и отключает оптимизацию WHERE→PREWHERE.

​
Роли

Вы можете создать любые предопределённые роли в разделе roles файла конфигурации user.xml. Структура раздела roles: 
<roles>
    <test_role>
        <grants>
            <query>GRANT SHOW ON *.*</query>
            <query>REVOKE SHOW ON system.*</query>
            <query>GRANT CREATE ON *.* WITH GRANT OPTION</query>
        </grants>
    </test_role>
</roles>
Эти роли также можно назначить пользователям в разделе users: 
<users>
    <user_name>
        ...
        <grants>
            <query>GRANT test_role</query>
        </grants>
    </user_name>
<users>
Последнее изменение 10 июня 2026 г.