From 824e4a9245f24686261f6c5ff96ee29a63e22412 Mon Sep 17 00:00:00 2001 From: Chris Moore <107723039+cwillum@users.noreply.github.com> Date: Wed, 2 Nov 2022 12:42:00 -0700 Subject: [PATCH] Configuring Dashboards multi-authentication sign-in window (#1549) * fix#1488-multi-authc Signed-off-by: cwillum * fix#1488-multi-authc Signed-off-by: cwillum * fix#1488-multi-authc Signed-off-by: cwillum * fix#1488-multi-authc Signed-off-by: cwillum * fix#1488-multi-authc Signed-off-by: cwillum * fix#1488-multi-authc Signed-off-by: cwillum * fix#1488-multi-authc Signed-off-by: cwillum * fix#1488-multi-authc Signed-off-by: cwillum * fix#1488-multi-authc Signed-off-by: cwillum * fix#1488-multi-authc Signed-off-by: cwillum * fix#1488-multi-authc Signed-off-by: cwillum * fix#1488-multi-authc Signed-off-by: cwillum * fix#1488-multi-authc Signed-off-by: cwillum * fix#1488-multi-authc Signed-off-by: cwillum * fix#1488-multi-authc Signed-off-by: cwillum * fix#1488-multi-authc-fin Signed-off-by: cwillum * fix#1488-multi-authc-fin Signed-off-by: cwillum * fix#1488-multi-authc-fin Signed-off-by: cwillum * fix#1488-multi-authc-fin Signed-off-by: cwillum * fix#1488-multi-auth-editorial Signed-off-by: cwillum * fix#1488-multi-auth-editorial Signed-off-by: cwillum Signed-off-by: cwillum --- _security-plugin/configuration/multi-auth.md | 132 ++++++++++++++++++ .../configuration/openid-connect.md | 6 +- _security-plugin/configuration/saml.md | 3 + _security-plugin/configuration/yaml.md | 2 +- 4 files changed, 140 insertions(+), 3 deletions(-) create mode 100644 _security-plugin/configuration/multi-auth.md diff --git a/_security-plugin/configuration/multi-auth.md b/_security-plugin/configuration/multi-auth.md new file mode 100644 index 00000000..25605b28 --- /dev/null +++ b/_security-plugin/configuration/multi-auth.md @@ -0,0 +1,132 @@ +--- +layout: default +title: Multiple authentication options for Dashboards sign-in +parent: Configuration +nav_order: 3 +--- + +# Configure Dashboards sign-in for multiple authentication options + +You can configure the sign-in window for OpenSearch Dashboards to provide either a single option for authenticating users at sign-in or multiple options. Currently, Dashboards supports basic authentication, OpenID Connect, and SAML as the multiple options. + +## General steps for configuring multiple authentication options + +Consider the following sequence of steps before configuring the sign-in window for multiple authentication options. + +1. Decide which types of authentication to make available at sign-in. +1. Configure each authentication type, including an authentication domain for the identity provider (IdP) and the essential settings that give each type sign-in access to OpenSearch Dashboards. For OpenId Connect backend configuration, see [OpenID Connect]({{site.url}}{{site.baseurl}}/security-plugin/configuration/openid-connect/). For SAML backend configuration, see [SAML]({{site.url}}{{site.baseurl}}/security-plugin/configuration/saml/). +1. Add, enable, and configure multiple option authentication settings in the `opensearch_dashboards.yml` file. + +## Enabling multiple authentication options + +By default, Dashboards provides basic authentication for sign-in. To enable multiple options for authentication, begin by adding `opensearch_security.auth.multiple_auth_enabled` to the `opensearch_dashboards.yml` file and setting it to `true`. + +To specify the multiple authentication types as options during sign-in, add the `opensearch_security.auth.type` setting to the `opensearch_dashboards.yml` file and enter multiple types as values. When more than one authentication type is added to the setting, the Dashboards sign-in window recognizes multiple types and adjusts to accommodate the sign-in options. + +When setting up Dashboards to provide multiple authentication options, basic authentication is always required as one of the values for the setting. +{: .note } + +Add a single value to the setting when only one authentication type is needed. + +```yml +opensearch_security.auth.type: "openid" +``` + +For multiple authentication options, add values to the setting as an array separated by commas. As a reminder, Dashboards currently supports a combination of basic authentication, OpenID Connect, and SAML as a valid set of values. In the setting, these values are expressed as `"basicauth"`, `"openid"`, and `"saml"`. + +```yml +opensearch_security.auth.type: ["basicauth","openid"] +opensearch_security.auth.multiple_auth_enabled: true +``` + +```yml +opensearch_security.auth.type: ["basicauth","saml"] +opensearch_security.auth.multiple_auth_enabled: true +``` + +```yml +opensearch_security.auth.type: ["basicauth","saml","openid"] +opensearch_security.auth.multiple_auth_enabled: true +``` + +When the `opensearch_security.auth.type` setting contains `basicauth` and one other authentication type, the sign-in window appears as in the following example. + +Basic authentication and one other type in the sign-in window + +With all three valid authentication types specified, the sign-in window appears as in the following example. + +All three authentication types specified in the sign-in window + +## Customizing the sign-in environment + +In addition to the essential sign-in settings for each authentication type, you can configure additional settings in the `opensearch_dashboards.yml` file to customize the sign-in window so that it clearly represents the options that are available. For example, you can replace the label on the sign-in button with the name and icon of the IdP. Refer to the settings and descriptions that follow. + +Multi-option sign-in window with with some customization + +### Basic authentication settings + +These settings allow you to customize the basic username and password sign-in button. + +Setting | Description +:--- | :--- |:--- |:--- | +`opensearch_security.ui.basicauth.login.brandimage` | Login button logo. Supported file types are SVG, PNG, and GIF. +`opensearch_security.ui.basicauth.login.showbrandimage` | Determines whether a logo for the login button is displayed or not. Default is `true`. + +### OpenID Connect authentication settings + +These settings allow you to customize the sign-in button associated with OpenID Connect authentication. For the essential settings required to use OpenID Connect as a single sign-in option, see [OpenSearch Dashboards single sign-on]({{site.url}}{{site.baseurl}}/security-plugin/configuration/openid-connect/#opensearch-dashboards-single-sign-on). + +Setting | Description +:--- | :--- |:--- |:--- | +`opensearch_security.ui.openid.login.buttonname` | Display name for the login button. "Log in with single sign-on" by default. +`opensearch_security.ui.openid.login.brandimage` | Login button logo. Supported file types are SVG, PNG, and GIF. +`opensearch_security.ui.openid.login.showbrandimage` | Determines whether a logo for the login button is displayed or not. Default is `false`. + +### SAML authentication settings + +These settings allow you to customize the sign-in button associated with SAML authentication. For the essential settings required to use SAML as a sign-in option, see [OpenSearch Dashboards configuration]({{site.url}}{{site.baseurl}}/security-plugin/configuration/saml/#opensearch-dashboards-configuration). + +Setting | Description +:--- | :--- |:--- |:--- | +`opensearch_security.ui.saml.login.buttonname` | Display name for the login button. "Log in with single sign-on" by default. +`opensearch_security.ui.saml.login.brandimage` | Login button logo. Supported file types are SVG, PNG, and GIF. +`opensearch_security.ui.saml.login.showbrandimage` | Determines whether a logo for the login button is displayed or not. Default is `false`. + +## Sample setup +The following example shows basic settings in the `opensearch_dashboards.yml` file when it is configured for two types of authentication at sign-in. + +```yml +# The several settings directly below are typical of all `opensearch_dashboards.yml` configurations. # +server.host: 0.0.0.0 +server.port: 5601 +opensearch.hosts: ["https://localhost:9200"] +opensearch.ssl.verificationMode: none +opensearch.username: +opensearch.password: +opensearch.requestHeadersAllowlist: ["securitytenant","Authorization"] +opensearch_security.multitenancy.enabled: true +opensearch_security.multitenancy.tenants.preferred: ["Private", "Global"] +opensearch_security.readonly_mode.roles: [""] + +# Settings that enable multiple option authentication in the sign-in window # +opensearch_security.auth.multiple_auth_enabled: true +opensearch_security.auth.type: ["basicauth","openid"] + +# Basic authentication customization # +opensearch_security.ui.basicauth.login.brandimage: +opensearch_security.ui.basicauth.login.showbrandimage: true + +# OIDC auth customization and start settings # +opensearch_security.ui.openid.login.buttonname: Log in with +opensearch_security.ui.openid.login.brandimage: +opensearch_security.ui.openid.login.showbrandimage: true + +opensearch_security.openid.base_redirect_url: <"OIDC redirect URL"> +opensearch_security.openid.verify_hostnames: false +opensearch_security.openid.refresh_tokens: false +opensearch_security.openid.logout_url: <"OIDC logout URL"> + +opensearch_security.openid.connect_url: <"OIDC connect URL"> +opensearch_security.openid.client_id: +opensearch_security.openid.client_secret: +``` diff --git a/_security-plugin/configuration/openid-connect.md b/_security-plugin/configuration/openid-connect.md index 0a5281fc..08da9739 100755 --- a/_security-plugin/configuration/openid-connect.md +++ b/_security-plugin/configuration/openid-connect.md @@ -21,7 +21,7 @@ The security plugin can integrate with identify providers that use the OpenID Co You can change the keys used for signing the JWTs directly in your IdP. If the security plugin detects an unknown key, it tries to retrieve it from the IdP. This rollover is transparent to the user. -* OpenSearch Dashboards single sign-on +* OpenSearch Dashboards as single sign-on or as one option among multiple authentication types in the Dashboards sign-in window. ## Configure OpenID Connect integration @@ -270,7 +270,7 @@ OpenID Connect providers usually publish their configuration in JSON format unde Beyond the ID, each client also has a client secret assigned. The client secret is usually generated when the client is created. Applications can obtain an identity token only when they provide a client secret. You can find this secret in the settings of the client on your IdP. -### Configuration parameters +### Configuration settings Name | Description :--- | :--- @@ -313,6 +313,8 @@ opensearch.ssl.verificationMode: none opensearch.requestHeadersAllowlist: ["Authorization", "security_tenant"] ``` +To include OpenID Connect with other authentication types in the Dashboards sign-in window, see [Multiple option authentication for Dashboards sign-in]({{site.url}}{{site.baseurl}}/security-plugin/configuration/multi-auth/). +{: .note } ### OpenSearch security configuration diff --git a/_security-plugin/configuration/saml.md b/_security-plugin/configuration/saml.md index fb27033a..83dfb4e1 100755 --- a/_security-plugin/configuration/saml.md +++ b/_security-plugin/configuration/saml.md @@ -314,6 +314,9 @@ If you use the logout POST binding, you also need to ad the logout endpoint to y 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 [Multiple option authentication for Dashboards sign-in]({{site.url}}{{site.baseurl}}/security-plugin/configuration/multi-auth/). +{: .note } + ### IdP-initiated SSO To use IdP-initiated SSO, set the Assertion Consumer Service endpoint of your IdP to this: diff --git a/_security-plugin/configuration/yaml.md b/_security-plugin/configuration/yaml.md index 6b1e7e90..12c587fc 100644 --- a/_security-plugin/configuration/yaml.md +++ b/_security-plugin/configuration/yaml.md @@ -2,7 +2,7 @@ layout: default title: YAML files parent: Configuration -nav_order: 3 +nav_order: 4 --- # YAML files