Создать SAML-приложение в Yandex Identity Hub для интеграции с OpenSearch

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

Чтобы пользователи вашей организации могли аутентифицироваться в OpenSearch с помощью технологии единого входа по стандарту SAML, создайте SAML-приложение в Identity Hub, настройте его на стороне Identity Hub и на стороне OpenSearch.

Управлять SAML-приложениями может пользователь, которому назначена роль organization-manager.samlApplications.admin или выше.

Чтобы дать доступ пользователям вашей организации в OpenSearch:

1. Создайте приложение.
2. Настройте интеграцию.
3. Убедитесь в корректной работе приложения.

Создайте приложениеСоздайте приложение

Настройте интеграциюНастройте интеграцию

Чтобы настроить интеграцию OpenSearch с созданным SAML-приложением в Identity Hub, выполните настройки на стороне кластера OpenSearch и на стороне Identity Hub.

1. Получите метаданные для созданного ранее приложения:

   1. Войдите в сервис Yandex Identity Hub.
   2. На панели слева выберите Приложения и выберите созданное ранее SAML-приложение.
   3. На вкладке Обзор в блоке Конфигурация поставщика удостоверений (IdP) скопируйте значение параметра Issuer / IdP EntityID, которое необходимо задать на стороне кластера OpenSearch.
   4. На вкладке Обзор в блоке Конфигурация поставщика удостоверений (IdP) нажмите кнопку Скачать файл с метаданными.

   Скачанный XML-файл содержит необходимые метаданные и сертификат, который используется для проверки подписи SAML-ответов.

2. Настройте SAML-аутентификацию для кластера OpenSearch.

   Настройка производится путём изменения конфигурационных файлов config.yml и roles_mapping.yml плагина OpenSearch Security Plugin, по умолчанию находящихся в каталоге /etc/opensearch/opensearch-security/, а также файла OpenSearch Dashboards opensearch_dashboards.yml, по умолчанию расположенного в каталоге /etc/opensearch-dashboards/.

   1. Поместите ранее загруженный файл метаданных idp-metadata.xml в каталог плагина OpenSearch Security Plugin (например, /etc/opensearch/opensearch-security/saml/).

   2. Убедитесь, что пользователь OpenSearch (обычно opensearch) имеет права на чтение этого файла.

      sudo chown opensearch:opensearch /etc/opensearch/opensearch-security/saml/idp-metadata.xml
      
      sudo chmod 644 /etc/opensearch/opensearch-security/saml/idp-metadata.xml
      

   3. Сгенерируйте ключ exchange_key для подписи токенов JSON Web Tokens (JWT).

      Совет

      Ключ JSON Web Tokens (JWT) должен представлять собой строку, сгенерированную с использованием алгоритма HMAC256. Вы можете использовать онлайн‑генераторы или утилиты командной строки, создающие криптографически надёжные строки с поддержкой данного алгоритма.

   4. Добавьте новый домен аутентификации SAML yandex_saml_auth_domain в секции authc файла config.yml и укажите параметры как показано ниже.

      authc:
       # ... (оставьте существующий basic_internal_auth для служебного пользователя) ...
      
       # Домен аутентификации SAML для Yandex Identity Hub
       yandex_saml_auth_domain:
         order: 1 # Рекомендуется: 1 или 2
         http_enabled: true
         transport_enabled: false
         http_authenticator:
           type: saml
           challenge: true
           config:
             # --- Настройки IdP (Yandex Identity Hub) ---
             idp:
               # Путь к загруженному XML-файлу метаданных 
               metadata_file: "/etc/opensearch/opensearch-security/saml/idp-metadata.xml"
      
             # --- Настройки SP (OpenSearch) ---
             sp:
               # Параметр должен совпадать с SP EntityID, который указан в Yandex Identity Hub
               entity_id: "opensearch-saml-sso" 
      
             # URL-адрес вашего Dashboards
             kibana_url: "https://<your-dashboards-url>/"
        
             # Ключ для подписи токенов JWT
             exchange_key: "5efe29a39306bed6bd4f67af06d54d813ff8b05692ef480204c917602ffdd9a9"
      
             # --- Настройка групп доступа ---
             # Имя атрибута в SAML-ответе, содержащего группы
             roles_key: "groups" 
       
      # ... 
      

      Совет

      В современных версиях плагина OpenSearch Security Plugin добавлен параметр metadata_url, позволяющий напрямую загружать файл метаданных из Yandex Identity Hub. Если ваша версия поддерживает этот параметр, вам не потребуется загружать и размещать файл метаданных на сервер. Для настройки достаточно заменить параметр metadata_file в конфигурационном файле config.yml на параметр metadata_url.

      # ... 
      
      # --- Настройки IdP (Yandex Identity Hub) ---
      idp:
        # URL XML-файла метаданных 
        metadata_url: "https://auth.yandex.cloud/saml/metadata/ek0vbjom..." 
      
      # ... 
      

   5. Чтобы сопоставить группы пользователей Yandex Identity Hub с внутренними ролями OpenSearch при SAML-аутентификации, отредактируйте файл roles_mapping.yml плагина OpenSearch Security Plugin. Добавьте требуемые группы из Identity Hub в секцию backend_roles соответствующих ролей в OpenSearch, как показано ниже.

      # ...
      
      # Группа "opensearch-users" из Yandex Identity Hub 
      # сопоставляется с ролью "all_access" в OpenSearch
      all_access:
        reserved: false
        backend_roles:
          - "admin"
          - "opensearch-users" # группа созданная в Identity Hub 
        description: "Allow full access for opensearch-users group from Identity Hub"
      
      # ... 
      

      Совет

      В качестве альтернативного варианта сопоставления ролей можно использовать веб‑интерфейс OpenSearch Dashboards.

      Сопоставление ролей через веб‑интерфейс OpenSearch Dashboards

      1. Войдите в OpenSearch Dashboards под учётной записью admin.
      2. В левом боковом меню перейдите в раздел: Management → Security.
      3. В левой панели выберите пункт Roles.
      4. Настройте сопоставления ролей:
         1. Кликните на название необходимой роли (например, all_access).
         2. Перейдите на вкладку Mapped users.
         3. Нажмите кнопку Manage mapping.
         4. В поле Backend roles укажите группу пользователей Identity Hub, которую требуется сопоставить с ролью OpenSearch, например opensearch-users.
         5. Нажмите кнопку Map.

   6. После изменений в файлах config.yml и roles_mapping.yml необходимо загрузить новую конфигурацию в кластер вашего OpenSearch. Для этого используйте скрипт securityadmin.sh.

      # Убедитесь, что вы используете правильные пути к сертификатам и ключам
      # и что securityadmin.sh запущен с правами администратора.
      
      sudo "/usr/share/opensearch/plugins/opensearch-security/tools/securityadmin.sh" \
          -cd "/etc/opensearch/opensearch-security" \
          -icl \
          -key "<путь_к_вашему_ключу>" \
          -cert "<путь_к_вашему_сертификату>" \
          -cacert "<путь_к_корневому_сертификату_CA>" \
          -nhnv
      

   7. Внесите изменения в конфигурационный файл OpenSearch Dashboards opensearch_dashboards.yml следующим образом:

      # ...
      
      # Включите множественную аутентификацию
      opensearch_security.auth.multiple_auth_enabled: true
      
      # Укажите доступные типы аутентификации
      # (оставьте basic для служебного пользователя)
      opensearch_security.auth.type: [basicauth, saml]
      
      # ... 
      

   8. Перезапустите сервисы OpenSearch.

      sudo systemctl restart opensearch
      sudo systemctl restart opensearch-dashboards
      

