[Yandex Cloud documentation](../../../index.md) > [Yandex Identity Hub](../../index.md) > [Tutorials](../index.md) > [Setting up single sign-on (SSO) for apps](index.md) > OpenSearch

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

[OpenSearch](https://opensearch.org/) is a highly scalable open-source system of search and analysis tools. OpenSearch comes with the [OpenSearch Dashboards](https://docs.opensearch.org/latest/dashboards/) data visualization UI. 

For the users of your [organization](../../concepts/organization.md) to be able to authenticate to OpenSearch via [SAML](https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language) SSO, create a [SAML app](../../concepts/applications.md#saml) in Yandex Identity Hub and configure it both in Yandex Identity Hub and OpenSearch.

SAML apps can be managed by users with the `organization-manager.samlApplications.admin` [role](../../security/index.md#organization-manager-samlApplications-admin) or higher.

To give access to OpenSearch to the users of your organization:

1. [Create an app](#create-app).
1. [Set up the integration](#setup-integration).
1. [Make sure the application works correctly](#validate).

## Create an app {#create-app}

{% list tabs group=instructions %}

- Cloud Center UI {#cloud-center}

    1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization).
    1. In the left-hand panel, select ![shapes-4](../../../_assets/console-icons/shapes-4.svg) **Apps**.
    1. In the top-right corner, click ![Circles3Plus](../../../_assets/console-icons/circles-3-plus.svg) **Create application** and in the window that opens:
        1. Select the **SAML (Security Assertion Markup Language)** single sign-on method.
        1. In the **Name** field, specify a name for your new app: `opensearch-app`.

        1. Optionally, in the **Description** field, enter a description for the new app.
        1. Optionally, add [labels](../../../resource-manager/concepts/labels.md):

            1. Click **Add label**.
            1. Add a label in `key: value` format.
            1. Press **Enter**.
        1. Click **Create application**.

{% endlist %}

## Set up the integration {#setup-integration}

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

1. Get the metadata for the [new app](#create-app):

    1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization).
    1. In the left-hand panel, select ![shapes-4](../../../_assets/console-icons/shapes-4.svg) **Apps** and select the new SAML app.
    1. On the **Overview** tab, under **Identity provider (IdP) configuration**, copy the `Issuer / IdP EntityID` value you have to set on the OpenSearch cluster side.
    1. On the **Overview** tab, under **Identity provider (IdP) configuration**, click **Download metadata file**.

      The downloaded [XML](https://en.wikipedia.org/wiki/XML) file contains the required metadata and a certificate used for SAML response signature verification.

1. Set up SAML authentication for your OpenSearch cluster.

    To do this, edit the`config.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/`. 
   
    1. Make sure the OpenSearch user, usually `opensearch`, has read access to this file.
   
        ```bash
        sudo chown opensearch:opensearch /etc/opensearch/opensearch-security/saml/idp-metadata.xml
   
        sudo chmod 644 /etc/opensearch/opensearch-security/saml/idp-metadata.xml
        ```

    1. Generate an `exchange_key` to sign **JSON web tokens (JWTs)**. 

        {% note 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.

        {% endnote %}

    1. 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.

        ```yaml
        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:one or two
           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" 
         
        # ... 
        ```
        {% note 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`.
    
        ```yaml
        # ... 

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

        # ... 
        ```
      
        {% endnote %}

    1. 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](../../concepts/groups.md) from Yandex Identity Hub to the `backend_roles` section of the relevant OpenSearch roles, as shown below.

        ```yaml
        # ...
 
        # 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 Yandex Identity Hub 
          description: "Allow full access for opensearch-users group from Yandex Identity Hub"
  
        # ... 
        ```

        {% note tip %}

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

        {% endnote %}
        
        {% cut "Mapping roles through the OpenSearch Dashboards web UI" %}
        
        1. Log in to OpenSearch Dashboards using the `admin` credentials.
        1. In the left-hand menu, navigate to **Management** → **Security**.
        1. In the left-hand panel, select **Roles**.
        1. Configure role mapping:
            1. Click the name of the role you need, e.g., `all_access`.
            1. Go to the **Mapped users** tab.
            1. Click **Manage mapping**.
            1. In the **Backend roles** field, specify the Yandex Identity Hub [user group](../../concepts/groups.md) to map with the OpenSearch role, e.g., `opensearch-users`.
            1. Click **Map**.

        {% endcut %}

    1. 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.
   
        ```bash
        # 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
        ```

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

        ```yaml
        # ...

        # 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]

        # ... 
        ```

    1. Restart the OpenSearch services.
   
        ```bash
        sudo systemctl restart opensearch
        sudo systemctl restart opensearch-dashboards
        ```

### Set up the SAML application in Yandex Identity Hub {#setup-idp}

#### Set up service provider endpoints {#sp-endpoints}

{% list tabs group=instructions %}

- Cloud Center UI {#cloud-center}

  1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization).
  1. In the left-hand panel, click ![shapes-4](../../../_assets/console-icons/shapes-4.svg) **Apps** and select your SAML app.
  1. At the top right, click ![pencil](../../../_assets/console-icons/pencil.svg) **Edit** and in the window that opens:  
      1. In the **SP EntityID ** field, specify `opensearch-saml-sso`.
      1. In the **ACS URL** field, enter this address: `https://<your-dashboards-url>/_opendistro/_security/saml/acs`.
      1. Click **Save**.

{% endlist %}

#### Add a user groups attribute {#group-attribute}

To set up automatic user-to-role mapping upon OpenSearch login, add the user group attribute. Follow these steps:

{% list tabs group=instructions %}

- Cloud Center UI {#cloud-center}

    1. In the top-right corner, click ![circles-3-plus](../../../_assets/console-icons/circles-3-plus.svg) **Add group attribute** and in the window that opens.
    1. In the **Attribute name** field, leave `groups`.
    1. In the **Transmitted groups** field, select `Assigned groups only`.
    1. Click **Add**.

{% endlist %}

For more information about configuring attributes, see [Configure user and group attributes](../../operations/applications/saml-create.md#setup-attributes).

### Add users {#add-users}

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

{% note info %}

Users and groups added to a SAML application can be managed by a user with the `organization-manager.samlApplications.userAdmin` [role](../../security/index.md#organization-manager-samlApplications-userAdmin) or higher.

{% endnote %}

1. Once you set up role mapping in OpenSearch, [create](../../operations/create-group.md) the relevant [groups](../../concepts/groups.md):

    {% list tabs group=instructions %}

    - Cloud Center UI {#cloud-center}

        1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization).
        1. In the left-hand panel, select ![groups](../../../_assets/console-icons/persons.svg) **Groups**.
        1. In the top-right corner of the page, click ![Circles3Plus](../../../_assets/console-icons/circles-3-plus.svg) **Create group**.
        1. Enter the group name, e.g., `opensearch-users`. Make sure it matches the group name mapped to the role in OpenSearch.
        1. Click **Create group**.
        1. Add users to the group:
            1. Navigate to the **Members** tab.  
            1. Click **Add member**.
            1. In the window that opens, select the users.
            1. Click **Save**.

    {% endlist %}

1. Add users to the application:

    {% list tabs group=instructions %}

    - Cloud Center UI {#cloud-center}

        1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization).
        1. In the left-hand panel, click ![shapes-4](../../../_assets/console-icons/shapes-4.svg) **Apps** and select your app.
        1. Navigate to the **Users and groups** tab.
        1. Click ![person-plus](../../../_assets/console-icons/person-plus.svg) **Add users**.
        1. In the window that opens, select the user or user group.
        1. Click **Add**.

    {% endlist %}

## Make sure your application works correctly {#validate}

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. Follow these steps:

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