Разбор параметров config.yml для LDAP-аутентификации в OpenSearch 2026

LDAP-аутентификация в OpenSearch Security plugin настраивается в файле config.yml. В домене ldap_authc_domain указывают LDAP-сервер, транспорт, базу поиска, фильтр пользователя и способ получения групп. После успешной проверки пароля OpenSearch получает backend roles и сопоставляет их с ролями через roles_mapping.yml.

Минимальная рабочая схема выглядит так: пользователь отправляет логин и пароль через OpenSearch Dashboards или REST API, Security plugin ищет учетную запись в LDAP, проверяет пароль через bind пользователя, извлекает группы и назначает права OpenSearch. LDAP отвечает за проверку личности, а роли OpenSearch определяют разрешенные действия.

Названия и поведение отдельных параметров зависят от версии OpenSearch и OpenSearch Security plugin. Перед изменением рабочей конфигурации проверьте установленную версию, сохраните резервную копию и сверьте структуру YAML с документацией для конкретного релиза.

Как настроить LDAP-аутентификацию в OpenSearch

Минимальная схема работы OpenSearch с LDAP

Запрос к OpenSearch Dashboards или REST API попадает в HTTP-аутентификатор Security plugin. Для Basic Authentication обычно используется домен с типом basic. Домен передает учетные данные в LDAP backend.

1. OpenSearch принимает логин и пароль.
2. LDAP backend подключается к одному из серверов каталога.
3. Сервисная учетная запись выполняет поиск пользователя, если каталог запрещает анонимный поиск.
4. OpenSearch формирует DN найденной записи и проверяет пароль через bind пользователя.
5. LDAP backend получает группы пользователя.
6. Security plugin сопоставляет группы с ролями OpenSearch.

Ошибка на первых четырех шагах обычно дает отказ в аутентификации. Успешный вход с ответом HTTP 403 указывает на проблему авторизации: группа не найдена, роль не сопоставлена или у роли нет разрешения на нужный индекс.

Какие файлы участвуют в настройке

• config.yml хранит настройки доменов аутентификации и LDAP backend.
• roles_mapping.yml связывает LDAP-группы, указанные в backend_roles, с ролями OpenSearch.
• internal_users.yml содержит локальных пользователей Security plugin. Аварийную локальную учетную запись полезно сохранить до проверки LDAP.
• opensearch_dashboards.yml задает параметры подключения OpenSearch Dashboards к кластеру и не заменяет LDAP-конфигурацию Security plugin.

LDAP-подключение и порядок authc-доменов задаются в config.yml. Права LDAP-пользователей обычно настраиваются отдельно через roles_mapping.yml.

Пример блока ldap_authc_domain в config.yml

authc:
  ldap_authc_domain:
    http_enabled: true
    order: 1
    http_authenticator:
      type: basic
      challenge: false
    authentication_backend:
      type: ldap
      config:
        enable_ssl: true
        enable_start_tls: false
        hosts:
          - ldap.example.internal:636
        userbase: ou=people,dc=example,dc=org
        usersearch: '(uid={0})'
        username_attribute: uid
        bind_dn: uid=opensearch-bind,ou=service,dc=example,dc=org
        bind_password: '${LDAP_BIND_PASSWORD}'
        rolesearch: '(member={0})'
        userrolename: memberOf
        pemtrustedcas_content: |
          -----BEGIN CERTIFICATE-----
          REPLACE_WITH_CA_CERTIFICATE
          -----END CERTIFICATE-----

Этот фрагмент служит шаблоном. Значения ldap.example.internal, DN, фильтры, атрибуты, пароль и сертификат нужно заменить под конкретную схему каталога. Переменная ${LDAP_BIND_PASSWORD} не гарантирует автоматическую подстановку секрета во всех способах загрузки Security plugin, поэтому способ хранения пароля нужно проверить для вашей версии и окружения.

Структура authentication_backend

