Troubleshooting Wazuh RBAC

Wazuh Role-Based Access Control (RBAC) issues are rarely caused by a single misconfiguration.

In most cases, they emerge from a mismatch between how roles are defined in the dashboard and how permissions are actually enforced at the backend security layer.

This disconnect often leads to a misleading situation where roles appear correctly configured but have no observable effect on user access.

At a high level, Wazuh RBAC governs what a user can see and do across agents, rules, indices, and APIs.

When it breaks, users typically retain broader access than intended, or custom restrictions simply do not apply.

These failures are especially common after upgrades, multi-node deployments, or when integrating with external authentication providers.

For reference on Wazuh’s security architecture and access control model, see the official documentation:

A useful real-world pattern noted by security engineers (including contributors in OpenSearch and SIEM deployment communities) is that RBAC issues in Wazuh are almost never “frontend bugs.”

Instead, they are almost always caused by incorrect role mappings or backend security plugin enforcement mismatches.

Understanding Wazuh RBAC Behavior

What RBAC is in Wazuh

In Wazuh, RBAC defines access control rules that determine what authenticated users can view or modify.

This includes:

Agent visibility (which endpoints a user can see)
Index permissions (OpenSearch/Wazuh Indexer indices)
Rule and alert access
API-level operations

RBAC is implemented on top of the underlying OpenSearch Security plugin, meaning Wazuh does not enforce permissions independently, it delegates enforcement to the indexer security layer.

How roles, users, and policies interact in the Wazuh dashboard

The RBAC model typically involves three layers:

Users: Authenticated identities (local or via SSO/LDAP)
Roles: Collections of permissions (index patterns, API privileges, dashboard access)
Policies / mappings: Bind users to roles and define scope constraints

When a user logs into the Wazuh dashboard, their session token carries role mappings that are evaluated against backend index permissions.

If mappings are incorrect or incomplete, the dashboard may still render data, but without proper filtering.

Why RBAC issues often appear as “ignored permissions” or “default access fallback”

A common symptom is that restricted users still see full datasets.

This usually happens because:

The backend defaults to a permissive role when mapping fails
Index patterns are too broad (e.g., wazuh-alerts-*)
Role mapping is missing at the indexer level but exists in the dashboard UI

This creates a false impression that RBAC is “not working,” when in reality it is partially applied but overridden by fallback permissions.

Scope of the problem: roles created but not enforced

One of the most frequent operational failures is creating roles in the Wazuh dashboard without ensuring they are properly registered in the Wazuh Indexer security plugin.

This leads to:

Roles visible in UI but absent in backend security config
Users assigned to roles that have no index permissions
Authentication succeeding, but authorization silently failing

This mismatch is the core reason RBAC issues often persist even after “correct” configuration changes.

How Wazuh RBAC Actually Works (Under the Hood)

Role-based access vs user mapping vs backend security plugin

Wazuh RBAC is not a standalone authorization system.

Instead, it is a layered abstraction over the OpenSearch Security plugin.

There are three critical enforcement points:

Wazuh dashboard layer: UI-level filtering (non-authoritative)
Wazuh API layer: operational checks (agent management, queries)
Wazuh Indexer (OpenSearch Security): primary enforcement layer

The key takeaway is that only the indexer layer enforces true data access control.

Dashboard and API restrictions are secondary and can be bypassed if backend roles are misconfigured.

Role definitions stored in Wazuh Indexer / OpenSearch security layer

Role definitions are persisted in the security index (commonly .opendistro_security or .opensearch-security depending on version). These definitions include:

Allowed index patterns (e.g., wazuh-alerts-*)
Allowed cluster permissions
Tenant access (if multi-tenancy is enabled)

If a role exists only in the dashboard configuration but not in the security index, it is effectively inert.

Mapping users to backend roles

User-to-role mapping is a critical enforcement step.

It is handled through:

Internal security config files OR
Security API calls to the indexer

Mapping defines which roles are applied at login time. If mapping is missing or misaligned:

Users authenticate successfully
But receive default or empty permission sets
Or inherit overly broad roles like all_access

This is one of the most common root causes of RBAC inconsistencies in production deployments.

Token/session-based permission evaluation flow

When a user logs into Wazuh:

Credentials are authenticated (local auth, LDAP, SSO, etc.)
A session token is issued
The token includes role metadata
Each request to the indexer is evaluated against:
- Role permissions
- Index patterns
- Cluster privileges
Access is granted or denied per request

