Authentication in OpenSearch Dashboards using Keycloak

You can use Keycloak to authenticate users working with OpenSearch Dashboards in a Managed Service for OpenSearch cluster.

To set up authentication:

1. Configure an identity provider.
2. Set up SSO for the cluster.
3. Configure roles for SSO.
4. Test SSO.

Getting startedGetting started

1. Make sure you can access OpenSearch Dashboards using the admin user credentials.

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

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

2. Make sure you can use Keycloak:

   • Check that you can access Keycloak.

   • Check that you can access the realm you need.

   • Check that you have the required permissions within this realm to manage:

     • Roles.
     • Users and groups.
     • Clients (in Keycloak, these are applications used for authentication).

   This tutorial assumes that:

   • To manage Keycloak, you need a super administrator account enabling any operation in any realm.

   • All operations are performed in the master realm.

   • Keycloak is accessible at:

     http://keycloak.example.com:8080
     

   • The Keycloak admin console is accessible at:

     http://keycloak.example.com:8080/admin/
     

Configure an identity providerConfigure an identity provider

1. Connect to the Keycloak management console and select the master realm.

2. Create a client:

   1. In the left-hand panel, select Clients. Click Create client.

   2. In the Client type field, select SAML.

   3. In the Client ID field, specify the client ID.

      This ID must match the URL used to connect to OpenSearch Dashboards:

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

   4. Click Next.

   5. Specify the ACS URL in these fields:

      • Home URL
      • Valid redirect URIs
      • IDP Initiated SSO Relay State

      The ACS URL must be in the following format:

      https://c-cat0adul1fj0********.rw.mdb.yandexcloud.net/_opendistro/_security/saml/acs
      

   6. Click Save.

3. Make sure you can use the client: the relevant option in the top-right corner must be set to Enabled.

4. On the Settings tab, configure the client parameters as follows:

   • SAML Capabilities:

     • Name ID format: email.
     • Force name ID format: Make sure to enable this option.
     • Force POST binding: Make sure to enable this option.
     • Include AuthnStatement: Make sure to enable this option.

   • Signature and Encryption:

     • Sign documents: Make sure to enable this option.
     • Sign assertions: Make sure to enable this option.
     • Signature algorithm: RSA_SHA256.
     • SAML signature key name: CERT_SUBJECT.
     • Canonicalization method: EXCLUSIVE.

5. Click Save.

6. On the Keys tab, disable the requirement for client message signing.

   To do this, disable Client signature required.

7. On the Client scopes tab, configure role mapping for the client:

   1. Click URL to connect to OpenSearch Dashboards with the -dedicated suffix.

   2. On the Mappers tab, click Configure a new mapper. Select the Role list mapper from the list.

   3. Specify the following mapper settings:

      • Name: Any mapper name, e.g., OpenSearch Mapper.
      • Role attribute name: roles.
      • SAML Attribute NameFormat: Basic.
      • Single Role Attribute: Make sure to enable this option.

   4. Click Save.

Set up SSO for the clusterSet up SSO for the cluster

1. Get the metadata for the previously created client:

   1. Connect to the Keycloak management console and select the master realm.

   2. In the left-hand panel, select Clients.

   3. Click URL to connect to OpenSearch Dashboards.

   4. In the top-right corner, expand the Action menu and select Download adapter config.

   5. Select the Mod Auth Mellon Files format and click Download.

      This will download an archive.

   6. Extract the idp-metadata.xml file from the archive. This file contains all required metadata.

2. Set up SSO for the cluster.

   Tip

   Below are the steps for the management console; however you may use other available Yandex Cloud interfaces.

   To set up a Keycloak authentication source:

   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 required values for these settings:

      • idp_entity_id: Provider ID.

        For Keycloak, this ID matches the URL referring to the master realm:

        http://keycloak.example.com:8080/realms/master
        

      • idp_metadata_file: Select and upload the metadata file extracted from the archive.

      • sp_entity_id: Service provider ID.

        Use the same ID you specified when configuring the Keycloak client in the Client ID field:

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

      • kibana_url: URL to connect to OpenSearch Dashboards.

      • roles_key: Attribute that stores a list of roles.

        Specify the same attribute you configured for the Keycloak mapper: roles.

      • subject_key: Leave the field empty.

      • Enable: Make sure to enable this option.

   5. Click Save.

3. Wait for the cluster status to change to Running. It may take a few minutes to apply settings.

Configure roles for SSOConfigure roles for SSO

1. Configure Keycloak so that its users get the appropriate roles:

   1. Connect to the Keycloak management console and select the master realm.

   2. Create a role:

      1. In the left-hand panel, select Realm roles. Click Create role.

      2. In the Role name field, enter a role name.

         In the steps below, we will use kc_demo_role as the role name.

      3. Click Save.

   3. Create and configure a user:

      1. In the left-hand panel, select Users. Click Add user.

      2. Specify user credentials:

         • Username: Account name.

           In the steps below, we will use kc_demo_user as the account name.

         • Email: Email address.

           In the steps below, we will use kc_demo_user@example.com as the email address.

         • Email verified: Make sure to enable this setting.

           Note

           For the sake of simplicity, this tutorial assumes that this setting is enabled to skip email verification at first login.

      3. Click Create.

      4. In the Credentials tab, click Set password and enter a password.

         Also, disable Temporary.

         Note

         For the sake of simplicity, this tutorial assumes that this setting is disabled to avoid password change at first login.

   4. Create and configure a group:

      1. In the left-hand panel, select Groups and click Create group.

      2. Enter a group name and click Create.

         In the steps below, we will use kc_demo_group as the group name.

      3. Click the group name to open its properties.

      4. In the Members tab, click Add member, select kc_demo_user, and click Add.

      5. In the Role mapping tab, click Assign role, enable Filter by realm roles, select kc_demo_role from the role list, and click Assign.

2. Map OpenSearch cluster roles with those in Keycloak. This will enable you to access a cluster using SSO.

   To map roles:

   1. Connect to OpenSearch Dashboards as the admin user.

   2. In the left-hand menu, select OpenSearch Plugins → Security.

   3. In the left-hand panel, select Roles.

   4. Configure role mapping:

      1. Click the role name.

         The next steps assume that you select the kibana_user role.

      2. Go to the Mapped users tab.

      3. Click Manage mapping.

      4. Under Backend roles, enter the name of the Keycloak role to map with the OpenSearch role and click Map.

         The next steps assume that you select the kc_demo_role role.

Keycloak users added to kc_demo_group will now get the kc_demo_role role.

Upon successful authentication with OpenSearch Dashboards, the user with the kc_demo_role role will get the kibana_user role in OpenSearch.

Test SSOTest SSO

1. Open your browser in guest or private browsing mode.

   For this, you must use a computer with access to Keycloak.

2. Connect to OpenSearch Dashboards.

   On the login page, click Log in with single sign-on rather than entering your username and password.

   If you have set up everything correctly, the browser will redirect you to the authentication page in Keycloak.

3. Enter the kc_demo_user credentials and click Sign in.

   After successful authentication, Keycloak will redirect you to the ACS URL, and from there you will be redirected to the OpenSearch Dashboards home page.

4. Make sure the user has the kibana_user role in OpenSearch.

   To do this, click the user avatar in the top-right corner and select View roles and identities. This will show you the roles assigned to the user.

5. Make sure you can perform all actions the kibana_user role permits.