LDAP - ClickHouse Documentation

Эта страница не применима к 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-поиском. Префикс будет удалён из исходных строк, а полученные строки будут интерпретироваться как имена локальных ролей.

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

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

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

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

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

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