Importantly, RBAC is evaluated per request, not just at login. This means changes to roles may not take effect until:

Token refresh occurs
Session is invalidated
Or cache is cleared in the security plugin

This explains why role updates often appear to “not apply immediately.”

Common Symptoms of RBAC Misconfiguration

Custom roles not restricting dashboards or indices

Users with restricted roles still see full dashboards or all alert indices.

This typically indicates:

Incorrect index patterns (too broad or incorrect naming)
Missing backend role mapping
Dashboard-level filtering only, with no index-level enforcement

Users still seeing “all agents” despite limited roles

Even when roles are intended to restrict agent visibility, users may still see all endpoints.

This usually occurs when:

Agent filtering is not enforced at the indexer layer
API permissions are not aligned with index permissions
Role lacks granular agent group constraints

Permissions not updating after role changes

A frequent source of confusion is that role updates do not appear to take effect immediately.

Common causes include:

Cached security tokens
Session persistence in the dashboard
Delayed propagation in the indexer security plugin

Logout/login required but still no effect

Even after re-authentication, changes may not apply if:

Role mapping was updated incorrectly (UI vs backend mismatch)
The security plugin has not reloaded configuration
Multiple authentication backends are conflicting (e.g., LDAP + internal users)

Inconsistent behavior between API and dashboard

A particularly confusing scenario is when:

Dashboard shows restricted data
But API returns broader results (or vice versa)

This indicates a layered enforcement mismatch, where:

Dashboard filters are applied client-side
API queries bypass or partially bypass RBAC constraints
Indexer permissions are not uniformly enforced across services

Primary Causes of RBAC Roles Not Applying

Missing or Incorrect Role Mapping

One of the most common failure points in Wazuh RBAC is the absence of proper user-to-role mapping at the backend security layer.

Even if a role is correctly defined in the Wazuh dashboard, it will not be enforced unless it is explicitly mapped to a backend security role in the Wazuh Indexer (OpenSearch Security plugin).

Typical issues include:

Users created in Wazuh dashboard but not mapped to any indexer role
Roles assigned in UI but not synchronized to .opendistro_security / .opensearch-security
Multiple roles assigned where one overrides or nullifies restrictions due to precedence rules

In practice, this leads to “phantom permissions” where users appear restricted but still inherit broad access from a default or overlapping role.

Cache and Session Persistence Issues

RBAC changes are frequently not reflected immediately due to cached authentication artifacts.

Key mechanisms involved:

JWT tokens containing embedded role claims
Dashboard session cookies retaining stale authorization metadata
Browser cache preserving older UI state of agent visibility or index access

Even after role updates, users may continue operating under old permissions until:

Session expiry
Manual logout/login
Token refresh in the authentication provider

This is why RBAC troubleshooting often incorrectly appears resolved at the configuration level but not in behavior.

Indexer Security Sync Problems

Wazuh RBAC enforcement ultimately depends on synchronization between the dashboard and the indexer security plugin.

Common issues include:

Role updates not propagated to OpenSearch security configuration
Partial cluster propagation delays in multi-node deployments
Mismatch between dashboard-defined roles and indexer-stored roles

When synchronization breaks, the dashboard may show updated roles, but enforcement at query time remains unchanged.

This is especially common in distributed setups where security configuration must propagate across multiple indexer nodes.

Incorrect Index Patterns or Permissions

Even correctly mapped roles will fail if index permissions are misconfigured.

Frequent mistakes include:

Missing required index patterns such as wazuh-alerts-*
Overly broad wildcards like * unintentionally granting full access
Incorrect index naming assumptions after version upgrades or index rotation

Since Wazuh relies heavily on index-based access control, even a small mismatch in index patterns can result in either:

No data visibility (over-restriction)
Full data exposure (over-permissioning)

API vs Dashboard Role Mismatch

A particularly confusing RBAC failure mode occurs when permissions differ between the Wazuh API layer and the dashboard UI layer.

Scenarios include:

Dashboard correctly restricts visibility, but API returns full datasets
API enforces restrictions, but dashboard UI still renders all agents or alerts
Role applied only in OpenSearch but not in Wazuh API configuration

This mismatch typically indicates that RBAC is only partially configured across system layers rather than fully enforced end-to-end.

Configuration File Conflicts

