LDAP-аутентификация в OpenSearch через Active Directory: настройка config.yml

LDAP-аутентификация связывает OpenSearch Security с Active Directory и переносит проверку учетных данных в доменный каталог. Пользователь вводит логин и пароль, OpenSearch ищет учетную запись по LDAP-фильтру, проверяет пароль через bind, получает группы AD и передает их как backend roles. Файл config.yml отвечает за аутентификацию и поиск групп, а roles_mapping.yml связывает группы с ролями OpenSearch.

Ниже приведен рабочий шаблон для типовой структуры AD. В нем используются отдельная сервисная учетная запись, поиск пользователей по sAMAccountName, поиск групп по атрибуту member и защищенное соединение LDAPS. Имена OU, домен, порт, параметры TLS и отдельные ключи нужно сверить с синтаксисом версии OpenSearch Security, установленной в вашем кластере.

authc:
  ldap:
    http_enabled: true
    transport_enabled: false
    order: 1
    http_authenticator:
      type: basic
      challenge: true
    authentication_backend:
      type: ldap
      config:
        enable_ssl: true
        enable_start_tls: false
        verify_hostnames: true
        hosts:
          - ad01.example.com:636
        bind_dn: 'CN=svc-opensearch,OU=Service Accounts,DC=example,DC=com'
        password: '${LDAP_BIND_PASSWORD}'
        userbase: 'OU=Users,DC=example,DC=com'
        usersearch: '(sAMAccountName={0})'

authz:
  ldap:
    http_enabled: true
    transport_enabled: false
    authorization_backend:
      type: ldap
      config:
        enable_ssl: true
        enable_start_tls: false
        verify_hostnames: true
        hosts:
          - ad01.example.com:636
        bind_dn: 'CN=svc-opensearch,OU=Service Accounts,DC=example,DC=com'
        password: '${LDAP_BIND_PASSWORD}'
        rolebase: 'OU=Groups,DC=example,DC=com'
        rolesearch: '(member={0})'

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

Рабочая схема OpenSearch Active Directory в config.yml

Что нужно подготовить до настройки LDAP в OpenSearch

Соберите параметры каталога до изменения файлов OpenSearch Security. Ошибка в одном DN или недоступный порт приведут к сбою еще до проверки пароля пользователя.

• DNS-имя или IP-адрес контроллера домена, например ad01.example.com.
• LDAP URL и порт: обычно LDAP использует 389, а LDAPS 636.
• Base DN домена, например DC=example,DC=com.
• DN сервисной учетной записи, например CN=svc-opensearch,OU=Service Accounts,DC=example,DC=com.
• Пароль сервисной учетной записи или способ безопасной передачи секрета.
• OU пользователей и OU групп, где OpenSearch будет выполнять поиск.
• Тестовый пользователь с известным форматом логина.
• Тестовая группа AD, членом которой состоит этот пользователь.

Проверьте разрешение DNS, маршрут до контроллера домена и доступность порта. Для LDAPS отдельно проверьте сертификат, имя узла в SAN и доверие к центру сертификации в Java truststore OpenSearch.

Перед настройкой сверьте формат config.yml с документацией OpenSearch Security для своей версии. Это особенно важно при переходе между крупными релизами, где менялись схемы конфигурации и способы применения security-файлов. Построчный разбор параметров можно использовать как дополнительную шпаргалку: разбор config.yml для LDAP-аутентификации в OpenSearch.

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

Процесс состоит из трех отдельных этапов:

1. Аутентификация. Блок authc ищет пользователя в AD и проверяет введенный пароль.
2. Авторизация. Блок authz получает группы пользователя через LDAP-поиск.
3. Назначение ролей. OpenSearch сравнивает полученные backend roles с записями в roles_mapping.yml.

Успешный bind к Active Directory подтверждает учетные данные, но не выдает доступ к индексам. Если группа не найдена или ее DN не совпадает с маппингом, пользователь пройдет проверку пароля и получит отказ в доступе.

Настройка bind DN и подключения OpenSearch к Active Directory

