LDAP

Not supported in ClickHouse Cloud

Примечание

Эта страница не относится к ClickHouse Cloud. Описанная здесь функция недоступна в услугах ClickHouse Cloud. См. руководство ClickHouse Совместимость с ClickHouse Cloud для получения дополнительной информации.

Сервер LDAP можно использовать для аутентификации пользователей ClickHouse. Для этого есть два подхода:

Использовать LDAP в качестве внешнего аутентификатора для существующих пользователей, которые определены в users.xml или в локальных путях управления доступом.
Использовать LDAP в качестве внешнего пользовательского каталога и разрешить аутентификацию локально не определённых пользователей, если они существуют на сервере LDAP.

В обоих этих случаях в конфигурации ClickHouse должен быть определён сервер LDAP с внутренним именем, чтобы на него можно было ссылаться из других частей конфигурации.

Определение сервера LDAP

Чтобы задать сервер LDAP, необходимо добавить раздел ldap_servers в файл config.xml.

Пример

<clickhouse>
    <!- ... -->
    <ldap_servers>
        <!- Typical LDAP server. -->
        <my_ldap_server>
            <host>localhost</host>
            <port>636</port>
            <bind_dn>uid={user_name},ou=users,dc=example,dc=com</bind_dn>
            <verification_cooldown>300</verification_cooldown>
            <follow_referrals>false</follow_referrals>
            <enable_tls>yes</enable_tls>
            <tls_minimum_protocol_version>tls1.2</tls_minimum_protocol_version>
            <tls_require_cert>demand</tls_require_cert>
            <tls_cert_file>/path/to/tls_cert_file</tls_cert_file>
            <tls_key_file>/path/to/tls_key_file</tls_key_file>
            <tls_ca_cert_file>/path/to/tls_ca_cert_file</tls_ca_cert_file>
            <tls_ca_cert_dir>/path/to/tls_ca_cert_dir</tls_ca_cert_dir>
            <tls_cipher_suite>ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:AES256-GCM-SHA384</tls_cipher_suite>
        </my_ldap_server>

        <!- Typical Active Directory with configured user DN detection for further role mapping. -->
        <my_ad_server>
            <host>localhost</host>
            <port>389</port>
            <bind_dn>EXAMPLE\{user_name}</bind_dn>
            <user_dn_detection>
                <base_dn>CN=Users,DC=example,DC=com</base_dn>
                <search_filter>(&amp;(objectClass=user)(sAMAccountName={user_name}))</search_filter>
            </user_dn_detection>
            <enable_tls>no</enable_tls>
        </my_ad_server>
    </ldap_servers>
</clickhouse>

Обратите внимание, что в секции 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-клиента автоматически переходить по LDAP referral, возвращаемым сервером. В основном актуально для сред Microsoft Active Directory, где поиск по поддереву на базовом DN верхнего уровня (например, `DC=example,DC=com`) может возвращать referral/ссылки поиска (например, `DC=DomainDnsZones,...`). Устанавливайте `true` только в том случае, если вам явно нужен поиск между партициями.
`enable_tls`	`yes`	Флаг, включающий использование защищённого connection к 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-запросами поиска, выполняемыми этим определением сервера (для определения DN пользователя и сопоставления ролей).

Подпараметры user_dn_detection

Раздел с параметрами LDAP-поиска для определения фактического DN пользователя, выполнившего bind. В основном используется в фильтрах поиска для дальнейшего сопоставления ролей, когда сервером является Active Directory. Полученный DN пользователя будет использоваться при замене подстрок {user_dn} везде, где это допустимо. По умолчанию DN пользователя равен bind DN, но после выполнения поиска он будет обновлён до фактически определённого значения DN пользователя.

Параметр	По умолчанию	Описание
`base_dn`	—	Шаблон, используемый для формирования базового DN для LDAP-поиска. Итоговый DN формируется заменой всех подстрок `{user_name}` и `{bind_dn}` в шаблоне на фактическое имя пользователя и bind DN во время LDAP-поиска.
`scope`	`subtree`	Область LDAP-поиска. Допустимые значения: `base`, `one_level`, `children`, `subtree`.
`search_filter`	—	Шаблон, используемый для формирования фильтра поиска для LDAP-поиска. Итоговый фильтр формируется заменой всех подстрок `{user_name}`, `{bind_dn}` и `{base_dn}` в шаблоне на фактическое имя пользователя, bind DN и base DN во время LDAP-поиска. Обратите внимание: специальные символы должны быть корректно экранированы в XML.

Внешний аутентификатор LDAP

Удалённый сервер LDAP может использоваться в качестве метода проверки паролей для локально определённых пользователей (пользователей, заданных в users.xml или в локальных путях управления доступом). Для этого укажите ранее определённое имя сервера LDAP вместо разделов password или аналогичных в определении пользователя.

При каждой попытке входа в систему ClickHouse пытается «привязаться» (bind) к DN, указанному параметром bind_dn в определении сервера LDAP, используя предоставленные учётные данные, и в случае успеха пользователь считается аутентифицированным. Это часто называют методом «simple bind».

Пример

<clickhouse>
    <!- ... -->
    <users>
        <!- ... -->
        <my_user>
            <!- ... -->
            <ldap>
                <server>my_ldap_server</server>
            </ldap>
        </my_user>
    </users>
</clickhouse>