In some deployments, RBAC behavior is affected by conflicting configuration sources:

roles.yml defining static role permissions
internal_users.yml overriding user definitions
Security plugin configuration being partially overwritten during upgrades

When multiple sources define overlapping roles or users, precedence rules may lead to unexpected outcomes such as:

Role definitions being silently overridden
Users inheriting unintended privileges
Updates appearing successful but not persisting after restart

Step-by-Step Troubleshooting Guide

Verify User-to-Role Mapping

Start by confirming that the user is correctly mapped to backend roles:

Check the Wazuh dashboard security configuration
Verify mappings exist in the OpenSearch Security backend
Ensure no conflicting or duplicate role assignments exist

If mapping is missing, RBAC will fail regardless of role definition quality.

Inspect Role Definitions

Next, validate that roles are correctly defined:

Confirm index permissions include required patterns (e.g., wazuh-alerts-*)
Verify cluster-level permissions for search and read operations
Ensure tenant or multi-tenancy settings are not restricting access unintentionally

This step isolates whether the issue is structural (definition-level) rather than mapping-related.

Force Session Refresh

Because RBAC is session-dependent, stale tokens can mask configuration changes.

Recommended actions:

Fully clear browser storage (cookies + local storage)
Log out and re-authenticate
Test in incognito/private mode to eliminate cache influence

This helps differentiate between true RBAC misconfiguration and client-side caching artifacts.

Check Indexer Security Plugin Logs

The OpenSearch security plugin provides direct insight into RBAC enforcement failures.

Look for:

Permission denied errors for specific indices
Role mapping warnings
Authentication vs authorization mismatches

These logs are often the most authoritative source of truth when UI behavior is misleading.

Validate Index Permissions

Confirm that role permissions align with actual index structure:

Verify correct access to wazuh-alerts-*, wazuh-archives-*, or custom indices
Ensure no missing read permissions for required data streams
Check for unintended wildcard exclusions

Index-level validation is critical because Wazuh RBAC is fundamentally index-driven.

Reapply Role Sync

If inconsistencies persist, force a configuration resync:

Reload or restart the OpenSearch/Wazuh Indexer security plugin
Reapply role definitions via API or configuration reload
Restart dashboard services if UI caching persists

In clustered environments, ensure all nodes receive updated security configuration.

Debugging with Logs and API Calls

Key logs to inspect (dashboard, indexer, manager)

Effective RBAC debugging requires correlating multiple log sources:

Wazuh dashboard logs: UI-level role and session behavior
Wazuh indexer logs: Authorization failures and security plugin enforcement
Wazuh manager logs: API-level access and agent-related permissions

Cross-referencing these logs helps identify whether the failure is:

Authentication-related (login issues)
Authorization-related (RBAC enforcement failure)
Or synchronization-related (config propagation delay)

Using Wazuh API to validate effective permissions

The Wazuh API can be used to confirm what a user is actually allowed to access, independent of UI interpretation.

Key checks include:

Listing accessible agents for a user
Querying allowed indices and rulesets
Verifying role assignments via API endpoints

This is often more reliable than dashboard inspection because it reflects backend enforcement rather than UI filtering.

Interpreting RBAC-related error messages

Common RBAC-related errors include:

“forbidden” or HTTP 403 responses (explicit authorization failure)
“no permissions for index” (index pattern mismatch)
“security_exception” (role mapping or plugin enforcement issue)

Interpretation rule of thumb:

403 errors → RBAC is actively enforcing denial
Empty results → RBAC or index mismatch rather than outright denial
Inconsistent API vs UI → layered configuration problem, not single-point failure

Advanced RBAC Edge Cases

Nested roles and inheritance conflicts

Wazuh RBAC does not always behave intuitively when multiple roles are layered onto a single user.

In OpenSearch-based security models, permissions are typically additive, meaning that a user inherits the union of all assigned role privileges.

However, complexity arises when roles contain overlapping or contradictory index patterns.

Common failure patterns include:

A restrictive role (wazuh-read-only) being effectively overridden by a broader role (all_access)
Conflicting index patterns (e.g., wazuh-alerts-* vs wazuh-*) unintentionally expanding access
Implicit privilege escalation due to inherited cluster-level permissions

In practice, “nested role behavior” is less about true inheritance and more about permission aggregation without conflict resolution logic, which can produce unintended access expansion.

Multi-tenant environments breaking role isolation

