Building SAML federation for Amazon OpenSearch Service with Okta

Amazon OpenSearch Service is a fully managed open search and analytics service powered by the Apache Lucene search library. Security Assertion Markup Language (SAML)-based federation for OpenSearch Dashboards lets you use your existing identity provider (IdP) like Okta to provide single sign-on (SSO) for OpenSearch Dashboards on OpenSearch Service domains.

This post shows step-by-step guidance to enable SP-initiated single sign-on (SSO) into OpenSearch Dashboards using Okta.

To use this feature, you must enable fine-grained access control. Rather than authenticating through Amazon Cognito or the internal user database, SAML authentication for OpenSearch Dashboards lets you use third-party identity providers to log in to OpenSearch Dashboards. SAML authentication for OpenSearch Dashboards is only for accessing OpenSearch Dashboards through a web browser.

Overview of Okta SAML authenticated solution

Figure 1 depicts a sample architecture of a generic, integrated solution between Okta and OpenSearch Dashboards over SAML authentication.

Figure 1. SAML transactions between Amazon OpenSearch Service and Okta

The initial sign-in flow is as follows:

1. User opens browser window and navigates to OpenSearch Dashboards
2. OpenSearch Service generates SAML authentication request
3. OpenSearch Service redirects request back to browser
4. Browser redirects to Okta URL
5. Okta parses SAML request, authenticates user, and generates SAML response
6. Okta returns encoded SAML response to browser
7. Browser sends SAML response back to OpenSearch Service Assertion Consumer Services (ACS) URL
8. ACS verifies SAML response
9. User logs into OpenSearch Service domain

Prerequisites

For this walkthrough, you should have the following prerequisites:

1. An AWS account
2. A virtual private cloud (VPC)-based OpenSearch Service domain with fine-grained access control enabled
3. Okta account with user and a group
4. A browser with network connectivity to Okta, OpenSearch Service domain, and OpenSearch Dashboards.

The steps in this post are structured into the following sections:

1. Identity provider (Okta) setup
2. Prepare OpenSearch Service for SAML configuration
3. Identity provider (Okta) SAML configuration
4. Finish OpenSearch Service for SAML configuration
5. Validation
6. Cleanup

Identity provider (Okta) setup

Step 1: Sign up for an Okta account

• Sign up for an Okta account, then click on the Sign up button to complete your account setup.
• If you already have an account with Okta, login to your Okta account.

Step 2: Create Groups in Okta

• Choose Directory in the left menu and click Groups to proceed.
• Click on Add Group and enter name as opensearch. Then click on the Save button, see Figure 2.

Figure 2. Creating a group in Okta

Step 3: Create users in Okta

• Choose People in left menu under Directory section and click the +Add Person button.
• Provide First name, Last name, username (email ID), and primary email. Then select set by admin from the Password dropdown, and choose first time password. Click on the Save button to create your user.
• Add more users as needed.

Step 4: Assign Groups to users 

• Choose Groups from the left menu, then click on the opensearch group created in Step 2. Click on the Assign People button to add users to the opensearch group. Next, either click on individual user under Person & Username, or use the Add All button to add all existing users to the opensearch group. Click on the Save button to complete adding users to your group.

Prepare OpenSearch Service for SAML configuration

Once OpenSearch Service domain is up and running, we can proceed with configuration.

• Navigate to the OpenSearch Service console
• Under Actions, choose Edit security configuration as shown in Figure 3

Figure 3. Enabling Amazon OpenSearch Service security configuration for SAML

• Under SAML authentication for OpenSearch Dashboards/Kibana, select the Enable SAML authentication check box, see Figure 4. When we enable SAML, it will create different URLs required for configuring SAML with your identity provider.

Figure 4. Amazon OpenSearch Service URLs for SAML configuration

We will be using the Service Provider entity ID and SP-initiated SSO URL (highlighted in Figure 4) for Okta SAML configuration. The OpenSearch Dashboards login flow can take one of two forms:

