Using password authentication

This method requires using a password during the enrollment process to ensure that Wazuh agents enrolled in the Wazuh manager are authenticated.

Follow the steps below to configure password authentication on different operating systems:

Prerequisites

Before a Wazuh agent can be enrolled in the Wazuh manager using the password authentication method, you must ensure the following on the Wazuh manager:

  1. Enable the password authentication option by adding the configuration highlighted below to the <auth> section of the Wazuh server configuration file /var/ossec/etc/ossec.conf:

    <auth>
      <use_password>yes</use_password>
    </auth>
    
  2. Set a password to be used for Wazuh agent enrollment. You can achieve this in two ways:

    1. Recommended - Setting your password. This is done by creating the /var/ossec/etc/authd.pass file on the Wazuh manager with your password.

      1. Replace <CUSTOM_PASSWORD> with your chosen agent enrollment password and run the following command:

        # echo "<CUSTOM_PASSWORD>" > /var/ossec/etc/authd.pass
        
      2. Change the authd.pass file permissions and ownership.

        # chmod 640 /var/ossec/etc/authd.pass
        # chown root:wazuh /var/ossec/etc/authd.pass
        
      3. Restart the Wazuh service for the changes to take effect.

        # systemctl restart wazuh-manager
        
    2. Allowing the agent enrollment service to set a random password. A new random password is generated each time the Wazuh manager service is restarted.

      1. Restart the Wazuh manager so the enrollment service generates a random password. This password is stored in /var/ossec/logs/ossec.log.

        # systemctl restart wazuh-manager
        
      2. Run the following command to get the Wazuh agent enrollment password:

        # grep "Random password" /var/ossec/logs/ossec.log
        
        2022/01/11 12:41:35 wazuh-authd: INFO: Accepting connections on port 1515. Random password chosen for agent authentication: 6258b4eb21550e4f182a08c10d94585e
        

Note

If the deployment architecture uses a multi-node cluster, ensure that password authorization is enabled on each Wazuh manager node. This prevents unauthorized agent enrollment through an unsecured Wazuh manager node. We recommend using the same enrollment password across all Wazuh manager nodes. This simplifies Wazuh agent enrollment and avoids the need to manage different passwords for each node.

Once the above prerequisites are fulfilled, you can enroll the Wazuh agent using the steps corresponding to the OS running on the endpoints with the Wazuh agent installed.

Linux/Unix

Follow these steps to enroll a Linux/Unix endpoint with password authentication:

  1. Launch the terminal, with root permission, create the /var/ossec/etc/authd.pass file with the agent enrollment password in it.

    # echo "<CUSTOM_PASSWORD>" > /var/ossec/etc/authd.pass
    
    1. Replace <CUSTOM_PASSWORD> with the agent enrollment password from the Wazuh manager.

    2. Set the file permissions for the authd.pass file to 640, and the owner should be root. You can configure the permissions and ownership by running the commands below:

      # chmod 640 /var/ossec/etc/authd.pass
      # chown root:wazuh /var/ossec/etc/authd.pass
      

      The output below shows the recommended file owner and permissions.

      -rw-r--r-- 1 root wazuh 18 Jan 11 13:03 /var/ossec/etc/authd.pass
      
  2. (Optional) To ensure the Wazuh agent can locate your password file if it is not in the default location (/var/ossec/etc/authd.pass), include the authorization_pass_path setting in the Wazuh agent configuration. Replace <PATH_TO_PASSWORD_FILE> with the filepath of the password file.

    <enrollment>
      <authorization_pass_path><PATH_TO_PASSWORD_FILE></authorization_pass_path>
    </enrollment>
    
  3. Add the Wazuh manager IP address or FQDN (Fully Qualified Domain Name) in the <client><server><address> section of the Wazuh agent configuration file /var/ossec/etc/ossec.conf. Replace <WAZUH_MANAGER_IP> with the Wazuh manager IP address or FQDN:

    <client>
       <server>
          <address><WAZUH_MANAGER_IP></address>
       ...
       </server>
    </client>
    

    This will allow the agent to enroll in the specified Wazuh manager.

  4. Restart the Wazuh agent to make the changes effective:

    # systemctl restart wazuh-agent
    
  5. Click on the upper-left menu icon and navigate to Server management > Endpoints Summary on the Wazuh dashboard to check for the newly enrolled Wazuh agent and its connection status. If the enrollment was successful, you will have an interface similar to the image below.

    Check newly enrolled Wazuh agent - Linux

