Skip to main content
The Wazuh Dashboard supports multiple authentication methods for connecting to the Wazuh Server API and controlling user access. This guide explains the available authentication modes and configuration options.

​
Wazuh Server API Authentication

​
Basic Authentication

The Dashboard connects to the Wazuh Server API using configured credentials. These credentials are defined in the opensearch_dashboards.yml file under the wazuh_core.hosts section.

​
Configuration Structure

wazuh_core.hosts:
  default:
    url: https://localhost
    port: 55000
    username: wazuh-wui
    password: wazuh-wui
    run_as: false

​
Multiple API Hosts

You can configure multiple Wazuh Server API hosts to connect to different environments or clusters: 
wazuh_core.hosts:
  production:
    url: https://wazuh-prod.example.com
    port: 55000
    username: wazuh-wui
    password: MyS3cr37P450r.*-
    run_as: true
  development:
    url: https://wazuh-dev.example.com
    port: 55000
    username: wazuh-wui
    password: DevP4ssw0rd
    run_as: false
  testing:
    url: https://wazuh-test.example.com
    port: 55000
    username: wazuh-wui
    password: TestP4ssw0rd
    run_as: true

​
API Host Configuration Parameters

​
URL

Parameter: url Type: String Default: https://localhost Description: The Wazuh Server API URL. Must be a valid URL starting with http:// or https://. Validation: Non-empty string

​
Port

Parameter: port Type: Number Default: 55000 Range: 1-65535 Description: The port number where the Wazuh Server API is listening. Validation: Integer between 1 and 65535

​
Username

Parameter: username Type: String Default: wazuh-wui Description: The username for authenticating to the Wazuh Server API. Validation:
  • Non-empty string
  • Minimum 4 characters
  • Maximum 64 characters

​
Password

Parameter: password Type: String (sensitive) Default: wazuh-wui Description: The password for the specified username. Validation:
  • Non-empty string
  • Maximum 64 characters
Security Note: Ensure proper file permissions on opensearch_dashboards.yml to protect password values.

​
Run As Mode

Parameter: run_as Type: Boolean Default: true Description: Enables the authentication context feature, allowing the Dashboard to execute API requests using the logged-in user’s credentials rather than the configured API user. Values:
  • true: Enable run_as mode (RBAC enabled)
  • false: Disable run_as mode

​
Run As Authentication Mode

​
Overview

The run_as parameter controls how the Dashboard authenticates with the Wazuh Server API. This feature implements Role-Based Access Control (RBAC) by executing API requests in the context of the logged-in Dashboard user.

​
How Run As Works

​
When run_as is Enabled (true)

  1. User authenticates to the Dashboard through OpenSearch Security
  2. Dashboard receives the user’s credentials from the authentication context
  3. Dashboard makes API requests to Wazuh Server using the logged-in user’s credentials
  4. Wazuh Server enforces permissions based on the user’s role assignments
  5. Users see only the data they have permission to access

​
When run_as is Disabled (false)

  1. User authenticates to the Dashboard through OpenSearch Security
  2. Dashboard makes all API requests using the configured API credentials (wazuh-wui)
  3. All users share the same API access level
  4. User-level RBAC is not enforced at the Wazuh Server level

​
Requirements for Run As Mode

Server API Configuration: The Wazuh Server API must have allow_run_as enabled in its configuration: 
<api>
  <auth>
    <allow_run_as>yes</allow_run_as>
  </auth>
</api>
User Requirements:
  • When run_as is enabled, the Dashboard username must be wazuh-wui
  • Users logging into the Dashboard must exist in both OpenSearch Security and Wazuh Server
  • User roles must be properly configured in Wazuh Server to define access permissions

​
Run As Status Codes

The Dashboard health check system verifies run_as configuration and reports one of the following statuses:
Status CodeDescription
EnabledRun as allowed for user and host
Host DisabledRun as disabled in the Wazuh Server configuration
All DisabledRun as disabled in both host and user configuration
User Not AllowedRun as not permitted for the configured user
Unable to CheckCannot verify run_as permission status

