> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Параметры настройки пользователей и ролей.

# Настройки пользователей и ролей

Раздел `users` в файле конфигурации `users.xml` содержит настройки пользователей.

<Note>
  ClickHouse также поддерживает [рабочий процесс, управляемый через SQL](/ru/concepts/features/security/access-rights#access-control-usage) для управления пользователями. Рекомендуем использовать именно его.
</Note>

Структура раздела `users`:

```xml theme={null}
<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>
```

<div id="user-namepassword">
  ### user\_name/password
</div>

Пароль можно указать в открытом виде или в виде SHA256 (в шестнадцатеричном формате).

* Чтобы задать пароль в открытом виде (**не рекомендуется**), укажите его в элементе `password`.

  Например: `<password>qwerty</password>`. Пароль можно оставить пустым.

<a id="password_sha256_hex" />

* Чтобы задать пароль с использованием его хэша SHA256, укажите его в элементе `password_sha256_hex`.

  Например: `<password_sha256_hex>65e84be33532fb784c48129675f9eff3a682b27168c0ea744b2cf58ee02337c5</password_sha256_hex>`.

  Пример генерации пароля в оболочке:

  ```bash theme={null}
  PASSWORD=$(base64 < /dev/urandom | head -c8); echo "$PASSWORD"; echo -n "$PASSWORD" | sha256sum | tr -d '-'
  ```

  Первая строка результата — пароль. Вторая строка — соответствующий хэш SHA256.

<a id="password_double_sha1_hex" />

* Для совместимости с клиентами MySQL пароль можно указать в виде двойного хэша SHA1. Укажите его в элементе `password_double_sha1_hex`.

  Например: `<password_double_sha1_hex>08b4a0f1de6ad37da17359e592c8d74788a83eb0</password_double_sha1_hex>`.

  Пример генерации пароля в оболочке:

  ```bash theme={null}
  PASSWORD=$(base64 < /dev/urandom | head -c8); echo "$PASSWORD"; echo -n "$PASSWORD" | sha1sum | tr -d '-' | xxd -r -p | sha1sum | tr -d '-'
  ```

  Первая строка результата — пароль. Вторая строка — соответствующий двойной хэш SHA1.

<div id="totp-authentication-configuration">
  ### Конфигурация аутентификации TOTP
</div>

Time-Based One-Time Password (TOTP) можно использовать для аутентификации пользователей ClickHouse с помощью временных кодов доступа, действующих ограниченное время.
Этот метод аутентификации TOTP соответствует стандарту [RFC 6238](https://datatracker.ietf.org/doc/html/rfc6238), поэтому он совместим с популярными 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, такие как секретный ключ, период действия, количество цифр и алгоритм хеширования.

**Пример**

````xml theme={null}
<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](https://linux.die.net/man/1/qrencode).

```bash theme={null}
$ qrencode -t ansiutf8 'otpauth://totp/ClickHouse?issuer=ClickHouse&secret=JBSWY3DPEHPK3PXP'
```

После настройки TOTP для пользователя одноразовый пароль можно использовать в процессе аутентификации, как описано выше.

### username/ssh-key

Этот параметр позволяет проходить аутентификацию с помощью SSH-ключей.

Если у вас есть SSH-ключ (например, созданный с помощью `ssh-keygen`),

```text theme={null}
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDNf0r6vRl24Ix3tv2IgPmNPO2ATa2krvt80DdcTatLj john@example.com
```

Ожидается, что элемент `ssh_key` будет

```xml theme={null}
<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>`) не имеет значения; используется только вложенный элемент аутентификации.

**Пример: несколько паролей**

```xml theme={null}
<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>
```

**Пример: сочетание разных способов аутентификации**

```xml theme={null}
<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**

```xml theme={null}
<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

Этот параметр включает или отключает использование [системы управления доступом и учётными записями](/ru/concepts/features/security/access-rights#access-control-usage), управляемой через SQL, для пользователя.

Возможные значения:

* 0 — Отключено.
* 1 — Включено.

Значение по умолчанию: 0.

### привилегии

Этот параметр позволяет предоставить выбранному пользователю любые права.
Каждый элемент списка должен быть запросом `GRANT` без указания получателей привилегий.

Пример:

```xml theme={null}
<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-запрос](https://en.wikipedia.org/wiki/Reverse_DNS_lookup), после чего применяется указанное регулярное выражение. Затем для результатов PTR-запроса выполняется ещё один DNS-запрос, и все полученные адреса сравниваются с адресом клиента. Настоятельно рекомендуем, чтобы регулярное выражение оканчивалось символом \$.

Все результаты DNS-запросов кэшируются до перезапуска сервера.

**Примеры**

Чтобы открыть доступ для пользователя из любой сети, укажите:

```xml theme={null}
<ip>::/0</ip>
```

<Note>
  Открывать доступ из любой сети небезопасно, если у вас не настроен должным образом брандмауэр или server не подключен к Интернету напрямую.
</Note>

Чтобы открыть доступ только с localhost, укажите:

```xml theme={null}
<ip>::1</ip>
<ip>127.0.0.1</ip>
```

### user\_name/profile

Пользователю можно назначить профиль настроек. Профили настроек задаются в отдельном разделе файла `users.xml`. Подробнее см. в разделе [Профили настроек](/ru/concepts/features/configuration/settings/settings-profiles).

### user\_name/quota

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

Вы можете назначить пользователю набор квот. Подробное описание настройки квот см. в разделе [Quotas](/ru/concepts/features/configuration/server-config/quotas).

### user\_name/databases

В этом разделе можно ограничить строки, которые ClickHouse возвращает для запросов `SELECT`, выполняемых текущим пользователем, тем самым реализовав базовую защиту на уровне строк.

**Пример**

Следующая конфигурация задаёт, что пользователь `user1` может видеть в результатах запросов `SELECT` только строки из `table1`, в которых значение поля `id` равно 1000.

```xml theme={null}
<user1>
    <databases>
        <database_name>
            <table1>
                <filter>id = 1000</filter>
            </table1>
        </database_name>
    </databases>
</user1>
```

`filter` может быть любым выражением, результатом которого является значение типа [UInt8](/ru/reference/data-types/int-uint). Обычно оно содержит сравнения и логические операторы. Строки из `database_name.table1`, для которых результат `filter` равен 0, не возвращаются этому пользователю. Такая фильтрация несовместима с операциями `PREWHERE` и отключает оптимизацию `WHERE→PREWHERE`.

## Роли

Вы можете создать любые предопределённые роли в разделе `roles` файла конфигурации `user.xml`.

Структура раздела `roles`:

```xml theme={null}
<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`:

```xml theme={null}
<users>
    <user_name>
        ...
        <grants>
            <query>GRANT test_role</query>
        </grants>
    </user_name>
<users>
```