Authentication Setup

Configure authentication methods for Wazuh Dashboard and Server API connections

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 Code	Description
Enabled	Run as allowed for user and host
Host Disabled	Run as disabled in the Wazuh Server configuration
All Disabled	Run as disabled in both host and user configuration
User Not Allowed	Run as not permitted for the configured user
Unable to Check	Cannot 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

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

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

Related Topics

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