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>
        <!- Типовой 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