Contact UsTry it for free
© 2026 Direct Cursus Technology L.L.C.

Creating a SAML app in Yandex Identity Hub for integration with OpenSearch

Written by
Updated at January 13, 2026

Note

This feature is at the Preview stage.

OpenSearch is a highly scalable open-source system of search and analysis tools. OpenSearch comes with the OpenSearch Dashboards data visualization UI.

To authenticate your organization's users to OpenSearch via SAML SSO, create a SAML app in Identity Hub and configure it appropriately both in Identity Hub and in OpenSearch.

SAML apps can be managed by users with the organization-manager.samlApplications.admin role or higher.

For the users of your organization to be able to access OpenSearch:

  1. Create an app.
  2. Set up the integration.
  3. Make sure the application works correctly.

Create an app

  1. Log in to Yandex Identity Hub.
  2. In the left-hand panel, select Apps.
  3. In the top-right corner, click Create application and in the window that opens:

    1. Select the SAML (Security Assertion Markup Language) single sign-on method.

    2. In the Name field, specify a name for your new app: opensearch-app.

    3. Optionally, in the Description field, enter a description for the new app.

    4. Optionally, add labels:

      1. Click Add label.
      2. Enter a label in key: value format.
      3. Press Enter.

    5. Click Create application.

Set up the integration

To configure OpenSearch integration with the SAML app you created in Identity Hub, complete the configuration both on the OpenSearch cluster side and in Identity Hub.

  1. Get the metadata for the new app:

    1. Log in to Yandex Identity Hub.
    2. In the left-hand panel, select Apps and select the new SAML app.
    3. On the Overview tab, under Identity provider (IdP) configuration, copy the Issuer / IdP EntityID value you have to set on the OpenSearch cluster side.
    4. On the Overview tab, under Identity provider (IdP) configuration, click Download metadata file.

    The downloaded XML file contains the required metadata and a certificate used for SAML response signature verification.

  2. Set up SAML authentication for your OpenSearch cluster.

    To do this, edit theconfig.yml and roles_mapping.yml configuration files for OpenSearch Security Plugin in the default /etc/opensearch/opensearch-security/ directory, and the opensearch_dashboards.yml file for OpenSearch Dashboards in the default /etc/opensearch-dashboards/ directory.

    1. Place the previously downloaded idp-metadata.xml file in the OpenSearch Security Plugin directory, e.g., /etc/opensearch/opensearch-security/saml/.

    2. Make sure the OpenSearch user, usually opensearch, has read access to this file.

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

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

    3. Generate an exchange_key to sign JSON web tokens (JWTs).

      Tip

      The JWT key must be a string generated with the HMAC256 algorithm. You can use online generators or command-line tools that produce cryptographically secure strings with support for this algorithm.

    4. Add a new SAML authentication domain named yandex_saml_auth_domain to the authc section of the config.yml file and configure it as shown below.

      authc:
 # ... (keep the current basic_internal_auth for the service user) ...

 # SAML authentication domain for Yandex Identity Hub
 yandex_saml_auth_domain:
   order: 1 # What we recommend: 1 or 2
   http_enabled: true
   transport_enabled: false
   http_authenticator:
     type: saml
     challenge: true
     config:
       # --- IdP settings (Yandex Identity Hub) ---
       idp:
         # Path to the uploaded XML metadata file 
         metadata_file: "/etc/opensearch/opensearch-security/saml/idp-metadata.xml"

       # --- SP settings (OpenSearch) ---
       sp:
         # This parameter must match the SP EntityID specified in Yandex Identity Hub
         entity_id: "opensearch-saml-sso" 

       # Your Dashboards URL
       kibana_url: "https://<your-dashboards-url>/"
  
       # Key to sign JWTs
       exchange_key: "5efe29a39306bed6bd4f67af06d54d813ff8b05692ef480204c917602ffdd9a9"

       # --- Configuring access groups ---
       # Name of the SAML response attribute containing groups
       roles_key: "groups" 
 
# ...

      Tip

      In the latest OpenSearch Security Plugin versions, you can use the metadata_url parameter to load the metadata file directly from Yandex Identity Hub. If your version supports it, you do not need to upload the metadata file to the server. To set it up, simply replace metadata_file with metadata_url in config.yml.

      # ... 

# --- IdP settings (Yandex Identity Hub) ---
idp:
  # XML metadata file URL 
  metadata_url: "https://auth.yandex.cloud/saml/metadata/ek0vbjom..." 

# ...

    5. To map Yandex Identity Hub user groups to internal OpenSearch roles during SAML authentication, edit the roles_mapping.yml file for OpenSearch Security Plugin. Add the required groups from Identity Hub to the backend_roles section of the relevant OpenSearch roles, as shown below.

      # ...

