Шаблон config.yml для LDAP-аутентификации OpenSearch в продакшене

LDAP-аутентификация OpenSearch настраивается через backend Security plugin в файле config.yml. Для production-среды нужны защищенное соединение LDAPS или StartTLS, отдельная сервисная учетная запись bind, ограниченные базы поиска пользователей и групп, а также точные LDAP-фильтры.

Ниже приведен адаптируемый шаблон для каталога с пользователями в ou=People и группами в ou=Groups. Перед применением замените все значения в угловых скобках, проверьте названия параметров для установленной версии OpenSearch Security и протестируйте LDAP-запросы отдельно от OpenSearch.

Аутентификация подтверждает личность пользователя. Авторизация назначает ему права. За поиск учетных записей и групп отвечает LDAP backend в config.yml, а за связь групп с ролями OpenSearch обычно отвечает roles_mapping.yml. Построчное объяснение параметров собрано в разборе config.yml для LDAP-аутентификации OpenSearch.

Готовый шаблон config.yml для LDAP в OpenSearch Security

Пример ниже рассчитан на LDAP-каталог с TLS на порту 636, атрибутом входа uid и группами типа groupOfNames. В Active Directory потребуется заменить атрибуты поиска, базы DN и фильтры.

authc:
  ldap:
    http_enabled: true
    transport_enabled: true
    order: 0
    http_authenticator:
      type: basic
      challenge: true
    authentication_backend:
      type: ldap
      config:
        enable_ssl: true
        enable_start_tls: false
        enable_ssl_client_auth: false
        verify_hostnames: true
        hosts:
          - <ldap.example.com>:636
          - <ldap-backup.example.com>:636
        bind_dn: <uid=opensearch-bind,ou=Service,dc=example,dc=com>
        password: <LDAP_BIND_PASSWORD>
        userbase: <ou=People,dc=example,dc=com>
        usersearch: (&(objectClass=inetOrgPerson)(uid={0}))
        username_attribute: uid
        rolebase: <ou=Groups,dc=example,dc=com>
        rolesearch: (&(objectClass=groupOfNames)(member={0}))
        userroleattribute: null
        rolename: cn
        resolve_nested_roles: false

Названия блоков в отдельных выпусках Security plugin могут отличаться. В одной версии используется authc с доменом ldap, в другой встречаются дополнительные параметры транспортной аутентификации или отдельный блок для групп. Ошибка в названии ключа может привести к игнорированию настройки или отказу при загрузке конфигурации.

Минимальный состав LDAP-конфигурации

Блок authc описывает домены аутентификации. Для LDAP-сценария нужны следующие элементы:

• order задает порядок проверки домена. Меньшее число означает более высокий приоритет.
• http_enabled включает домен для REST API OpenSearch.
• transport_enabled нужен, если домен участвует в аутентификации межузловых или транспортных запросов. Настройка зависит от способа работы кластера.
• http_authenticator задает способ передачи учетных данных. basic подходит для HTTP Basic Auth.
• challenge определяет, должен ли OpenSearch отправлять клиенту запрос на ввод учетных данных.
• authentication_backend.type со значением ldap подключает LDAP backend.
• hosts, bind_dn и password задают соединение и сервисную учетную запись.
• userbase, usersearch и username_attribute ограничивают поиск LDAP-пользователя.
• rolebase, rolesearch и rolename определяют поиск групп и имя группы, передаваемое в backend roles.

Параметры userbase и rolebase задают разные ветки каталога. Такое разделение сокращает область поиска и уменьшает риск совпадения с техническими или отключенными учетными записями.

Какие значения заменить перед применением

Пароль нельзя коммитить в открытом виде. Храните его в защищенном файле с правами, ограниченными пользователем OpenSearch, в Docker Secret, Kubernetes Secret или подключенном secret store. Возможность подстановки секрета и точный синтаксис зависят от способа установки и версии Security plugin.

Подготовка LDAP и OpenSearch перед настройкой

