authentik

authentik is an open source Identity Provider (IdP) for modern SSO. It supports SAML, OAuth2/OIDC, LDAP, RADIUS, and more. In this guide, we integrate the authentik IdP to authenticate users into the Wazuh platform.

Learn how to create administrator and read-only roles on authentik and map them to Wazuh roles in the sections below.

Setup authentik single sign-on with administrator role

Follow these steps to integrate authentik IdP with Wazuh for single sign-on and grant administrator access to the authenticated authentik users:

authentik configuration
Wazuh indexer configuration
Wazuh dashboard configuration

authentik configuration

Log in to authentik as an administrator and open the authentik Admin interface.
Create a new user.
1. Navigate to Directory > Users and click New User.
2. Set the Username, Display Name and Email address of the user.
3. Leave the other options as default and click Create User.
4. Select the newly created user, click Set password to assign a password to the user.
Create a user group in authentik.
1. Navigate to Directory > Groups and click New Group
2. Set a name for the group (for example, wazuh-administrators) and click Create Group.
3. Click the name of the newly created group and navigate to the Users tab.
4. Click Add existing user, select the previously created user, confirm the selection and click Assign.
Create a property mapping in authentik.

Navigate to Customization > Property Mappings and click Create. Create a SAML Provider Property Mapping with the following settings:
1. Name: Choose a descriptive name
2. SAML Attribute Name: Roles
3. Friendly Name: Leave blank.
4. Expression: Add the expression below, replace <ADMIN_GROUP_NAME> with the group name of the Administrator users, in our case, this is wazuh-administrators. The yield value (wazuh-admins) will be used later as the backend role in the Wazuh indexer configuration.
```
if ak_is_group_member(request.user, name="<ADMIN_GROUP_NAME>"):
    yield "wazuh-admins"
```
5. Click Finish.
Navigate to Applications > Applications and click Create with Provider to create an application and provider pair.
1. Application: Provide a descriptive Application Name (for example, Wazuh) and use the following required configuration. Replace <WAZUH_DASHBOARD_URL> with the corresponding value.
  - Slug: Provide a name or accept the auto-provided name.
  - Policy engine mode: ANY.
  - Launch URL: https://<WAZUH_DASHBOARD_URL>
  - Leave other values as default and click Next to proceed to the next step.
2. Choose a Provider type: Select SAML Provider as the provider type.
3. Configure Provider: Provide a name or accept the auto-provided name. Leave the authorization flow as default, and add the following required configurations. Replace <WAZUH_DASHBOARD_URL> with the corresponding value.
  - ACS URL: https://<WAZUH_DASHBOARD_URL>/_opendistro/_security/saml/acs
  - Issuer: wazuh-saml
  - Audience: wazuh-saml
  - Under Advanced protocol settings:
    - Property Mappings: add the Property Mapping you created in the previous section.
    - NameID Property Mapping: select a property mapping that will be used for Wazuh usernames (for example, authentik default SAML Mapping: Name or authentik default SAML Mapping: Email). Leave other values as default and click Next to proceed to the next step.
4. Configure Bindings: Leave as default and click Next to proceed to the next step.
5. Review and Submit Application: Review the configuration and click Submit.
Download metadata file
1. Navigate to Applications > Providers and click on the name of the provider that you created in the previous section (for example, Provider for Wazuh).
2. Under Related objects > Metadata, click on Download. Save the file as wazuh_authentik_meta.xml. This downloaded file is your SAML Metadata file and it will be required in the next section.

Wazuh indexer configuration

Edit the Wazuh indexer security configuration files. We recommend that you back up these files before you carry out the configuration.

Backup the existing Wazuh indexer security configuration files:

# /usr/share/wazuh-indexer/bin/indexer-security-init.sh --options "-backup /etc/wazuh-indexer/opensearch-security -icl -nhnv"

Generate a 64-character long random key using the following command.
```
# openssl rand -hex 32
```
The output will be used as the exchange_key in the /etc/wazuh-indexer/opensearch-security/config.yml file.
Place the wazuh_authentik_meta.xml file within the /etc/wazuh-indexer/opensearch-security/ directory. Set the file ownership to wazuh-indexer using the following command:
```
# chown wazuh-indexer:wazuh-indexer /etc/wazuh-indexer/opensearch-security/wazuh_authentik_meta.xml
```

