Elasticsearch How to Set Up Single Sign-On using SAML in OpenSearch

By Opster Expert Team - Gustavo

Updated: Jun 28, 2023

| 5 min read

This article is part of a series:

• Single sign on using SAML
• Single sign on using Active Directory
• Single sign on using OpenID connect

Important: There is a bug related to acs endpoints in OpenSearch 2.1 . This was fixed in version 2.3. Version 2.3 still uses the legacy _opendistro endpoints, future versions will use the new _plugin endpoints.

You can follow the bug status here: SAML auth uses legacy `_opendistro` route · Issue #2060 · opensearch-project/security (github.com)

Quick links

• Introduction
• How to implement SAML SSO using Okta idP
  1. Create an Okta Account
  2. Create User Groups
  3. Create Role Mappings in OpenSearch
  4. Create an App for OpenSearch Dashboards on Okta
  5. Enable SAML SSO in OpenSearch
  6. Apply Settings
• Conclusion

Introduction

Single sign-on has become a web standard, allowing users to log in to multiple applications using a single set of credentials.

In this article we will use SAML as the SSO (Single Sign On) method, and Okta as idP (Identity Provider) to authorize our Okta users to view certain Opensearch Dashboards without having to maintain two different user lists, or making users manage multiple Opensearch sets of credentials.

1. User login using Okta credentials.
2. Depending on its user Okta group, a different role mapping will be applied.
3. Each Okta group will be mapped to an Opensearch role with specific permissions.
4. Authorized Dashboards are returned to the user.

How to implement SAML SSO using Okta idP

Steps to implementing SAML SSO Using Okta idP

1. Create an Okta Account

Create a free Okta trial here: https://www.okta.com/free-trial/

2. Create User Groups

Here, we will create 2 Okta groups, to show how users can map these roles to OpenSearch user roles and tenants. In the Okta admin panel go to Directory -> Groups -> Add Groups -> Create the okta_dashboards_admin and okta_dashboards_user.

Don’t forget to assign Groups to the Application and users to the group on step #4.

3. Create Role Mappings in OpenSearch

Since only one login method can be active at a time, we must make sure we provide the right roles to Okta users, because after activating SAML, basic logins will be unavailable with the default admin user.

To do this, locate the roles you want to assign to your Okta users, and add the group to the mapped users list.

In this example,  okta_dashboards_admin users will be given the allow_all role, and  okta_dashboards_user  will be assigned the kibana_user role.

On OpenSearch Dashboards, go to Security -> Roles -> <name_of_the_role>  and in the Mapped Users section select “Manage Mapping.”

Add the name of the Okta group you want to use to the Backend roles.

Repeat these steps for each Okta group you want to map to OpenSearch user roles.

4. Create an App for OpenSearch Dashboards on Okta

Pay special attention here because what we fill in here needs to match the configuration we will create in OpenSearch.

Go to Applications and to Create App Integration.

Select SAML 2.0:

Choose any display name for the application, a logo (optional), and click Next.

Configure the following settings: 

Single sign on URL:

Opensearch > 2.3

 http://<your dashboards url>/_plugins/_security/saml/acs

Opensearch  2.3 or older

 http://<your dashboards url>/_opendistro/_security/saml/acs

Audience URI (SP Entity ID): opensearch-saml

For Group Attribute Statements (optional): Select “Roles” as name, “Unspecified” Name format, and Starts with “okta_dashboards_” as Filter. This way only the user roles related to this application are shown.

Click Next, Finish, and Create the Application. ​​Go to the right menu and select “SAML Setup => View SAML Setup Instructions,”  then click on: “How to configure SAML 2.0 for <Your Application Name>” 

And gather the following:

metadata_url:  https://trial-9564467.okta.com/app/<app_id>/sso/saml/metadata
where app_id is what is covered in the screenshots.

entity_id: http://www.okta.com/<app_id> 
This should match the value of “Identity Provider Issuer” in the screenshot.

Go back to Applications and Assign the Groups you created at the beginning. Do this by clicking Assign -> Assign to Groups.

5. Enable SAML SSO in OpenSearch

You need to modify 2 files:

/usr/share/opensearch/config/opensearch-security/config.yml

Fill out the following properties according to your setup:
– metadata_url
– entity_id
– kibana_url
– exchange_key

_meta:
 type: "config"
 config_version: 2


config:
 dynamic:
   authc:
     saml_auth_domain:
       http_enabled: true
       transport_enabled: false
       order: 1
       http_authenticator:
         type: saml
         challenge: true
         config:
           idp:
             metadata_url: https://<your_app_url>.okta.com/app/<your_app_id>/sso/saml/metadata #SAML's metadata url, provided by your IdP
             entity_id: http://www.okta.com/<your_app_id> #SAML's IdP entity ID, provided by your IdP
           sp:
             entity_id: opensearch-saml
           kibana_url: <your_dashboards_url>/
           roles_key: Roles
           exchange_key: "<HMAC256 generated string>"
       authentication_backend:
         type: noop
     basic_internal_auth_domain:
       description: "Authenticate via HTTP Basic against internal users database"
       http_enabled: true
       transport_enabled: true
       order: 0
       http_authenticator:
         type: basic
         challenge: false
       authentication_backend:
         type: intern

From here you can use what you’ve gathered so far.

SAML, unlike other protocols, is not meant to be used to exchange user credentials with each request. The security plugin trades the SAML response for a lightweight JSON web token that stores validated user attributes. This token is signed by an exchange key that you can choose freely. Note that when you change this key, all tokens signed with it become invalid immediately. These must be an HMAC256 string and 32 characters max.

To generate one, go to Free HMAC-SHA256 Online Generator Tool | Devglan and then assign it to the exchange_key.

It is important to have basic auth enabled because SAML will only work for dashboards, which means, we still need authentication for OpenSearch API calls.

/usr/share/opensearch-dashboards/config/opensearch_dashboards.yml

For Dashboards to use SAML SSO, add the following to your opensearch_dashboards.yml file: 

​​opensearch_security.auth.type: "saml"
server.xsrf.allowlist: ["/_plugins/_security/saml/acs/idpinitiated", "/_plugins/_security/saml/acs", "/_plugins/_security/saml/logout", "/_opendistro/_security/saml/acs"]

This will enable SAML and whitelist the SAML endpoints.

6. Apply Settings

To apply settings you must: 

a) Apply changes with securityadmin.sh

Example: 

Cd to the /usr/share/opensearch/plugins/opensearch-security/tools directory and run:

./securityadmin.sh -cd ../../../config/opensearch-security/ -icl -nhnv   -cacert ../../../config/root-ca.pem   -cert ../../../config/kirk.pem   -key ../../../config/kirk-key.pem

b) Restart opensearch dashboard

Now when you access your OpenSearch Dashboards URL, you will see the Okta Login page.

Now after login, you should see the following under “roles and identities.”

Conclusion

Setting up SSO in OpenSearch allows users to have the same users and permissions across applications without much hassle. Once our Okta Groups are defined, we can map these Groups into existing OpenSearch roles.