​
Checking Run As Status

The Dashboard automatically checks the run_as status during initialization. Review the Dashboard logs or health check results to verify the configuration: 
Server API hosts with run_as permission enabled: production, testing
If run_as is not properly enabled, you will see a warning: 
Some server API hosts have not enabled the run_as or the user has no the ability to use it

​
OpenSearch Security Integration

The Dashboard integrates with OpenSearch Security for user authentication and session management.

​
Security Plugin Configuration

opensearch_security.multitenancy.enabled: false
opensearch_security.readonly_mode.roles: ['kibana_read_only']

​
Request Headers

For proper authentication context propagation, configure the request headers allowlist: OpenSearch Dashboards 2.0+: 
opensearch.requestHeadersAllowlist: ['securitytenant', 'Authorization']
OpenSearch Dashboards 1.x: 
opensearch.requestHeadersWhitelist: ['securitytenant', 'Authorization']

​
Authentication Workflow

​
User Login Process

  1. User accesses the Dashboard URL
  2. OpenSearch Security intercepts the request
  3. User is redirected to the login page (or IdP if SSO is configured)
  4. User provides credentials
  5. OpenSearch Security validates credentials
  6. Session is created and user is granted access to the Dashboard
  7. Dashboard retrieves user context for API requests

​
API Request Authentication

  1. User action triggers an API request in the Dashboard
  2. Dashboard determines authentication method:
    • If run_as: true → Use logged-in user’s credentials
    • If run_as: false → Use configured API credentials
  3. Dashboard sends request to Wazuh Server API with appropriate credentials
  4. Wazuh Server validates credentials and checks permissions
  5. Response is returned and displayed to the user

​
Security Best Practices

​
Credential Management

  1. Use Strong Passwords: Configure complex passwords for API users
  2. Rotate Credentials: Periodically update API passwords
  3. Secure Configuration Files: Set restrictive permissions on opensearch_dashboards.yml
chown wazuh-dashboard:wazuh-dashboard /etc/wazuh-dashboard/opensearch_dashboards.yml
chmod 600 /etc/wazuh-dashboard/opensearch_dashboards.yml
  1. Use HTTPS: Always configure SSL/TLS for API connections
  2. Enable Run As: Use run_as: true for production environments to enforce proper RBAC

​
User Management

  1. Create users with minimum required permissions
  2. Define roles that align with organizational responsibilities
  3. Regularly audit user access and permissions
  4. Remove or disable accounts for departed users
  5. Monitor authentication logs for suspicious activity

​
Troubleshooting Authentication Issues

​
Connection Failures

Symptom: Cannot connect to Wazuh Server API Solutions:
  1. Verify the API URL and port are correct
  2. Check that the Wazuh Server API service is running
  3. Confirm network connectivity between Dashboard and Server
  4. Validate SSL/TLS certificates if using HTTPS
  5. Review firewall rules

​
Authentication Failures

Symptom: API requests fail with 401 Unauthorized Solutions:
  1. Verify username and password are correct
  2. Check that the user exists in Wazuh Server
  3. Confirm the user has required permissions
  4. Review Wazuh Server API logs for details

​
Run As Issues

Symptom: Run as not working or permission errors Solutions:
  1. Verify allow_run_as is enabled in Wazuh Server configuration
  2. Confirm the Dashboard username is wazuh-wui when run_as is enabled
  3. Check that logged-in users exist in Wazuh Server
  4. Verify user role assignments in Wazuh Server
  5. Review health check output for run_as status

​
Version Compatibility

Symptom: API version mismatch errors Solutions:
  1. Ensure Dashboard and Wazuh Server versions are compatible
  2. Major and minor version numbers should match
  3. Update components to matching versions if needed
  4. Review compatibility matrix in documentation