authc содержит домены аутентификации. ldap_authc_domain является произвольным именем блока. Параметр order задает приоритет домена при наличии нескольких способов входа.

http_authenticator определяет способ передачи учетных данных. Тип basic подходит для Basic Authentication в REST API и стандартных сценариев OpenSearch Dashboards. Параметр challenge управляет отправкой HTTP challenge. Его значение нужно согласовать с клиентами и другими authc-доменами.

authentication_backend связывает домен с backend типа ldap. Вложенный config содержит параметры подключения и поиска. Если LDAP-домен включен, но backend настроен с ошибкой, OpenSearch может успешно запуститься, однако вход будет завершаться отказом.

Плейсхолдеры, которые нужно заменить

• hosts и порт LDAP-сервера.
• userbase, база поиска пользователей.
• usersearch, фильтр поиска учетной записи.
• username_attribute, атрибут, соответствующий введенному логину.
• bind_dn и bind_password, учетные данные сервисного bind.
• rolesearch и userrolename, параметры поиска групп.
• pemtrustedcas_content, сертификат центра сертификации.

Сервисной учетной записи достаточно прав на чтение нужных веток LDAP. Административный DN для поиска пользователей использовать не следует.

Параметры подключения к LDAP-серверу

hosts и port

hosts содержит один или несколько адресов LDAP-серверов. В зависимости от версии конфигурация может принимать адрес с портом внутри элемента списка или отдельный параметр port. Этот синтаксис нужно сверить с версией Security plugin.

Стандартный порт LDAP без шифрования и для StartTLS, 389. Типичный порт LDAPS, 636. Доступность TCP-порта не подтверждает корректность TLS, bind или LDAP-поиска.

Для нескольких узлов проверьте DNS, маршрут и правила firewall с каждого узла OpenSearch. Отказоустойчивость зависит от того, как конкретная версия backend переключается между адресами при ошибке подключения или ответа.

enable_ssl и enable_start_tls

enable_ssl: true обычно используют для LDAPS, когда TLS устанавливается сразу после TCP-подключения, чаще всего на порту 636. При StartTLS соединение начинается как LDAP на порту 389, затем клиент отправляет команду расширения для перехода в TLS.

LDAPS и StartTLS требуют разных режимов на стороне каталога. Не включайте одновременно enable_ssl и enable_start_tls, если документация вашей версии прямо не описывает такую комбинацию. Неверный режим часто выглядит как таймаут или ошибка рукопожатия.

Для рабочей среды используйте шифрование. Незашифрованный LDAP допустим только в изолированном тестовом сценарии, когда риск передачи логина и пароля принят отдельно.

pemtrustedcas_content и проверка сертификата

pemtrustedcas_content содержит сертификат доверенного центра сертификации в формате PEM. OpenSearch использует его для проверки сертификата LDAP-сервера.

Проверьте четыре условия: имя в сертификате совпадает с адресом из hosts, сертификат не истек, цепочка до CA полная, а сервер отдает подходящий сертификат в выбранном режиме LDAPS или StartTLS.

Ошибка сертификата возникает до проверки пароля. В журналах она обычно сопровождается сообщениями о trust, handshake, hostname verification или цепочке сертификатов. Ошибка bind чаще содержит признаки invalid credentials или невозможности выполнить LDAP bind.

Таймауты и отказоустойчивость подключения

connect_timeout ограничивает время установки соединения. response_timeout ограничивает ожидание ответа каталога. Малые значения ускоряют отказ при недоступном сервере, но могут отбрасывать запросы при высокой задержке между площадками.

Для начала измерьте обычное время ответа LDAP с узла OpenSearch. Затем задайте таймаут с запасом, учитывая DNS, TLS-рукопожатие и нагрузку каталога. Параметры повторных попыток поддерживаются не во всех версиях и могут называться иначе.

Поиск пользователя в LDAP: base DN, фильтры и атрибуты

userbase: где искать учетные записи