Как выбрать сервисную учетную запись и bind DN

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

Используйте отдельную учетную запись, например:

CN=svc-opensearch,OU=Service Accounts,DC=example,DC=com

Не назначайте этой учетной записи права Domain Admin. Запретите интерактивный вход, если это допускает политика безопасности, задайте контролируемую ротацию пароля и храните секрет вне Git-репозитория. Открытая строка password в YAML удобна для лаборатории, но создает риск утечки в рабочей среде.

LDAP или LDAPS: как подключаться к контроллеру домена

Для рабочего кластера выбирайте LDAPS или StartTLS, если этот режим поддерживает ваша версия OpenSearch Security и инфраструктура AD. Пароль пользователя и учетные данные bind DN не должны передаваться по незашифрованному соединению.

Проверьте четыре условия:

• сертификат контроллера домена содержит DNS-имя, указанное в hosts;
• сертификат не просрочен;
• цепочка CA доверена JVM, которая запускает OpenSearch;
• DNS-имя разрешается с каждого узла кластера.

Отключение проверки сертификата не исправляет проблему TLS. Оно лишь скрывает ошибку и оставляет учетные данные под угрозой перехвата.

OpenSearch LDAP фильтр пользователей: UPN, sAMAccountName и cn

Фильтр пользователя должен соответствовать значению, которое вводит человек в форме OpenSearch Dashboards. В AD чаще всего используют короткий логин sAMAccountName или полный логин userPrincipalName.

Поиск по sAMAccountName для входа с коротким логином

Если пользователь вводит ivanov, используйте фильтр:

userbase: 'OU=Users,DC=example,DC=com'
usersearch: '(sAMAccountName={0})'

Плейсхолдер {0} заменяется введенным логином. Значение sAMAccountName обычно короткое и не содержит домен, например ivanov. Ограничьте userbase конкретной OU, если в каталоге есть несколько доменов, лесов или объектов с похожими именами.

Поиск по UPN для входа в формате user@domain

Для входа с адресом ivanov@example.com применяйте фильтр по атрибуту userPrincipalName:

userbase: 'OU=Users,DC=example,DC=com'
usersearch: '(userPrincipalName={0})'

UPN-суффикс может отличаться от DNS-имени домена. Например, контроллеры могут находиться в домене corp.example.com, а пользователи входить с суффиксом example.com. Не формируйте UPN по названию хоста контроллера. Получите реальные значения из AD через ldapsearch, ldp.exe или командлеты Active Directory PowerShell.

Почему cn не стоит использовать как основной логин

cn, или common name, описывает имя объекта в каталоге. Оно может содержать пробелы, изменяться после переименования пользователя и не гарантирует уникальность во всей области поиска.

Поиск по cn допустим в нестандартной схеме, где это поле строго контролируется и уникально. Для корпоративного входа обычно предсказуемее использовать sAMAccountName или userPrincipalName.

Если вход по короткому логину работает, а по UPN нет, проверьте формат значения в форме и фильтр usersearch. Если ситуация обратная, проверьте UPN-суффикс, область поиска и наличие атрибута у конкретной учетной записи.

Поиск групп Active Directory для авторизации OpenSearch

Пример rolesearch для групп AD с атрибутом member

В распространенной схеме AD группа хранит Distinguished Name пользователя в атрибуте member. Тогда поиск группы строится по DN найденного пользователя:

rolebase: 'OU=Groups,DC=example,DC=com'
rolesearch: '(member={0})'

Значение {0} здесь должно быть DN пользователя, например CN=Иванов Иван,OU=Users,DC=example,DC=com. В результате OpenSearch получает DN группы, например CN=OpenSearch-ReadOnly,OU=Groups,DC=example,DC=com.

В некоторых схемах применяют атрибут memberOf, groupOfNames или другой вариант поиска. Плейсхолдеры и поддерживаемые ключи зависят от версии LDAP backend. Проверяйте их по документации релиза и тестируйте на одной группе.

Как проверить DN пользователя и DN группы до изменения config.yml

