LDAP integration

Lightweight Directory Access Protocol (LDAP) is often used for centralizing user authentication and authorization data. It is also used to store structured data such as employee records, contact information, and more. LDAP can handle both authentication and authorization of users accessing the Wazuh dashboard.

Authentication is the process of verifying the identity of users or systems to ensure that they provide valid credentials, such as username and password. Authorization, on the other hand, is granting access to a user or system based on their identity. It retrieves the backend roles for the user and determines what actions they are allowed to perform on the Wazuh dashboard.

In this section, we outline the required configuration to integrate LDAP with the Wazuh platform. The guide assumes you already have an LDAP server or Microsoft Active Directory.

LDAP server configuration

Depending on your LDAP server configuration, you need to create users and groups or use existing ones. You also have to obtain some information from your AD/LDAP server:

  • Create an OU for the Users (or use an already created OU). Get the DN of the OU, in our example: ou=people,dc=example,dc=org.

  • Create an OU for the Group(s) (or use an already created OU). Get the DN of the OU, in our example: ou=Groups,dc=example,dc=org.

  • Create a user with sufficient privileges to bind to the service. Get the DN of the user, in our example, this is cn=admin,dc=example,dc=org.

  • Create a group where the users with access to Wazuh will be placed, in our example this is the Administrator and readonly groups.

  • Get the FQDN of the LDAP server or Domain Controller.

Authentication and authorization configuration

The auhtc section of the Wazuh indexer security configuration file handles authentication, while the authz section handles authorization. We recommend that you back up the /etc/wazuh-indexer/opensearch-security/config.yml file before you carry out this configuration.

  1. Save the LDAP server certificate. If you don’t have access to the root CA file of the LDAP server, run the following command on the Wazuh indexer node to retrieve the certificate. Replace <FQDN_LDAP_SERVER> with the Fully Qualified Domain Name of your LDAP server:

    $ echo -n | openssl s_client -connect <FQDN_LDAP_SERVER>:636 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > ldapcacert.pem
    

    The command copies everything between -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- (including these delimiters) and saves it in a new text file.

  2. Place the certificate 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/ldapcacert.pem
    
  3. Edit the /etc/wazuh-indexer/opensearch-security/config.yml file and change the appropriate values.

    • Under the authc section, modify the LDAP configuration. Your configuration should be similar to this:

      authc:
        ldap:
          description: "Authenticate via LDAP or Active Directory"
          http_enabled: true
          transport_enabled: false
          order: 5
          http_authenticator:
            type: basic
            challenge: false
          authentication_backend:
            type: ldap
            config:
              enable_ssl: true #Set to true if LDAPS is enabled, otherwise set to false.
              pemtrustedcas_filepath: /etc/wazuh-indexer/opensearch-security/ldapcacert.pem #Required when enable_ssl is set to true
              enable_start_tls: false
              enable_ssl_client_auth: false
              verify_hostnames: true
              hosts:
              - <FQDN_LDAP_SERVER>:636 #Port 389 for LDAP, 636 for LDAPS
              bind_dn: cn=admin,dc=example,dc=org
              password: <PASSWORD>
              userbase: 'ou=people,dc=example,dc=org'
              usersearch: (cn={0})  #Depending on your LDAP schema this can be CN, sAMAccountName, etc
              username_attribute: cn
      
    • Under the authz section, modify the LDAP configuration. Your configuration should be similar to this:

      authz:
        roles_from_myldap:
          description: "Authorize via LDAP or Active Directory"
          http_enabled: true
          transport_enabled: true
          authorization_backend:
            type: ldap
            config:
              enable_ssl: true #Set to true if LDAPS is enabled, otherwise set to false.
              pemtrustedcas_filepath: /etc/wazuh-indexer/opensearch-security/ldapcacert.pem #Required when enable_ssl is set to true
              enable_start_tls: false
              enable_ssl_client_auth: false
              verify_hostnames: true
              hosts:
              - <FQDN_LDAP_SERVER>:636 #Port 389 for LDAP, 636 for LDAPS
              bind_dn: cn=admin,dc=example,dc=org
              password: <PASSWORD>
              userbase: 'ou=people,dc=example,dc=org'
              usersearch: (cn={0}) #Depending on your LDAP schema this can be cn, sAMAccountName, etc
              username_attribute: cn
              rolebase: ou=Groups,dc=example,dc=org #This is the subtree in the directory that contains the role/group
              rolesearch: '(member={0})' #Depending on your LDAP schema this can be member, memberOf, etc
              userrolename: memberof
              rolename: cn
              skip_users:
                - admin
                - kibanaserver
      

    Change the following parameters to their corresponding value:

    • pemtrustedcas_filepath

    • hosts

    • bind_dn

    • password

    • userbase

    • usersearch

    • username_attribute

    • rolebase

    • rolesearch

    • userrolename

    • rolename

  4. 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.6.0
    Contacting opensearch cluster 'opensearch' and wait for YELLOW clusterstate ...
    Clustername: wazuh-cluster
    Clusterstate: YELLOW
    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 '/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
    