Сначала соберите параметры каталога и проверьте связность с каждого узла OpenSearch. Конфигурация, которая работает с одного администратора, может не работать с узла кластера из-за DNS, firewall, маршрутизации или различий в truststore.

Проверьте версию OpenSearch Security

Версию OpenSearch можно получить через доступный REST API кластера или посмотреть в пакетном менеджере, контейнерном образе и списке установленных плагинов. Для plugin-пакетов полезно зафиксировать точную версию, например opensearch-security, а не только основной номер OpenSearch.

Проверьте перед изменением:

• версию OpenSearch на всех узлах;
• версию Security plugin;
• формат текущего config.yml;
• поддержку используемых параметров LDAP;
• способ загрузки конфигурации в конкретной установке.

Не переносите шаблон между релизами без сверки схемы. Часть параметров может быть переименована, перенесена в другой блок или зависеть от выбранного authenticator.

Определите структуру пользователей и групп

Зафиксируйте в рабочей документации следующие значения:

• корневой DN, например dc=example,dc=com;
• базу пользователей, например ou=People,dc=example,dc=com;
• базу групп, например ou=Groups,dc=example,dc=com;
• атрибут входа: uid для OpenLDAP или sAMAccountName для Active Directory;
• тип групп: groupOfNames, posixGroup, group или другой objectClass;
• атрибут участника: member, uniqueMember, memberUid или memberOf;
• правила вложенных групп и их фактическую поддержку.

Для groupOfNames участник обычно хранится полным DN в атрибуте member. Для posixGroup часто используется короткое имя в memberUid. Active Directory обычно применяет объект класса group и атрибут member, а логин пользователя хранится в sAMAccountName.

Защищенное соединение OpenSearch с LDAP по TLS

В production передавайте bind-данные и LDAP-запросы по TLS. Открытый LDAP на порту 389 допустим для изолированной лаборатории, если это прямо предусмотрено архитектурой и сеть доверенная. Для рабочих учетных записей используйте LDAPS на 636 или StartTLS на 389.

LDAPS или StartTLS: что выбрать

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

Параметр verify_hostnames: true оставляйте включенным. Имя хоста в hosts должно совпадать с SAN сертификата LDAP-сервера. Подключение по IP может завершиться ошибкой проверки имени, если IP отсутствует в сертификате.

Сертификат и доверие к LDAP-серверу

OpenSearch должен доверять корневому или промежуточному CA, которым подписан сертификат LDAP-сервера. Импортируйте CA в truststore Java, который видит процесс OpenSearch, либо задайте truststore способом, предусмотренным вашей установкой.

Проверяйте цепочку с каждого узла:

openssl s_client -connect ldap.example.com:636 \
  -servername ldap.example.com \
  -showcerts 

В выводе проверьте цепочку сертификатов, срок действия, имя в SAN и итог проверки. Для StartTLS используйте режим, поддерживаемый вашей версией OpenSSL и LDAP-сервером, например:

openssl s_client -connect ldap.example.com:389 \
  -starttls ldap \
  -servername ldap.example.com

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

Bind-пользователь и хранение секрета

Bind-пользователю нужны права на чтение только тех веток, где OpenSearch ищет пользователей и группы. Ему обычно не требуется право изменять записи, создавать пользователей или просматривать весь каталог.

Создайте отдельную учетную запись, например uid=opensearch-bind,ou=Service,dc=example,dc=com. Запретите интерактивный вход, задайте отдельный срок ротации секрета и отслеживайте неудачные bind-операции.

В конфигурациях Data Prepper уже используется подход со ссылкой на secret store вместо хранения plaintext credentials. Тот же принцип применяйте к bind-паролю OpenSearch. Секрет не должен попадать в публичный Git, вывод CI/CD, Docker-образ или диагностический архив.

Ограничение поиска пользователей и групп в каталоге

Широкий поиск от корневого DN создает лишние LDAP-запросы и повышает вероятность совпадений. Используйте отдельные userbase и rolebase, задавайте objectClass и фильтр логина.

userbase и usersearch: поиск только нужных учетных записей