Multi-tenancy in Wazuh (via OpenSearch tenants or dashboard spaces) introduces another layer of RBAC complexity.

While tenants are designed to isolate dashboards and saved objects, index-level permissions remain the primary enforcement boundary.

Issues commonly observed:

Users can switch tenants but still query shared indices
Tenant isolation works in UI but fails at indexer level
Cross-tenant data leakage due to overly broad index permissions

This is a structural limitation: tenant separation is not a substitute for strict index-level RBAC enforcement.

LDAP/SSO integration overriding local roles

When integrating Wazuh with external identity providers such as LDAP, SAML, or OIDC, RBAC evaluation becomes dependent on external group-to-role mappings.

Failure modes include:

External group mappings overriding locally defined roles
Users assigned correct dashboard roles but receiving different backend roles via SSO claims
Token-based role injection replacing static role assignments

This is particularly common when:

LDAP group names do not match expected role mappings
SSO claims are not normalized before role assignment
Multiple identity providers are enabled simultaneously

In these cases, the identity provider effectively becomes the source of truth for RBAC, even if local configurations suggest otherwise.

Time-delayed role propagation in clustered setups

In multi-node Wazuh Indexer clusters, RBAC updates are not always immediately consistent across nodes.

Typical symptoms:

Role changes visible on one node but not another
Inconsistent access depending on which node handles the query
Temporary “permission flip-flopping” behavior

Root causes include:

Asynchronous configuration propagation across cluster nodes
Security plugin cache delays
Network partitioning or slow coordination between nodes

This leads to a distributed consistency lag problem, where RBAC state is eventually consistent rather than strongly consistent.

Best Practices for Reliable Wazuh RBAC Configuration

Keep role definitions minimal and explicit

RBAC complexity increases exponentially with each additional role layer. A best-practice approach is to:

Define roles with a single responsibility (e.g., “read-only alerts”)
Avoid combining unrelated permissions into one role
Prefer explicit index patterns over broad wildcards

This reduces ambiguity in permission evaluation and makes debugging significantly easier.

Avoid overlapping permissions across roles

Overlapping roles are one of the primary causes of unintended privilege escalation.

Recommended approach:

Ensure each role has a distinct scope (e.g., security_team_role vs network_team_role)
Avoid assigning multiple roles that cover the same index patterns unless strictly required
Regularly review aggregated permissions from all assigned roles

This ensures predictable and deterministic RBAC evaluation.

Standardize index patterns across environments

Inconsistent index naming is a hidden source of RBAC failures.

Best practices:

Use consistent naming conventions (e.g., wazuh-alerts-*, wazuh-archives-*)
Avoid environment-specific ad-hoc index patterns
Align index patterns across dev, staging, and production clusters

Standardization ensures that RBAC roles remain portable and predictable across deployments.

Regularly audit user-role mappings

RBAC drift is common in long-running deployments. Periodic audits should include:

Verifying active users and their assigned roles
Identifying orphaned or unused roles
Detecting privilege creep from accumulated role assignments

This helps prevent long-term security degradation due to configuration sprawl.

Test RBAC changes in staging before production

RBAC changes should never be applied directly to production without validation.

A proper staging process should:

Simulate real user access patterns
Validate index-level restrictions
Test API and dashboard consistency
Confirm role propagation across clustered nodes

This reduces the risk of introducing silent access control failures into production environments.

Preventing Future RBAC Issues

Implement RBAC change control workflow

RBAC should be treated as a critical security control, not a configuration toggle.

A robust workflow includes:

Peer review of all role changes
Version-controlled role definitions
Approval gating for production updates

This introduces governance around permission changes and reduces accidental misconfiguration.

Monitor role changes via audit logs

Wazuh and OpenSearch provide audit logging capabilities that can track:

Role creation and modification events
User-to-role mapping changes
Authentication and authorization decisions

Monitoring these logs helps detect:

Unauthorized privilege escalation attempts
Unexpected RBAC modifications
Configuration drift over time

Automate role validation checks

Automation can significantly reduce RBAC misconfiguration risk. Recommended checks include:

Verifying index access matches expected patterns
Detecting overly permissive wildcard roles
Validating user-role mapping consistency across nodes

These checks can be integrated into CI/CD pipelines or periodic compliance jobs.

Document all role structures and mappings

A frequently overlooked but critical practice is maintaining clear documentation of RBAC architecture.

Documentation should include:

