Setting Up Smart Monitor for Two-Factor Authentication over the OIDC Protocol
This is the third of three setup stages. First, configure the Keycloak provider and the Keycloak client.
Notation
Paths containing $OS_HOME and $OSD_HOME refer to files belonging to the respective services. If the services run on different servers, transfer the required files between them in advance.
The base addresses depend on the publishing scheme:
| Token | Description | Direct publishing | Behind a proxy |
|---|---|---|---|
<KEYCLOAK_BASE> | Keycloak base address | https://<KEYCLOAK_HOST>:8443 | https://<KEYCLOAK_HOST>/keycloak |
<OSD_BASE> | Smart Monitor Web base address | https://<OSD_HOST>:5601 | https://<OSD_HOST> |
The remaining tokens do not depend on the publishing scheme:
| Token | Description |
|---|---|
<KEYCLOAK_HOST> | external hostname of the Keycloak machine |
<OSD_HOST> | external hostname of the Smart Monitor Web machine |
<KEYCLOAK_CA> | name of the CA file that signed the certificate of the side terminating the connection: the proxy if there is one, otherwise Keycloak itself. A copy of the file is placed in the configuration directory of each service separately |
<REALM_ID> | technical realm name |
<CLIENT_ID> | technical client name, unique per host |
<CLIENT_SECRET> | client secret, the Credentials tab |
<COOKIE_PASS> | Smart Monitor Web cookie encryption key, ≥32 characters |
$OS_HOME | Smart Monitor Data Storage home directory |
$OSD_HOME | Smart Monitor Web home directory |
Setup order
Step 1. Creating a backup
cd $OS_HOME/plugins/opensearch-security/tools
sudo OPENSEARCH_JAVA_HOME=$OS_HOME/jdk/ ./securityadmin.sh \
-backup $OS_HOME/config/security-backup \
-icl -nhnv \
-cacert $OS_HOME/config/ca-cert.pem \
-cert $OS_HOME/config/admin-cert.pem \
-key $OS_HOME/config/admin-key.pem
On success, the command outputs nine SUCC: lines. Copy the backup directory off the host.
The -backup flag exports the configuration from the index, not from files on disk. The cluster must therefore be running. Create the backup once for the entire cluster on any node. Pass OPENSEARCH_JAVA_HOME on the same line because sudo clears environment variables.
Step 2. Changing the security settings
Edit config.yml and transfer the CA to every Smart Monitor Data Storage node.
File: $OS_HOME/config/opensearch-security/config.yml
2.1 Changing the authentication method
Check the challenge value in the basic authentication domain. If it is challenge: true, change it to false. Otherwise, Smart Monitor Data Storage returns WWW-Authenticate: Basic, and the browser opens its built-in sign-in dialog instead of redirecting to Keycloak. This does not affect requests from curl, Smart Monitor Data Collector, or collection agents: they send the Authorization header themselves.
2.2 Adding the OIDC domain
Add the OIDC domain to the authc section after the existing domains:
openid_auth_domain:
description: "Keycloak OIDC"
http_enabled: true
transport_enabled: false
order: 3
http_authenticator:
type: "openid"
challenge: false
config:
openid_connect_url: "<KEYCLOAK_BASE>/realms/<REALM_ID>/.well-known/openid-configuration"
subject_key: "preferred_username"
roles_key: "groups"
required_issuer: "<KEYCLOAK_BASE>/realms/<REALM_ID>"
required_audience: "<CLIENT_ID>"
openid_connect_idp:
enable_ssl: true
pemtrustedcas_filepath: $OS_HOME/config/<KEYCLOAK_CA>
authentication_backend:
type: "noop"
roles_key defines the claim from which backend roles are extracted. Without it, a user whose permissions come from Keycloak groups rather than AD signs in without roles and receives the no permissions message.
The file changes take effect only after step 6: the effective configuration is stored in the .opendistro_security index.
Keep the contents of config.yml identical on all nodes.
Step 3. Role mapping
In most cases, role mapping does not need to be changed. Permissions are assigned in one of two ways.
3.1 Through Active Directory
The authz: roles_with_ldap section applies to any authenticated user, including one who signed in through Keycloak. Smart Monitor Data Storage finds the user in AD by the sAMAccountName matching preferred_username and adds the AD groups to backend_roles.
3.2 Through matching names
A group in Keycloak is named the same as an existing backend_role.
Access to the interface is usually already granted: the kibana_user role typically has users: ["*"] set. It is therefore assigned to any authenticated user regardless of whether they have an entry in roles_mapping.yml.
Step 4. Smart Monitor Web configuration
Add the block to the end of the configuration. Do not change existing parameters.
Generate the cookie key:
head -c 48 /dev/urandom | base64 | tr -d '/+=' | head -c 48; echo
File: $OSD_HOME/config/opensearch_dashboards.yml
# 2FA
smart_monitor.auth.multiple_auth_enabled: true
smart_monitor.auth.type: ["openid", "basicauth"]
smart_monitor.openid.connect_url: "<KEYCLOAK_BASE>/realms/<REALM_ID>/.well-known/openid-configuration"
smart_monitor.openid.logout_url: "<KEYCLOAK_BASE>/realms/<REALM_ID>/protocol/openid-connect/logout"
smart_monitor.openid.client_id: "<CLIENT_ID>"
smart_monitor.openid.client_secret: "<CLIENT_SECRET>"
smart_monitor.openid.root_ca: "$OSD_HOME/config/<KEYCLOAK_CA>"
smart_monitor.openid.base_redirect_url: "<OSD_BASE>"
smart_monitor.openid.scope: "openid profile email"
smart_monitor.cookie.secure: true
smart_monitor.cookie.password: "<COOKIE_PASS>"
smart_monitor.cookie.ttl: 3600000
smart_monitor.session.ttl: 3600000
smart_monitor.session.keepalive: true
smart_monitor.ui.openid.login.buttonname: "Login with 2FA"
smart_monitor.ui.openid.login.buttonstyle: "ouiButton--fill btn-login"
smart_monitor.openid.root_ca points to the same CA as pemtrustedcas_filepath in step 2. However, a separate copy of the file is required in the Smart Monitor Web configuration directory: the process uses its own list of trusted certificates.
Keep smart_monitor.cookie.secure: true in both publishing schemes. Behind a proxy, Smart Monitor Web accepts HTTP connections, but the browser uses HTTPS. Without this setting, the cookie will not be stored.
To allow only 2FA sign-in, replace the first two lines of the block with:
smart_monitor.auth.multiple_auth_enabled: false
smart_monitor.auth.type: ["openid"]
Target configuration: domain users sign in only with the second factor, while service accounts use a password. To achieve this, change http_enabled: true to false in the ldap block of $OS_HOME/config/opensearch-security/config.yml. The consequences are described in Security considerations.
Step 5. Proxy in front of Smart Monitor Web
The step is performed only in the scheme with a proxy. With direct publishing it is skipped entirely.
The following example configures nginx on the Smart Monitor Web host.
Set the buffer sizes for id_token in the location / block in front of Smart Monitor Web:
proxy_buffer_size 32k;
proxy_buffers 8 32k;
proxy_busy_buffers_size 64k;
At the http or server level, set:
large_client_header_buffers 8 32k;
The token is passed in a cookie and headers. With the default nginx buffer sizes, the server may respond with 502 after successful authentication.
The rule for the SSO sign-in button is described in SSO login button.
nginx -t && systemctl reload nginx
Step 6. Applying the Smart Monitor Data Storage configuration
cd $OS_HOME/plugins/opensearch-security/tools
sudo OPENSEARCH_JAVA_HOME=$OS_HOME/jdk/ ./securityadmin.sh \
-f $OS_HOME/config/opensearch-security/config.yml -t config \
-icl -nhnv \
-cacert $OS_HOME/config/ca-cert.pem \
-cert $OS_HOME/config/admin-cert.pem \
-key $OS_HOME/config/admin-key.pem
Run the command once on any node: the configuration is applied to the entire cluster. There is no need to run it on every node.
Smart Monitor Data Storage does not need to be restarted: the configuration is applied dynamically. Smart Monitor Web reads its configuration file at startup, so restart it:
systemctl restart opensearch-dashboards
After signing in through Keycloak, run the request in Main Menu - Dev Tools:
GET _plugins/_security/authinfo
The user_name field contains the username from Keycloak, and backend_roles contains their groups. If the username is correct but backend_roles is empty, the groups claim was not passed. Check the client mapper.
Rolling Back Changes
Restoring the backup reverses not only the 2FA settings but also any other security configuration changes made after the backup was created.
On the host where the backup was created, run:
cd $OS_HOME/plugins/opensearch-security/tools
sudo OPENSEARCH_JAVA_HOME=$OS_HOME/jdk/ ./securityadmin.sh \
-cd $OS_HOME/config/security-backup \
-icl -nhnv \
-cacert $OS_HOME/config/ca-cert.pem \
-cert $OS_HOME/config/admin-cert.pem \
-key $OS_HOME/config/admin-key.pem
The -cd flag loads all nine security configuration files. Use it only with the backup directory. Then remove the added block from the Smart Monitor Web configuration and restart the service.
SSO login button
There is no setting for the openid sign-in button address. Add the missing route manually according to the publishing scheme.
When using a proxy, add a redirect rule. Example for nginx:
location = /auth/openid/captureUrlFragment {
if ($args) {
return 302 /auth/openid/login?$args;
}
return 302 /app/overview;
}
With direct publishing, the Login with 2FA button does not work. Open the Keycloak sign-in page through the direct link: <OSD_BASE>/auth/openid/login?nextUrl=%2Fapp%2Foverview.
Security considerations
As long as auth.type contains basicauth, the second factor remains optional: a domain user can sign in without a code. To require the second factor, set ["openid"] in Smart Monitor Web and close port 9200 with a firewall. Otherwise, direct API requests do not require the second factor.
To let only internal Smart Monitor Data Storage accounts sign in with a password while domain users authenticate through Keycloak, disable the LDAP domain for the HTTP layer in config.yml:
ldap:
http_enabled: false # was true
transport_enabled: true
Do not change the authz: roles_with_ldap section: it provides roles and continues to add AD groups for users coming from Keycloak. After this change, domain accounts can no longer authenticate with a username and password on :9200.