SAML authentication for OpenSearch Dashboards - Amazon OpenSearch Service (successor to Amazon Elasticsearch Service)
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

SAML authentication for OpenSearch Dashboards

SAML authentication for OpenSearch Dashboards lets you use your existing identity provider to offer single sign-on (SSO) for Dashboards on Amazon OpenSearch Service domains running OpenSearch or Elasticsearch 6.7 or later. To use SAML authentication, you must enable fine-grained access control. You can't enable fine-grained access control on existing domains, only new ones. By extension, this means you can only enable SAML authentication on new domains or existing ones that have fine-grained access control already enabled.

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 Dashboards, manage fine-grained access control, search your data, and build visualizations. OpenSearch Service supports providers that use the SAML 2.0 standard, such as Okta, Keycloak, Active Directory Federation Services (ADFS), and Auth0.

Note

Requests from OpenSearch Service to third-party providers aren't explicitly encrypted with a service provider certificate.

SAML authentication for Dashboards is only for accessing OpenSearch Dashboards through a web browser. Your SAML credentials do not let you make direct HTTP requests to the OpenSearch or Dashboards APIs.

SAML configuration overview

This documentation assumes you have an existing identity provider and some familiarity with it. We can't provide detailed configuration steps for your exact provider, only for your OpenSearch Service domain.

