LDAP

Not supported in ClickHouse Cloud

Примечание

This page is not applicable to ClickHouse Cloud. The feature documented here is not available in ClickHouse Cloud services. See the ClickHouse Cloud Compatibility guide for more information.

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

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

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

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

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

Пример

<clickhouse>
    <!- ... -->
    <ldap_servers>
        <!- Типовой LDAP-сервер. -->
        <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>
            <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>

        <!- Типовой Active Directory с настроенным обнаружением DN пользователя для последующего сопоставления ролей. -->
        <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 — порт LDAP‑сервера, по умолчанию 636, если enable_tls имеет значение true, иначе 389.
bind_dn — шаблон, используемый для формирования DN для привязки (bind).
- Итоговый DN будет сформирован путем замены всех подстрок {user_name} в шаблоне на фактическое имя пользователя при каждой попытке аутентификации.
user_dn_detection — раздел с параметрами поиска в LDAP для определения фактического DN пользователя, к которому выполнена привязка.
- В основном используется в фильтрах поиска для последующего сопоставления ролей, когда сервером является Active Directory. Полученный DN пользователя будет использоваться при замене подстрок {user_dn} везде, где это разрешено. По умолчанию DN пользователя устанавливается равным bind DN, но после выполнения поиска он будет обновлен фактическим обнаруженным значением DN пользователя.
  - base_dn — шаблон, используемый для формирования базового DN для поиска в LDAP.
    - Итоговый DN будет сформирован путем замены всех подстрок {user_name} и {bind_dn} в шаблоне на фактическое имя пользователя и bind DN во время поиска в LDAP.
  - scope — область поиска в LDAP.
    - Допустимые значения: base, one_level, children, subtree (значение по умолчанию).
  - search_filter — шаблон, используемый для формирования фильтра поиска в LDAP.
    - Итоговый фильтр будет сформирован путем замены всех подстрок {user_name}, {bind_dn} и {base_dn} в шаблоне на фактическое имя пользователя, bind DN и base DN во время поиска в LDAP.
    - Обратите внимание, что специальные символы должны быть корректно экранированы в XML.
verification_cooldown — период времени в секундах после успешной попытки привязки, в течение которого пользователь считается успешно аутентифицированным для всех последующих запросов без обращения к LDAP‑серверу.
- Укажите 0 (значение по умолчанию), чтобы отключить кеширование и принудительно обращаться к LDAP‑серверу для каждого запроса аутентификации.
enable_tls — флаг, включающий использование защищенного соединения с LDAP‑сервером.
- Укажите no для незашифрованного протокола ldap:// (не рекомендуется).
- Укажите yes для протокола LDAP поверх SSL/TLS ldaps:// (рекомендуется, используется по умолчанию).
- Укажите starttls для устаревшего протокола StartTLS (незашифрованный протокол ldap://, повышаемый до TLS).
tls_minimum_protocol_version — минимальная версия протокола SSL/TLS.
- Допустимые значения: ssl2, ssl3, tls1.0, tls1.1, tls1.2 (значение по умолчанию).
tls_require_cert — способ проверки сертификата удаленного узла (peer) 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).

Внешний аутентификатор 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>
        <!- Типовой LDAP-сервер. -->
        <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>

        <!- Типовой Active Directory с маппингом ролей на основе определенного 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-серверов, определённых в конфигурационном разделе ldap_servers выше. Этот параметр обязателен и не может быть пустым.
roles — Раздел со списком локально определённых ролей, которые будут назначены каждому пользователю, полученному из LDAP-сервера.
- Если роли здесь не указаны или не назначены в процессе сопоставления ролей (см. ниже), пользователь не сможет выполнять никакие действия после аутентификации.
role_mapping — Раздел с параметрами поиска LDAP и правилами сопоставления.
- Когда пользователь аутентифицируется, выполняется поиск в LDAP с использованием search_filter и имени пользователя, выполнившего вход. Для каждой записи, найденной в ходе этого поиска, извлекается значение указанного атрибута. Для каждого значения атрибута, которое имеет указанный префикс, префикс удаляется, и оставшаяся часть значения становится именем локальной роли, определённой в ClickHouse, которую предполагается создать заранее с помощью оператора CREATE ROLE.
- В одном и том же разделе ldap может быть определено несколько разделов role_mapping. Все они будут применяться.
  - base_dn — Шаблон, используемый для построения базового DN для поиска в LDAP.
    - Итоговый DN будет построен путём замены всех подстрок {user_name}, {bind_dn} и {user_dn} в шаблоне фактическим именем пользователя и значениями bind DN и user DN при каждом поиске в LDAP.
  - scope — Область поиска в LDAP.
    - Допустимые значения: base, one_level, children, subtree (значение по умолчанию).
  - search_filter — Шаблон, используемый для построения фильтра поиска для запроса к LDAP.
    - Итоговый фильтр будет построен путём замены всех подстрок {user_name}, {bind_dn}, {user_dn} и {base_dn} в шаблоне фактическим именем пользователя и значениями bind DN, user DN и base DN при каждом поиске в LDAP.
    - Обратите внимание, что специальные символы должны быть корректно экранированы в XML.
  - attribute — Имя атрибута, значения которого будут возвращены поиском LDAP. По умолчанию — cn.
  - prefix — Префикс, который ожидается в начале каждой строки в исходном списке строк, возвращённом поиском LDAP. Префикс будет удалён из исходных строк, а полученные строки будут интерпретированы как имена локальных ролей. По умолчанию — пустой.

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

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

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

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

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

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