• Service provider (SP) initiated: You navigate to your OpenSearch Dashboard (for example, https://my-domain.us-east-1.es.amazonaws.com/_dashboards), which redirects you to the login screen. After you log in, the identity provider redirects you to OpenSearch Dashboards.
• Identity provider (IdP) initiated: You navigate to your identity provider, log in, and choose OpenSearch Dashboards from an application directory.

We will complete the rest of the OpenSearch Service SAML configuration after the Okta SAML configuration.

Okta SAML configuration

• Go back to Okta.com, and choose Applications from the left menu. Click on Applications, then click on Create App Integration and choose SAML 2.0. Click on the Next button to proceed, as shown in Figure 5.
• For this example, we are creating an application called “OpenSearch Dashboard”.
• Select Platform as Web, and select Sign on method as SAML 2.0. Click on the Create button to proceed.

Figure 5. Creating a SAML app integration in Okta

• Enter the App name as OpenSearch, use default options, and click on the Next button to proceed.
• Enter the following under the SAML Settings section, as shown in Figure 6. Click on the Next button to proceed.
  • Single Sign on URL = https://vpc-XXXXX-XXXXX.us-west-2.es.amazonaws.com/_dashboards/_opendistro/_security/saml/acs (SP-initiated SSO URL)
  • Audience URI(SP Entity ID) = https://vpc-XXXXX-XXXXX.us-west-2.es.amazonaws.com (Service Provider entity ID)
  • Default RelayState = leave it blank
  • Name ID format = Select EmailAddress from drop down
  • Application username = Select Okta username from dropdown
  • Update application username on = leave it set to default
• Enter the following under Attribute Statements (optional) section.
  • Name = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  • Name format = Select URI Reference from dropdown
  • Value = user.email
• Enter the following under the Group Attribute Statements (optional) section.
  • Name = http://schemas.xmlsoap.org/claims/Group
  • Name format = Select URI Reference from dropdown
  • Filter = Select Matches regex from dropdown and enter value as .*open.* to match the group created in previous steps for OpenSearch Dashboards access.

Figure 6. SAML configuration in Okta

• Select I’m a software vendor. I’d like to integrate my app with Okta under the Help Okta Support understand how you configured this application section.
• Click on the Finish button to complete the Okta SAML application configuration.
• Choose Sign on menu. Right click on the Identity Provider metadata hyperlink to download the Okta identity provider metadata as okta.xml. You will use this for the SAML configuration in OpenSearch Service, see Figure 7.

Figure 7. Downloading Okta identity provider metadata for SAML configuration

• Choose the Assignments menu and click on Assign-> Assign to Groups
• Select the opensearch group, click on Assign, and click on the Done button to complete the Group assignment, as shown in Figure 8.

Figure 8. Assigning groups to the app in Okta

• Switch back to the OpenSearch Service domain
• Under the Import IdP metadata section:
  • Metadata from IdP: Import the Okta identity provider metadata from the downloaded XML file
  • SAML master backend role: opensearch (Okta group). Provide the SAML backend role/group SAML assertion key for group SSO into OpenSearch Dashboard.
• Under Optional SAML settings:
  • Leave Subject Key blank
  • Role key should be http://schemas.xmlsoap.org/claims/Group. You can view a sample assertion during the configuration process with tools like SAML-tracer. This can help you examine and troubleshoot the contents of real assertions.
  • Session time to live (mins): 60
• Click on the Save changes button (Figure 9) to complete OpenSearch Service SAML configuration for OpenSearch Dashboards. We have successfully completed SAML configuration, and now we are ready for testing.

Figure 9. Configuring Amazon OpenSearch Service SAML parameters

Validating access with Okta users

• Access the OpenSearch Dashboards endpoint from the previously created OpenSearch Service cluster. The OpenSearch Dashboards URL can be found in General information within “My Domains” of the OpenSearch Service console, as shown in Figure 10. The first access to OpenSearch Dashboards URL redirects you to the Okta login screen.

Figure 10. Validating Okta user access with Amazon OpenSearch Service

• Now copy and paste the OpenSearch Dashboards URL in your browser, and enter the user credentials.
• If your OpenSearch Service domain is hosted within a private VPC, you will not be able to access your OpenSearch Dashboard over public internet. But you can still use SAML as long as your browser can communicate with both your OpenSearch Service cluster and your identity provider.
• You can create a Mac or Windows EC2 instance within the same VPC so that you can access Amazon OpenSearch Dashboard from EC2 instance’s web browser to validate your SAML configuration. Or you can access your OpenSearch Dashboard through Site-to-Site VPN from your on-premises environment.
• After successful login, you will be redirected into the OpenSearch Dashboards home page. Here, you can explore our sample data and visualizations in OpenSearch Dashboards (Figure 11).

Figure 11. SAML authenticated OpenSearch Dashboards

• Now, you have successfully federated OpenSearch Dashboards with Okta as an identity provider. You can connect OpenSearch Dashboards by using your Okta credentials.

Cleaning up

After you test out this solution, remember to delete all the resources you created, to avoid incurring future charges. Refer to these links:

• Deleting your OpenSearch Service domain
• Deleting your Okta account (if needed)

Conclusion

In this blog post, we have demonstrated how to set up Okta as an identity provider over SAML authentication for OpenSearch Dashboards access. Get started by checking the Amazon OpenSearch Service Developer Guide, which provides guidance on how to build applications using OpenSearch Service.