The Dashboards login flow can take one of two forms:

  • Service provider (SP) initiated: You navigate to Dashboards (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 Dashboards.

  • Identity provider (IdP) initiated: You navigate to your identity provider, log in, and choose Dashboards from an application directory.

OpenSearch Service provides two single sign-on URLs, SP-initiated and IdP-initiated, but you only need the one that matches your desired Dashboards login flow. If you want to configure both SP- and IdP-initiated authentication, you must do so through your identity provider. For example, in Okta you can enable Allow this app to request other SSO URLs and add one or more IdP-initiated SSO URLs.

Regardless of which authentication type you use, the goal is to log in through your identity provider and receive a SAML assertion that contains your username (required) and any backend roles (optional, but recommended). This information allows fine-grained access control to assign permissions to SAML users. In external identity providers, backend roles are typically called "roles" or "groups."

Note

You can't change the SSO URL from its service-provided value, so SAML authentication for Dashboards does not support proxy servers.

Enabling SAML authentication

You can only enable SAML authentication for OpenSearch Dashboards on existing domains, not during the creation of new ones. Due to the size of the IdP metadata file, we highly recommend using the Amazon console.

Domains only support one Dashboards authentication method at a time. If you have Amazon Cognito authentication for OpenSearch Dashboards enabled, you must disable it before you can enable SAML.

To enable SAML authentication for Dashboards (console)

  1. Choose the domain, Actions and Edit security configuration.

  2. Select Enable SAML authentication.

  3. Note the service provider entity ID and the two SSO URLs. You only need one of the SSO URLs. For guidance, see SAML configuration overview.

    Tip

    These URLs change if you later enable a custom endpoint for your domain. In that situation, you must update your IdP.

  4. Use these values to configure your identity provider. This is the most complex part of the process, and unfortunately, terminology and steps vary wildly by provider. Consult your provider's documentation.

    In Okta, for example, you create a "SAML 2.0 web application." For Single sign on URL, specify the SSO URL that you chose in step 3. For Audience URI (SP Entity ID), specify the SP entity ID.

    Rather than users and backend roles, Okta has users and groups. For Group Attribute Statements, we recommend adding role to the Name field and the regular expression .+ to the Filter field. This statement tells the Okta identity provider to include all user groups under the role field of the SAML assertion after a user authenticates.

    In Auth0, you create a "regular web application" and then enable the SAML 2.0 add-on. In Keycloak, you create a "client."

  5. After you configure your identity provider, it generates an IdP metadata file. This XML file contains information on the provider, such as a TLS certificate, single sign-on endpoints, and the identity provider's entity ID.

    Copy the contents of the IdP metadata file and paste it into the Metadata from IdP field in the OpenSearch Service console. Alternately, choose Import from XML file and upload the file. The metadata file should look something like this:

    <?xml version="1.0" encoding="UTF-8"?> <md:EntityDescriptor entityID="entity-id" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"> <md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"> <md:KeyDescriptor use="signing"> <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <ds:X509Data> <ds:X509Certificate>tls-certificate</ds:X509Certificate> </ds:X509Data> </ds:KeyInfo> </md:KeyDescriptor> <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat> <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat> <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="idp-sso-url"/> <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="idp-sso-url"/> </md:IDPSSODescriptor> </md:EntityDescriptor>
  6. Copy the value of the entityID property from your metadata file and paste it into the IdP entity ID field in the OpenSearch Service console. Many identity providers also display this value as part of a post-configuration summary. Some providers call it the "issuer".

  7. Provide a SAML master username and/or a SAML master backend role. This username and/or backend role receives full permissions to the cluster, equivalent to a new master user, but can only use those permissions within Dashboards.

    In Okta, for example, you might have a user jdoe who belongs to the group admins. If you add jdoe to the SAML master username field, only that user receives full permissions. If you add admins to the SAML master backend role field, any user who belongs to the admins group receives full permissions.

    The contents of the SAML assertion must exactly match the strings that you use for the SAML master username and/or SAML master role. Some identity providers add a prefix before their usernames, which can cause a hard-to-diagnose mismatch. In the identity provider user interface, you might see jdoe, but the SAML assertion might contain auth0|jdoe. Always use the string from the SAML assertion.

    Many identity providers let you view a sample assertion during the configuration process, and tools like SAML-tracer can help you examine and troubleshoot the contents of real assertions. Assertions look something like this:

    <?xml version="1.0" encoding="UTF-8"?> <saml2:Assertion ID="id67229299299259351343340162" IssueInstant="2020-09-22T22:03:08.633Z" Version="2.0" xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"> <saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">idp-issuer</saml2:Issuer> <saml2:Subject> <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">username</saml2:NameID> <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"> <saml2:SubjectConfirmationData NotOnOrAfter="2020-09-22T22:08:08.816Z" Recipient="domain-endpoint/_dashboards/_plugins/_security/saml/acs"/> </saml2:SubjectConfirmation> </saml2:Subject> <saml2:Conditions NotBefore="2020-09-22T21:58:08.816Z" NotOnOrAfter="2020-09-22T22:08:08.816Z"> <saml2:AudienceRestriction> <saml2:Audience>domain-endpoint</saml2:Audience> </saml2:AudienceRestriction> </saml2:Conditions> <saml2:AuthnStatement AuthnInstant="2020-09-22T19:54:37.274Z"> <saml2:AuthnContext> <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef> </saml2:AuthnContext> </saml2:AuthnStatement> <saml2:AttributeStatement> <saml2:Attribute Name="role" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">GroupName Match Matches regex ".+" (case-sensitive) </saml2:AttributeValue> </saml2:Attribute> </saml2:AttributeStatement> </saml2:Assertion>
  8. (Optional) Expand Additional settings.

  9. Leave the Subject key field empty to use the NameID element of the SAML assertion for the username. If your assertion doesn't use this standard element and instead includes the username as a custom attribute, specify that attribute here.

    If you want to use backend roles (recommended), specify an attribute from the assertion in the Role key field, such as role or group. This is another situation in which tools like SAML-tracer can help.

  10. By default, OpenSearch Dashboards logs users out after 60 minutes. You can increase this value up to 1,440 (24 hours) by specifying the Session time to live.

  11. Choose Save changes. The domain enters a processing state for approximately one minute, during which time Dashboards is unavailable.

  12. After the domain finishes processing, open Dashboards.

    • If you chose the SP-initiated URL, navigate to domain-endpoint/_dashboards/.

    • If you chose the IdP-initiated URL, navigate to your identity provider's application directory.

    In both cases, log in as either the SAML master user or a user who belongs to the SAML master backend role. To continue the example from step 7, log in as either jdoe or a member of the admins group.

  13. After Dashboards loads, choose Security and Roles.

  14. Map roles to allow other users to access Dashboards.

    For example, you might map your trusted colleague jroe to the all_access and security_manager roles. You might also map the backend role analysts to the readall and kibana_user roles.

    If you prefer to use the API rather than Dashboards, see the following sample request:

    PATCH _plugins/_security/api/rolesmapping [ { "op": "add", "path": "/security_manager", "value": { "users": ["master-user", "jdoe", "jroe"], "backend_roles": ["admins"] } }, { "op": "add", "path": "/all_access", "value": { "users": ["master-user", "jdoe", "jroe"], "backend_roles": ["admins"] } }, { "op": "add", "path": "/readall", "value": { "backend_roles": ["analysts"] } }, { "op": "add", "path": "/kibana_user", "value": { "backend_roles": ["analysts"] } } ]

Sample CLI command

The following Amazon CLI command enables SAML authentication for OpenSearch Dashboards on an existing domain:

aws opensearch update-domain-config \ --domain-name my-domain \ --advanced-security-options '{"SAMLOptions":{"Enabled":true,"MasterUserName":"my-idp-user","MasterBackendRole":"my-idp-group-or-role","Idp":{"EntityId":"entity-id","MetadataContent":"metadata-content-with-quotes-escaped"},"RolesKey":"optional-roles-key","SessionTimeoutMinutes":180,"SubjectKey":"optional-subject-key"}}'

You must escape all quotes and newline characters in the metadata XML. For example, use <KeyDescriptor use=\"signing\">\n instead of <KeyDescriptor use="signing"> and a line break. For detailed information about using the Amazon CLI, see the Amazon CLI Command Reference.

Sample configuration API request

The following request to the configuration API enables SAML authentication for OpenSearch Dashboards on an existing domain:

POST https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/domain/my-domain/config { "AdvancedSecurityOptions": { "SAMLOptions": { "Enabled": true, "MasterUserName": "my-idp-user", "MasterBackendRole": "my-idp-group-or-role", "Idp": { "EntityId": "entity-id", "MetadataContent": "metadata-content-with-quotes-escaped" }, "RolesKey": "optional-roles-key", "SessionTimeoutMinutes": 180, "SubjectKey": "optional-subject-key" } } }

You must escape all quotes and newline characters in the metadata XML. For example, use <KeyDescriptor use=\"signing\">\n instead of <KeyDescriptor use="signing"> and a line break. For detailed information about using the configuration API, see Configuration API reference for Amazon OpenSearch Service.

SAML troubleshooting

Error Details

Your request: '/some/path' is not allowed.

Verify that you provided the correct SSO URL (step 3) to your identity provider.

Please provide valid identity provider metadata document to enable SAML.

Your IdP metadata file does not conform to the SAML 2.0 standard. Check for errors using a validation tool.

SAML configuration options aren't visible in the console.

Update to the latest service software.

SAML configuration error: Something went wrong while retrieving the SAML configuration, please check your settings.

This generic error can occur for many reasons.

  • Check that you provided your identity provider with the correct SP entity ID and SSO URL.

  • Regenerate the IdP metadata file, and verify the IdP entity ID. Add any updated metadata in the Amazon console.

  • Verify that your domain access policy allows access to OpenSearch Dashboards and _plugins/_security/*. In general, we recommend an open access policy for domains that use fine-grained access control.

  • Consult your identity provider's documentation for steps on configuring SAML.

Missing role: No roles available for this user, please contact your system administrator.

You successfully authenticated, but the username and any backend roles from the SAML assertion are not mapped to any roles and thus have no permissions. These mappings are case-sensitive.

Verify the contents of your SAML assertion using a tool like SAML-tracer and your role mapping using the following call:

GET _plugins/_security/api/rolesmapping

Your browser continuously redirects or receives HTTP 500 errors when trying to access OpenSearch Dashboards.

These errors can occur if your SAML assertion contains a large number of roles totaling approximately 1,500 characters. For example, if you pass 80 roles, the average length of which is 20 characters, you might exceed the size limit for cookies in your web browser.

You can't log out of ADFS.

ADFS requires all logout request to be signed, which OpenSearch Service doesn't support. Remove <SingleLogoutService /> from the IdP metadata file to force OpenSearch Service to use its own internal logout mechanism.

Disabling SAML authentication

To disable SAML authentication for OpenSearch Dashboards (console)

  1. Choose the domain, Actions, and Edit security configuration.

  2. Uncheck Enable SAML authentication.

  3. Choose Save changes.

  4. After the domain finishes processing, verify the fine-grained access control role mapping with the following request:

    GET _plugins/_security/api/rolesmapping

    Disabling SAML authentication for Dashboards does not remove the mappings for the SAML master username and/or the SAML master backend role. If you want to remove these mappings, log in to Dashboards using the internal user database (if enabled), or use the API to remove them:

    PUT _plugins/_security/api/rolesmapping/all_access { "users": [ "master-user" ] }