Configuring SAML authentication
The Security Assertion Markup Language (SAML) is used for transferring 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 this OASIS guide
Managed Service for OpenSearch works with any SAML 2.0-compatible identity provider.
To set up SAML authentication:
- Configure an identity provider.
- Set up a Managed Service for OpenSearch cluster to use this IdP for SSO.
- Configure cluster roles for SSO users on the IdP side.
Configuring an identity provider
-
Create an application on the IdP side.
-
Specify the Assertion Consumer Service (ACS) URL.
Use this URL with a special cluster FQDN:
https://c-<OpenSearch_cluster_ID>.rw.mdb.yandexcloud.net/_opendistro/_security/saml/acsYou can get the cluster ID with the list of clusters in the folder.
URL example:
https://c-e4ut2....rw.mdb.yandexcloud.net/_opendistro/_security/saml/acs -
Specify the SP Entity ID (Audience URI).
Use this URL with a special cluster FQDN:
https://c-<cluster_ID>rw.mdb.yandexcloud.net/URL example:
https://c-e4ut2....rw.mdb.yandexcloud.net/ -
Specify the Name ID Format:
email, if you use an identity federation with the Keycloak provider.persistent, for other providers.
-
Get the data you need to set up SAML SSO on OpenSearch side:
- Copy the information about the identity provider issuer.
- Save the provider metadata file in XML format.
You will need it to set up SSO for your cluster.
Setting up SSO for the cluster
Warning
Incorrect settings may cause the cluster to fail.
-
In the management console
, navigate to the folder page. -
Navigate to the Managed Service for OpenSearch service.
-
Click the name of your cluster and select the Authentication sources tab.
-
Click Settings.
-
Specify the parameters of your external authentication source:
-
idp_entity_id: Information about the identity provider issuer obtained when configuring the IdP.
-
idp_metadata_file: Provider metadata file in XML format obtained when configuring the IdP.
-
sp_entity_id: Application-defined SP Entity ID (Audience URI). Make sure it matches the ID specified when configuring the IdP.
-
kibana_url: URL with a special cluster FQDN, same as 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 specified, the
NameIDparameter is used. -
Session timeout: Session lifetime, in minutes. Specify if it is not set by the identity provider.
If there is no value or
0, the session lifetime is unlimited (default). -
Enable: Sets whether to activate an authentication source after creating it.
-
-
Click Save.
-
Get an IAM token for API authentication and put it in an environment variable:
export IAM_TOKEN="<IAM_token>" -
Call the Cluster.UpdateAuthSettings method, e.g., via the following cURL
request: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>", "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_subject_in_SAML_response>", "jwtDefaultExpirationTimeout": "<session_lifetime>" } } }'Where
settingsis a set of SSO settings that contain thesamlsection with the following parameters:-
enabled: Enable SSO,trueorfalse. -
idpEntityId: ID of the identity provider issuer obtained when configuring the IdP. -
idpMetadataFile: Path to the Base64 metadata file. -
spEntityId: SP Entity ID (Audience URI) of your application. Make sure it matches the URI you specified when configuring the IdP. -
dashboardsUrl: URL of the host with theDASHBOARDSrole. -
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 specified, theNameIDparameter is used. -
jwtDefaultExpirationTimeout: Session lifetime, in minutes. Specify if it is not set by the identity provider.If there is no value or
0, the session lifetime is unlimited (default).
You can get the cluster ID with the list of clusters in the folder.
-
-
View the server response to make sure your request was successful.
-
Get an IAM token for API authentication and put it in an environment variable:
export IAM_TOKEN="<IAM_token>" -
Clone the cloudapi
repository:cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapiBelow, we assume that the repository contents reside in the
~/cloudapi/directory. -
Call the ClusterService.UpdateAuthSettings method, e.g., via the following gRPCurl
request: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>", "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_subject_in_SAML_response>", "jwt_default_expiration_timeout": "<session_lifetime>" } } }' \ mdb.api.cloud.yandex.net:443 \ yandex.cloud.mdb.opensearch.v1.ClusterService.UpdateAuthSettingsWhere
settingsis a set of SSO settings that contain thesamlsection with the following parameters:-
enabled: Enable SSO,trueorfalse. -
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: SP Entity ID (Audience URI) of your application. Make sure it matches the URI you specified when configuring the IdP. -
dashboards_url: URL of the host with theDASHBOARDSrole. -
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 specified, theNameIDparameter is used. -
jwt_default_expiration_timeout: Session lifetime, in minutes. Specify if it is not set by the identity provider.If there is no value or
0, the session lifetime is unlimited (default).
You can get the cluster ID with the list of clusters in the folder.
-
-
View the server response to make sure your request was successful.
Note
For more information about SAML attributes, see this OpenSearch guide
Configuring roles for SSO
To access the cluster via SSO, associate the cluster roles with the SSO users on the IdP side:
- Map the roles
of the OpenSearch users on the IdP side to the roles in the cluster. Perform this operation asadminin one of the following ways:- Using OpenSearch Dashboards
. - Using the OpenSearch API
.
- Using OpenSearch Dashboards
- On the IdP side, create a user that meets the role mappings defined in OpenSearch.
- 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.