Edit the /etc/wazuh-indexer/opensearch-security/config.yml file and change the following values:

Set the order in basic_internal_auth_domain to 0, and set the challenge flag to false.
Include a saml_auth_domain configuration under the authc 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: '/etc/wazuh-indexer/opensearch-security/wazuh_authentik_meta.xml'
          entity_id: 'wazuh-saml'
        sp:
          entity_id: 'wazuh-saml'
        kibana_url: https://<WAZUH_DASHBOARD_URL>
        roles_key: Roles
        exchange_key: 'b1d6dd32753374557dcf92e241.......'
    authentication_backend:
      type: noop

Ensure to change the following parameters to their corresponding value:

idp.metadata_file
idp.entity_id
sp.entity_id
kibana_url
roles_key
exchange_key

Run the securityadmin script to load the configuration changes made in the config.yml file.

# export JAVA_HOME=/usr/share/wazuh-indexer/jdk/ && bash /usr/share/wazuh-indexer/plugins/opensearch-security/tools/securityadmin.sh -f /etc/wazuh-indexer/opensearch-security/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:

Security Admin v7
Will connect to localhost:9200 ... done
Connected as "CN=admin,OU=Wazuh,O=Wazuh,L=California,C=US"
OpenSearch Version: 2.19.4
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-user
Will update '/config' with /etc/wazuh-indexer/opensearch-security/config.yml
   SUCC: Configuration for 'config' created or updated
SUCC: Expected 1 config types for node {"updated_config_types":["config"],"updated_config_size":1,"message":null} is 1 (["config"]) due to: null
Done with success

Edit the /etc/wazuh-indexer/opensearch-security/roles_mapping.yml file and change the following values:

Configure the roles_mapping.yml file to associate the property mapping in authentik to the appropriate Wazuh indexer role; in our case, we map this to the all_access role.
```
all_access:
  reserved: false
  hidden: false
  backend_roles:
  - "wazuh-admins"
```

Run the securityadmin script to load the configuration changes made in the roles_mapping.yml file.

# export JAVA_HOME=/usr/share/wazuh-indexer/jdk/ && bash /usr/share/wazuh-indexer/plugins/opensearch-security/tools/securityadmin.sh -f /etc/wazuh-indexer/opensearch-security/roles_mapping.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:

Security Admin v7
Will connect to localhost:9200 ... done
Connected as "CN=admin,OU=Wazuh,O=Wazuh,L=California,C=US"
OpenSearch Version: 2.19.4
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-user
Will update '/rolesmapping' with /etc/wazuh-indexer/opensearch-security/roles_mapping.yml
   SUCC: Configuration for 'rolesmapping' created or updated
SUCC: Expected 1 config types for node {"updated_config_types":["rolesmapping"],"updated_config_size":1,"message":null} is 1 (["rolesmapping"]) due to: null
Done with success

Wazuh dashboard configuration

Check the value of run_as in the /usr/share/wazuh-dashboard/data/wazuh/config/wazuh.yml configuration file. If run_as is set to false, change it to true. This is required to create a role mapping in the Wazuh dashboard, ensuring the backend role provided by the IdP is correctly mapped to the corresponding Wazuh role.
```
hosts:
  - default:
      url: https://localhost
      port: 55000
      username: wazuh-wui
      password: "<WAZUH_WUI_PASSWORD>"
      run_as: true
```
Click ☰ to open the menu on the Wazuh dashboard, go to Server management → Security, and then Roles mapping to open the page
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 administrator.
- Custom rules: Click Add new rule to expand this field.
- User field: backend_roles
- Search operation: FIND
- Value: Assign the yield value configured in the authentik property mapping configuration. In our case, this is wazuh-admins.
- Click Save role mapping to save and map the backend role with Wazuh as administrator.

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.multiple_auth_enabled: true
opensearch_security.auth.type: ["basicauth","saml"]
server.xsrf.allowlist: ["/_opendistro/_security/saml/acs", "/_opendistro/_security/saml/logout", "/_opendistro/_security/saml/acs/idpinitiated"]

