SAML

The security plugin supports user authentication through SAML single sign-on. The security plugin implements the web browser SSO profile of the SAML 2.0 protocol.

This profile is meant for use with web browsers. It is not a general-purpose way of authenticating users against the security plugin, so its primary use case is to support OpenSearch Dashboards single sign-on.

Docker example

We provide a fully functional example that can help you understand how to use SAML with OpenSearch Dashboards.

  1. Download and unzip the example ZIP file.
  2. At the command line, run docker-compose up.
  3. Review the files:

    • docker-compose.yml defines two OpenSearch nodes, an OpenSearch Dashboards server, and a SAML server.
    • custom-opensearch_dashboards.yml add a few SAML settings to the default opensearch_dashboards.yml file.
    • config.yml configures SAML for authentication.
  4. Access OpenSearch Dashboards at http://localhost:5601. Note that OpenSearch Dashboards immediately redirects you to the SAML login page.

  5. Log in as admin with a password of admin.

  6. After logging in, note that your user in the upper-right is SAMLAdmin, as defined in /var/www/simplesamlphp/config/authsources.php of the SAML server.

  7. If you want to examine the SAML server, run docker ps to find its container ID and then docker exec -it <container-id> /bin/bash.

    In particular, you might find it helpful to review the contents of the /var/www/simplesamlphp/config/ and /var/www/simplesamlphp/metadata/ directories.

Activating SAML

To use SAML for authentication, you need to configure a respective authentication domain in the authc section of plugins/opensearch-security/securityconfig/config.yml. Because SAML works solely on the HTTP layer, you do not need any authentication_backend and can set it to noop. Place all SAML-specific configuration options in this chapter in the config section of the SAML HTTP authenticator:

  1. authc:
  2. saml_auth_domain:
  3. http_enabled: true
  4. transport_enabled: false
  5. order: 1
  6. http_authenticator:
  7. type: saml
  8. challenge: true
  9. config:
  10. idp:
  11. metadata_file: okta.xml
  12. ...
  13. authentication_backend:
  14. type: noop

After you have configured SAML in config.yml, you must also activate it in OpenSearch Dashboards.

Running multiple authentication domains

We recommend adding at least one other authentication domain, such as LDAP or the internal user database, to support API access to OpenSearch without SAML. For OpenSearch Dashboards and the internal OpenSearch Dashboards server user, you also must add another authentication domain that supports basic authentication. This authentication domain should be placed first in the chain, and the challenge flag must be set to false:

  1. authc:
  2. basic_internal_auth_domain:
  3. http_enabled: true
  4. transport_enabled: true
  5. order: 0
  6. http_authenticator:
  7. type: basic
  8. challenge: false
  9. authentication_backend:
  10. type: internal
  11. saml_auth_domain:
  12. http_enabled: true
  13. transport_enabled: false
  14. order: 1
  15. http_authenticator:
  16. type: saml
  17. challenge: true
  18. config:
  19. ...
  20. authentication_backend:
  21. type: noop

Identity provider metadata

A SAML identity provider (IdP) provides a SAML 2.0 metadata file describing the IdP’s capabilities and configuration. The security plugin can read IdP metadata either from a URL or a file. The choice that you make depends on your IdP and your preferences. The SAML 2.0 metadata file is required.

NameDescription
idp.metadata_fileThe path to the SAML 2.0 metadata file of your IdP. Place the metadata file in the config directory of OpenSearch. The path has to be specified relative to the config directory. Required if idp.metadata_url is not set.
idp.metadata_urlThe SAML 2.0 metadata URL of your IdP. Required if idp.metadata_file is not set.

IdP and service provider entity ID

An entity ID is a globally unique name for a SAML entity, either an IdP or a service provider (SP). The IdP entity ID is usually provided by your IdP. The SP entity ID is the name of the configured application or client in your IdP. We recommend adding a new application for OpenSearch Dashboards and using the URL of your OpenSearch Dashboards installation as the SP entity ID.

NameDescription
idp.entity_idThe entity ID of your IdP. Required.
sp.entity_idThe entity ID of the service provider. Required.

OpenSearch Dashboards settings