userbase задает DN, относительно которого выполняется поиск пользователей. Для ограниченной ветки это может быть ou=people,dc=example,dc=org. Для Active Directory часто используют ветку домена, например DC=example,DC=org, если пользователи размещены в нескольких OU.

Слишком широкий base DN увеличивает число проверяемых записей и риск совпадения нескольких учетных записей. Начинайте с самой узкой ветки, которая включает всех нужных пользователей.

usersearch и плейсхолдер имени пользователя

usersearch задает LDAP-фильтр. В записи (uid={0}) значение {0} заменяется логином, введенным пользователем. Для Active Directory часто применяют (sAMAccountName={0}) или (userPrincipalName={0}).

Проверьте скобки LDAP-фильтра, регистр атрибутов, экранирование специальных символов и отсутствие лишних условий. Фильтр должен находить одну ожидаемую учетную запись. Несколько совпадений создают неоднозначное поведение.

username_attribute и формат логина

username_attribute указывает атрибут, который OpenSearch использует как имя пользователя. Типичные варианты: uid для OpenLDAP, sAMAccountName для короткого имени в Active Directory, userPrincipalName для формата user@example.org.

Выбор атрибута влияет на допустимый формат логина. Формат domain\username и формат user@domain не взаимозаменяемы: фильтр и атрибут должны соответствовать фактическому значению, которое вводит пользователь.

bind_dn и bind_password

bind_dn и bind_password задают сервисную учетную запись, от имени которой backend ищет пользователя и группы. Это отдельная read-only учетная запись с минимальными правами.

Пароль не следует хранить в открытом виде в Git, резервных копиях без защиты или командной истории. Используйте механизм секретов, доступный в вашей инфраструктуре, и ограничьте права на файл конфигурации.

Anonymous bind допустим только при явно разрешенной политике каталога. Если анонимный поиск запрещен, оставьте сервисный bind. Учетная запись администратора LDAP для этой задачи избыточна.

Для проверки структуры поиска удобно использовать шпаргалку по диагностике LDAP-аутентификации с командами проверки bind, Base DN и сетевого соединения.

Поиск LDAP-групп и сопоставление с ролями OpenSearch

rolesearch: как получить группы пользователя

rolesearch задает фильтр поиска групп. В OpenLDAP группа может хранить DN пользователя в member или uniqueMember. В Active Directory часто используют member, а членство пользователя может быть доступно через атрибут memberOf.

Прямой поиск выглядит как проверка группы по DN пользователя, например (member={0}). Обратный поиск читает атрибут членства из записи пользователя. Поддержка конкретного синтаксиса и вложенных групп зависит от версии LDAP backend.

userrolename и custom_attribute_names

userrolename указывает атрибут, из которого OpenSearch получает роли или группы пользователя. Значение memberOf подходит только тогда, когда каталог действительно заполняет этот атрибут и backend умеет его читать.

custom_attribute_names применяют для дополнительных атрибутов, которые нужно передать в контекст пользователя. Названия и формат параметра зависят от версии Security plugin. Если вход успешен, но backend roles пуст, сначала проверьте фактический ответ LDAP и соответствие схемы этим параметрам.

Типичный симптом ошибки групп: пользователь проходит проверку пароля, но получает HTTP 403. В логах и диагностическом ответе нужно найти список backend roles, а затем сопоставить его с ключами в roles_mapping.yml.

roles_mapping.yml для LDAP-групп

opensearch_dashboards_read_only:
  backend_roles:
    - 'cn=opensearch-readonly,ou=groups,dc=example,dc=org'

readall:
  backend_roles:
    - 'cn=opensearch-readonly,ou=groups,dc=example,dc=org'

В первом блоке LDAP-группа получает роль доступа к OpenSearch Dashboards. Во втором группа получает роль чтения, если такая роль настроена в вашей конфигурации. Название значения в backend_roles должно совпадать с тем, что реально возвращает LDAP backend: полным DN, коротким именем группы или другим атрибутом.

