Introduce LDAP description as a separate section in docs.

docs/auth_ldap.md

+# Механизм аутентификации на базе LDAP
+В данном разделе приведены сведения об аутентификации в Picodata с
+помощью протокола LDAP.
+
+## Общие сведения {: #intro }
+
+[Lightweight Directory Access
+Protocol](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol){:target="_blank"}
+(далее LDAP) — это легковесный протокол для доступа к службе каталогов
+[X.500](https://en.wikipedia.org/wiki/X.500){:target="_blank"}, которая
+часто используется организациями для контроля доступа к ресурсам и
+управления доменными учетными записями. Существует множество серверов,
+которые поддерживают данный протокол: OpenLDAP, GLAuth и прочие.
+
+Типичный сеанс связи с LDAP-сервером выглядит примерно так: клиент
+подключается к серверу, отправляет запрос, дожидается ответа сервера и
+закрывает соединение. На основании ответа сервера клиент может принять
+решение об авторизации пользователя, инициировавшего подключение.
+
+В качестве запроса в Picodata используется `BIND`, позволяющий
+произвести аутентификацию пользователя с использованием заранее
+известного Distinguished Name (DN) и факторов аутентификации (например,
+пароля).
+
+<!-- Запрос `SEARCH` позволит узнавать неизвестные данные, такие как `DN`.
+Есть и другие типы запросов, которые позволяют осуществлять
+администрирование учетных записей, то есть создание, редактирование,
+удаление и т.д. -->
+
+Для использования протокола LDAP в Picodata следует указать одноименный
+метод аутентификации (`{ auth_type = 'ldap' })`). Примеры см. [ниже](#user-setup).
+
+## Особенности работы LDAP {: #ldap-concepts }
+
+* Коммуникация с LDAP-сервером происходит один раз при установке новой
+  пользовательской сессии. Если аутентификация пройдена успешно, сессия
+  будет установлена, и до самого ее конца повторная аутентификация
+  производиться не будет.
+* **Метод отвечает только за аутентификацию.** Группы, права и владение
+  объектами и т.д. не синхронизируются с удаленным сервером LDAP.
+* Метод требует дополнительной настройки кластера через переменные среды
+  UNIX.
+* Метод невозможно использовать в случае отказа удаленного сервера LDAP.
+* Метод не кеширует результаты аутентификации.
+
+## Настройка {: #setup }
+
+### Настройка LDAP на уровне пользователей  {: #user-setup }
+
+Как и другие методы аутентификации, LDAP можно указать при создании
+нового пользователя через параметр `auth_type`:
+
+```lua
+-- Поле пароля оставлено пустым
+pico.create_user('username', '', { auth_type = 'ldap' })
+```
+
+Помимо этого, можно сменить метод аутентификации уже существующего
+пользователя:
+
+```lua
+-- Поле пароля оставлено пустым
+pico.change_password('username', '', {auth_type = 'ldap'})
+```
+
+Обратите внимание, что при использовании метода LDAP **не требуется**
+указывать пароль пользователя. Это связано с тем, что Picodata не хранит
+пароли: при каждой попытке аутентификации клиент будет отправлять пароль
+в сообщении `IPROTO_AUTH`; в свою очередь Picodata будет использовать
+полученный пароль при взаимодействии с сервером LDAP.
+
+Подробнее о работе с пользователями и привилегиями и см. разделе
+[Публичный API Picodata](../api).
+
+### Настройка кластера Picodata {: #cluster-setup }
+
+Для корректной работы метода нужно установить следующие переменные среды
+UNIX:
+
+* `TT_LDAP_URL` — URL, указывающий на удаленный сервер LDAP, например:
+  `ldap://localhost:1389`.
+* `TT_LDAP_DN_FMT` — произвольная формат-строка DN для запроса `BIND`.
+  Пример: `cn=$USER,ou=users,dc=example,dc=org`. Вместо `$USER` будет
+  подставлено фактическое имя пользователя Picodata (производится только
+  для первого упоминания `$USER`).
+
+В текущей реализации строка форматирования DN общая для всех
+пользователей. Кроме того, нет возможности установить персональный DN
+для конкретного пользователя. В качестве параметра можно использовать
+только имена пользователей.
+
+Переменные среды не кешируются — их можно менять во время эксплуатации
+кластера; в этом случае для новых попыток аутентификации будут
+использоваться актуальные значения параметров.
+
+### Устранение неполадок {: #troubleshooting }
+
+В отличие от других методов аутентификации, LDAP требует дополнительной
+настройки, без которой аутентификация с использованием этого метода
+будет невозможна. Также важно понимать, что любые проблемы с удаленным
+LDAP-сервером немедленно отразятся на возможности аутентифицировать
+пользователей. Для решения этой проблемы администраторам предлагается
+временно изменить метод аутентификации (например, на `'chap-sha1'`) для
+затронутых пользователей при помощи функции смены пароля:
+
+```lua
+pico.change_password('username', 'new_password', { auth_type = 'chap-sha1' })
+```
+
+---
+[Исходный код страницы](https://git.picodata.io/picodata/picodata/docs/-/blob/main/docs/auth_ldap.md)
+

docs/index.md

@@ -33,6 +33,7 @@ Picodata — распределенная система
 ### Архитектурная документация {: #arch-docs }
 * [Схема инициализации кластера](clustering)
 * [Принципы работы распределенного SQL](sql/review)
+* [Механизм аутентификации на базе LDAP](auth_ldap)
 
 
 На данном портале представлена техническая документация программного

mkdocs.yml

@@ -26,6 +26,7 @@ nav:
     - clustering.md
     - discovery.md
     - sql/review.md
+    - auth_ldap.md