The web browser SSO profile exchanges information through HTTP GET or POST. For example, after you log in to your IdP, it sends an HTTP POST back to OpenSearch Dashboards containing the SAML response. You must configure the base URL of your OpenSearch Dashboards installation where the HTTP requests are being sent to.

NameDescription
kibana_urlThe OpenSearch Dashboards base URL. Required.

Username and Role attributes

Subjects (for example, user names) are usually stored in the NameID element of a SAML response:

  1. <saml2:Subject>
  2. <saml2:NameID>admin</saml2:NameID>
  3. ...
  4. </saml2:Subject>

If your IdP is compliant with the SAML 2.0 specification, you do not need to set anything special. If your IdP uses a different element name, you can also specify its name explicitly.

Role attributes are optional. However, most IdPs can be configured to add roles in the SAML assertions as well. If present, you can use these roles in your role mappings:

  1. <saml2:Attribute Name='Role'>
  2. <saml2:AttributeValue >Everyone</saml2:AttributeValue>
  3. <saml2:AttributeValue >Admins</saml2:AttributeValue>
  4. </saml2:Attribute>

If you want to extract roles from the SAML response, you need to specify the element name that contains the roles.

NameDescription
subject_keyThe attribute in the SAML response where the subject is stored. Optional. If not configured, the NameID attribute is used.
roles_keyThe attribute in the SAML response where the roles are stored. Optional. If not configured, no roles are used.

Request signing

Requests from the security plugin to the IdP can optionally be signed. Use the following settings to configure request signing.

NameDescription
sp.signature_private_keyThe private key used to sign the requests or to decode encrypted assertions. Optional. Cannot be used when private_key_filepath is set.
sp.signature_private_key_passwordThe password of the private key, if any.
sp.signature_private_key_filepathPath to the private key. The file must be placed under the OpenSearch config directory, and the path must be specified relative to that same directory.
sp.signature_algorithmThe algorithm used to sign the requests. See the next table for possible values.

The security plugin supports the following signature algorithms.

AlgorithmValue
DSA_SHA1http://www.w3.org/2000/09/xmldsig#dsa-sha1;
RSA_SHA1http://www.w3.org/2000/09/xmldsig#rsa-sha1;
RSA_SHA256http://www.w3.org/2001/04/xmldsig-more#rsa-sha256;
RSA_SHA384http://www.w3.org/2001/04/xmldsig-more#rsa-sha384;
RSA_SHA512http://www.w3.org/2001/04/xmldsig-more#rsa-sha512;

Logout

Usually, IdPs provide information about their individual logout URL in their SAML 2.0 metadata. If this is the case, the security plugin uses them to render the correct logout link in OpenSearch Dashboards. If your IdP does not support an explicit logout, you can force a re-login when the user visits OpenSearch Dashboards again.

NameDescription
sp.forceAuthnForce a re-login even if the user has an active session with the IdP.

Currently, the security plugin supports only the HTTP-Redirect logout binding. Make sure this is configured correctly in your IdP.

Exchange key settings

SAML, unlike other protocols, is not meant to be used for exchanging user credentials with each request. The security plugin trades the SAML response for a lightweight JSON web token that stores the 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.

NameDescription
exchange_keyThe key to sign the token. The algorithm is HMAC256, so it should have at least 32 characters.

TLS settings

If you are loading the IdP metadata from a URL, we recommend that you use SSL/TLS. If you use an external IdP like Okta or Auth0 that uses a trusted certificate, you usually do not need to configure anything. If you host the IdP yourself and use your own root CA, you can customize the TLS settings as follows. These settings are used only for loading SAML metadata over HTTPS.

NameDescription
idp.enable_sslWhether to enable the custom TLS configuration. Default is false (JDK settings are used).
idp.verify_hostnamesWhether to verify the hostnames of the server’s TLS certificate.

Example:

  1. authc:
  2. saml_auth_domain:
  3. http_enabled: true
  4. transport_enabled: false
  5. order: 1
  6. http_authenticator:
  7. type: saml
  8. challenge: true
  9. config:
  10. idp:
  11. enable_ssl: true
  12. verify_hostnames: true
  13. ...
  14. authentication_backend:
  15. type: noop