Сначала подтвердите структуру каталога отдельным LDAP-инструментом. Например, поиск пользователя через ldapsearch может выглядеть так:

ldapsearch -H ldaps://ad01.example.com:636 \
  -D 'CN=svc-opensearch,OU=Service Accounts,DC=example,DC=com' \
  -W \
  -b 'OU=Users,DC=example,DC=com' \
  '(sAMAccountName=ivanov)' \
  distinguishedName userPrincipalName memberOf

Проверьте, что запрос возвращает ровно одну учетную запись, ее distinguishedName соответствует ожидаемой OU, а атрибуты групп заполнены.

В доменной среде аналогичную проверку можно выполнить через PowerShell:

Get-ADUser -Identity ivanov -Properties DistinguishedName,UserPrincipalName,MemberOf
Get-ADGroup -Identity 'OpenSearch-ReadOnly' -Properties DistinguishedName,Member

Сервисная учетная запись должна видеть объекты и атрибуты, которые участвуют в поиске. Ошибка в OU или CN при ручном копировании встречается чаще, чем проблема с самим OpenSearch.

Вложенные группы и ограничения типовой LDAP-схемы

Фильтр (member={0}) обычно проверяет прямое членство пользователя. Если пользователь входит в группу A, а группа A включена в группу B, простой поиск может не вернуть группу B.

Поддержка вложенных групп зависит от возможностей AD, выбранного LDAP-фильтра и версии OpenSearch Security. Сначала проверьте прямое членство на тестовой группе. Вложенность добавляйте отдельным изменением и подтверждайте фактические backend roles в журналах.

Связь групп AD с ролями OpenSearch через roles_mapping.yml

Пример маппинга backend_roles на группу Active Directory

Полученный DN группы нужно точно сопоставить с ролью OpenSearch:

opensearch_read_only:
  reserved: false
  hidden: false
  cluster_permissions:
    - 'cluster_composite_ops_ro'
  index_permissions:
    - index_patterns:
        - 'logs-*'
      allowed_actions:
        - 'read'

opensearch_read_only:
  backend_roles:
    - 'CN=OpenSearch-ReadOnly,OU=Groups,DC=example,DC=com'

В реальном roles_mapping.yml структура записи зависит от версии и стандартных шаблонов OpenSearch Security. Смысл остается одинаковым: значение в backend_roles должно полностью совпасть с DN, который возвращает rolesearch. Сравнивайте регистр, пробелы, OU и все компоненты DC.

Роль opensearch_read_only нужно определить отдельно в roles.yml или через поддерживаемый API управления безопасностью. Один маппинг без разрешений роли не дает доступа к индексам.

Как выдать минимально необходимые права на индексы и OpenSearch Dashboards

Создайте отдельные группы AD для чтения, записи и администрирования. Например:

• OpenSearch-ReadOnly получает чтение индексов logs-*;
• OpenSearch-ReadWrite получает чтение и запись в разрешенные индексы;
• OpenSearch-Admins получает административные полномочия по утвержденной политике.

Ограничивайте index_patterns конкретными шаблонами. Отдельно проверьте права OpenSearch Dashboards и tenant permissions, если включена multi-tenancy. Доступ к интерфейсу и доступ к данным проходят через разные разрешения.

Модель RBAC через LDAP-группы для Linux, TrueNAS и Kubernetes разобрана в отдельном руководстве: группы безопасности через LDAP и RBAC.

Применение конфигурации и проверка LDAP-аутентификации OpenSearch

Проверка сценария входа тестовым пользователем

Перед изменением сохраните резервные копии config.yml, roles.yml и roles_mapping.yml. Оставьте локальную учетную запись администратора или другой аварийный способ доступа, чтобы ошибка LDAP не заблокировала управление кластером.

1. Примените security-конфигурацию способом, который поддерживает ваша версия OpenSearch Security.
2. Выполните вход тестовым пользователем через выбранный формат, например ivanov или ivanov@example.com.
3. Проверьте успешную проверку пароля.
4. Убедитесь, что OpenSearch получил ожидаемый DN группы как backend role.
5. Проверьте доступ к разрешенному индексу.
6. Проверьте отказ при обращении к индексу, который не входит в разрешенные шаблоны.