Role definitions and their purpose
User-to-role mappings
Index pattern assignments
External identity provider mappings (LDAP/SSO)

This becomes essential for troubleshooting, audits, and onboarding new administrators, especially in complex deployments.

Frequently Asked Questions (FAQ)

Question: Why are my Wazuh custom roles not taking effect immediately?

RBAC changes in Wazuh often fail to appear immediately due to session caching and token persistence.

When a user logs in, their permissions are embedded into a session token (or JWT-like structure), which may continue to be used until it expires or is refreshed.

Additionally, OpenSearch Security plugin updates can propagate asynchronously across cluster nodes, meaning some nodes may still enforce older role definitions temporarily.

Question: Does logging out fix RBAC changes in Wazuh?

Logging out and back in often resolves RBAC inconsistencies, but not always. It only works if the underlying issue is stale session data. If the problem originates from:

Incorrect role mapping
Missing index permissions
Backend security plugin misconfiguration
then re-authentication will not resolve the issue.

Question: How do I confirm effective permissions for a user?

The most reliable approach is to evaluate permissions at the backend indexer level, not just the dashboard UI. You can:

Use Wazuh API endpoints to list accessible agents and resources
Inspect OpenSearch security plugin “effective roles” for the user
Review audit logs for authorization decisions

This gives a true representation of what the system enforces rather than what the UI displays.

Question: Can multiple roles override each other in Wazuh?

No explicit override mechanism exists in Wazuh RBAC. Instead, permissions are aggregated (additive model) across all assigned roles.

This means:

Broad roles can unintentionally expand access
There is no strict “deny overrides allow” hierarchy in most configurations
Conflicts are resolved through union of permissions rather than precedence

As a result, poorly structured role combinations can lead to unintended privilege escalation.

Question: Why do API permissions differ from dashboard permissions?

This typically indicates a layered RBAC enforcement mismatch:

The dashboard may apply UI-level filtering only
The API enforces backend security constraints differently
OpenSearch index permissions may be correctly enforced while UI still shows cached data

This inconsistency usually points to misalignment between:

Wazuh API configuration
OpenSearch Security plugin roles
Dashboard session state

Question: Do I need to restart Wazuh after RBAC changes?

Not always. In most cases, RBAC changes should propagate without a full restart. However, restarts or reloads may be required when:

Security plugin configuration is updated directly in files
Role mappings fail to propagate across cluster nodes
Cached sessions prevent updated permissions from being applied

In production systems, a security plugin reload or controlled node restart is preferred over restarting the entire Wazuh stack.

Question: What logs show RBAC denial errors?

RBAC-related issues can be identified across multiple log sources:

Wazuh indexer logs: show security_exception and index-level denial messages
Wazuh dashboard logs: indicate UI access or session authorization issues
Wazuh manager logs: reflect API-level access restrictions

The most definitive signals usually come from the indexer security plugin logs, which show explicit authorization failures.

Question: Can OpenSearch security settings override Wazuh RBAC?

Yes. In fact, OpenSearch Security is the authoritative enforcement layer in Wazuh deployments that use it. This means:

OpenSearch role definitions can override or invalidate dashboard-level RBAC settings
If indexer permissions are too permissive, Wazuh UI restrictions may be ineffective
True access control is ultimately determined by OpenSearch security configuration, not the dashboard alone

This is a critical architectural point: Wazuh RBAC is an abstraction, not the enforcement engine.

Conclusion

RBAC issues in Wazuh are rarely caused by a single misconfiguration.

In most real-world deployments, failures stem from a combination of incorrect role mapping, cached sessions, and indexer-level security mismatches.

The dashboard may suggest that roles are correctly applied, but the underlying OpenSearch Security layer ultimately determines what users can actually access.

A consistent pattern in troubleshooting is that RBAC problems are not “UI bugs,” but backend authorization mismatches between:

Role definitions
User-to-role mappings
Index-level permissions in OpenSearch Security

Before assuming RBAC is broken, the first step should always be verifying the backend configuration directly at the indexer level, followed by checking session validity and propagation delays across clustered nodes.

For reliable RBAC behavior in Wazuh environments, the key principles are consistency and verification: ensure roles are explicitly defined, mappings are correctly applied, and index permissions align with expected data boundaries.

When these layers are aligned, RBAC becomes predictable; when they are not, it fails silently in ways that often appear misleading at the UI level.