Map LDAP role to Wazuh dashboard

LDAP can be used for authorization by retrieving the backend roles associated with a user. This backend role can be used to determine the access privileges of a user on the Wazuh dashboard. In this section, we map the LDAP roles to the administrator and read-only roles on the Wazuh dashboard.

Setup administrator role

Follow these steps to create a new role mapping and grant administrator permissions to the backend role.

  1. Configure the roles_mapping.yml file to map the role (CN) we have in our LDAP server to the appropriate Wazuh indexer role. In our case, we map users in the Administrator group in LDAP to the all_access role on Wazuh indexer.

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

    all_access:
      reserved: false
      hidden: false
      backend_roles:
      - "admin"
      - "Administrator"
      description: "Maps admin to all_access"
    
  2. 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.6.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 /etc/wazuh-indexer/opensearch-security
    Will update '/rolesmapping' with /etc/wazuh-indexer/opensearch-security/roles_mapping.yml
       SUCC: Configuration for 'rolesmapping' created or updated
    Done with success
    SUCC: Expected 1 config types for node {"updated_config_types":["rolesmapping"],"updated_config_size":1,"message":null} is 1 (["rolesmapping"]) due to: null
    
  3. 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, 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 to true, you need to add a role mapping on the Wazuh dashboard. To map the backend role to Wazuh, follow these steps:

    1. Click Wazuh to open the Wazuh dashboard menu, select Security, and then Roles mapping to open the page.

      Roles mapping selection
    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 administrator.

      • Custom rules: Click Add new rule to expand this field.

      • User field: backend_roles.

      • Search operation: FIND.

      • Value: Assign the name of your backend role in your LDAP server. In our case, this is a group named Administrator which contains users with administrator roles

      Create administrator new role mapping
    3. Click Save role mapping to save and map the backend role with Wazuh as administrator.

  4. Restart the Wazuh dashboard service using this command:

    # systemctl restart wazuh-dashboard
    
  5. Test the configuration. To test the configuration, go to your Wazuh dashboard URL and log in with your LDAP details.

Setup read-only role

  1. 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, select 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, assign the name of the read-only role you have in your LDAP server and click on Map to confirm the action. In our case, the backend role (CN) is readonly.

  2. 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, 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 to true, you need to add a role mapping on the Wazuh dashboard. To map the backend role to Wazuh, follow these steps:

    1. Click the upper-left menu icon to open the available options, and click Wazuh.

    2. Click Wazuh to open the Wazuh dashboard menu, select Security, and then Roles mapping to open the page.

      Roles mapping selection
    3. 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 name of your backend role in your LDAP server. In our case, this is a group named readonly which contains users with read only roles.

      Create readonly new role mapping
    4. Click Save role mapping to save and map the backend role with Wazuh as read-only.

  3. Restart the Wazuh dashboard service using this command:

    # systemctl restart wazuh-dashboard
    
  4. Test the configuration. To test the configuration, go to your Wazuh dashboard URL and log in with your LDAP details.