Certificate validation

Configure the root CA used for validating the IdP TLS certificate by setting one of the following configuration options:

  1. config:
  2. idp:
  3. pemtrustedcas_filepath: path/to/trusted_cas.pem
  1. config:
  2. idp:
  3. pemtrustedcas_content: |-
  4. MIID/jCCAuagAwIBAgIBATANBgkqhkiG9w0BAQUFADCBjzETMBEGCgmSJomT8ixk
  5. ARkWA2NvbTEXMBUGCgmSJomT8ixkARkWB2V4YW1wbGUxGTAXBgNVBAoMEEV4YW1w
  6. bGUgQ29tIEluYy4xITAfBgNVBAsMGEV4YW1wbGUgQ29tIEluYy4gUm9vdCBDQTEh
  7. ...
NameDescription
idp.pemtrustedcas_filepathPath to the PEM file containing the root CAs of your IdP. The files must be placed under the OpenSearch config directory, and you must specify the path relative to that same directory.
idp.pemtrustedcas_contentThe root CA content of your IdP server. Cannot be used when pemtrustedcas_filepath is set.

Client authentication

The security plugin can use TLS client authentication when fetching the IdP metadata. If enabled, the security plugin sends a TLS client certificate to the IdP for each metadata request. Use the following keys to configure client authentication.

NameDescription
idp.enable_ssl_client_authWhether to send a client certificate to the IdP server. Default is false.
idp.pemcert_filepathPath to the PEM file containing the client certificate. The file must be placed under the OpenSearch config directory, and the path must be specified relative to the config directory.
idp.pemcert_contentThe content of the client certificate. Cannot be used when pemcert_filepath is set.
idp.pemkey_filepathPath to the private key of the client certificate. The file must be placed under the OpenSearch config directory, and the path must be specified relative to the config directory.
idp.pemkey_contentThe content of the private key of your certificate. Cannot be used when pemkey_filepath is set.
idp.pemkey_passwordThe password of your private key, if any.

Enabled ciphers and protocols

You can limit the allowed ciphers and TLS protocols for the IdP connection. For example, you can only enable strong ciphers and limit the TLS versions to the most recent ones.

NameDescription
idp.enabled_ssl_ciphersArray of enabled TLS ciphers. Only the Java format is supported.
idp.enabled_ssl_protocolsArray of enabled TLS protocols. Only the Java format is supported.

Minimal configuration example

The following example shows the minimal configuration:

  1. authc:
  2. saml_auth_domain:
  3. http_enabled: true
  4. transport_enabled: false
  5. order: 1
  6. http_authenticator:
  7. type: saml
  8. challenge: true
  9. config:
  10. idp:
  11. metadata_file: metadata.xml
  12. entity_id: http://idp.example.com/
  13. sp:
  14. entity_id: https://opensearch-dashboards.example.com
  15. kibana_url: https://opensearch-dashboards.example.com:5601/
  16. roles_key: Role
  17. exchange_key: 'peuvgOLrjzuhXf ...'
  18. authentication_backend:
  19. type: noop

OpenSearch Dashboards configuration

Because most of the SAML-specific configuration is done in the security plugin, just activate SAML in your opensearch_dashboards.yml by adding the following:

  1. opensearch_security.auth.type: "saml"

In addition, the OpenSearch Dashboards endpoint for validating the SAML assertions must be whitelisted:

  1. server.xsrf.whitelist: ["/_plugins/_security/saml/acs"]

If you use the logout POST binding, you also need to whitelist the logout endpoint:

  1. server.xsrf.whitelist: ["/_plugins/_security/saml/acs", "/_plugins/_security/saml/logout"]

IdP-initiated SSO

To use IdP-initiated SSO, set the Assertion Consumer Service endpoint of your IdP to this:

  1. /_plugins/_security/saml/acs/idpinitiated

Then add this endpoint to server.xsrf.whitelist in opensearch_dashboards.yml:

  1. server.xsrf.whitelist: ["/_plugins/_security/saml/acs/idpinitiated", "/_plugins/_security/saml/acs", "/_plugins/_security/saml/logout"]