LDAP

Руководство по настройке аутентификации через LDAP для ClickHouse

Эта страница не применима к ClickHouse Cloud. Описанная здесь возможность недоступна в сервисах ClickHouse Cloud. Дополнительные сведения см. в руководстве ClickHouse Cloud Compatibility.

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

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

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

​

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

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

Пример

<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>
            <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>

        <!- Типичный Active Directory с настроенным определением user 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	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, используя предоставленные учётные данные, и, если это удаётся, пользователь считается аутентифицированным. Этот способ часто называют методом “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.

Query

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, выполняется LDAP-поиск с использованием search_filter и имени вошедшего пользователя. Для каждой записи, найденной в ходе этого поиска, извлекается значение указанного атрибута. Для каждого значения атрибута с указанным префиксом префикс удаляется, а оставшаяся часть значения становится именем локальной роли, определённой в ClickHouse, которую необходимо заранее создать с помощью оператора 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-поиском. Префикс будет удалён из исходных строк, а полученные строки будут интерпретироваться как имена локальных ролей.