Для быстрой сверки базового конфига пригодится материал с минимальной LDAP-схемой и отдельным production-вариантом: минимальный config.yml для LDAP-аутентификации OpenSearch.

Какие журналы OpenSearch смотреть при ошибке

Ищите сообщения в журналах OpenSearch и OpenSearch Security. Диагностируйте цепочку по порядку:

• ошибки DNS или подключения к порту указывают на сеть, маршрут или имя узла;
• TLS handshake error обычно связан с CA, SAN, сроком сертификата или truststore;
• ошибка bind указывает на неверный DN сервисной учетной записи, пароль или отсутствие соединения;
• нулевой результат usersearch указывает на неверный userbase, атрибут или формат логина;
• invalid credentials после найденной записи указывает на пароль пользователя или ограничения AD;
• пустой список групп указывает на ошибку rolebase, rolesearch, атрибута member или прав чтения;
• ошибка 403 после успешного входа указывает на несовпадение backend role с roles_mapping.yml или недостаточные разрешения роли.

Не включайте избыточное debug-логирование в рабочей среде надолго. Журналы могут раскрыть DN, структуру каталога и диагностические данные, которые относятся к учетным записям.

Типовые ошибки LDAP-аутентификации в OpenSearch и их устранение

Пользователь не найден: Base DN, OU и LDAP-фильтр

Проверьте, что userbase указывает на ветку, где реально находится пользователь. Поиск в DC=example,DC=com даст широкий результат, но усложнит диагностику и повысит нагрузку на каталог. Для рабочей схемы задавайте конкретную OU, если структура AD это позволяет.

Проверьте специальные символы в DN: запятые, обратные слеши, апострофы и национальные символы требуют аккуратного экранирования. Сначала получите фактический DN через LDAP-инструмент, затем перенесите его в YAML без ручного сокращения.

Пользователь аутентифицирован, но доступ запрещен

Не меняйте рабочий usersearch, пока не проверите авторизацию. Сравните фактический DN группы, возвращенной AD, со строкой в backend_roles. Для Active Directory роль чаще получает полный DN, а не короткое имя группы.

Проверьте прямое членство тестового пользователя, наличие группы в результате rolesearch и разрешения самой роли OpenSearch. Учетная запись может успешно пройти LDAP-проверку и получить 403 из-за отсутствия индексных или tenant permissions.

Ошибки LDAPS и сертификатов

При ошибке TLS проверьте DNS, порт 636, срок действия сертификата, цепочку CA и совпадение имени узла с SAN. Для нескольких контроллеров домена повторите проверку с каждого узла OpenSearch, потому что локальное хранилище сертификатов может отличаться.

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

Чек-лист перед вводом LDAP-интеграции в рабочую среду

• Проверена версия OpenSearch Security и синтаксис config.yml.
• DNS и сетевой доступ к контроллеру домена проверены с каждого узла.
• Используется LDAPS или согласованный вариант StartTLS.
• CA-сертификат добавлен в доверенное хранилище JVM.
• Сервисная учетная запись имеет минимальные права чтения.
• Пароль bind DN не хранится открытым текстом в репозитории.
• userbase и usersearch проверены через LDAP-инструмент.
• rolebase и rolesearch возвращают ожидаемую группу.
• DN тестовой группы полностью совпадает с записью в roles_mapping.yml.
• Есть тестовый пользователь с проверенным паролем.
• Сохранен локальный администратор или аварийный путь доступа.
• Проверены разрешения на разрешенные и запрещенные индексы.
• Журналы просмотрены после применения изменений.

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

Ключевая проверка выглядит так: OpenSearch находит пользователя по выбранному атрибуту, проверяет пароль, получает DN группы и сопоставляет его с backend role. Если каждый этап подтвержден отдельно, причина ошибки обычно локализуется за несколько проверок.