Для OpenLDAP пример фильтра может выглядеть так:

userbase: ou=People,dc=example,dc=com
usersearch: (&(objectClass=inetOrgPerson)(uid={0}))
username_attribute: uid

Значение {0} заменяется введенным логином. Фильтр требует одновременно подходящий objectClass и точное совпадение атрибута uid.

Для Active Directory базовая часть может выглядеть так:

userbase: OU=Users,DC=example,DC=com
usersearch: (&(objectClass=user)(sAMAccountName={0}))
username_attribute: sAMAccountName

Если доступ разрешен только членам специальной группы, добавьте ограничение с учетом схемы каталога. Фильтр должен проверяться через ldapsearch, потому что синтаксически корректный YAML не подтверждает корректность LDAP-логики.

rolebase и rolesearch: получение только нужных групп

Для групп groupOfNames, где в member хранится DN пользователя, используется пример:

rolebase: ou=Groups,dc=example,dc=com
rolesearch: (&(objectClass=groupOfNames)(member={0}))
rolename: cn
userroleattribute: null
resolve_nested_roles: false

В этом варианте {0} обычно получает DN найденного пользователя, а rolename: cn передает в backend roles короткое имя группы. Если каталог хранит полные DN в ролях, mapping должен использовать именно этот формат.

Для схемы с атрибутом пользователя memberOf часто требуется получить группы из записи пользователя:

userroleattribute: memberOf
rolename: cn

Точный вариант зависит от реализации LDAP backend. Не смешивайте rolesearch по группам и userroleattribute без проверки результата: при неверной комбинации вход пройдет, но список backend roles окажется пустым.

Вложенные группы увеличивают число запросов и зависят от возможностей каталога. Оставляйте resolve_nested_roles: false, пока не подтвердите необходимость вложенности и корректность результата на тестовой группе.

Фильтры LDAP для OpenLDAP и Active Directory

Проверка записи пользователя:

ldapsearch -H ldaps://ldap.example.com:636 \
  -D 'uid=opensearch-bind,ou=Service,dc=example,dc=com' \
  -W \
  -b 'ou=People,dc=example,dc=com' \
  '(&(objectClass=inetOrgPerson)(uid=alice))' dn uid memberOf

Проверка группы по DN пользователя:

ldapsearch -H ldaps://ldap.example.com:636 \
  -D 'uid=opensearch-bind,ou=Service,dc=example,dc=com' \
  -W \
  -b 'ou=Groups,dc=example,dc=com' \
  '(&(objectClass=groupOfNames)(member=uid=alice,ou=People,dc=example,dc=com))' cn member

Для Active Directory замените базу, bind DN, objectClass и атрибуты на значения своей схемы. Не копируйте фильтр OpenLDAP без изменений.

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

Успешный LDAP bind не выдает пользователю права автоматически. Security plugin получает группы, формирует backend_roles, а затем проверяет их в roles_mapping.yml.

Как LDAP-группа превращается в backend role

Предположим, LDAP возвращает группу ldap-opensearch-readers через атрибут cn. В mapping нужно указать ровно это имя. Несовпадение регистра, короткого имени и полного DN приводит к отсутствию роли.

Проверяйте:

• какое значение возвращает LDAP для cn;
• используется ли короткое имя или полный DN;
• совпадает ли регистр в mapping;
• не содержит ли значение лишних пробелов;
• получает ли пользователь группу через прямое или вложенное членство.

Пример roles_mapping.yml для трех групп

all_access:
  reserved: false
  backend_roles:
    - ldap-opensearch-admins

opensearch_operators:
  reserved: false
  backend_roles:
    - ldap-opensearch-operators

opensearch_readers:
  reserved: false
  backend_roles:
    - ldap-opensearch-readers

В этом примере all_access назначается только группе администраторов. Для операторов и читателей создайте отдельные роли в roles.yml с минимальным набором разрешений. Названия ролей могут отличаться от имен LDAP-групп, но mapping должен оставаться однозначным.

Практическая схема настройки ролей через группы LDAP разобрана в руководстве по ролям OpenSearch через LDAP.