Административные роли выдавайте отдельной группе и только при необходимости. Сопоставление групп с правами на индексы описано в руководстве по RBAC через LDAP-группы.

Дополнительные параметры config.yml для стабильной авторизации

Порядок authc-доменов

Параметр order определяет приоритет authc-доменов. Если рядом с LDAP включен внутренний домен, запрос может попасть в него раньше LDAP. Проверьте порядок и поведение при неверном пароле.

Аварийную локальную учетную запись храните в internal_users.yml и проверяйте до переключения. Она нужна для восстановления доступа при недоступности LDAP или ошибке конфигурации, но ее пароль должен быть уникальным и защищенным.

Кэширование и нагрузка на каталог

Кэширование снижает число запросов к LDAP и задержку повторных входов. При этом изменения групп и отзыв доступа могут применяться с задержкой, равной времени жизни кэша.

Для административных групп выбирайте короткий период кэширования, если отзыв доступа должен действовать быстро. Любые параметры кэша сверяйте с версией Security plugin: набор ключей и их расположение могут отличаться.

Анонимный доступ и аварийные сценарии

anonymous_auth_enabled и challenge влияют на обработку запросов без учетных данных. В рабочей среде не разрешайте анонимный доступ без отдельного требования и проверки каждого открытого маршрута.

Подготовьте два сценария восстановления: вход локальной аварийной учетной записью и возврат к резервной копии конфигурации. Проверяйте их на тестовом узле до изменения production-кластера.

Как применить изменения config.yml

Проверка YAML до загрузки

Перед загрузкой проверьте отступы, кавычки, двоеточия, типы значений и вложенность authc. YAML не допускает произвольной замены пробелов табуляцией. Список hosts должен соответствовать синтаксису установленной версии.

• Сохраните резервную копию текущей конфигурации Security plugin.
• Удалите реальные пароли из примеров и Git.
• Проверьте YAML парсером, доступным в вашем окружении.
• Убедитесь, что сертификат CA записан полностью и начинается с BEGIN CERTIFICATE.
• Проверьте конфигурацию на тестовом узле или стенде.

Запуск securityadmin.sh

Изменения config.yml попадают в кластер через securityadmin.sh, если этот способ предусмотрен вашей версией и режимом развертывания. Утилита должна соответствовать версии OpenSearch, а административный сертификат должен иметь DN, разрешенный настройками Security plugin.

./securityadmin.sh \
  -cd /path/to/securityconfig \
  -f config.yml \
  -icl \
  -nhnv \
  -cacert /path/to/ca.pem \
  -cert /path/to/admin.pem \
  -key /path/to/admin-key.pem \
  -h opensearch-node.example.internal

Параметр -nhnv отключает проверку имени хоста. Для рабочей среды не используйте его без необходимости. Адрес, сертификаты и путь к каталогу замените на значения своей инфраструктуры.

Перед запуском проверьте состояние кластера и доступность узла. Неверный административный сертификат, несовместимая версия утилиты или отсутствие прав могут привести к отказу загрузки.

Проверка примененных настроек

1. Проверьте журнал opensearch.log на ошибки разбора и загрузки Security plugin.
2. Выполните тестовый вход LDAP-пользователем.
3. Проверьте полученные backend roles.
4. Откройте разрешенный раздел Dashboards или выполните запрос к тестовому индексу.
5. Проверьте, что запрещенный индекс возвращает отказ.

Если включены audit logs, используйте их для разделения событий authentication failure и authorization failure.

Диагностика ошибок LDAP-аутентификации в OpenSearch

OpenSearch не подключается к LDAP

Начинайте с узла OpenSearch. Проверьте разрешение имени, маршрут, firewall и TCP-порт:

getent hosts ldap.example.internal
nc -vz ldap.example.internal 636
openssl s_client -connect ldap.example.internal:636 -servername ldap.example.internal

