SAML - OpenSearch Documentation
SAML | OpenSearch Documentation
OpenSearch
About
Releases
Roadmap
FAQ
Platform
Observability
Security Analytics
Vector Database
Playground Demo
Performance Benchmarks
Community
Forum
Slack
Events
Solutions Providers
Projects
Members
Documentation
OpenSearch and Dashboards
Data Prepper
Clients
Benchmark
Migration Assistant
Blog
Documentation
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.
Visit the
saml-demo branch
of the demos repository and download it to a folder of your choice. If you’re not familiar with how to use GitHub, see the
OpenSearch onboarding guide
for instructions.
Navigate to the
demo
folder:
cd
Review the following files, as needed:
.env
Defines the OpenSearch and OpenSearch Dashboards version to use. The default is the latest version (3.6).
Defines the
OPENSEARCH_INITIAL_ADMIN_PASSWORD
variable required by versions 2.12 and later.
./custom-config/opensearch_dashboards.yml
: Includes the SAML settings for the default
opensearch_dashboards.yml
file.
./custom-config/config.yml
: Configures SAML for authentication.
docker-compose.yml
: Defines an OpenSearch server node, an OpenSearch Dashboards server node, and a SAML server node.
./saml/config/authsources.php
: Contains the list of users that can be authenticated by this SAML domain.
From the command line, run:
docker compose up.
Access OpenSearch Dashboards at
Select
Log in with single sign-on
. This redirects you to the SAML login page.
Log in to OpenSearch Dashboards with a user defined in
./saml/config/authsources.php
(such as
user1
with password
user1pass
).
After logging in, note that the user ID shown in the upper-right corner of the screen is the same as the
NameID
attribute for the user defined in
./saml/config/authsources.php
of the SAML server (that is,
saml-test
for
user1
).
If you want to examine the SAML server, run
docker ps
to find its container ID and then
docker exec -it
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
config/opensearch-security/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:
_meta
type
config"
config_version
config
dynamic
authc
saml_auth_domain
http_enabled
true
transport_enabled
false
order
http_authenticator
type
saml
challenge
true
config
idp
metadata_file
okta.xml
...
authentication_backend
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
_meta
type
config"
config_version
config
dynamic
authc
basic_internal_auth_domain
http_enabled
true
transport_enabled
true
order
http_authenticator
type
basic
challenge
false
authentication_backend
type
internal
saml_auth_domain
http_enabled
true
transport_enabled
false
order
http_authenticator
type
saml
challenge
true
config
...
authentication_backend
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.
Name
Description
idp.metadata_file
The 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_url
The 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.
Name
Description
idp.entity_id
The entity ID of your IdP. Required.
sp.entity_id
The entity ID of the service provider. Required.
Time disparity compensation for JWT validation
Occasionally you may find that the clock times between the authentication server and the OpenSearch node are not perfectly synchronized. When this is the case, even by a few seconds, the system that either issues or receives a JSON Web Token (JWT) may try to validate
nbf
(not before) and
exp
(expiration) claims and fail to authenticate the user due to the time disparity.
By default, OpenSearch Security allows for a window of 30 seconds to compensate for possible misalignment between server clock times. To set a custom value for this feature and override the default, you can add the
jwt_clock_skew_tolerance_seconds
setting to the
config.yml
http_authenticator
type
saml
challenge
true
config
idp
metadata_file
okta.xml
jwt_clock_skew_tolerance_seconds
20
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.
Name
Description
kibana_url
The 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:
...
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
If you want to extract roles from the SAML response, you need to specify the element name that contains the roles.
Name
Description
subject_key
The attribute in the SAML response where the subject is stored. Optional. If not configured, the
NameID
attribute is used.
roles_key
The 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.
Name
Description
sp.signature_private_key
The 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_password
The password of the private key, if any.
sp.signature_private_key_filepath
Path 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_algorithm
The algorithm used to sign the requests. See the next table for possible values.
The private key must be in PKCS#8 format. If you want to use an encrypted key, it must be encrypted with a PKCS#12-compatible algorithm (3DES).
The Security plugin supports the following signature algorithms.
Algorithm
Value
DSA_SHA1
RSA_SHA1
RSA_SHA256
RSA_SHA384
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.
Name
Description
sp.forceAuthn
Force 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 JWT that stores the validated user attributes. This token is signed by an exchange key of your choice. Note that when you change this key, all tokens signed with it become invalid immediately.
Name
Description
exchange_key
The key to sign the token. The algorithm is HMACSHA512, therefore we recommend to use 64 characters, for example
9a2h8ajasdfhsdiydfn7dtd6d5ashsd89a2h8ajasdHhsdiyLfn7dtd6d5ashsdI
. Ensure that you enter a value for
exchange_key
, otherwise an error is returned.
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.
Name
Description
idp.enable_ssl
Whether to enable the custom TLS configuration. Default is
false
(JDK settings are used).
idp.verify_hostnames
Whether to verify the hostnames of the server’s TLS certificate.
Example:
authc
saml_auth_domain
http_enabled
true
transport_enabled
false
order
http_authenticator
type
saml
challenge
true
config
idp
enable_ssl
true
verify_hostnames
true
...
authentication_backend
type
noop
Certificate validation
Configure the root CA used for validating the IdP TLS certificate by setting
one
of the following configuration options:
config
idp
pemtrustedcas_filepath
path/to/trusted_cas.pem
config
idp
pemtrustedcas_content
|-
-----BEGIN CERTIFICATE-----
MIID/jCCAuagAwIBAgIBATANBgkqhkiG9w0BAQUFADCBjzETMBEGCgmSJomT8ixk
ARkWA2NvbTEXMBUGCgmSJomT8ixkARkWB2V4YW1wbGUxGTAXBgNVBAoMEEV4YW1w
bGUgQ29tIEluYy4xITAfBgNVBAsMGEV4YW1wbGUgQ29tIEluYy4gUm9vdCBDQTEh
...
-----END CERTIFICATE-----
Name
Description
idp.pemtrustedcas_filepath
Path 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_content
The 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.
Name
Description
idp.enable_ssl_client_auth
Whether to send a client certificate to the IdP server. Default is
false
idp.pemcert_filepath
Path 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_content
The content of the client certificate. Cannot be used when
pemcert_filepath
is set.
idp.pemkey_filepath
Path 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_content
The content of the private key of your certificate. Cannot be used when
pemkey_filepath
is set.
idp.pemkey_password
The 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.
Name
Description
idp.enabled_ssl_ciphers
Array of enabled TLS ciphers. Only the Java format is supported.
idp.enabled_ssl_protocols
Array of enabled TLS protocols. Only the Java format is supported.
Minimal configuration example
The following example shows the minimal configuration:
_meta
type
config"
config_version
config
dynamic
authc
saml_auth_domain
http_enabled
true
transport_enabled
false
order
http_authenticator
type
saml
challenge
true
config
idp
metadata_file
metadata.xml
entity_id
sp
entity_id
kibana_url
roles_key
Role
exchange_key
peuvgOLrjzuhXf
...'
authentication_backend
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:
opensearch_security.auth.type
saml"
In addition, you must add the OpenSearch Dashboards endpoint for validating the SAML assertions to your allow list:
server.xsrf.allowlist
/_opendistro/_security/saml/acs"
If you use the logout POST binding, you also need to ad the logout endpoint to your allow list:
server.xsrf.allowlist
/_opendistro/_security/saml/acs"
/_opendistro/_security/saml/logout"
To include SAML with other authentication types in the Dashboards sign-in window, see
Configuring sign-in options
Session management with additional cookies
To improve session management—especially for users who have multiple roles assigned to them—Dashboards provides an option to split cookie payloads into multiple cookies and then recombine the payloads when receiving them. This can help prevent larger SAML assertions from exceeding size limits for each cookie. The two settings in the following example allow you to set a prefix name for additional cookies and specify the number of them. They are added to the
opensearch_dashboards.yml
file. The default number of additional cookies is three:
opensearch_security.saml.extra_storage.cookie_prefix
security_authentication_saml
opensearch_security.saml.extra_storage.additional_cookies
Note that reducing the number of additional cookies can cause some of the cookies that were in use before the change to stop working. We recommend establishing a fixed number of additional cookies and not changing the configuration after that.
If the ID token from the IdP is especially large, OpenSearch may throw a server log authentication error indicating that the HTTP header is too large. In this case, you can increase the value for the
http.max_header_size
setting in the
opensearch.yml
file.
IdP-initiated SSO
To use IdP-initiated SSO, set the Assertion Consumer Service endpoint of your IdP to this:
/_opendistro/_security/saml/acs/idpinitiated
Then add this endpoint to
server.xsrf.allowlist
in
opensearch_dashboards.yml
server.xsrf.allowlist
/_opendistro/_security/saml/acs/idpinitiated"
/_opendistro/_security/saml/acs"
/_opendistro/_security/saml/logout"
Docker example
Activating SAML
Running multiple authentication domains
Identity provider metadata
IdP and service provider entity ID
Time disparity compensation for JWT validation
OpenSearch Dashboards settings
Username and Role attributes
Request signing
Logout
Exchange key settings
TLS settings
Certificate validation
Client authentication
Enabled ciphers and protocols
Minimal configuration example
OpenSearch Dashboards configuration
IdP-initiated SSO
WAS THIS PAGE HELPFUL?
✔ Yes
✖ No
Tell us why
350 characters left
Thank you for your feedback!
Have a question?
Ask us on the OpenSearch forum
Want to contribute?
Edit this page
or
create an issue
OpenSearch Links
Get Involved
Code of Conduct
Forum
GitHub
Slack
Resources
About
Release Schedule
Maintenance Policy
FAQ
Testimonials
Trademark and Brand Policy
Connect
Meetup
Copyright © OpenSearch Project a Series of LF Projects, LLC
For web site terms of use, trademark policy and other project policies please see
US