Authentication Setup

​

Wazuh Server API Authentication

​

Basic Authentication

​

Configuration Structure

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

​

Multiple API Hosts

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

​

Port

​

Username

• Non-empty string
• Minimum 4 characters
• Maximum 64 characters

​

Password

• Non-empty string
• Maximum 64 characters

​

Run As Mode

• true: Enable run_as mode (RBAC enabled)
• false: Disable run_as mode

​

Run As Authentication Mode

​

Overview

​

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

<api>
  <auth>
    <allow_run_as>yes</allow_run_as>
  </auth>
</api>

• 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

​

Checking Run As Status

Server API hosts with run_as permission enabled: production, testing

Some server API hosts have not enabled the run_as or the user has no the ability to use it

​

OpenSearch Security Integration

​

Security Plugin Configuration

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

​

Request Headers

opensearch.requestHeadersAllowlist: ['securitytenant', 'Authorization']

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

4. Use HTTPS: Always configure SSL/TLS for API connections
5. 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

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

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

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

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

​

Related Topics

• Single Sign-On Configuration
• Plugin Settings
• Health Check System