Contact UsGet started

Configuring SAML authentication

Written by
Updated at November 18, 2024

Warning

Yandex Managed Service for Elasticsearch is unavailable as of April 11, 2024.

You can create an OpenSearch cluster in Yandex Cloud as an alternative to Elasticsearch.

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 Elasticsearch cluster gets information from an identity provider (IdP).

For more information about SAML and SSO, see the OASIS documentation.

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

Warning

SSO is supported by Managed Service for Elasticsearch clusters in the Platinum edition with public access enabled for all hosts with the Data node role. If you downgrade the Elasticsearch edition, the SSO feature is disabled.

To set up SAML authentication:

  1. Configure an identity provider.
  2. Set up a Managed Service for Elasticsearch 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-<Elasticsearch_cluster_ID>.rw.mdb.yandexcloud.net/api/security/saml/callback

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

    Example: https://c-e4ut2....rw.mdb.yandexcloud.net/api/security/saml/callback

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

    Use the URL with a special cluster FQDN:

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

    Example: https://c-e4ut2....rw.mdb.yandexcloud.net

  4. Specify the Name ID Format: persistent.

  5. Using the data provided by the IdP:

    • 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 Elasticsearch.

  2. Click the cluster name and open the Access control tab.

  3. Click Create.

  4. Create an authentication provider:

    • Provider type: SAML.

    • Name: Provider name.

    • Description: Provider description.

    • Hint: Login hint.

    • Icon: Provider icon.

    • Select Enabled.

    • SAML settings:

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

      • attribute_principal: Format of the nameid parameter, e.g, nameid:persistent. Same as the Name ID Format of the IdP.

      • attribute_groups: User privileges groups (recommended).

      • attribute_name: Username (optional).

      • attribute_email: User's email address (optional).

      • attribute_dn: X.500 Distinguished Name user ID (optional).

  5. Click Create.

  1. Convert the metadata file received from the Identity Provider Issuer to Base64 format.

  2. To set identity provider settings on the cluster side, use the addProviders REST API method for the Auth resource or the AuthService/AddProviders gRPC API call and provide the following in the request:

    • Cluster ID in the clusterId parameter.

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

    • SAML in the type parameter.

    • Provider name in the name parameter.

    • true in the enabled parameter.

    • Provider description in the description parameter.

    • ID of the Identity Provider Issuer obtained when configuring the IdP, in the idpEntityId parameter.

    • Path to the Base64 metadata file, in the idpMetadataFile parameter.

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

    • URL with a special cluster FQDN in the kibanaUrl parameter. Same as the spEntityId.

    • Format of the nameid parameter, e.g., nameid:persistent, in the attributePrincipal parameter. Same as the Name ID Format of the IdP.

Note

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

Configure roles for SSO

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

  1. Map the roles of the Elasticsearch 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 Elasticsearch.
  3. Grant this user access to the previously created application.

To log in to the Elasticsearch cluster using the new user's credentials, go to the Kibana page.

Examples

Enabling SAML SSO with Okta

To set up SSO with Okta for a cluster with the c9qmc1lmo2k0******** ID:

  1. Configure the Okta identity provider.
  2. Set up SSO for the Managed Service for Elasticsearch cluster.
  3. Configure roles for SSO with Okta.

Configure the Okta identity provider

  1. Create a new application:
    • Select the Applications tab.
    • Click Create App Integration.
    • Select SAML 2.0.
    • Click Next.
  2. Under General Settings, specify the application name in the App name parameter and click Next.
  3. Under SAML Settings:

    • Specify the Single sign on URL:

      https://c-c9qmc1lmo2k0********.rw.mdb.yandexcloud.net/api/security/saml/callback

    • Enable the Use this for Recipient URL and Destination URL option.

    • Specify the Audience URI (SP Entity ID):

      https://c-c9qmc1lmo2k0********.rw.mdb.yandexcloud.net

    • Specify the Name ID Format: Persistent.

    • Click Next.

  4. Under Feedback:
    • Select I'm an Okta customer adding an internal app and This is an internal app that we have created.
    • Click Finish.
  5. On the Sign On tab, click View Setup Instructions:

    • Copy the Identity Provider Issuer:

      http://www.okta.com/exkv2pzpvigX********

    • Copy the Provide the following IDP metadata to your SP provider field value and save it to a file, e.g., okta.xml.

For more information about other parameters, see the Okta documentation.

Set up SSO for the cluster

Let's assume we have this idp_entity_id provided after the IdP setup: http://www.okta.com/exkv2pzpvigX********.

Set up SSO for the cluster. When setting it up, specify:

  • idp_entity_id: http://www.okta.com/exkv2pzpvigX********.
  • idp_metadata_file: Metadata file provided by Okta.
  • sp_entity_id: https://c-c9qmc1lmo2k0********.rw.mdb.yandexcloud.net.
  • kibana_url: https://c-c9qmc1lmo2k0********.rw.mdb.yandexcloud.net.
  • attribute_principal: nameid:persistent.

Configure roles for SSO with Okta

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

  1. Configure roles for the Managed Service for Elasticsearch cluster:

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

  2. Click the cluster name and open the Kibana tab.

  3. In the authorization window, specify the admin user and the password you set when configuring the cluster.

  4. Open Management → Stack Management → Security → Role Mappings.

    Note

    The Role Mappings function is available in the Elasticsearch Platinum edition.

    Read more about updating the Elasticsearch edition.

  5. Click Create role mapping.

  6. To create a role mapping, fill in the fields:

    • Mapping name: Unique role mapping name.
    • Roles: Selected role.
    • Mapping rules: Rules for mapping roles.

    For example, to set a rule that will map users with the example.com domain and the editor role:

    1. Select the editor role.
    2. Add the All are true rule.
    3. Add the username field with the text type and the *@example.com value to the rule.
  1. Create a user on the Okta side:

    1. Open Directory → People

    2. Click Add person.

    3. Specify user parameters: First name, Last name, username, and password.

      They must meet the role mapping rules set in Managed Service for Elasticsearch.

    4. Click Save.

  2. Go to the Applications section.
  3. Click Assign User to App.
  4. Assign the application to the appropriate user.
  5. Click Next.
  6. If necessary, edit the specified username. This will be the username displayed in Kibana.
  7. Click Confirm Assignments.

To log in to the Managed Service for Elasticsearch cluster using the new user's credentials:

  1. In the management console, go to the folder page and select Managed Service for Elasticsearch.
  2. Click the cluster name and open the Kibana tab.
  3. In the authorization window, select the option that you specified when setting up SSO in the Provider description.
  4. Specify Username and Password.
Previous
Connecting to a cluster
Next
Updating cluster settings