Затем проверьте bind сервисной учетной записи с LDAP-клиентом, если утилита доступна в окружении. Успешное TCP-соединение подтверждает только сеть, оно не подтверждает DN, пароль и фильтр поиска.

Ошибка TLS или сертификата

Сверьте порт и режим: LDAPS обычно использует 636, StartTLS обычно начинается на 389. Проверьте CA, hostname, срок действия и промежуточные сертификаты. Ищите в opensearch.log слова handshake, trust, certificate и hostname.

Отключение проверки сертификата помогает локализовать причину только во временном тесте. Оставлять такой режим в рабочей среде нельзя, поскольку клиент перестает подтверждать подлинность LDAP-сервера.

Пользователь найден, но пароль не принимается

Разделите две операции: usersearch находит LDAP-запись, а bind пользователя проверяет пароль. Успешный поиск не доказывает, что пароль верен.

Проверьте фильтр, атрибут логина, формат имени, DN найденной записи, блокировку учетной записи и политики каталога. Для Active Directory отдельно проверьте различие между sAMAccountName и userPrincipalName.

Вход успешен, но возвращается HTTP 403

Проверьте rolesearch, userrolename, custom_attribute_names и фактический список backend roles. Затем найдите соответствующее значение в roles_mapping.yml.

Если роль назначена, проверьте ее разрешения на нужный индекс и раздел Dashboards. Ошибка доступа к конкретному индексу отличается от отсутствия базовой роли Dashboards.

Диагностический чек-лист

1. Зафиксировать версии OpenSearch и Security plugin.
2. Сделать backup конфигурации.
3. Проверить синтаксис YAML.
4. Проверить DNS, маршрут и порт LDAP.
5. Проверить TLS и CA.
6. Проверить bind сервисной учетной записи.
7. Проверить userbase и usersearch.
8. Проверить атрибут и формат логина.
9. Проверить bind пользователя с его паролем.
10. Проверить поиск групп и backend roles.
11. Проверить roles_mapping.yml и права индексов.
12. Повторить вход после очистки кэша, если он включен.

Для связанных сценариев LDAP в инфраструктуре полезны инструкции по настройке LDAP в TrueNAS SCALE и подключению групп Active Directory в других системах.

Безопасный шаблон config.yml для рабочей среды

Что заменить перед использованием

• Hostname и порт LDAP-узлов.
• Режим TLS и сертификат доверенного CA.
• userbase и usersearch.
• username_attribute и формат логина.
• bind_dn и способ передачи секрета.
• rolesearch, userrolename и имена групп.
• Значения order, таймаутов и кэша.
• DN административного сертификата для securityadmin.sh.

Параметры из примера нельзя переносить в production без проверки версии. Особенно это касается структуры LDAP backend, названий таймаутов, поиска групп и способов хранения bind-пароля.

Контрольный список перед включением LDAP

• Резервный локальный вход проверен.
• LDAP доступен с каждого узла OpenSearch.
• TLS включен, CA доверен, hostname проверяется.
• Сервисная учетная запись имеет только права чтения.
• Секрет отсутствует в Git и открытых логах.
• Тестовая учетная запись находится ожидаемым фильтром.
• LDAP-группа получает нужную роль OpenSearch.
• Лишние административные права не выдаются.
• Проверены успешный вход, отказ по паролю и HTTP 403.
• Есть план отката при недоступности LDAP.

Итоговая таблица параметров

Для размещения OpenSearch и LDAP в изолированной инфраструктуре можно использовать облачные серверы и Kubernetes-ресурсы Timeweb Cloud, если требования к сети, сертификатам и хранению секретов согласованы с политикой вашей компании.

Корректная LDAP-аутентификация в OpenSearch состоит из трех связанных частей: доступного и защищенного LDAP-соединения, точного поиска пользователя и правильного сопоставления групп с ролями. Проверяйте их отдельно. Такой порядок быстро показывает, где находится ошибка, и снижает риск потери доступа к кластеру.