Contact UsGet started

Configuring SAML authentication

Written by
Updated at April 9, 2025

Security Assertion Markup Language (SAML) is used for exchanging authentication and authorization data between two parties. With SAML, you can implement a single sign-on system (SSO) to switch between applications without re-authentication.

When using SAML and SSO, a Managed Service for OpenSearch cluster gets information from an identity provider (IdP). For more information about SAML and SSO, see the OASIS documentation.

Managed Service for OpenSearch works with any SAML 2.0 compatible identity provider.

To set up SAML authentication:

  1. Configure an identity provider.
  2. Set up a Managed Service for OpenSearch cluster to use this IdP for SSO.
  3. Configure cluster roles for SSO users on the IdP side.

Configure an identity provider

  1. Create an application on the IdP side.

  2. Specify the Assertion Consumer Service (ACS) URL.

    Use the URL with a special cluster FQDN:

    https://c-<OpenSearch_cluster_ID>.rw.mdb.yandexcloud.net/_opendistro/_security/saml/acs

    You can request the cluster ID with the list of clusters in the folder.

    URL example: https://c-e4ut2....rw.mdb.yandexcloud.net/_opendistro/_security/saml/acs

  3. Specify the SP Entity ID (Audience URI).

    Use the URL with a special cluster FQDN:

    https://c-<cluster_ID>rw.mdb.yandexcloud.net/

    URL example: https://c-e4ut2....rw.mdb.yandexcloud.net/

  4. Specify the Name ID Format:

  5. Get the data you need to set up SAML SSO on OpenSearch side:

    • Copy the information about the Identity Provider Issuer.
    • Save the provider's metadata file in XML format.

    You will need it to set up SSO for your cluster.

Set up SSO for the cluster

Warning

