> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-home-button.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Руководство по настройке аутентификации через LDAP для ClickHouse
# LDAP
Эта страница не применима к [ClickHouse Cloud](https://clickhouse.com/cloud). Описанная здесь возможность недоступна в сервисах ClickHouse Cloud.
Дополнительные сведения см. в руководстве ClickHouse [Cloud Compatibility](/ru/products/cloud/guides/cloud-compatibility).
LDAP-сервер можно использовать для аутентификации пользователей ClickHouse. Для этого есть два подхода:
* Использовать LDAP как внешний аутентификатор для существующих пользователей, определённых в `users.xml` или в локальных путях управления доступом.
* Использовать LDAP как внешний каталог пользователей и разрешить аутентификацию пользователей, не определённых локально, если они существуют на LDAP-сервере.
Для обоих подходов в конфигурации ClickHouse должен быть определён LDAP-сервер с внутренним именем, чтобы на него могли ссылаться другие части конфигурации.
## Определение сервера LDAP
Чтобы определить сервер LDAP, необходимо добавить в `config.xml` раздел `ldap_servers`.
**Пример**
```xml theme={null}
localhost
636
uid={user_name},ou=users,dc=example,dc=com
300
false
yes
tls1.2
demand
/path/to/tls_cert_file
/path/to/tls_key_file
/path/to/tls_ca_cert_file
/path/to/tls_ca_cert_dir
ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:AES256-GCM-SHA384
localhost
389
EXAMPLE\{user_name}
CN=Users,DC=example,DC=com
(&(objectClass=user)(sAMAccountName={user_name}))
no
```
Обратите внимание: в разделе `ldap_servers` можно задать несколько LDAP-серверов, используя для них разные имена.
**Параметры**
| Параметр | По умолчанию | Описание |
| ------------------------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `host` | — | Имя хоста или IP-адрес LDAP-сервера. Этот параметр обязателен и не может быть пустым. |
| `port` | `636` / `389` | Порт LDAP-сервера. По умолчанию используется `636`, если `enable_tls` установлен в `yes`, иначе — `389`. |
| `bind_dn` | — | Шаблон, используемый для формирования DN для bind. Итоговый DN формируется заменой всех подстрок `{user_name}` в шаблоне на фактическое имя пользователя при каждой попытке аутентификации. |
| `auth_dn_prefix` | — | **Устарело.** Альтернатива `bind_dn`. Не может использоваться вместе с `bind_dn`. Если параметр указан, bind DN формируется как `auth_dn_prefix + {user_name} + auth_dn_suffix`. Например, значение `auth_dn_prefix`, равное `uid=`, и `auth_dn_suffix`, равное `,ou=users,dc=example,dc=com`, эквивалентны значению `bind_dn`, равному `uid={user_name},ou=users,dc=example,dc=com`. |
| `auth_dn_suffix` | — | **Устарело.** См. `auth_dn_prefix`. |
| `verification_cooldown` | `0` | Период времени в секундах после успешной попытки bind, в течение которого пользователь будет считаться успешно прошедшим аутентификацию для всех последующих запросов без обращения к LDAP-серверу. Укажите `0`, чтобы отключить кэширование и принудительно обращаться к LDAP-серверу для каждого запроса аутентификации. |
| `follow_referrals` | `false` | Флаг, разрешающий клиентской библиотеке LDAP автоматически переходить по referral, возвращаемым сервером. В основном актуально для сред Microsoft Active Directory, где поиск по поддереву на уровне base DN верхнего уровня (например, `DC=example,DC=com`) может возвращать referral/search reference (например, `DC=DomainDnsZones,...`). Устанавливайте `true` только если вам явно нужен межпартиционный поиск. |
| `enable_tls` | `yes` | Флаг, включающий использование защищенного соединения с LDAP-сервером. Укажите `no` для незашифрованного протокола `ldap://` (не рекомендуется), `yes` для LDAP поверх SSL/TLS `ldaps://` (рекомендуется) или `starttls` для устаревшего протокола StartTLS (незашифрованный протокол `ldap://`, повышаемый до TLS). |
| `tls_minimum_protocol_version` | `tls1.2` | Минимальная версия протокола SSL/TLS. Допустимые значения: `ssl2`, `ssl3`, `tls1.0`, `tls1.1`, `tls1.2`. |
| `tls_require_cert` | `demand` | Режим проверки сертификата узла для SSL/TLS. Допустимые значения: `never`, `allow`, `try`, `demand`. |
| `tls_cert_file` | — | Путь к файлу сертификата. |
| `tls_key_file` | — | Путь к файлу ключа сертификата. |
| `tls_ca_cert_file` | — | Путь к файлу CA‑сертификата. |
| `tls_ca_cert_dir` | — | Путь к каталогу, содержащему CA‑сертификаты. |
| `tls_cipher_suite` | — | Разрешенный набор шифров (в нотации OpenSSL). |
| `search_limit` | `256` | Максимальное количество записей, которое может быть возвращено LDAP-поиском, выполняемым этим определением сервера (для определения user DN и сопоставления ролей). |
**Подпараметры `user_dn_detection`**
Раздел с параметрами LDAP-поиска для определения фактического user DN привязанного пользователя. В основном используется в search filter для дальнейшего сопоставления ролей, когда сервером является Active Directory. Полученный user DN будет использоваться при замене подстрок `{user_dn}` везде, где это разрешено. По умолчанию user DN совпадает с bind DN, но после выполнения поиска он будет обновлен до фактически определенного значения user DN.
| Параметр | По умолчанию | Описание |
| --------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `base_dn` | — | Шаблон, используемый для формирования base DN для LDAP-поиска. Итоговый DN формируется заменой всех подстрок `{user_name}` и `{bind_dn}` в шаблоне на фактическое имя пользователя и bind DN во время LDAP-поиска. |
| `scope` | `subtree` | Область LDAP-поиска. Допустимые значения: `base`, `one_level`, `children`, `subtree`. |
| `search_filter` | — | Шаблон, используемый для формирования search filter для LDAP-поиска. Итоговый filter формируется заменой всех подстрок `{user_name}`, `{bind_dn}` и `{base_dn}` в шаблоне на фактическое имя пользователя, bind DN и base DN во время LDAP-поиска. Обратите внимание, что специальные символы должны быть корректно экранированы в XML. |
## Внешний аутентификатор LDAP
Удалённый LDAP-сервер можно использовать для проверки паролей локально определённых пользователей (пользователей, определённых в `users.xml` или в локальных путях управления доступом). Для этого в определении пользователя укажите имя ранее определённого LDAP-сервера вместо `password` или аналогичных секций.
При каждой попытке входа ClickHouse пытается выполнить "bind" с указанным DN, заданным параметром `bind_dn` в [Определении сервера LDAP](#ldap-server-definition), используя предоставленные учётные данные, и, если это удаётся, пользователь считается аутентифицированным. Этот способ часто называют методом "simple bind".
**Пример**
```xml theme={null}
my_ldap_server
```
Обратите внимание, что пользователь `my_user` ссылается на `my_ldap_server`. Этот LDAP-сервер должен быть настроен в основном файле `config.xml`, как описано выше.
Когда включена [система управления доступом и учётными записями](/ru/concepts/features/security/access-rights#access-control-usage), управляемая через SQL, пользователей, аутентифицируемых LDAP-серверами, также можно создавать с помощью оператора [CREATE USER](/ru/reference/statements/create/user).
```sql title="Query" theme={null}
CREATE USER my_user IDENTIFIED WITH ldap SERVER 'my_ldap_server';
```
## Внешний каталог пользователей LDAP
Помимо локально определённых пользователей, в качестве источника пользовательских определений можно использовать удалённый LDAP-сервер. Для этого укажите имя ранее определённого LDAP-сервера (см. [Определение сервера LDAP](#ldap-server-definition)) в разделе `ldap` внутри раздела `users_directories` файла `config.xml`.
При каждой попытке входа ClickHouse пытается найти определение пользователя локально и аутентифицировать его обычным образом. Если пользователь не определён, ClickHouse будет считать, что он существует во внешнем каталоге LDAP, и попытается выполнить "bind" с указанным DN на LDAP-сервере, используя предоставленные учётные данные. В случае успеха пользователь будет считаться существующим и аутентифицированным. Пользователю будут назначены роли из списка, указанного в разделе `roles`. Кроме того, можно выполнить LDAP-"search", а результаты преобразовать в имена ролей и назначить эти роли пользователю, если также настроен раздел `role_mapping`. Для всего этого должна быть включена [система управления доступом и учётными записями](/ru/concepts/features/security/access-rights#access-control-usage), управляемая через SQL, а роли должны создаваться с помощью оператора [CREATE ROLE](/ru/reference/statements/create/role).
**Пример**
Добавляется в `config.xml`.
```xml theme={null}
my_ldap_server
ou=groups,dc=example,dc=com
subtree
(&(objectClass=groupOfNames)(member={bind_dn}))
cn
clickhouse_
my_ad_server
CN=Users,DC=example,DC=com
CN
subtree
(&(objectClass=group)(member={user_dn}))
clickhouse_
```
Обратите внимание, что `my_ldap_server`, на который есть ссылка в разделе `ldap` внутри раздела `user_directories`, должен быть ранее определённым сервером LDAP, настроенным в `config.xml` (см. [Определение сервера LDAP](#ldap-server-definition)).
**Параметры**
| Параметр | По умолчанию | Описание |
| -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `server` | — | Одно из имён LDAP-серверов, определённых выше в разделе конфигурации `ldap_servers`. Этот параметр обязателен и не может быть пустым. |
| `roles` | — | Раздел со списком локально определённых ролей, которые будут назначены каждому пользователю, полученному с LDAP-сервера. Если здесь роли не указаны и не назначаются при сопоставлении ролей (см. ниже), пользователь не сможет выполнять какие-либо действия после аутентификации. |
**Подпараметры `role_mapping`**
Раздел с параметрами LDAP-поиска и правилами сопоставления. Когда пользователь проходит аутентификацию, пока соединение всё ещё привязано к LDAP, выполняется LDAP-поиск с использованием `search_filter` и имени вошедшего пользователя. Для каждой записи, найденной в ходе этого поиска, извлекается значение указанного атрибута. Для каждого значения атрибута с указанным префиксом префикс удаляется, а оставшаяся часть значения становится именем локальной роли, определённой в ClickHouse, которую необходимо заранее создать с помощью оператора [CREATE ROLE](/ru/reference/statements/create/role). Внутри одного и того же раздела `ldap` можно определить несколько разделов `role_mapping`. Все они будут применены.
| Параметр | По умолчанию | Описание |
| --------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `base_dn` | — | Template, используемый для формирования base DN для LDAP-поиска. Итоговый DN формируется заменой всех подстрок `{user_name}`, `{bind_dn}` и `{user_dn}` в шаблоне на фактические имя пользователя, bind DN и user DN при каждом LDAP-поиске. |
| `scope` | `subtree` | Область LDAP-поиска. Допустимые значения: `base`, `one_level`, `children`, `subtree`. |
| `search_filter` | — | Template, используемый для формирования search filter для LDAP-поиска. Итоговый filter формируется заменой всех подстрок `{user_name}`, `{bind_dn}`, `{user_dn}` и `{base_dn}` в шаблоне на фактические имя пользователя, bind DN, user DN и base DN при каждом LDAP-поиске. Обратите внимание, что специальные символы должны быть корректно экранированы в XML. |
| `attribute` | `cn` | Имя атрибута, значения которого будут возвращены в результате LDAP-поиска. |
| `prefix` | пусто | Префикс, ожидаемый перед каждой строкой в исходном списке строк, возвращённом LDAP-поиском. Префикс будет удалён из исходных строк, а полученные строки будут интерпретироваться как имена локальных ролей. |