Минимальные права для LDAP-пользователей в OpenSearch

Модель least privilege разделяет права на трех уровнях: cluster permissions, index permissions и tenant permissions. Каждая группа получает набор действий, необходимый для ее рабочих задач.

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

Пример роли читателя:

opensearch_readers:
  reserved: false
  cluster_permissions:
    - 'cluster_composite_ops_ro'
  index_permissions:
    - index_patterns:
        - 'logs-app-*'
      allowed_actions:
        - 'read'
  tenant_permissions:
    - tenant_patterns:
        - 'app_logs'
      allowed_actions:
        - 'kibana_all_read'

Названия действий зависят от версии и установленной модели ролей. Проверьте их в текущем Security plugin перед загрузкой.

Доступ к Dashboards и tenant permissions

Права REST API и права OpenSearch Dashboards проверяются отдельно. Пользователь может читать индекс через API, но не видеть saved objects в Dashboards. Обратная ситуация тоже возможна, если tenant permissions настроены шире index permissions.

Для каждой группы проверьте:

• вход в Dashboards;
• доступ к нужному tenant;
• чтение saved objects;
• видимость разрешенных индексов;
• отсутствие доступа к административным разделам.

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

• all_access всем пользователям LDAP;
• security_rest_api_access операторам и читателям без рабочей необходимости;
• wildcard-паттерны на все индексы;
• административные cluster permissions для групп чтения;
• запись и удаление данных там, где требуется только поиск.

Начинайте с пустого набора разрешений и добавляйте конкретные действия после проверки API. Временная выдача all_access скрывает ошибку mapping и часто остается в рабочей конфигурации.

Применение config.yml и проверка в работающем кластере

Порядок действий снижает риск потери доступа и рассинхронизации узлов. Меняйте конфигурацию через штатный инструмент Security plugin, а не ручным редактированием файлов на одном сервере.

Резервная копия и план отката

Перед изменением сохраните:

• текущие config.yml, roles.yml и roles_mapping.yml;
• версию OpenSearch и Security plugin;
• имена узлов и целевой cluster name;
• рабочий admin-сертификат;
• проверенный способ возврата прежней конфигурации.

Проверьте локальный admin-доступ до начала работ. Ошибка в authentication domain или mapping может заблокировать вход всех пользователей, включая LDAP-администраторов.

Проверка YAML и LDAP-запросов до применения

Сначала проверьте отступы, вложенность и обязательные ключи YAML-парсером, доступным в вашей среде. Затем отдельно проверьте DNS, TCP-порт, TLS handshake, bind и поиск пользователя через ldapsearch.

Диагностический порядок:

1. Разрешить имя LDAP-сервера с каждого узла OpenSearch.
2. Проверить доступность порта 636 или 389.
3. Проверить цепочку сертификата и имя в SAN.
4. Выполнить bind сервисной учетной записью.
5. Найти тестового пользователя фильтром из usersearch.
6. Найти его группы фильтром из rolesearch.
7. Сверить полученное имя группы с roles_mapping.yml.

Применение через securityadmin.sh

securityadmin.sh загружает конфигурацию Security plugin в кластер. Для запуска требуется admin-сертификат с допустимым DN, сетевой доступ к REST или transport endpoint согласно настройкам и совместимость версии инструмента с кластером.

Общий порядок выглядит так:

./securityadmin.sh \
  -cd /path/to/securityconfig \
  -icl \
  -nhnv \
  -cacert /path/to/ca.pem \
  -cert /path/to/admin.pem \
  -key /path/to/admin-key.pem

Параметр -nhnv отключает проверку имени узла в клиенте securityadmin. Не переносите его автоматически в production-процедуру: требования зависят от сертификатов и версии инструмента. При включенной проверке hostname используйте корректные DNS-имена и сертификаты.

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

Функциональная проверка после изменений

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