Incorrect settings may cause the cluster to fail.

  1. In the management console, go to the folder page and select Managed Service for OpenSearch.

  2. Click the cluster name and open the Authentication sources tab.

  3. Click Settings.

  4. Specify the parameters of external authentication source:

    • idp_entity_id: Information about the Identity Provider Issuer obtained when configuring the IdP.

    • idp_metadata_file: Provider's metadata file in XML format obtained when configuring the IdP.

    • sp_entity_id: Application-defined SP Entity ID (Audience URI). Make sure it is the same as the ID specified when configuring the IdP.

    • kibana_url: URL with a special cluster FQDN, same as the sp_entity_id.

    • roles_key: Name of the SAML response parameter that stores the roles. The SAML response comes from the identity provider. Skipping this parameter disables the use of roles.

    • subject_key: Name of the SAML response parameter that stores the subject. The SAML response comes from the identity provider. If it is not set, the NameID parameter is used.

    • Session timeout: Session lifetime in minutes. Specify if not set by the identity provider.

      If there is no value or 0, the session lifetime is unlimited (default).

    • Enable: Shows whether to activate an authentication source after creating it.

  5. Click Save.

  1. Get an IAM token for API authentication and put it into the environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Use the Cluster.UpdateAuthSettings method and send the following request, e.g., via cURL:

    curl \
    --request PUT \
    --header "Authorization: Bearer $IAM_TOKEN" \
    --header "Content-Type: application/json" \
    --url 'https://mdb.api.cloud.yandex.net/managed-opensearch/v1/clusters/<cluster_ID>/auth' \
    --data '{
                "settings": {
                    "saml": {
                        "enabled": "<enable_SSO:_true_or_false>",
                        "idpEntityId": "<IdP_issuer_ID>",
                        "idpMetadataFile": "<metadata_file>",
                        "spEntityId": "<SP_Entity_ID_app_URI>",
                        "dashboardsUrl": "<Dashboards_host_URL>",
                        "rolesKey": "<parameter_with_roles_in_SAML_response>",
                        "subjectKey": "<parameter_with_topic_in_SAML_response>",
                        "jwtDefaultExpirationTimeout": "<session_lifetime>"
                    }
                }
            }'

    Where settings is a set of SSO settings. Contains the saml section with the following parameters:

    • enabled: Enable SSO.

    • idpEntityId: ID of the Identity Provider Issuer obtained when configuring the IdP.

    • idpMetadataFile: Path to the Base64 metadata file.

    • spEntityId: URI of the SP Entity ID (Audience URI) application. Use the URI you specified when configuring the IdP.

    • dashboardsUrl: URL of the host with the DASHBOARDS role.

    • rolesKey: Name of the SAML response parameter that stores the roles. The SAML response comes from the identity provider. Skipping this parameter disables the use of roles.

    • subjectKey: Name of the SAML response parameter that stores the subject. The SAML response comes from the identity provider. If it is not set, the NameID parameter is used.

    • jwtDefaultExpirationTimeout: Session lifetime in minutes. Specify if not set by the identity provider.

      If there is no value or 0, the session lifetime is unlimited (default).

    You can request the cluster ID with the list of clusters in the folder.

  3. View the server response to make sure the request was successful.

  1. Get an IAM token for API authentication and put it into the environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Clone the cloudapi repository:

    cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi

    Below, we assume the repository contents are stored in the ~/cloudapi/ directory.

  3. Use the ClusterService.UpdateAuthSettings call and send a request, e.g., via gRPCurl:

    grpcurl \
  -format json \
  -import-path ~/cloudapi/ \
  -import-path ~/cloudapi/third_party/googleapis/ \
  -proto ~/cloudapi/yandex/cloud/mdb/opensearch/v1/cluster_service.proto \
  -rpc-header "Authorization: Bearer $IAM_TOKEN" \
  -d '{
        "settings": {
            "saml": {
                "enabled": "<enable_SSO:_true_or_false>",
                "idp_entity_id": "<IdP_issuer_ID>",
                "idp_metadata_file": "<metadata_file>",
                "sp_entity_id": "<SP_Entity_ID_app_URI>",
                "dashboards_url": "<Dashboards_host_URL>",
                "roles_key": "<parameter_with_roles_in_SAML_response>",
                "subject_key": "<parameter_with_topic_in_SAML_response>",
                "jwt_default_expiration_timeout": "<session_lifetime>"
            }
        }
    }' \
mdb.api.cloud.yandex.net:443 \
yandex.cloud.mdb.opensearch.v1.ClusterService.UpdateAuthSettings

    Where settings is a set of SSO settings. Contains the saml section with the following parameters:

    • enabled: Enable SSO.

    • idp_entity_id: ID of the Identity Provider Issuer obtained when configuring the IdP.

    • idp_metadata_file: Path to the Base64 metadata file.

    • sp_entity_id: URI of the SP Entity ID (Audience URI) application. Use the URI you specified when configuring the IdP.

    • dashboards_url: URL of the host with the DASHBOARDS role.

    • roles_key: Name of the SAML response parameter that stores the roles. The SAML response comes from the identity provider. Skipping this parameter disables the use of roles.

    • subject_key: Name of the SAML response parameter that stores the subject. The SAML response comes from the identity provider. If it is not set, the NameID parameter is used.

    • jwt_default_expiration_timeout: Session lifetime in minutes. Specify if not set by the identity provider.

      If there is no value or 0, the session lifetime is unlimited (default).

    You can request the cluster ID with the list of clusters in the folder.

  4. View the server response to make sure the request was successful.

Note

For more information about SAML attributes, see the OpenSearch documentation.

Configure roles for SSO

To access the cluster via SSO, associate the cluster roles with the SSO users on the IdP side:

  1. Map the roles of the OpenSearch users on the IdP side to the roles in the cluster. Perform this operation as an admin user in one of the following ways:
  2. On the IdP side, create a user that meets the role mappings defined in OpenSearch.
  3. Grant this user access to the previously created application.

To log in to OpenSearch using the new user's credentials, go to the OpenSearch Dashboards page.

Examples of integration with providers

Authentication in OpenSearch Dashboards using Keycloak.

Previous
Connecting to a cluster
Next
Updating cluster settings