Authenticating a Yandex Managed Service for OpenSearch cluster in OpenSearch Dashboards using Keycloak
You can use Keycloak
To set up authentication:
Note
This tutorial was tested for OpenSearch 2.8 and Keycloak 24.0 clusters.
Getting started
-
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/
-
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 provider
-
Connect to the Keycloak management console and select the
master
realm. -
Create a client:
-
In the left-hand panel, select Clients. Click Create client.
-
In the Client type field, select SAML.
-
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/
-
Click Next.
-
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
-
Click Save.
-
-
Make sure you can use the client: the relevant option in the top-right corner must be set to Enabled.
-
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.
- Name ID format:
-
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
.
-
-
Click Save.
-
On the Keys tab, disable the requirement for client message signing.
To do this, disable Client signature required.
-
On the Client scopes tab, configure role mapping for the client:
-
Click URL to connect to OpenSearch Dashboards with the
-dedicated
suffix. -
On the Mappers tab, click Configure a new mapper. Select the Role list mapper from the list.
-
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.
- Name: Any mapper name, e.g.,
-
Click Save.
-
Set up SSO for the cluster
-
Get the metadata for the previously created client:
-
Connect to the Keycloak management console and select the
master
realm. -
In the left-hand panel, select Clients.
-
Click URL to connect to OpenSearch Dashboards.
-
In the top-right corner, expand the Action menu and select Download adapter config.
-
Select the
Mod Auth Mellon Files
format and click Download.This will download an archive.
-
Extract the
idp-metadata.xml
file from the archive. This file contains all required metadata.
-
-
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:
-
In the management console
, go to the folder page and select Managed Service for OpenSearch. -
Click the cluster name and open the Authentication sources tab.
-
Click Settings.
-
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.
-
-
Click Save.
-
-
Wait for the cluster status to change to
Running
. It may take a few minutes to apply settings.
Configure roles for SSO
-
Configure Keycloak so that its users get the appropriate roles:
-
Connect to the Keycloak management console and select the
master
realm. -
Create a role:
-
In the left-hand panel, select Realm roles. Click Create role.
-
In the Role name field, enter a role name.
In the steps below, we will use
kc_demo_role
as the role name. -
Click Save.
-
-
Create and configure a user:
-
In the left-hand panel, select Users. Click Add user.
-
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.
-
-
Click Create.
-
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.
-
-
Create and configure a group:
-
In the left-hand panel, select Groups and click Create group.
-
Enter a group name and click Create.
In the steps below, we will use
kc_demo_group
as the group name. -
Click the group name to open its properties.
-
In the Members tab, click Add member, select
kc_demo_user
, and click Add. -
In the Role mapping tab, click Assign role, enable Filter by realm roles, select
kc_demo_role
from the role list, and click Assign.
-
-
-
Map OpenSearch cluster roles with those in Keycloak. This will enable you to access a cluster using SSO.
To map roles:
-
Connect to OpenSearch Dashboards as the
admin
user. -
In the left-hand menu, select OpenSearch Plugins → Security.
-
In the left-hand panel, select Roles.
-
Configure role mapping:
-
Click the role name.
The next steps assume that you select the
kibana_user
role. -
Go to the Mapped users tab.
-
Click Manage mapping.
-
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 SSO
-
Open your browser in guest or private browsing mode.
For this, you must use a computer with access to Keycloak.
-
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.
-
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.
-
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.
-
Make sure you can perform all actions the
kibana_user
role permits.