Restart the Wazuh dashboard service using this command:
```
# systemctl restart wazuh-dashboard
```
To test the configuration, go to your Wazuh dashboard URL and log in with your authentik account.

Setup authentik single sign-on with read-only role

Follow these steps to integrate authentik IdP with Wazuh for single sign-on and grant read-only role to the authenticated authentik users on the Wazuh platform:

authentik configuration
Wazuh indexer configuration
Wazuh dashboard configuration

authentik configuration

Log in to authentik as an administrator and open the authentik Admin interface.
Create a new user
1. Navigate to Directory > Users and click New User.
2. Set the Username, Display Name and Email address of the user.
3. Leave the other options as default and click Create User.
4. Select the newly created user, click Set password to assign a password to the user.
Create a user group in authentik
1. Navigate to Directory > Groups and click New Group
2. Set a name for the group (for example, wazuh-ro-group) and click Create Group.
3. Click the name of the newly created group and navigate to the Users tab.
4. Click Add existing user, select the previously created user, confirm the selection and click Assign.
Create a property mapping in authentik

Navigate to Customization > Property Mappings and click Create. Create a SAML Provider Property Mapping with the following settings. If you have previously configured authentik with Wazuh administrator role, update the existing SAML Provider Property Mapping setting:
1. Name: Choose a descriptive name
2. SAML Attribute Name: Roles
3. Friendly Name: Leave blank.
4. Expression: If you have previously configured authentik with Wazuh administrator role, add the expression below and update the property mapping. The yield value (wazuh-readonly) will be used later as the backend role in the Wazuh indexer configuration.
```
if ak_is_group_member(request.user, name="<ADMIN_GROUP_NAME>"):
    yield "wazuh-admins"
elif ak_is_group_member(request.user, name="<READONLY_GROUP_NAME>"):
    yield "wazuh-readonly"
```
  If you are setting up authentik with Wazuh read-only role only, add the expression below and click Finish. The yield value (wazuh-readonly) will be used later as the backend role in the Wazuh indexer configuration.
```
if ak_is_group_member(request.user, name="<READONLY_GROUP_NAME>"):
    yield "wazuh-readonly"
```
  Where:
  - <ADMIN_GROUP_NAME> is the group name of the administrator users.
  - <READONLY_GROUP_NAME> is the group name of the read-only users.
Navigate to Applications > Applications and click Create with Provider to create an application and provider pair. Skip this step if you have previously configured authentik with Wazuh administrator role.
1. Application: Provide a descriptive Application Name (for example, Wazuh) and use the following required configuration. Replace <WAZUH_DASHBOARD_URL> with the corresponding value.
  - Slug: Provide a name or accept the auto-provided name.
  - Policy engine mode: ANY.
  - Launch URL: https://<WAZUH_DASHBOARD_URL>
  - Leave other values as default and click Next to proceed to the next step.
2. Choose a Provider type: Select SAML Provider as the provider type.
3. Configure Provider: Provide a name or accept the auto-provided name. Leave the authorization flow as default, and add the following required configurations. Replace <WAZUH_DASHBOARD_URL> with the corresponding value.
  - ACS URL: https://<WAZUH_DASHBOARD_URL>/_opendistro/_security/saml/acs
  - Issuer: wazuh-saml
  - Audience: wazuh-saml
  - Under Advanced protocol settings:
    - Property Mappings: add the Property Mapping you created in the previous section.
    - NameID Property Mapping: select a property mapping that will be used for Wazuh usernames (for example, authentik default SAML Mapping: Name or authentik default SAML Mapping: Email). Leave other values as default and click Next to proceed to the next step.
4. Configure Bindings: Leave as default and click Next to proceed to the next step.
5. Review and Submit Application: Review the configuration and click Submit.
Download metadata file
1. Navigate to Applications > Providers and click on the name of the provider that you created in the previous section (for example, Provider for Wazuh).
2. Under Related objects > Metadata, click on Download. Save the file as wazuh_authentik_meta.xml. This downloaded file is your SAML Metadata file and it will be required in the next section.