# The opensearch-users group from Yandex Identity Hub 
# maps to the all_access role in OpenSearch
all_access:
  reserved: false
  backend_roles:
    - "admin"
    - "opensearch-users" # group created in Identity Hub 
  description: "Allow full access for opensearch-users group from Identity Hub"

# ...

      Tip

      You can alternatively map roles through the OpenSearch Dashboards web UI.

      Mapping roles through the OpenSearch Dashboards web UI
      1. Log in to OpenSearch Dashboards using the admin credentials.
      2. In the left-hand menu, navigate to Management → Security.
      3. In the left-hand panel, select Roles.
      4. Configure role mapping:
        1. Click the name of the role you need, e.g., all_access.
        2. Go to the Mapped users tab.
        3. Click Manage mapping.
        4. In the Backend roles field, specify the Identity Hub user group to map with the OpenSearch role, e.g., opensearch-users.
        5. Click Map.

    6. After making changes to the config.yml and roles_mapping.yml files, apply the new configuration to your OpenSearch cluster by running the securityadmin.sh script.

      # Make sure to provide the correct paths to the certificates and keys
# and run securityadmin.sh with administrator privileges.

sudo "/usr/share/opensearch/plugins/opensearch-security/tools/securityadmin.sh" \
    -cd "/etc/opensearch/opensearch-security" \
    -icl \
    -key "<path_to_your_key>" \
    -cert "<path_to_your_certificate>" \
    -cacert "<path_to_root_CA_certificate>" \
    -nhnv

    7. Edit the opensearch_dashboards.yml configuration file for OpenSearchDashboards as follows:

      # ...

# Enable multi-factor authentication
opensearch_security.auth.multiple_auth_enabled: true

# Provide the available authentication types
# (keep basic authentication for the service user)
opensearch_security.auth.type: [basicauth, saml]

# ...

    8. Restart the OpenSearch services.

      sudo systemctl restart opensearch
sudo systemctl restart opensearch-dashboards

Set up the SAML application in Yandex Identity Hub

Set up service provider endpoints

  1. Log in to Yandex Identity Hub.
  2. In the left-hand panel, click Apps and select your SAML app.
  3. At the top right, click Edit and in the window that opens:
    1. In the **SP EntityID ** field, specify opensearch-saml-sso.
    2. In the ACS URL field, enter this address: https://<your-dashboards-url>/_opendistro/_security/saml/acs.
    3. Click Save.

Add a user groups attribute

To set up automatic user-to-role mapping upon OpenSearch login, add the user group attribute. Proceed as follows:

  1. In the top-right corner, click Add group attribute and in the window that opens.
  2. In the Attribute name field, leave groups.
  3. In the Transmitted groups field, select Assigned groups only.
  4. Click Add.

For more information about configuring attributes, see Configure user and group attributes.

Add users

For your organization's users to be able to authenticate in OpenSearch Dashboards with the Identity Hub SAML app, you need to explicitly add these users and groups to that app.

Note

Users and groups added to a SAML application can be managed by a user with the organization-manager.samlApplications.userAdmin role or higher.

  1. Once you set up role mapping in OpenSearch, create the relevant groups:

    1. Log in to Yandex Identity Hub.
    2. In the left-hand panel, select Groups.
    3. In the top-right corner of the page, click Create group.
    4. Enter the group name, e.g., opensearch-users. Make sure it matches the group name mapped to the role in OpenSearch.
    5. Click Create group.
    6. Add users to the group:
      1. Navigate to the Members tab.
      2. Click Add member.
      3. In the window that opens, select the users.
      4. Click Save.

  2. Add users to the application:

    1. Log in to Yandex Identity Hub.
    2. In the left-hand panel, click Apps and select your app.
    3. Navigate to the Users and groups tab.
    4. Click Add users.
    5. In the window that opens, select the user or user group.
    6. Click Add.

Make sure your application works correctly

To make sure both your SAML app and its integration with OpenSearch work correctly, authenticate to OpenSearch Dashboards as one of the users you added to the app. Proceed as follows:

  1. In your browser, navigate to the address of your OpenSearch Dashboards instance.
  2. If logged in to OpenSearch Dashboards, log out.
  3. On the OpenSearch Dashboards authentication page, click Log in with single sign-on.
  4. On the Yandex Cloud authentication page, enter your email address and user password. The user must be a member of a group added to the app.
  5. Make sure you are logged in to OpenSearch Dashboards.
  6. If you have configured role mapping:
    1. Click the user icon in OpenSearch Dashboards.
    2. Go to View roles and identities.
    3. Make sure the Roles section displays the all_access role and the Backend roles section displays the opensearch-users role.
Previous
Managed Service for OpenSearch
Next
Managed Service for GitLab