Обратите внимание, что пользователь my_user относится к my_ldap_server. Этот LDAP-сервер должен быть настроен в основном файле config.xml, как описано ранее.

Когда включено основанное на SQL управление доступом и учетными записями, пользователи, аутентифицируемые LDAP-серверами, также могут быть созданы с помощью оператора CREATE USER.

Запрос:

CREATE USER my_user IDENTIFIED WITH ldap SERVER 'my_ldap_server';

Внешний пользовательский каталог LDAP

Помимо локально заданных пользователей, в качестве источника описаний пользователей может использоваться удалённый сервер LDAP. Для этого укажите ранее определённое имя сервера LDAP (см. Определение сервера LDAP) в секции ldap внутри секции users_directories файла config.xml.

При каждой попытке входа ClickHouse сначала пытается найти описание пользователя локально и аутентифицировать его как обычно. Если пользователь не определён, ClickHouse предполагает, что его описание существует во внешнем каталоге LDAP и пытается выполнить операцию bind к указанному DN на сервере LDAP, используя предоставленные учётные данные. В случае успеха пользователь считается существующим и аутентифицированным. Пользователю будут назначены роли из списка, указанного в секции roles. Дополнительно может быть выполнен LDAP‑поиск (search), результаты которого могут быть преобразованы и интерпретированы как имена ролей и затем назначены пользователю, если также настроена секция role_mapping. Всё это подразумевает, что SQL‑управляемая Система управления доступом и учётными записями включена и роли созданы с помощью оператора CREATE ROLE.

Пример

Размещается в файле config.xml.

<clickhouse>
    <!- ... -->
    <user_directories>
        <!- Typical LDAP server. -->
        <ldap>
            <server>my_ldap_server</server>
            <roles>
                <my_local_role1 />
                <my_local_role2 />
            </roles>
            <role_mapping>
                <base_dn>ou=groups,dc=example,dc=com</base_dn>
                <scope>subtree</scope>
                <search_filter>(&amp;(objectClass=groupOfNames)(member={bind_dn}))</search_filter>
                <attribute>cn</attribute>
                <prefix>clickhouse_</prefix>
            </role_mapping>
        </ldap>

        <!- Typical Active Directory with role mapping that relies on the detected user DN. -->
        <ldap>
            <server>my_ad_server</server>
            <role_mapping>
                <base_dn>CN=Users,DC=example,DC=com</base_dn>
                <attribute>CN</attribute>
                <scope>subtree</scope>
                <search_filter>(&amp;(objectClass=group)(member={user_dn}))</search_filter>
                <prefix>clickhouse_</prefix>
            </role_mapping>
        </ldap>
    </user_directories>
</clickhouse>

Обратите внимание, что my_ldap_server, указанный в разделе ldap внутри секции user_directories, должен быть ранее определённым LDAP-сервером, описанным в config.xml (см. Определение LDAP-сервера).

Параметры

Параметр	По умолчанию	Описание
`server`	—	Одно из имён LDAP-серверов, определённых выше в секции config `ldap_servers`. Этот параметр является обязательным и не может быть пустым.
`roles`	—	Секция со списком локально определённых ролей, которые будут назначены каждому пользователю, полученному с LDAP-сервера. Если здесь не указаны роли и они не назначены при сопоставлении ролей (см. ниже), пользователь не сможет выполнять какие-либо действия после аутентификации.

Подпараметры role_mapping

Секция с параметрами LDAP-поиска и правилами сопоставления. Когда пользователь проходит аутентификацию, пока соединение всё ещё привязано к LDAP, выполняется LDAP-поиск с использованием search_filter и имени вошедшего пользователя. Для каждой записи, найденной во время этого поиска, извлекается значение указанного атрибута. Для каждого значения атрибута, имеющего указанный префикс, префикс удаляется, а оставшаяся часть значения становится именем локальной роли, определённой в ClickHouse, которую предполагается заранее создать с помощью команды CREATE ROLE. Внутри одной и той же секции ldap может быть определено несколько секций role_mapping. Все они будут применены.

Параметр	По умолчанию	Описание
`base_dn`	—	Template, используемый для формирования базового DN для LDAP-поиска. Итоговый DN формируется заменой всех подстрок `{user_name}`, `{bind_dn}` и `{user_dn}` в Template на фактическое имя пользователя, DN привязки и DN пользователя при каждом LDAP-поиске.
`scope`	`subtree`	Область LDAP-поиска. Допустимые значения: `base`, `one_level`, `children`, `subtree`.
`search_filter`	—	Template, используемый для формирования фильтра поиска для LDAP-поиска. Итоговый фильтр формируется заменой всех подстрок `{user_name}`, `{bind_dn}`, `{user_dn}` и `{base_dn}` в Template на фактическое имя пользователя, DN привязки, DN пользователя и базовый DN при каждом LDAP-поиске. Обратите внимание, что специальные символы должны быть корректно экранированы в XML.
`attribute`	`cn`	Имя атрибута, значения которого возвращаются LDAP-поиском.
`prefix`	пусто	Префикс, ожидаемый перед каждой строкой в исходном списке строк, возвращаемом LDAP-поиском. Префикс будет удалён из исходных строк, а полученные строки будут интерпретироваться как имена локальных ролей.

Определение сервера LDAP​

Внешний аутентификатор LDAP​

Внешний пользовательский каталог LDAP​

Определение сервера LDAP

Внешний аутентификатор LDAP

Внешний пользовательский каталог LDAP