Windows

Follow these steps to enroll a Windows endpoint with password authentication:

The Wazuh agent installation directory depends on the host's architecture.

  • C:\Program Files (x86)\ossec-agent for 64-bit systems.

  • C:\Program Files\ossec-agent for 32-bit systems.

  1. Launch PowerShell as an administrator.

  2. Create a file called authd.pass and save the password. Replace <CUSTOM_PASSWORD> with the agent enrollment password created on the Wazuh manager.

    For 32-bit systems

    # echo “<CUSTOM_PASSWORD>” > "C:\Program Files\ossec-agent\authd.pass"
    

    For 64-bit systems

    # echo “<CUSTOM_PASSWORD>” > "C:\Program Files (x86)\ossec-agent\authd.pass"
    
  3. (Optional) To ensure the Wazuh agent can locate your password file if it is not in the default location (C:\Program Files (x86)\ossec-agent\authd.pass), include the authorization_pass_path setting in the Wazuh agent configuration. Replace <PATH_TO_PASSWORD_FILE> with the filepath of the password file.

    <enrollment>
      <authorization_pass_path><PATH_TO_PASSWORD_FILE></authorization_pass_path>
    </enrollment>
    
  4. Add the Wazuh manager IP address or FQDN (Fully Qualified Domain Name) in the <client><server><address> section of the agent configuration file in C:\Program Files (x86)\ossec-agent\ossec.conf. Replace <WAZUH_MANAGER_IP> with the IP address or FQDN of the Wazuh manager.

    <client>
       <server>
           <address><WAZUH_MANAGER_IP></address>
          ...
       </server>
    </client>
    
  5. Restart the Wazuh agent to make the changes effective.

    # Restart-Service -Name wazuh
    
  6. Click on the upper-left menu icon and navigate to Server management > Endpoints Summary on the Wazuh dashboard to check for the newly enrolled Wazuh agent and its connection status. If the enrollment was successful, you will have an interface similar to the image below.

    Check newly enrolled Wazuh agent - Windows

macOS

Follow the steps below to enroll a macOS endpoint with password authentication:

  1. Launch the terminal, with root permission, create a file called /Library/Ossec/etc/authd.pass and save the password to it:

    # echo "<CUSTOM_PASSWORD>" > /Library/Ossec/etc/authd.pass
    
    1. Replace <CUSTOM_PASSWORD> with the agent enrollment password created on the Wazuh manager.

    2. Set the file permissions for the authd.pass file to 640 and the owner should be root. Configure the permissions and ownership by running the commands below:

      # chmod 640 /Library/Ossec/etc/authd.pass
      # chown root:wazuh /Library/Ossec/etc/authd.pass
      

      The output below shows the recommended file owner and permissions:

      -rw-r--r-- 1 root wazuh 18 Jan 11 13:03 /Library/Ossec/etc/authd.pass
      
  2. (Optional) To ensure the Wazuh agent can locate your password file if it is not in the default location (/Library/Ossec/etc/authd.pass), include the authorization_pass_path setting in the Wazuh agent configuration. Replace <PATH_TO_PASSWORD_FILE> with the filepath of the password file.

    <enrollment>
      <authorization_pass_path><PATH_TO_PASSWORD_FILE></authorization_pass_path>
    </enrollment>
    
  3. Add the Wazuh manager IP address or FQDN (Fully Qualified Domain Name) to the agent configuration file in /Library/Ossec/etc/ossec.conf. Replace <WAZUH_MANAGER_IP> with the IP address or FQDN of the Wazuh manager.

    <client>
      <server>
        <address><WAZUH_MANAGER_IP></address>
        ...
      </server>
    </client>
    
  4. Restart the Wazuh agent to make the changes effective:

    # /Library/Ossec/bin/wazuh-control restart
    
  5. Click on the upper-left menu icon and navigate to Server management > Endpoints Summary on the Wazuh dashboard to check for the newly enrolled Wazuh agent and its connection status. If the enrollment was successful, you will have an interface similar to the image below.

    Check newly enrolled Wazuh agent - macOS