• администратор входит и выполняет только согласованные административные операции;
• оператор читает и изменяет назначенные ресурсы, но не управляет security-настройками;
• читатель читает logs-app-* и получает отказ при обращении к закрытому индексу;
• пользователь видит разрешенный tenant в Dashboards;
• пользователь без LDAP-группы не получает рабочую роль.

Фиксируйте коды ответа. Успешный вход дает 200 или другой ожидаемый положительный ответ для разрешенного действия, а запрещенный запрос должен завершаться 403.

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

LDAP-сервер недоступен или не проходит TLS

Проверяйте проблему с узла OpenSearch, а не с рабочей станции администратора. Сравните DNS-ответы, маршрут и правила firewall. Затем проверьте сертификат, срок действия, SAN и доверенный CA.

В логах ищите сообщения со словами SSLHandshakeException, PKIX path building failed, Connection refused и timeout. Каждое сообщение указывает на отдельный уровень сбоя: truststore, порт или сеть.

Пользователь найден, но вход завершается ошибкой

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

Если сервисный bind работает, а пользовательский bind завершается Invalid Credentials, проверяйте пароль, блокировку учетной записи, срок действия и ограничения политики каталога.

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

HTTP 403 означает отказ в доступе к уже понятому сервером запросу. Для LDAP-сценария чаще всего отсутствует корректное сопоставление группы с ролью.

Проверьте в таком порядке:

1. Возвращается ли группа из LDAP.
2. Совпадает ли формат имени группы с mapping.
3. Загружен ли актуальный roles_mapping.yml.
4. Содержит ли роль нужные index permissions.
5. Разрешен ли нужный tenant в Dashboards.

Не устраняйте 403 временной выдачей all_access. Сначала зафиксируйте фактическую backend role и конкретное запрещенное действие.

Группы пользователя не определяются

Сопоставьте схему группы с фильтром. При groupOfNames ищите DN пользователя в member, при posixGroup проверяйте memberUid. В Active Directory убедитесь, что фильтр учитывает group, а имя пользователя и DN не перепутаны.

Если применяются вложенные группы, проверьте настройку resolve_nested_roles, поведение контроллера и ограничения на рекурсивный поиск. Сначала добейтесь корректного результата для прямого членства.

Production-чеклист OpenSearch LDAP-конфигурации

Что проверить перед публикацией и внедрением

• Версии OpenSearch и Security plugin зафиксированы.
• Все плейсхолдеры заменены реальными значениями.
• Выбран LDAPS или StartTLS, открытый LDAP не используется без обоснования.
• Сертификат LDAP-сервера действителен, его SAN совпадает с DNS-именем.
• CA импортирован в truststore нужного процесса.
• Bind-пользователь имеет права только на чтение нужных веток.
• Пароль не хранится в публичном Git и логах.
• userbase и rolebase ограничены конкретными OU.
• usersearch и rolesearch проверены через ldapsearch.
• Группы администраторов, операторов и читателей разделены.
• Wildcard-права и безусловный all_access исключены.
• Подготовлены резервная копия, admin-сертификат и план отката.

Минимальный набор проверок после внедрения

1. Успешный вход пользователя из каждой разрешенной группы.
2. Отказ при неверном пароле.
3. Отказ пользователя без разрешенной группы.
4. Чтение разрешенного индекса.
5. 403 при обращении к закрытому индексу.
6. Проверка записи и изменения данных для операторов.
7. Проверка входа в Dashboards и доступа к нужному tenant.
8. Проверка backend roles в логах или доступном диагностическом механизме.
9. Отсутствие TLS ошибок и массовых поисковых запросов в LDAP.
10. Проверка ротации bind-пароля по подготовленной процедуре.

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

Рабочая production-конфигурация LDAP для OpenSearch строится вокруг четырех проверок: защищен ли канал, ограничены ли базы поиска, корректно ли группы превращаются в backend roles и не выданы ли пользователям лишние разрешения.

После проверки конфигурации зафиксируйте версии, значения DN, фильтры, mapping и тестовые результаты в базе знаний команды. Это сокращает время восстановления при смене сертификатов, контроллера LDAP или узла OpenSearch.