Wazuh indexer configuration

Edit the Wazuh indexer security configuration files. We recommend that you back up these files before you carry out the configuration.

Backup the existing Wazuh indexer security configuration files:

# /usr/share/wazuh-indexer/bin/indexer-security-init.sh --options "-backup /etc/wazuh-indexer/opensearch-security -icl -nhnv"

Generate a 64-character long random key using the following command.
```
# openssl rand -hex 32
```
The output will be used as the exchange_key in the /etc/wazuh-indexer/opensearch-security/config.yml file.
Place the wazuh_authentik_meta.xml file within the /etc/wazuh-indexer/opensearch-security/ directory. Set the file ownership to wazuh-indexer using the following command:
```
# chown wazuh-indexer:wazuh-indexer /etc/wazuh-indexer/opensearch-security/wazuh_authentik_meta.xml
```

Edit the /etc/wazuh-indexer/opensearch-security/config.yml file and change the following values:

Set the order in basic_internal_auth_domain to 0, and set the challenge flag to false.
Include a saml_auth_domain configuration under the authc 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: '/etc/wazuh-indexer/opensearch-security/wazuh_authentik_meta.xml'
          entity_id: 'wazuh-saml'
        sp:
          entity_id: 'wazuh-saml'
        kibana_url: https://<WAZUH_DASHBOARD_URL>
        roles_key: Roles
        exchange_key: 'b1d6dd32753374557dcf92e241.......'
    authentication_backend:
      type: noop

Ensure to change the following parameters to their corresponding value:

idp.metadata_file
idp.entity_id
sp.entity_id
kibana_url
roles_key
exchange_key

Run the securityadmin script to load the configuration changes made in the config.yml file.

# export JAVA_HOME=/usr/share/wazuh-indexer/jdk/ && bash /usr/share/wazuh-indexer/plugins/opensearch-security/tools/securityadmin.sh -f /etc/wazuh-indexer/opensearch-security/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:

Security Admin v7
Will connect to localhost:9200 ... done
Connected as "CN=admin,OU=Wazuh,O=Wazuh,L=California,C=US"
OpenSearch Version: 2.19.4
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-user
Will update '/config' with /etc/wazuh-indexer/opensearch-security/config.yml
   SUCC: Configuration for 'config' created or updated
SUCC: Expected 1 config types for node {"updated_config_types":["config"],"updated_config_size":1,"message":null} is 1 (["config"]) due to: null
Done with success

Wazuh dashboard configuration

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.
1. Log into the Wazuh dashboard as administrator.
2. Click the upper-left menu icon ☰ to open the options, go to Indexer management → Security, and then Roles to open the roles page.
3. 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: global_tenant and select the Read only option.
4. Select the newly created role.
5. Select the Mapped users tab and click Manage mapping.
6. Under Backend roles, add the yield value in authentik 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. If run_as is set to false, change it to true. This is required to create a role mapping in the Wazuh dashboard, ensuring the backend role provided by the IdP is correctly mapped to the corresponding Wazuh role.
```
hosts:
  - default:
      url: https://localhost
      port: 55000
      username: wazuh-wui
      password: "<WAZUH_WUI_PASSWORD>"
      run_as: true
```
1. Click ☰ to open the menu on the Wazuh dashboard, go to Server management → Security, and then Roles mapping to open the page.
2. 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 yield value configured in the authentik property mapping configuration. In our case, this is wazuh-readonly.
  - Click Save role mapping to save and map the backend role with Wazuh as read-only.

opensearch_security.auth.multiple_auth_enabled: true
opensearch_security.auth.type: ["basicauth","saml"]
server.xsrf.allowlist: ["/_opendistro/_security/saml/acs", "/_opendistro/_security/saml/logout", "/_opendistro/_security/saml/acs/idpinitiated"]

Restart the Wazuh dashboard service using this command:
```
# systemctl restart wazuh-dashboard
```
To test the configuration, go to your Wazuh dashboard URL and log in with your authentik account.