Describe work with ldaps scheme and add information about nested groups (#6489)

Co-authored-by: Ivan Blinkov <ivan@ydb.tech>

Author: molotkov-and

ydb/docs/ru/core/concepts/auth.md

@@ -77,7 +77,7 @@
 
 На данный момент {{ ydb-short-name }} поддерживает только один способ LDAP аутентификации, так называемый search+bind метод, состоящий из нескольких шагов. После получения логина и пароля пользователя, которого нужно аутентифицировать, выполняется операция *bind* с заранее определенными в секции [ldap_authentication](../deploy/configuration/config.md#ldap-auth-config) учетными данными специального сервисного аккаунта. Учетные данные такого сервисного аккаунта задаются через параметры конфигурации **bind_dn** и **bind_password**. После успешной аутентификации сервисного пользователя от его имени выполняется поиск в LDAP каталоге пользователя, который пытается аутентифицироваться в системе. Операция *search* выполняется для всего поддерева, корень которого берется из параметра конфигурации **base_dn**. Поиск записи в поддереве осуществляется в соответствии с фильтром, задаваемым в параметре конфигурации **search_filter**. После того как запись пользователя была найдена, {{ ydb-short-name }} выполняет повторную операцию *bind* от лица этого найденного пользователя, используя ранее запрошенный пароль. Успех аутентификации пользователя определяется результатом повторной операции *bind*.
 
-После успешной аутентификации пользователя формируется токен. Далее этот токен используется вместо логина и пароля. Оперирование токеном ускоряет процесc аутентификации и повышает безопасность.
+После успешной аутентификации пользователя формируется токен. Далее этот токен используется вместо логина и пароля. Оперирование токеном ускоряет процесс аутентификации и повышает безопасность.
 
 {% note info %}
 
@@ -91,7 +91,11 @@
 
 Группы, как и сам пользователь, являются субъектами выполнения операций над объектами схемы базы данных. Для разграничения доступа к различным ресурсам базы данных субъектам могут назначаться права доступа. И в соответствии со списком назначенных прав субъекты будут авторизованы на выполнение тех или иных операций.
 
-Процесс получения списка групп пользователя из LDAP каталога похож на те действия, которые выполняются при аутентификации. Сначала выполняется операция *bind* для сервисного пользователя, учетные данные которого записаны в параметрах **bind_dn** и **bind_password** секции [ldap_authentication](../deploy/configuration/config.md#ldap-auth-config) файла конфигурации. После успешной аутентификации выполняется поиск записи пользователя, для которого был ранее сформирован токен. Поиск также выполняется в соответствии с параметром **search_filter**. Если пользователь всё ещё существует, то в качестве возвращаемого результата операции *search* будет список значений атрибута *memberOf*. Атрибут *memberOf* хранит уникальные имена (Distinguished Name, DN) групп, в которых состоит пользователь.
+Процесс получения списка групп пользователя из LDAP каталога похож на те действия, которые выполняются при аутентификации. Сначала выполняется операция *bind* для сервисного пользователя, учетные данные которого записаны в параметрах **bind_dn** и **bind_password** секции [ldap_authentication](../deploy/configuration/config.md#ldap-auth-config) файла конфигурации. После успешной аутентификации выполняется поиск записи пользователя, для которого был ранее сформирован токен. Поиск также выполняется в соответствии с параметром **search_filter**. Если пользователь всё ещё существует, то в качестве возвращаемого результата операции *search* будет список значений атрибута, записанного в параметре **requested_group_attribute**. В случае, если этот параметр пуст, то аттрибутом обратного членства в группе будет являться *memberOf*. Атрибут *memberOf* хранит уникальные имена (Distinguished Name, DN) групп, в которых состоит пользователь.
+
+#### Получение групп
+
+По умолчанию {{ ydb-short-name }} выполняет поиск только тех групп, в которых пользователь состоит непосредственно. С помощью включения флага **extended_settings.enable_nested_groups_search** секции [ldap_authentication](../deploy/configuration/config.md#ldap-auth-config) {{ ydb-short-name }} будет пытаться получить группы на всех уровнях вложенности, а не только те, в которые пользователь входит напрямую. Если {{ ydb-short-name }} настроен для работы с Active Directory, для поиска всех вложенных групп будет использовано специфичное для Active Directory правило соответствия [LDAP_MATCHING_RULE_IN_CHAIN](https://learn.microsoft.com/en-us/windows/win32/adsi/search-filter-syntax?redirectedfrom=MSDN). Это правило позволяет получить все вложенные группы одним запросом. Для LDAP-серверов на основе OpenLDAP поиск групп будет выполнен рекурсивным обходом графа, что в общем случае требует выполнения нескольких запросов. Как для Active Directory, так и для OpenLDAP поиск групп будет выполнен только для поддерева, корень которого берётся из параметра конфигурации **base_dn**.
 
 {% note info %}
 
@@ -137,3 +141,20 @@ cn=Developers,ou=Groups,dc=mycompany,dc=net@ldap
 * Аутентификация пользователя внутренним механизмом {{ ydb-short-name }}: `ydb --user user1 -p ydb_profile scheme ls`
 
 {% endnote %}
+
+### TLS соединение
+
+В зависимости от указанных параметров конфигурации {{ ydb-short-name }} может устанавливать либо зашифрованное либо незашифрованное соединение. Зашифрованное соединение с LDAP сервером устанавливается с использованием протокола TLS. Такой способ рекомендуется использовать для production кластеров. Существует два способа включить TLS соединение:
+
+* Автоматически. Используется схема соединения [`ldaps`](#ldaps)
+* Использование расширения LDAP протокола [`StartTls`](#starttls)
+
+При использовании незашифрованного соединения, все данные, которые передаются в запросах к LDAP серверу, будут передаваться в открытом виде, в том числе и пароли. Таким способом соединения проще начать пользоваться, он больше подходит для экспериментов или тестирования.
+
+#### LDAPS
+
+Для того чтобы {{ ydb-short-name }} автоматически установила зашифрованное соединение с LDAP-сервером, необходимо в [параметре конфигурации](../deploy/configuration/config.md#ldap-auth-config) **scheme** установить значение `ldaps`. TLS-диалог будет инициирован на порту, указанном в конфигурации. Если порт не указан, для схемы `ldaps` будет применён порт по умолчанию 636. LDAP-сервер должен быть настроен на приём TLS-соединений на указанных портах.
+
+#### Расширение LDAP протокола `StartTls` {#starttls}
+
+`StartTls` — это расширение протокола LDAP, используемое для шифрования сообщений по протоколу TLS. Оно позволяет передавать в рамках одного соединения с LDAP-сервером одни сообщения в зашифрованном виде, а другие — открыто. Сообщение с этим расширением отправляется от {{ ydb-short-name }} к LDAP-серверу для инициирования TLS-соединения. В случае {{ ydb-short-name }} не предусмотрено включение и выключение TLS-соединения в рамках одного соединения. Поэтому при использовании расширения `StartTls` после установления зашифрованного соединения {{ ydb-short-name }} будет отправлять все дальнейшие сообщения к LDAP-серверу в зашифрованном виде. Одним из преимуществ использования данного расширения вместо схемы `ldaps` (при соответствующей настройке LDAP-сервера) является возможность установить TLS-соединение на нешифрованном порту. Расширение включается в [секции `use_tls`](../deploy/configuration/config.md#ldap-auth-config) файла конфигурации.

ydb/docs/ru/core/deploy/configuration/config.md

@@ -614,7 +614,10 @@ blob_storage_config:
 auth_config:
   #...
   ldap_authentication:
-    host: "ldap-hostname.example.net"
+    hosts:
+      - "ldap-hostname-01.example.net"
+      - "ldap-hostname-02.example.net"
+      - "ldap-hostname-03.example.net"
     port: 389
     base_dn: "dc=mycompany,dc=net"
     bind_dn: "cn=serviceAccaunt,dc=mycompany,dc=net"
@@ -625,23 +628,32 @@ auth_config:
       ca_cert_file: "/path/to/ca.pem"
       cert_require: DEMAND
   ldap_authentication_domain: "ldap"
+  scheme: "ldap"
+  requested_group_attribute: "memberOf"
+  extended_settings:
+      enable_nested_groups_search: true
+
   refresh_time: "1h"
   #...
 ```
 
 Параметр | Описание
 --- | ---
-`host` | Имя хоста, на котором работает LDAP сервер
+`hosts` | Список имен хостов, на котором работает LDAP сервер
 `port` | Порт для подключения к LDAP серверу
 `base_dn` | Корень поддерева в LDAP каталоге, начиная с которого будет производиться поиск записи пользователя
 `bind_dn` | Отличительное имя (Distinguished Name, DN) сервисного аккаунта, от имени которого выполняется поиск записи пользователя
 `bind_password` | Пароль сервисного аккаунта, от имени которого выполняется поиск записи пользователя
 `search_filter` | Фильтр для поиска записи пользователя в LDAP каталоге. В строке фильтра может встречаться последовательность символов *$username*, которая будет заменена на имя пользователя, запрошенное для аутентификации в базе данных
 `use_tls` | Настройки для конфигурирования TLS соединения между {{ ydb-short-name }} и LDAP сервером
-`enable` | Определяет будет ли попытка установить TLS соединение
+`enable` | Определяет, будет ли произведена попытка установить TLS-соединение с [использованием запроса `StartTls`](../../concepts/auth.md#starttls). При установке значения этого параметра в `true`, необходимо отключить использование схемы соединения `ldaps`, присвоив параметру `ldap_authentication.scheme` значение `ldap`.
 `ca_cert_file` | Путь до файла сертификата удостоверяющего центра
 `cert_require` | Уровень требований к сертификату LDAP сервера.<br/>Возможные значения:<ul><li>`NEVER` - {{ ydb-short-name }} не запрашивает сертификат или проверку проходит любой сертификат.</li><li>`ALLOW` - {{ ydb-short-name }} требует, что бы LDAP сервер предоставил сертификат. Если предоставленному сертификату нельзя доверять, TLS сессия все равно установится.</li><li>`TRY` - {{ ydb-short-name }} требует, что бы LDAP сервер предоставил сертификат. Если предоставленному сертификату нельзя доверять, установление TLS соединения прекращается.</li><li>`DEMAND` и `HARD` - Эти требования эквивалентны параметру `TRY`. По умолчанию установлено значение `DEMAND`.</li></ul>
 `ldap_authentication_domain` | Идентификатор, прикрепляемый к имени пользователя, позволяющий отличать пользователей из LDAP каталога от пользователей аутентифицируемых с помощью других провайдеров. Значение по умолчанию `ldap`
+`scheme` | Схема соединения с LDAP-сервером.<br>Возможные значения:<ul><li>`ldap` — {{ ydb-short-name }} будет выполнять соединение с LDAP-сервером без какого-либо шифрования. Пароли будут отправляться на LDAP-сервер в открытом виде. Это значение установлено по умолчанию.</li><li>`ldaps` — {{ ydb-short-name }} будет выполнять зашифрованное соединение с LDAP-сервером по протоколу TLS с самого первого запроса. Для успешного установления соединения по схеме `ldaps` необходимо отключить использование [запроса `StartTls`](../../concepts/auth.md#starttls) в секции `ldap_authentication.use_tls.enable: false` и заполнить информацию о сертификате `ldap_authentication.use_tls.ca_cert_file` и уровне требования сертификата `ldap_authentication.use_tls.cert_require`.</li><li>При использовании любого другого значения будет браться значение по умолчанию - `ldap`.</li></ul>
+`requested_group_attribute` | Атрибут обратного членства в группе. По умолчанию `memberOf`.
+`extended_settings.enable_nested_groups_search` | Флаг определяет, будет ли выполнятся запрос для получения всего дерева групп, в которые входят непосредственные группы пользователя.
+`host` | Имя хоста, на котором работает LDAP-сервер. Это устаревший параметр, вместо него должен использоваться параметр `hosts`.
 `refresh_time` | Определяет время, когда будет попытка обновить информацию о пользователе. Конкретное время обновления будет лежать в интервале от `refresh_time/2` до `refresh_time`
 
 ## Настройка стабильных имен узлов кластера {#node-broker-config}