Настройте SAML-приложение на стороне Yandex Identity HubНастройте SAML-приложение на стороне Yandex Identity Hub

Настройте эндпоинты поставщика услугНастройте эндпоинты поставщика услуг

Добавьте атрибут групп пользователейДобавьте атрибут групп пользователей

Чтобы настроить механизм автоматической привязки пользователей к соответствующим ролям при входе в систему OpenSearch, добавьте атрибут группы пользователей. Для этого:

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

Добавьте пользователейДобавьте пользователей

Чтобы пользователи вашей организации могли аутентифицироваться в OpenSearch Dashboards с помощью SAML‑приложения Identity Hub, необходимо явно добавить в это приложение пользователей и группы.

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

   Интерфейс Cloud Center

   1. Войдите в сервис Yandex Identity Hub.
   2. На панели слева выберите Группы.
   3. В правом верхнем углу страницы нажмите Создать группу.
   4. Задайте название группы (например, opensearch-users). Оно должно полностью совпадать с именем группы, указанным при сопоставлении с ролью в OpenSearch.
   5. Нажмите Создать группу.
   6. Добавьте пользователей в группу:
      1. Перейдите на вкладку Участники.
      2. Нажмите Добавить участника.
      3. В открывшемся окне выберите необходимых пользователей.
      4. Нажмите Сохранить.

2. Добавьте пользователей в приложение:

   Интерфейс Cloud Center

   1. Войдите в сервис Yandex Identity Hub.
   2. На панели слева выберите Приложения и выберите необходимое приложение.
   3. Перейдите на вкладку Пользователи и группы.
   4. Нажмите Добавить пользователей.
   5. В открывшемся окне выберите требуемого пользователя или группу пользователей.
   6. Нажмите Добавить.

Убедитесь в корректной работе приложенияУбедитесь в корректной работе приложения

Чтобы проверить корректность работы SAML‑приложения и его интеграцию с OpenSearch, выполните аутентификацию в OpenSearch Dashboards под учётной записью одного из пользователей, добавленных в приложение. Для этого:

1. В браузере перейдите по адресу вашего экземпляра OpenSearch Dashboards.
2. Если вы были авторизованы в OpenSearch Dashboards, выйдите из профиля.
3. На странице аутентификации OpenSearch Dashboards нажмите Log in with single sign-on.
4. На странице аутентификации Yandex Cloud укажите адрес электронной почты и пароль пользователя. Пользователь должен состоять в группе, добавленной в приложение.
5. Убедитесь, что вы авторизовались в OpenSearch Dashboards.
6. Если вы настроили сопоставление ролей, то:
   1. Нажмите на иконку пользователя в OpenSearch Dashboards.
   2. Перейдите в View roles and identities.
   3. Убедитесь, что в блоке Roles отображается роль all_access, а в блоке Backend roles — opensearch-users.