> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wazuh/wazuh-dashboard-plugins/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```yml theme={null}
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:

```yml theme={null}
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:

```xml theme={null}
<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

```yml theme={null}
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+:**

```yml theme={null}
opensearch.requestHeadersAllowlist: ['securitytenant', 'Authorization']
```

**OpenSearch Dashboards 1.x:**

```yml theme={null}
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`

```bash theme={null}
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](/configuration/single-sign-on)
* [Plugin Settings](/configuration/settings)
* [Health Check System](/configuration/health-check)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.