Keycloak is an open source identity and access management tool. It provides user federation, strong authentication, user management, and fine-grained authorization for modern applications and services. In this guide, we integrate the KeyCloak IdP to authenticate users into the Wazuh platform.
There are three stages in the single sign-on integration:
Create a new realm. Log in to the Keycloak admin console, expand the master drop-down menu and click Add Realm. Input a name in the Realm name field; in our case, this is named
Wazuh
. Click on Create to apply this configuration... thumbnail:: /images/single-sign-on/keycloak/01-create-a-new-realm.png :title: Create a new realm :align: center :width: 80%
Create a new client. In the newly created realm, navigate to Clients > Create Client and modify the following parameters:
- Client type: select
SAML
from the drop-down menu. - Client ID: input
wazuh-saml
. This is theSP Entity ID
value which will be used later in theconfig.yml
on the Wazuh indexer instance.
You can leave the rest of the values as default. Click Save to apply the configuration.
.. thumbnail:: /images/single-sign-on/keycloak/02-create-a-new-client.png :title: Create a new client :align: center :width: 80%
- Client type: select
Configure client settings.
Navigate to Clients > Settings and ensure the Enabled button is turned on. Complete the section with these parameters:
- Client ID:
wazuh-saml
- Name:
Wazuh SSO
- Valid redirect URIs:
https://<WAZUH_DASHBOARD_URL>/*
- IDP-Initiated SSO URL name:
wazuh-dashboard
- Name ID format:
username
- Force POST binding:
ON
- Include AuthnStatement:
ON
- Sign documents:
ON
- Sign assertions:
ON
- Signature algorithm:
RSA_SHA256
- SAML signature key name:
KEY_ID
- Canonicalization method:
EXCLUSIVE
- Front channel logout:
ON
Replace the
WAZUH_DASHBOARD_URL
field with the corresponding URL of your Wazuh dashboard instance.The configuration must be similar to the highlighted blue rectangles:
.. thumbnail:: /images/single-sign-on/keycloak/03-configure-client-settings.png :title: Configure client settings :align: center :width: 80%
.. thumbnail:: /images/single-sign-on/keycloak/04-configure-client-settings.png :title: Configure client settings :align: center :width: 80%
.. thumbnail:: /images/single-sign-on/keycloak/05-configure-client-settings.png :title: Configure client settings :align: center :width: 80%
.. thumbnail:: /images/single-sign-on/keycloak/06-configure-client-settings.png :title: Configure client settings :align: center :width: 80%
You can leave the rest of the values as default. Click Save to apply the configuration.
- Client ID:
Navigate to Clients > Keys and complete the section with these parameters:
- Client signature required:
Off
.. thumbnail:: /images/single-sign-on/keycloak/07-client-signature-required.png :title: Client signature required :align: center :width: 80%
- Client signature required:
Navigate to Clients > Advanced > Fine Grain SAML Endpoint Configuration and complete the section with these parameters:
- Assertion Consumer Service POST Binding URL:
https://<WAZUH_DASHBOARD_URL>/_opendistro/_security/saml/acs/idpinitiated
- Logout Service Redirect Binding URL:
https://<WAZUH_DASHBOARD_URL>/app/wazuh
.. thumbnail:: /images/single-sign-on/keycloak/08-fine-grain-saml-endpoint-configuration.png :title: Fine Grain SAML Endpoint Configuration :align: center :width: 80%
You can leave the rest of the values as default. Click Save to apply the configuration.
- Assertion Consumer Service POST Binding URL:
Create a new role. Navigate to Realm roles > Create role and complete the section with these parameters:
Role name: Input
wazuh-readonly
. This will be our backend role in the Wazuh Indexer configuration... thumbnail:: /images/single-sign-on/keycloak/read-only/09-create-a-new-role-RO.png :title: Create a new role :align: center :width: 80%
Click on Save to apply the configuration.
Create a new user.
Navigate to Users > Add user and fill in the required information.
.. thumbnail:: /images/single-sign-on/keycloak/10-create-a-new-user.png :title: Create a new user :align: center :width: 80%
Click on Create to apply the configuration.
Navigate to Users > Credentials > Set password and input a password for the newly created user. You will use these credentials to log in to the Wazuh dashboard.
.. thumbnail:: /images/single-sign-on/keycloak/11-set-password.png :title: Set password :align: center :width: 80%
Click on Save to apply the configuration.
Create a new group and assign the user.
Go to Groups > Create group and assign a name to the group. In our case, this is Wazuh read only.
.. thumbnail:: /images/single-sign-on/keycloak/read-only/12-create-a-new-group-RO.png :title: Create a new group :align: center :width: 80%
Click on the newly created group, navigate to Members > Add member and select the user created in the previous step. Click on Add to add it to the group.
.. thumbnail:: /images/single-sign-on/keycloak/13-add-member.png :title: Add member :align: center :width: 80%
In the newly created group details, go to Role Mapping > Assign role and select the
wazuh-readonly
role created in step 3. Click on Assign to apply the configuration... thumbnail:: /images/single-sign-on/keycloak/read-only/14-assign-role-RO.png :title: Assign role :align: center :width: 80%
Configure protocol mapper.
Navigate to Client scopes > role_list > Mappers > Configure a new mapper.
.. thumbnail:: /images/single-sign-on/keycloak/15-configure-a-new-mapper.png :title: Configure a new mapper :align: center :width: 80%
Select Role list from the list as seen below:
.. thumbnail:: /images/single-sign-on/keycloak/16-select-role-list.png :title: Select Role list :align: center :width: 80%
Complete the Add mapper section with these parameters:
- Mapper type:
Role list
- Name:
wazuhRoleKey
. You can use any name here. - Role attribute name:
Roles
. This will be theroles_key
on the Wazuh Indexer configuration. - SAML Attribute NameFormat:
Basic
- Single Role Attribute:
On
.. thumbnail:: /images/single-sign-on/keycloak/17-complete-the-add-mapper-section.png :title: Complete the Add mapper section :align: center :width: 80%
- Mapper type:
Click on Save to apply the configuration.
Note the necessary parameters from the SAML settings of Keycloak.
The parameters already obtained during the integration are:
sp.entity_id
:wazuh-saml
roles_key
:Roles
kibana_url
:https://<WAZUH_DASHBOARD_URL>
To obtain the remaining parameters.
- Navigate to Clients and select the name of your client. In our case, this is wazuh-saml.
- Navigate to Action > Download adapter config, and ensure the Format option is Mod Auth Mellon files.
- Click on Download to download the remaining files.
.. thumbnail:: /images/single-sign-on/keycloak/18-download-adapter-config.png :title: Download adapter config :align: center :width: 80%
The downloaded files contain the
idp.metadata.xml
file and thesp.metadata.xml
file.- The
idp.entityID
parameter is in theidp.metadata.xml
file. - The
exchange_key
parameter is found in theds:X509Certificate
field in theidp.metadata.xml
file.
.. thumbnail:: /images/single-sign-on/keycloak/19-the-exchange_key-parameter.png :title: The exchange_key parameter :align: center :width: 80%
- The
Edit the Wazuh indexer security configuration files. We recommend that you back up these files before you carry out the configuration.
Place the
idp.metadata.xml
andsp.metadata.xml
files within the/usr/share/wazuh-indexer/plugins/opensearch-security/securityconfig/
directory. Set the file ownership to wazuh-indexer using the following command:chown wazuh-indexer:wazuh-indexer /usr/share/wazuh-indexer/plugins/opensearch-security/securityconfig/idp.metadata.xml chown wazuh-indexer:wazuh-indexer /usr/share/wazuh-indexer/plugins/opensearch-security/securityconfig/sp.metadata.xml
Edit the
/usr/share/wazuh-indexer/plugins/opensearch-security/securityconfig/config.yml
file and change the following values:- Set the
order
inbasic_internal_auth_domain
to0
, and set thechallenge
flag tofalse
. - Include a
saml_auth_domain
configuration under theauthc
section similar to the following:
authc: ... basic_internal_auth_domain: description: "Authenticate via HTTP Basic against internal users database" http_enabled: true transport_enabled: true order: 0 http_authenticator: type: "basic" challenge: false authentication_backend: type: "intern" saml_auth_domain: http_enabled: true transport_enabled: false order: 1 http_authenticator: type: saml challenge: true config: idp: metadata_file: “/usr/share/wazuh-indexer/plugins/opensearch-security/securityconfig/idp.metadata.xml” entity_id: “http://192.168.XX.XX:8080/realms/Wazuh” sp: entity_id: wazuh-saml metadata_file: /usr/share/wazuh-indexer/plugins/opensearch-security/securityconfig/sp.metadata.xml kibana_url: https://<WAZUH_DASHBOARD_ADDRESS> roles_key: Roles exchange_key: 'MIICajCCAdOgAwIBAgIBAD.........' authentication_backend: type: noop
Ensure to change the following parameters to their corresponding value:
idp.metadata_file
idp.entity_id
sp.entity_id
sp.metadata_file
kibana_url
roles_key
exchange_key
- Set the
Run the
securityadmin
script to load the configuration changes made in theconfig.yml
file.# export JAVA_HOME=/usr/share/wazuh-indexer/jdk/ && bash /usr/share/wazuh-indexer/plugins/opensearch-security/tools/securityadmin.sh -f /usr/share/wazuh-indexer/plugins/opensearch-security/securityconfig/config.yml -icl -key /etc/wazuh-indexer/certs/admin-key.pem -cert /etc/wazuh-indexer/certs/admin.pem -cacert /etc/wazuh-indexer/certs/root-ca.pem -h localhost -nhnv
The
-h
flag specifies the hostname or the IP address of the Wazuh indexer node. Note that this command uses localhost, set your Wazuh indexer address if necessary.The command output must be similar to the following:
Will connect to localhost:9300 ... done Connected as CN=admin,OU=Wazuh,O=Wazuh,L=California,C=US OpenSearch Version: 1.2.4 OpenSearch Security Version: 1.2.4.0 Contacting opensearch cluster 'opensearch' and wait for YELLOW clusterstate ... Clustername: wazuh-cluster Clusterstate: GREEN Number of nodes: 1 Number of data nodes: 1 .opendistro_security index already exists, so we do not need to create one. Populate config from /home/wazuh Will update '_doc/config' with /usr/share/wazuh-indexer/plugins/opensearch-security/securityconfig/config.yml SUCC: Configuration for 'config' created or updated Done with success
Create a new role mapping for the backend role. Follow these steps to create a new role mapping, and grant read-only permissions to the backend role.
- Log into the Wazuh dashboard as administrator.
- Click the upper-left menu icon ☰ to open the options, select Security, and then Roles to open the roles page.
- Click Create role, complete the empty fields with the following parameters, and then click Create to complete the task.
- Name: Assign a name to the role.
- Cluster permissions:
cluster_composite_ops_ro
- Index:
*
- Index permissions:
read
- Tenant permissions: Select
global_tenant
and theRead only
option.
- Select the newly created role.
- Select the Mapped users tab and click Manage mapping.
- Under Backend roles, add the value of the Role name attribute in Keycloak configuration and click Map to confirm the action. In our case, the backend role is
wazuh-readonly
.
Check the value of
run_as
in the/usr/share/wazuh-dashboard/data/wazuh/config/wazuh.yml
configuration file. Ifrun_as
is set tofalse
, proceed to the next step.hosts: - default: url: https://localhost port: 55000 username: wazuh-wui password: "<wazuh-wui-password>" run_as: false
If
run_as
is set totrue
, you need to add a role mapping on the Wazuh dashboard. To map the backend role to Wazuh, follow these steps:Click the upper-left menu icon ☰ to open the available options.
Click Wazuh to open the Wazuh dashboard menu, select Security, and then Roles mapping to open the page.
.. thumbnail:: /images/single-sign-on/Wazuh-role-mapping.gif :title: Wazuh role mapping :alt: Wazuh role mapping :align: center :width: 80%
Click Create Role mapping and complete the empty fields with the following parameters:
- Role mapping name: Assign a name to the role mapping.
- Roles: Select
readonly
. - Custom rules: Click Add new rule to expand this field.
- User field:
backend_roles
- Search operation:
FIND
- Value: Assign the value of the realm role in Keycloak configuration. In our case, this is
wazuh-readonly
.
.. thumbnail:: /images/single-sign-on/keycloak/read-only/Wazuh-role-mapping-RO.png :title: Create Wazuh role mapping :alt: Create Wazuh role mapping :align: center :width: 80%
Click Save role mapping to save and map the backend role with Wazuh as read-only.
Note
For versions 4.3.9 and earlier, also replace
path: `/auth/logout`
withpath: `/logout`
in/usr/share/wazuh-dashboard/plugins/securityDashboards/server/auth/types/saml/routes.js
. We recommend that you back up these files before you carry out the configuration.... this.router.get({ path: `/logout`, validate: false ...
Edit the Wazuh dashboard configuration file. Add these configurations to
/etc/wazuh-dashboard/opensearch_dashboards.yml
. We recommend that you back up these files before you carry out the configuration.opensearch_security.auth.type: "saml" server.xsrf.whitelist: ["/_opendistro/_security/saml/acs", "/_opendistro/_security/saml/logout", "/_opendistro/_security/saml/acs/idpinitiated"]
Restart the Wazuh dashboard service using this command:
Test the configuration. Go to your Wazuh dashboard URL and log in with your Keycloak account.