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

# Creating a SAML app in Yandex Identity Hub for integration with Managed Service for 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. [Yandex Managed Service for OpenSearch](../../../managed-opensearch/index.md) is an OpenSearch cluster management service for the Yandex Cloud infrastructure. Managed Service for OpenSearch supports SAML authentication for secure single sign-on for users across your organization.

For the users of your [organization](../../concepts/organization.md) to be able to authenticate to Managed Service for 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 the OpenSearch cluster.

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

## Getting started {#before-you-begin}

Make sure you can [access OpenSearch Dashboards](../../../managed-opensearch/operations/connect/clients.md#dashboards) using the `admin` user credentials. For information on how to create and configure an OpenSearch cluster, see [Creating an OpenSearch cluster](../../../managed-opensearch/operations/cluster-create.md).

In this tutorial, we will use the following URL to access the OpenSearch Dashboards web interface:

```url
https://c-cat0adul1fj0********.rw.mdb.yandexcloud.net/
```

To give access to Managed Service for OpenSearch to the users of your organization:

1. [Create the 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 Managed Service for 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 SSO for the OpenSearch cluster.

    {% note tip %}

    Below are the steps for the management console; however you may [use other available Yandex Cloud](../../../managed-opensearch/operations/saml-authentication.md#configuration-sso) interfaces.

    {% endnote %}

    To set up a Yandex Identity Hub authentication source:

    1. In the [management console](https://console.yandex.cloud), select a folder.
    1. Navigate to **Managed Service for OpenSearch**.
    1. Click the name of your cluster and select the **Authentication sources** tab.
    1. Click **Settings**.
    1. Specify the required values for these settings:

        * **idp_entity_id**: Provider ID. Enter the previously saved `Issuer / IdP EntityID` value.

        * **idp_metadata_file**: Select and upload the previously downloaded metadata file.

        * **sp_entity_id**: Service provider ID.
        
            This ID must match the URL used to connect to OpenSearch Dashboards:

            ```url
            https://c-cat0adul1fj0********.rw.mdb.yandexcloud.net/
            ```

        * **kibana_url**: URL to connect to OpenSearch Dashboards.

        * **roles_key**: Attribute that stores a list of roles. Set it to `groups`.

        * **subject_key**: Leave this field empty.

        * **Session timeout**: Leave the `0` value.

        * **Enable**: Make sure to enable this option.

    1. Click **Save**. Wait for the cluster status to change to `Running`. It may take a few minutes to apply the settings.

1. Configure role mapping in OpenSearch.

    To ensure that Yandex Identity Hub user groups are mapped to OpenSearch roles during authentication:

    1. Connect to OpenSearch Dashboards as `admin`.
    1. In the left-hand menu, select **OpenSearch Plugins** → **Security**.
    1. In the left-hand panel, select **Roles**.
    1. Configure role mapping:
        1. Click the role name. In this guide, it is `kibana_user`.
        1. Go to the **Mapped users** tab.
        1. Click **Manage mapping**.
        1. Under **Backend roles**, enter the name of the Yandex Identity Hub [user group](../../concepts/groups.md) a role will be mapped to in OpenSearch, e.g., `opensearch-users`.
        1. Click **Map**.
    
    Now your organization's users added to the `opensearch-users` group will be getting the `kibana_user` role upon successful authentication in 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, select ![shapes-4](../../../_assets/console-icons/shapes-4.svg) **Apps** and then, the 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, enter the URL for connection to OpenSearch Dashboards.
      1. In the **ACS URL** field, specify the ACS URL.

        The ACS URL has the following format:

        ```url
        https://c-cat0adul1fj0********.rw.mdb.yandexcloud.net/_opendistro/_security/saml/acs
        ```
      1. Click **Save**.

{% endlist %}

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

OpenSearch users have to get one of the basic roles upon login. For this to work, the Yandex Identity Hub authentication source must provide in its SAML response a list of user groups that will have roles mapped in OpenSearch. 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 user groups to the SAML 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. If you have configured role mapping in Managed Service for OpenSearch, [create](../../operations/create-group.md) the groups as needed:

    {% 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 a name, e.g., `opensearch-users`. The group name must exactly match the user group name specified when mapping to the OpenSearch role.
        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 required 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, select ![shapes-4](../../../_assets/console-icons/shapes-4.svg) **Apps** and select the required 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 required user or user group.
        1. Click **Add**.

    {% endlist %}

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

To make sure both your SAML app and Managed Service for OpenSearch integration 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 `kibana_user` role and the **Backend roles** section displays the `opensearch-users` role.