Field guide

Wazuh Dashboard Authorization-Token Troubleshooting

Alerts to Answers Analyst Field Guide 02 - v20

Introduction

This guide addresses authorization-token failures that prevent the Wazuh application from authenticating or communicating normally with the server API. It separates the visible Dashboard symptom from the service, API, manager-process, certificate, RBAC, and resource conditions that can cause it.

Purpose and Scope

Use the workflow to preserve evidence, identify the failed layer, and justify a controlled restart only when the collected evidence supports it. The guide is designed for the validated Wazuh lab and is not a substitute for an organization's production incident or change-management process.

Chapter and Lab Alignment

Alignment	Placement
Primary chapter alignment	Chapter 9 - Operating the Platform
Supporting chapter alignment	Chapter 4 - Dashboard and Investigations
Lab alignment	Primary: Lab 0 and Lab 9. Supporting: Labs 1-4.
Recommended point of use	Use when authentication fails, Error 3002 appears, or the API returns HTTP 500.

Symptom

The Wazuh application reports that it cannot obtain an authorization token, sometimes with Error 3002 and an HTTP 500 response from:

POST /security/user/authenticate

An HTTP 500 response indicates a server-side failure. It does not prove that the Dashboard service is the root cause.

1. Preserve the Evidence

Record the time, affected user, Dashboard URL, exact error, and recent configuration or service changes before restarting anything.

2. Check Component Health

sudo systemctl --no-pager --full status wazuh-manager
sudo systemctl --no-pager --full status wazuh-dashboard
sudo /var/ossec/bin/wazuh-control status

Use systemctl for service control. Use wazuh-control status to inspect the Wazuh manager processes.

3. Verify the API Listener

The Wazuh server API uses TCP 55000 by default:

sudo ss -lntp | grep ':55000'

A listener confirms that a process owns the port; it does not prove authentication is healthy.

4. Inspect the API Log

Depending on API log format, the active log is api.log or api.json:

sudo ls -l /var/ossec/logs/api.log /var/ossec/logs/api.json 2>/dev/null
sudo tail -n 100 /var/ossec/logs/api.log 2>/dev/null
sudo tail -n 100 /var/ossec/logs/api.json 2>/dev/null

Correlate entries with the recorded failure time. Look for unavailable daemons, authentication/RBAC errors, certificate problems, malformed requests, resource exhaustion, or startup failures.

5. Inspect Manager Processes and Journal

If the API reports an unavailable daemon, verify that daemon rather than assuming the historical wazuh-execd incident applies:

sudo /var/ossec/bin/wazuh-control status
sudo journalctl -u wazuh-manager --since "YYYY-MM-DD HH:MM:SS" --no-pager

For an execd finding specifically:

pgrep -a -x wazuh-execd

No output supports the finding that the process is absent. Do not start individual Wazuh daemons manually during routine troubleshooting.

6. Perform a Controlled Restart When Justified

After logs and process evidence identify the manager as the affected layer:

sudo systemctl restart wazuh-manager
sudo systemctl --no-pager --full status wazuh-manager
sudo /var/ossec/bin/wazuh-control status

Then refresh the Dashboard and retest authentication. Restarting the Dashboard is unnecessary when restoring manager/API health resolves the failure.

Escalation

Escalate instead of repeatedly restarting when:

the manager or API immediately fails again;
logs identify certificate, RBAC, disk, memory, or configuration errors;
multiple nodes disagree about daemon health;
the problem follows an upgrade or unsupported customization.

Validation Checklist

Validation check	Validation check
☐ Exact failure and time recorded	☐ Correct API log format inspected
☐ Manager and Dashboard service state checked	☐ Manager journal correlated with the failure
☐ Wazuh daemon state checked	☐ Restart performed only when evidence justified it
☐ API listener checked	☐ Authentication retested and result documented

Technical References

Wazuh documentation: server API requests, authentication, logs, and timeouts (https://documentation.wazuh.com/current/user-manual/api/requests-responses.html); architecture and required ports (https://documentation.wazuh.com/current/getting-started/architecture.html); and wazuh-control (https://documentation.wazuh.com/current/user-manual/reference/tools/wazuh-control.html).