How to Configure Wazuh RBAC

Role-based access control (RBAC) is an important part of securing a Wazuh deployment as the number of users, security analysts, administrators, and monitored environments grows. Instead of granting permissions individually to every user, Wazuh RBAC allows administrators to associate permissions with roles and then assign those roles to users.

This approach is particularly useful in Security Operations Centers (SOCs), where different users require different levels of access.

A security analyst may need to view alerts and investigate agents, while a security engineer may need permission to modify rules and configurations.

A Wazuh administrator, meanwhile, may require broad access to manage users, agents, policies, and the Wazuh infrastructure.

RBAC provides a structured way to enforce these distinctions while reducing the risk of excessive privileges.

Why role-based access control matters in Wazuh

A Wazuh deployment can contain sensitive security information, including endpoint telemetry, authentication events, vulnerability information, security configuration assessments, malware detections, and incident data.

Giving every user unrestricted access creates unnecessary security exposure.

RBAC addresses this problem by associating permissions with organizational responsibilities rather than managing access independently for every individual.

For example, an organization could define roles such as:

• Security Analyst: Read alerts, investigate events, and inspect endpoint information.
• Incident Responder: Investigate incidents and perform approved response actions.
• Security Engineer: Modify detection rules, configurations, and security policies.
• Wazuh Administrator: Manage users, agents, cluster settings, and security configuration.
• Auditor: Obtain read-only visibility into relevant security information.

This follows the principle of least privilege: users should receive the permissions necessary to perform their responsibilities without automatically receiving administrative access.

NIST’s foundational RBAC research describes the model as assigning permissions to roles and then assigning users to those roles.

This reduces the complexity of administering permissions individually and makes authorization policies easier to manage.

In Wazuh specifically, roles group access rights through rules and policies.

Administrators can modify a role once and have the resulting permission changes apply to users assigned to that role.

How Wazuh RBAC improves security and access governance

Wazuh RBAC improves access governance by establishing a predictable relationship between a user’s responsibilities and the resources they can access.

Consider a SOC with 30 analysts.  Without role-based authorization, administrators could potentially have to maintain permissions for each analyst individually.

With RBAC, the administrator can create an analyst role with the appropriate permissions and assign all analysts to that role.

If the analyst role later needs an additional read permission, the administrator can modify the role rather than changing every individual account.

This provides several benefits:

• Least privilege: Users receive only the permissions required for their jobs.
• Centralized authorization: Permissions can be managed through roles rather than scattered across individual users.
• Consistent access: Users performing the same function can receive the same authorization.
• Simpler administration: Changing a role can update access for multiple users.
• Better auditing: Security teams can review which roles exist and which users are assigned to them.
• Reduced privilege creep: Users can be removed from roles when responsibilities change.
• Improved separation of duties: Administrative and investigative responsibilities can be separated.

NIST research also emphasizes that RBAC can reduce the cost and complexity of security administration in large networked environments.

For Wazuh deployments, RBAC should therefore be treated as part of the overall security architecture rather than simply as a convenience for creating user accounts.

If you are also implementing centralized authentication, RBAC can complement authentication technologies such as LDAP, SAML, OIDC, or SSO.

Authentication determines who the user is; RBAC helps determine what that authenticated user is allowed to do.

Related Guides:

• How to Configure Wazuh LDAP Authentication
• How to Configure Wazuh SSO
• How to Configure Wazuh SAML Authentication
• How to Configure Wazuh OIDC

What this guide covers

This guide explains how Wazuh RBAC works and how its major authorization components fit together.

It covers:

• Wazuh users
• Local and externally authenticated users
• Authentication versus authorization
• Wazuh security roles
• Built-in and custom roles
• Role assignments
• Wazuh permissions
• API permissions
• Dashboard and index permissions
• Read and write access
• Administrative permissions
• Wazuh tenants
• Multi-tenancy
• Data isolation
• Global and custom tenants
• The relationship between users, roles, permissions, and tenants

The goal is to provide a practical conceptual foundation before moving into the configuration steps for creating users, defining roles, mapping permissions, and testing access.

What Is Wazuh RBAC?

Wazuh RBAC is the role-based authorization system used to control what authenticated users can access and which operations they can perform within Wazuh.

The underlying RBAC concept is straightforward: instead of attaching every permission directly to an individual user, permissions are grouped into roles.

Users are then assigned to the appropriate roles.

Wazuh’s documentation describes its RBAC implementation around four primary components: users, roles, rules, and policies.

Users make requests to Wazuh resources, roles group access rights, rules determine when policies apply, and policies define the permissions that are allowed.

It is important to recognize that Wazuh deployments contain multiple authorization layers.

The Wazuh Server API has its own RBAC mechanism, while the Wazuh Dashboard and Wazuh Indexer use security controls that govern access to dashboard resources and indexed data.

A complete Wazuh access-control strategy therefore needs to consider the different layers rather than treating “RBAC” as a single permission switch.

Definition of Role-Based Access Control

Role-Based Access Control is an authorization model in which permissions are associated with roles rather than being assigned directly to individual users.

A simplified RBAC relationship looks like this:

User → Role → Permissions → Resources

For example:

Alice → Security Analyst → Read Alerts → Wazuh alert data

Another user could be assigned:

Bob → Security Engineer → Read/Write Rules → Wazuh rule configuration

The advantage is that the permissions are attached to the role.

If Alice changes departments, her administrator can remove her from the analyst role and assign her to another appropriate role without rebuilding the entire authorization structure.

NIST’s RBAC model identifies users, roles, permissions, operations, and objects as fundamental elements of an RBAC system.

How RBAC works in Wazuh

In the Wazuh Server API, RBAC is organized around users, roles, rules, and policies.

A user makes a request.

A role groups the access rights that should apply to that user.

A rule defines the conditions under which a policy applies.

A policy defines the actions that are permitted or denied against resources.

Wazuh’s API documentation describes policies using three key elements:

• Actions — What operation can be performed.
• Resources — Which Wazuh resources the operation applies to.
• Effect — Whether the operation is allowed or denied.

This creates a layered authorization process.

Rather than asking only whether a user has logged in successfully, Wazuh can determine whether that user has the appropriate authorization to perform the requested operation.

For example, two authenticated users might both be able to access the Wazuh API, but only one may have authorization to modify configuration settings.

This distinction between authentication and authorization is critical when troubleshooting Wazuh access problems.

Wazuh users, roles, permissions, and tenants

The four concepts most administrators need to understand are users, roles, permissions, and tenants.

Users represent the people or identities accessing Wazuh.

Roles represent the responsibilities or access profiles assigned to those users.

Permissions determine what operations those roles can perform.

Tenants provide a mechanism for separating access to Wazuh Dashboard data and resources in multi-tenant environments.

These components can be thought of as different layers:

A user can have one or more roles, and a role can contain multiple permissions.

This makes the model scalable as an organization grows.

Wazuh provides built-in roles for common administrative and read-only functions while also allowing administrators to create custom authorization structures.

RBAC vs. traditional user-based access control

In a user-based access-control model, permissions can be assigned directly to individual users.

For example:

• Alice → read alerts
• Bob → read alerts
• Carol → read alerts
• David → read alerts
• Eve → read alerts

This becomes increasingly difficult to maintain as the number of users grows.

With RBAC, those permissions can instead be associated with a role:

• Security Analyst → read alerts
• Alice → Security Analyst
• Bob → Security Analyst
• Carol → Security Analyst
• David → Security Analyst
• Eve → Security Analyst

If the organization changes the analyst permissions, administrators can update the role rather than modifying every user individually.

This is one of the central advantages identified in the original RBAC research by David Ferraiolo and Richard Kuhn: access policies can be managed around organizational roles rather than individual identities.

User-based permissions can still be appropriate in exceptional cases, but role-based authorization generally provides a more maintainable structure for larger Wazuh environments.

How Wazuh RBAC fits into the Wazuh security architecture

Wazuh RBAC should be viewed as one component of a broader Wazuh security architecture.

A simplified access flow looks like this:

User → Authentication → Wazuh Dashboard/API → Authorization → Role/Policy Evaluation → Resource

Authentication establishes the user’s identity.

Authorization determines whether that identity has permission to perform the requested action.

The Wazuh Dashboard provides the user interface through which analysts and administrators interact with the platform.

The Wazuh Server API provides programmatic access to Wazuh management functionality, while the Wazuh Indexer stores and serves indexed security data.

This distinction is important because a user may successfully authenticate while still being unable to perform a particular operation.

For example, a user might be able to log into the Wazuh Dashboard but receive a 403 Forbidden response when attempting an administrative operation.

That situation generally points toward authorization or permission configuration rather than a basic authentication failure.

Related Guide: Troubleshooting Wazuh RBAC

RBAC also works alongside other Wazuh security mechanisms, including authentication providers, multi-tenancy, index permissions, dashboard permissions, and API authorization.

For organizations using external identity providers, the authentication system and Wazuh RBAC should be designed together.

The identity provider establishes the user’s identity, while Wazuh maps that identity to the appropriate authorization structure.

How Wazuh RBAC Works

Understanding how Wazuh RBAC works requires looking at the relationship between users, security roles, permissions, and tenants.

At a high level, the process is:

1. User authenticates → 2. Wazuh identifies the user → 3. Roles are associated with the user → 4. Policies and permissions are evaluated → 5. Access is granted or denied

The exact authorization path depends on which Wazuh component the user is interacting with.

The Wazuh Server API has its own RBAC model, while the Wazuh Indexer and Dashboard introduce additional security concepts.

Wazuh Users

A Wazuh user is an identity that can interact with the Wazuh platform.

Users may be created and managed through Wazuh’s internal user database or associated with an external authentication system.

The Wazuh documentation supports internal users and describes integration with external authentication systems such as SAML, LDAP, and Active Directory.

The important distinction is that a user account establishes identity, while the roles associated with that identity establish authorization.

Creating and managing Wazuh users

Administrators can manage internal users through the Wazuh Dashboard.

For example, Wazuh provides an interface under the security and user-management areas where administrators can create internal users and map those users to appropriate roles.

A typical workflow is:

1. Create or identify the user.
2. Configure authentication credentials or an external identity mapping.
3. Assign the appropriate role.
4. Configure the role’s permissions.
5. Configure any required tenant or index access.
6. Test the resulting authorization.
7. Review the user’s effective permissions.

The important principle is to avoid treating user creation and permission assignment as the same operation.

Creating a user establishes an identity. Assigning a role establishes what that identity can do.

Local users and externally authenticated users

Wazuh can work with internally managed users as well as externally authenticated identities.

Internal users are maintained within the Wazuh environment.

External authentication allows organizations to centralize identity management using technologies such as LDAP, SAML, or other supported authentication mechanisms.

This separation is useful in enterprise environments because identity lifecycle management can remain centralized while Wazuh continues to control authorization.

For example, an organization might authenticate analysts through its corporate identity provider while mapping those users to Wazuh roles based on their responsibilities.

Related Guides:

• How to Configure Wazuh LDAP Authentication
• How to Configure Wazuh SSO
• How to Configure Wazuh SAML Authentication
• How to Configure Wazuh OIDC

User authentication vs. authorization

Authentication and authorization are related but fundamentally different.

Authentication asks:

Who are you?

Authorization asks:

What are you allowed to do?

A successful login only establishes that the user has authenticated successfully.

It does not automatically mean the user should have administrator privileges.

For example, an analyst could authenticate successfully but be denied access to an administrative endpoint because their assigned role does not include the required permission.

This distinction is especially useful when diagnosing Wazuh access errors.

A login failure generally requires investigation of authentication mechanisms, credentials, certificates, identity providers, or session configuration.

A successful login followed by 403 Forbidden, missing data, or unavailable administrative functions is more likely to involve authorization, roles, permissions, mappings, or tenant configuration.

Wazuh Security Roles

A Wazuh security role is a collection of access rights that can be assigned to users.

Rather than assigning individual permissions repeatedly, administrators define an access profile through a role and then assign users to that role.

Wazuh’s documentation provides predefined roles for common administrative functions and allows administrators to create custom roles when the built-in roles do not meet an organization’s requirements.

What a Wazuh security role is

A role represents a defined authorization profile.

For example, a role could be designed for:

• Read-only security monitoring
• Security analysis
• Incident response
• Agent management
• Rule administration
• Cluster administration
• User administration
• Full Wazuh administration

The role should reflect the responsibilities of the person using it rather than simply granting the maximum permissions available.

This is where role engineering becomes important.

A well-designed role should contain enough permissions for the job but avoid unrelated administrative privileges.

Built-in Wazuh roles

Wazuh provides predefined roles for common use cases.

For example, the Wazuh RBAC reference includes roles such as:

• cluster_admin
• cluster_readonly
• readonly
• users_admin

The readonly role provides read permissions across several Wazuh capabilities, while cluster_admin provides administrative access to Wazuh cluster functionality.

The users_admin role provides access to user-management functionality.

Built-in roles are useful because they provide a starting point for common authorization requirements.

However, organizations should not automatically assign an administrative role simply because it is convenient.

A custom role may be more appropriate when analysts, engineers, auditors, and administrators have different responsibilities.

Custom roles

Custom roles allow administrators to create more precise authorization models.

For example, an organization might want analysts to:

• View alerts
• View agent information
• Investigate security events
• Review vulnerability information

while preventing them from:

• Modifying detection rules
• Managing users
• Changing cluster configuration
• Modifying security policies

A custom role can be designed around those requirements.

This is particularly important for larger SOC environments where different teams need different access boundaries.

Custom roles should be designed using the least-privilege principle.

Start with the minimum permissions required for the job and add permissions only when there is a documented operational requirement.

Assigning users to roles

After a role has been created, users must be mapped to it.

The Wazuh Dashboard provides role-mapping functionality for associating users with Wazuh roles.

Wazuh’s documentation describes a workflow in which an internal user is created, mapped to an Indexer role where applicable, and then mapped to Wazuh through the Dashboard’s security configuration.

A simplified relationship is:

User → Role Mapping → Role → Policies/Permissions

If a custom role does not appear to work, administrators should verify every part of this chain.

Common causes of unexpected access include:

• The user was not mapped to the intended role.
• The wrong role was assigned.
• The role does not contain the required permission.
• An Indexer role does not provide the expected Wazuh Server API permissions.
• Tenant access is incorrectly configured.
• A conflicting role or mapping affects the effective permissions.
• The user needs to sign out and establish a new session before changes become visible.

Wazuh Permissions

Permissions determine what an authorized user can actually do.

A role may contain many permissions, but those permissions must correspond to the resources and operations required by the user’s responsibilities.

Wazuh’s API RBAC model uses policies to define actions, resources, and effects.

This enables authorization to be more granular than simply categorizing someone as an administrator or non-administrator.

Index permissions

Index permissions control access to indexed Wazuh data.

This is particularly important because Wazuh environments can contain large amounts of security telemetry.

Different teams may need access to different datasets or tenant-specific information.

For example, an organization could need to separate:

• Production endpoint data
• Development endpoint data
• Security operations data
• Compliance data
• Regional environments

Index-level authorization can help enforce these boundaries where the underlying Wazuh Indexer security configuration supports them.

Administrators should therefore distinguish between permission to access a Wazuh management function and permission to access the underlying indexed security data.

API permissions

API permissions control which Wazuh Server API operations a user is authorized to execute.

Wazuh’s API RBAC system uses policy definitions to control actions against resources.

The platform includes predefined policies and roles covering common capabilities such as agents, rules, decoders, cluster functionality, SCA, vulnerability detection, and other Wazuh features.

This means an analyst can potentially have permission to retrieve information without having permission to modify it.

API permissions are especially important for automation because scripts, integrations, and administrative tools may interact with Wazuh through API endpoints rather than through the Dashboard.

Dashboard permissions

Dashboard access controls determine which Wazuh Dashboard functionality and data users can access.

The Dashboard is the primary interface many SOC analysts use to investigate alerts and monitor endpoints.

Consequently, restricting access to the appropriate dashboards, indices, tenants, and management functions is an important part of implementing least privilege.

A user might therefore be allowed to access security monitoring dashboards while being prevented from accessing administrative configuration areas.

Dashboard authorization should be considered together with Indexer permissions and Wazuh Server API permissions rather than configured independently.

Read vs. write access

One of the most important distinctions in a Wazuh RBAC design is between read and write privileges.

Read permissions generally allow users to retrieve or inspect information.

Write permissions allow users to modify configuration, data, rules, policies, or other resources.

For example:

The exact permissions should be determined by the organization’s operational requirements rather than by this generic model.

Giving every analyst write access can create unnecessary risk.

A compromised analyst account with configuration privileges could potentially modify security controls, disable monitoring mechanisms, or alter detection logic.

Separating read-only investigation from configuration management is therefore a useful RBAC design pattern.

Administrative permissions

Administrative permissions should be reserved for users who genuinely need them.

Depending on the Wazuh functionality involved, administrative access can provide capabilities such as:

• Managing users
• Managing roles
• Managing agents
• Modifying rules
• Changing security configuration
• Managing cluster functionality
• Modifying policies
• Changing system settings

Wazuh’s built-in RBAC reference includes specialized administrative roles rather than requiring every administrator to receive identical permissions.

For example, users_admin is focused on user-management functionality, while cluster_admin provides administrative access to cluster-related functionality.

This illustrates an important RBAC principle: administrative access should be scoped to the administrative responsibility whenever possible.

Wazuh Tenants

Tenants provide an additional access-control boundary within the Wazuh Dashboard and Indexer security architecture.

They are particularly useful in environments where multiple groups need to use the same Wazuh deployment while maintaining logical separation between their data and dashboards.

What Wazuh tenants are

A tenant represents a logical workspace through which users can access a defined set of Wazuh Dashboard resources and data.

Instead of allowing every authenticated user to see the same information, tenant-based access can help establish boundaries between different teams, environments, or organizational units.

For example, a managed security provider could potentially use separate logical spaces for different customers, while a large enterprise could use different spaces for separate business units or operational teams.

Multi-tenancy and data isolation

Multi-tenancy becomes particularly valuable when multiple groups share the same Wazuh infrastructure.

A tenant can be used to help separate:

• Different business units
• Different customers
• Production and development environments
• Regional security operations teams
• Different SOC functions

The objective is to prevent users from automatically gaining visibility into data outside their assigned operational scope.

Tenant isolation should not be treated as a replacement for all other authorization controls.

It works alongside users, roles, index permissions, and other security mechanisms.

Related Guide: How to Set Up Wazuh Multi-Tenancy

Global tenant vs. custom tenants

Wazuh environments can use a global tenant as well as custom tenants depending on the deployment and access-control requirements.

The global tenant provides a shared workspace for users who need access to common Wazuh resources.

Custom tenants allow organizations to create more specific logical boundaries.

For example:

• Global → Shared security operations resources
• SOC → Security analyst workspace
• Compliance → Compliance-focused dashboards and data
• Engineering → Security engineering resources
• Customer-A → Managed security customer environment
• Customer-B → Separate managed security customer environment

The exact tenant design should reflect how the organization separates its security data and responsibilities.

How tenants interact with RBAC

Tenants and RBAC solve related but different problems.

RBAC answers:

What is this user allowed to do?

Tenant authorization answers:

Which logical data and workspace should this user be allowed to access?

A complete access model therefore combines the two.

For example, consider an analyst who belongs to the Security Analyst role and has access to the SOC tenant.

The role might allow the analyst to read security information, while the tenant limits the analyst’s workspace and data scope.

Conceptually:

User

↓

Security Analyst Role

↓

Read Permissions

SOC Tenant

↓

Authorized Wazuh Data and Functions

This distinction is especially important in multi-tenant Wazuh deployments.

Granting a user the correct role does not necessarily mean that the user should have unrestricted visibility across every tenant or dataset.

A well-designed Wazuh RBAC implementation therefore considers identity, role, permission, and tenant scope together.

The result is a layered authorization model that can support both least privilege and logical data separation across a growing Wazuh environment.

Wazuh RBAC Prerequisites

Before configuring Wazuh RBAC, verify that the Wazuh components responsible for authentication, authorization, data access, and the Dashboard are functioning correctly.

RBAC configuration can span multiple layers of a Wazuh deployment.

The Wazuh Manager provides the Wazuh Server API and its RBAC functionality, while the Wazuh Indexer and Wazuh Dashboard provide additional security and access-control mechanisms.

A problem at any of these layers can make a correctly configured role appear to be ineffective.

For example, a user may authenticate successfully but fail to access indexed data because the corresponding Indexer permissions or tenant configuration are incorrect.

Wazuh Manager requirements

The Wazuh Manager must be installed, running, and accessible before configuring Wazuh Server API RBAC.

Verify that:

• The Wazuh Manager service is running.
• The Wazuh Server API is available.
• The API can authenticate administrative requests.
• The Wazuh Manager configuration is valid.
• The Wazuh Manager and API versions are compatible with the rest of the deployment.
• Cluster communication is healthy if the deployment uses multiple Wazuh Manager nodes.

RBAC configuration frequently involves API requests, so API availability should be verified before troubleshooting authorization.

You can also use the Wazuh API to confirm that the management plane is responding before changing security configuration.

Wazuh Indexer requirements

The Wazuh Indexer must be operational if users need access to Wazuh alert data, indexed events, dashboards, or other information stored in the Indexer.

Verify:

• The Wazuh Indexer service is running.
• The cluster is healthy.
• Required Wazuh indices exist.
• Indexer security is functioning.
• The Wazuh Dashboard can communicate with the Indexer.
• The intended users have appropriate index permissions.

This distinction is important because Wazuh Server API permissions and Indexer permissions are not interchangeable.

A user can have permission to perform an operation through the Wazuh Server API while still lacking permission to retrieve the corresponding indexed data.

Related Guide: How to Build a Wazuh Indexer Cluster

Wazuh Dashboard requirements

The Wazuh Dashboard provides the primary graphical interface for managing users, roles, tenants, and security-related settings.

Before modifying RBAC, confirm that:

• The Dashboard loads normally.
• Users can authenticate.
• The Dashboard can communicate with the Wazuh Indexer.
• The Wazuh Dashboard plugin is functioning.
• Existing administrative users can access the required security-management interfaces.

If the Dashboard is already experiencing authentication or authorization problems, resolve those issues before changing RBAC.

Related Guide: Wazuh Dashboard Not Loading? Complete Troubleshooting Guide

Administrative access requirements

You need an account with sufficient administrative privileges to create roles, modify permissions, manage users, and configure tenant access.

Do not attempt to perform RBAC changes with an ordinary analyst or read-only account.

Before making changes, identify at least one administrative account that can:

• Create or modify security roles.
• Manage users.
• Configure role mappings.
• Manage tenant access.
• Review security configuration.
• Test authorization.

For production environments, it is also good practice to maintain a separate administrative account rather than using a highly privileged account for routine security monitoring.

This provides a separation between daily analyst activity and privileged administration.

Understanding Wazuh security configuration

Before creating a custom role, understand which Wazuh component controls each type of permission.

A simplified model is:

This separation prevents one of the most common RBAC configuration mistakes: assuming that assigning a Wazuh role automatically grants access to every underlying resource.

When troubleshooting, identify the exact resource the user is attempting to access and determine which authorization layer controls that resource.

Backing up configuration before making changes

Back up the relevant Wazuh security configuration before creating or modifying roles.

A backup gives you a recovery point if an incorrectly configured role, permission, or mapping prevents administrators from accessing the Dashboard or management interfaces.

At minimum, document or back up:

• Existing users.
• Existing roles.
• Role mappings.
• Security policies.
• Tenant configuration.
• Relevant Wazuh configuration files.
• Indexer security configuration.
• Dashboard security-related configuration.

For production environments, perform the backup before making changes during a maintenance window.

Do not rely solely on screenshots of the Dashboard. Export or preserve the actual configuration whenever your deployment and Wazuh version provide an appropriate mechanism for doing so.

Also document the original state of the environment.

A simple change record containing the old role definition, new role definition, affected users, and expected result can make rollback and troubleshooting substantially easier.

How to View Existing Wazuh Roles and Permissions

Before creating a custom Wazuh RBAC role, inspect the existing security model.

Wazuh provides built-in roles that cover common access requirements, and an existing role may already provide most or all of the permissions you need.

Reusing an appropriate built-in role is generally preferable to creating another custom role with overlapping permissions.

The exact interface and available roles can vary between Wazuh releases, so use the security-management interface provided by your installed version.

Accessing the Wazuh Dashboard

Sign in to the Wazuh Dashboard using an account with sufficient security-administration privileges.

From the Dashboard, navigate to the security or access-management functionality available in your deployment.

Depending on your Wazuh version and configuration, you may encounter separate areas for:

• Internal users.
• Roles.
• Role mappings.
• Index permissions.
• Tenant permissions.
• Security configuration.

If the security-management options are unavailable, first verify that the account you used has the required administrative privileges.

A missing security-management interface does not necessarily indicate a broken Wazuh installation.

It may simply mean that the current user does not have permission to manage security settings.

Reviewing existing security roles

Start by reviewing the roles already available in the deployment.

Look for roles corresponding to common responsibilities such as:

• Read-only monitoring.
• Cluster administration.
• User administration.
• Security analysis.
• Security engineering.
• Custom operational roles.

Wazuh’s RBAC reference documents built-in roles and their associated policies.

Reviewing those definitions before creating a custom role can help prevent unnecessary duplication.

Related Guide: Troubleshooting Wazuh RBAC: Why Your Custom User Roles Aren’t Applying

When reviewing an existing role, ask:

1. What users currently receive this role?
2. What permissions does it contain?
3. Which resources can it access?
4. Does it permit read operations?
5. Does it permit write operations?
6. Does it provide administrative access?
7. Does it have access to the required tenant?
8. Does it contain permissions unrelated to the user’s responsibilities?

The final question is particularly important when determining whether an existing role can safely be reused.

Identifying role permissions

After identifying a candidate role, inspect its individual permissions.

Separate permissions into categories such as:

• API operations.
• Index access.
• Cluster operations.
• Dashboard functionality.
• Tenant access.
• Read operations.
• Write operations.
• Administrative operations.

Do not evaluate a role solely by its name.

A role called analyst, for example, may have been customized in your environment. Its name does not guarantee that it provides exactly the permissions expected.

Always inspect the actual policies and mappings.

Checking user-role assignments

Next, identify which roles are assigned to each user.

This is important when troubleshooting unexpected access.

Suppose an analyst can modify a Wazuh configuration even though the intended analyst role is read-only.

The problem may not be the analyst role itself. The user could also be assigned to another role that grants write or administrative permissions.

Therefore, effective authorization should be evaluated across all roles assigned to the user.

Review:

• User identity.
• Assigned roles.
• Role mappings.
• External identity mappings, if applicable.
• Tenant assignments.
• Index permissions.
• API permissions.

When a user has unexpectedly broad access, look for an additional role or mapping before modifying the intended role.

Reviewing tenant permissions

Finally, inspect the tenant access associated with the user or role.

A role may provide access to a particular class of resources while the tenant configuration determines which logical workspace or data scope the user can access.

Verify:

• Which tenants the user can access.
• Which tenant is the user’s default.
• Whether the user can switch between tenants.
• Which indices are associated with those tenants.
• Whether the tenant contains the data the user is expected to see.

This is especially important in managed security environments and large enterprises where multiple teams share the same Wazuh deployment.

How to Create a Wazuh RBAC Role

Creating a custom Wazuh RBAC role should begin with access requirements rather than with the permissions available in the Dashboard.

The objective is not to create the most powerful role possible.

The objective is to create the smallest role that allows a user to perform their assigned responsibilities.

This is the practical application of least privilege.

Define the Role Requirements

Before opening the role-management interface, document what the role actually needs to accomplish.

For example:

Security analysts need to investigate alerts and endpoint activity but must not modify Wazuh configuration, detection rules, users, or cluster settings.

That requirement can then be translated into specific permissions.

Determine which users need access

Identify the users or groups that will receive the role.

For example:

• Tier 1 SOC analysts.
• Tier 2 incident responders.
• Vulnerability-management analysts.
• Compliance auditors.
• Security engineers.

Avoid creating roles for individual people unless there is a strong reason to do so.

The role should normally represent a job function, while the user represents an individual identity.

This makes the authorization model easier to maintain as employees join, leave, or change responsibilities.

Identify the resources they need

Next, list the actual Wazuh resources users need to access.

For an analyst, this might include:

• Security alerts.
• Agent information.
• Vulnerability information.
• Security Configuration Assessment results.
• File Integrity Monitoring events.
• Authentication events.
• Relevant dashboards.

For an engineer, the list might additionally include:

• Detection rules.
• Decoders.
• Agent configuration.
• Wazuh configuration.
• API management functions.

Explicitly identifying resources prevents administrators from granting broad access simply because the exact required permission has not yet been identified.

Determine read and write requirements

For every resource, determine whether the user needs:

Read access

The user can view or retrieve information.

Write access

The user can modify the resource.

Administrative access

The user can manage the resource or security configuration itself.

For example:

This exercise often reveals that users require substantially less privilege than initially assumed.

Apply the principle of least privilege

Grant the minimum permissions necessary to perform the documented job function.

Avoid creating a role with broad administrative access simply because it makes testing easier.

A useful design sequence is:

Required task → Required resource → Required operation → Minimum permission

For example:

Investigate alerts → Alert data → Read → Read permission

rather than:

Investigate alerts → Entire Wazuh environment → Administrator

Least privilege also makes compromised accounts less dangerous because the attacker inherits only the permissions associated with the compromised user’s role.

Create a Custom Security Role

Once the requirements are documented, create the custom role using the Wazuh security-management functionality available in your deployment.

Give the role a descriptive name that clearly communicates its purpose.

Good role names are functional and predictable, such as:

• soc_analyst
• incident_responder
• vulnerability_analyst
• wazuh_auditor
• security_engineer

Avoid names such as role1, custom, or new_admin, because they provide little information about the intended authorization boundary.

Define the role name

Choose a name based on the user’s job function rather than the individual user.

For example:

Good:

security_analyst

Less useful:

john_permissions

The first can be assigned to multiple analysts and remains meaningful if John leaves the team.

Document the purpose of the role alongside the configuration so future administrators understand why it exists.

Configure index permissions

Define which Wazuh indices the role can access and what operations are permitted.

For an analyst role, this will typically involve read access to the security data required for investigation.

Do not automatically grant access to every index.

Where data separation is required, restrict access to the indices corresponding to the user’s assigned tenant, environment, business unit, or operational function.

Index permissions are particularly important because Wazuh can contain security data that should not be exposed to every user.

Configure cluster permissions

Determine whether the role needs access to Wazuh or Indexer cluster functionality.

Most analysts should not require cluster-administration privileges.

Cluster-level permissions should generally be restricted to users responsible for:

• Cluster administration.
• Node management.
• Indexer administration.
• Performance management.
• Infrastructure troubleshooting.

For example, a security analyst investigating a failed authentication event normally has no operational reason to modify cluster settings.

Granting cluster administration in that situation would violate least privilege.

Configure tenant permissions

Assign the role access to the tenants required by the users who will receive it.

For example, an analyst assigned to a SOC tenant may need access to that tenant but not to an engineering or compliance tenant.

Tenant permissions should align with the organization’s data-separation requirements.

When creating a multi-tenant architecture, document the relationship between:

User → Role → Tenant → Index/Data

This makes authorization decisions easier to audit and troubleshoot.

Configure API permissions

If users or applications associated with the role need to interact with the Wazuh Server API, configure the appropriate API permissions.

Start by identifying the exact API operations required.

For example:

• Retrieve agent information.
• Retrieve alerts.
• Query configuration.
• Manage agents.
• Modify rules.
• Perform administrative operations.

Do not grant broad API access merely because a user needs one or two API endpoints.

Wazuh’s RBAC API model allows policies to specify actions, resources, and effects, providing the basis for more granular authorization.

Assign Permissions to the Role

After defining the resources, configure the permissions required by the role.

Think of this stage as translating the access requirements documented earlier into enforceable authorization rules.

Granting specific permissions

Grant only the permissions required for the role’s documented tasks.

For example, if an analyst only needs to investigate endpoint alerts, the role should not automatically receive permissions for:

• User administration.
• Cluster administration.
• Rule modification.
• Decoder modification.
• Security configuration changes.

Specific permissions make the role easier to understand and audit.

Restricting sensitive operations

Pay particular attention to permissions that can change the security posture of the Wazuh environment.

Sensitive operations can include:

• Creating or deleting users.
• Modifying roles.
• Changing security policies.
• Modifying detection rules.
• Modifying decoders.
• Changing agent configuration.
• Changing cluster configuration.
• Managing privileged integrations.

These permissions should normally be restricted to dedicated administrative or engineering roles.

Avoiding excessive privileges

One common RBAC mistake is adding permissions until the user’s workflow works and then leaving every added permission in place.

Instead, test incrementally.

Start with the minimum role.

If an operation fails, identify exactly which permission is missing.

Add that permission.

Test again.

This produces a much cleaner authorization model than starting with administrator access and attempting to remove unnecessary permissions later.

Validating the final permission set

Before assigning the role to production users, review the complete permission set.

Ask:

• Can the role access the required resources?
• Can it modify anything it should only read?
• Can it access unrelated tenants?
• Can it access unrelated indices?
• Can it manage users?
• Can it modify security configuration?
• Can it modify detection rules?
• Does it have cluster administration privileges?
• Are any permissions broader than necessary?

A permission review should ideally be performed by someone other than the person who created the role for sensitive production environments. This provides a basic separation-of-duties check.

How to Assign Wazuh Roles to Users

After creating a role, assign it to the appropriate users and configure their corresponding tenant access.

The process should be treated as a controlled authorization change rather than simply selecting a role from a dropdown.

Create or select a Wazuh user

First, identify the user who needs access.

For a local Wazuh account, create the user if one does not already exist.

For an externally authenticated user, verify that the identity-provider mapping is configured correctly.

Do not create duplicate local accounts for users who should be managed through centralized authentication unless there is a specific operational reason to do so.

Assign one or more roles

Assign the role that matches the user’s job function.

A user may require more than one role when their responsibilities span multiple functions.

For example, a security engineer could require:

• A general monitoring role.
• An engineering role.
• A specialized administrative role.

However, multiple roles should not be used as a substitute for thoughtful role design.

Remember that the user’s effective permissions may be broader than the permissions visible in any one role because the user can inherit permissions from multiple assigned roles or mappings.

Configure tenant access

Assign the user access to the appropriate tenant or tenants.

For example:

User: SOC Analyst

Role: security_analyst

Tenant: SOC

Access: Read-only security investigation

This provides a clearer authorization boundary than simply assigning the analyst to a broad administrative role.

If the user requires access to multiple tenants, document the business reason for each additional tenant.

Verify effective permissions

Do not assume that role assignment succeeded simply because the role appears in the user’s profile.

Verify the user’s effective authorization.

Check:

• Assigned roles.
• Role mappings.
• Index permissions.
• API permissions.
• Tenant access.
• Dashboard access.
• Effective read/write privileges.

Then compare those permissions against the original access requirements.

This is particularly important when a user has multiple roles because permissions can accumulate across assignments.

Test the user’s access

Finally, sign in as the test user and verify both permitted and prohibited operations.

For example, for a read-only analyst role:

Allowed:

• View alerts.
• View authorized agents.
• View permitted dashboards.
• Search authorized security data.

Denied:

• Modify detection rules.
• Create users.
• Change roles.
• Modify cluster configuration.
• Access unauthorized tenant data.

Testing both sides of the authorization boundary is critical.

A role is not fully validated merely because the user can perform the tasks they need.

You also need to confirm that the user cannot perform sensitive operations outside their responsibility.

For production deployments, record the test results as part of the RBAC change documentation.

A practical validation workflow is:

Create role → Assign role → Configure tenant → Log in as test user → Test allowed actions → Test denied actions → Review logs → Approve for production

This approach provides much stronger assurance than checking only whether the role appears correctly in the Wazuh Dashboard.

How to Configure RBAC for Different Wazuh Teams

A good Wazuh RBAC implementation should reflect the responsibilities of each security team rather than giving every user the same permissions.

A Security Operations Center (SOC), for example, may have analysts who investigate alerts, incident responders who need additional response capabilities, security administrators who manage the platform, and auditors who require visibility without modification privileges.

Creating separate roles for these functions provides clearer authorization boundaries and makes access reviews easier.

A typical Wazuh deployment can use a structure such as:

The exact permissions should be adjusted to the organization’s operational requirements.

Security Analysts

Security analysts generally need broad visibility into security telemetry but should not automatically receive permissions to modify Wazuh configuration.

A typical analyst role should prioritize read access.

Read-only alert access

Analysts need to view and search the security events required to investigate incidents.

Depending on the organization’s deployment, this can include access to:

• Wazuh alerts.
• Agent information.
• Authentication events.
• File Integrity Monitoring events.
• Vulnerability findings.
• Security Configuration Assessment results.
• Malware and threat-detection events.
• Relevant security dashboards.

Read-only access reduces the risk that an analyst accidentally modifies security configuration while investigating an incident.

It also limits the potential impact of a compromised analyst account.

Dashboard access

Analysts normally require access to the Wazuh Dashboard for day-to-day investigation.

Their role should provide access to the dashboards and data relevant to their responsibilities while restricting administrative areas they do not need.

For example, an analyst may need:

• Security events.
• Agent status.
• Vulnerability dashboards.
• FIM dashboards.
• SCA results.
• Authentication dashboards.

They generally should not need unrestricted access to:

• User administration.
• Role management.
• Security configuration.
• Cluster administration.

Related Guide: How to Configure Wazuh Alerts

Investigation permissions

Investigation permissions should allow analysts to obtain enough information to understand and triage security events.

A typical investigation workflow might involve:

1. Reviewing an alert.
2. Identifying the affected agent.
3. Examining related events.
4. Reviewing the source IP or user involved.
5. Checking vulnerability information.
6. Examining FIM or authentication activity.
7. Determining whether escalation is required.

The analyst role should support these activities without providing unnecessary configuration privileges.

For example, an analyst who needs to investigate a custom detection rule does not necessarily need permission to modify that rule.

Related Guide: How to Create Custom Detection Rules in Wazuh (With Examples)

Incident Responders

Incident responders require broader permissions than analysts because their responsibilities can include containment, investigation, and response actions.

However, response access should still be limited to the actions actually required by the incident-response process.

Alert investigation

Incident responders generally require all of the investigation capabilities available to analysts.

They may additionally need access to:

• Detailed agent information.
• Process and system information.
• Related security events.
• File Integrity Monitoring data.
• Authentication events.
• Vulnerability information.
• Active Response status.
• Historical alerts.

The objective is to allow responders to move from detection to containment without unnecessarily granting full administrative access.

Agent management requirements

Some incident-response teams need limited agent-management capabilities.

Depending on the organization’s procedures, responders may need to:

• Identify affected agents.
• Query agent status.
• Restart or reconnect agents.
• Collect additional information.
• Isolate affected endpoints through approved response procedures.

Agent-management permissions should be separated from full Wazuh administration wherever possible.

For example, a responder may need permission to manage an affected endpoint but should not necessarily be able to create Wazuh administrators or change the entire cluster configuration.

Related Guide: How to Configure Wazuh Active Response

Response-related permissions

Response permissions deserve particular attention because they can have direct operational consequences.

Wazuh Active Response can execute actions on monitored endpoints in response to detected events.

Giving broad response privileges to every analyst can therefore create unnecessary risk.

A responder role might be permitted to initiate approved response workflows while preventing the user from changing the underlying Active Response configuration.

For example:

Responder:

• Execute approved response action.
• View response results.
• Investigate affected agent.

Administrator:

• Configure response commands.
• Modify response policies.
• Create or remove response integrations.

This separation helps maintain a distinction between using an approved security control and changing the security control itself.

Security Administrators

Security administrators require significantly broader permissions because they are responsible for maintaining the Wazuh security platform itself.

However, even administrator roles should be designed around specific responsibilities whenever practical.

User and role management

A security administrator may need to:

• Create users.
• Disable users.
• Modify users.
• Assign roles.
• Create custom roles.
• Modify role mappings.
• Review authorization.
• Configure tenant access.

These permissions should be restricted to trusted administrators because incorrect RBAC changes can affect the entire organization.

A useful practice is to maintain at least one separate emergency administrative account that is not used for routine analyst activities.

Configuration access

Depending on the administrator’s responsibilities, configuration access may include:

• Wazuh Manager configuration.
• Agent configuration.
• Detection rules.
• Decoders.
• Integrations.
• Active Response configuration.
• Indexer security.
• Dashboard security configuration.

Not every administrator needs every one of these capabilities.

For example, a security-content administrator responsible for rules and decoders does not necessarily need authority to manage users.

Related Guide: How to Configure ossec.conf for Log Monitoring in Wazuh

Administrative permissions

Administrative permissions should be granted carefully because they can affect the security posture and availability of the entire Wazuh deployment.

Also, administrative roles may include permissions for:

• User administration.
• Role administration.
• Security policy management.
• Cluster management.
• Configuration management.
• Index management.
• Integration management.

Where possible, separate these responsibilities into specialized roles.

For example:

RBAC Administrator → User and role management

Wazuh Engineer → Configuration and detection management

Indexer Administrator → Indexer and storage management

This reduces the number of users with unrestricted privileges.

Auditors

Auditors generally require visibility rather than modification capabilities.

An auditor should be able to review the information necessary to determine whether security controls are operating correctly without being able to change those controls.

Read-only access

An auditor role may provide read access to:

• Security alerts.
• Agent inventory.
• Security configuration assessments.
• Vulnerability findings.
• Authentication events.
• Audit logs.
• Relevant dashboards.
• Retention and monitoring information.

The exact data should be determined by the organization’s compliance requirements.

Related Guide: How to Configure Wazuh Audit Logs

Restricted access to sensitive resources

Auditors may need broad read access but should not automatically receive access to every sensitive dataset.

For example, some environments may contain:

• Credentials or authentication-related information.
• Sensitive endpoint telemetry.
• Customer-specific data.
• Personally identifiable information.
• Restricted incident-response information.

The auditor role should therefore expose only the information required for the audit.

This is another situation where tenant and index-level restrictions can complement RBAC.

Compliance reporting requirements

Compliance teams may need access to evidence showing that security controls are operating as expected.

Useful evidence can include:

• Security Configuration Assessment results.
• Authentication events.
• Vulnerability findings.
• File Integrity Monitoring events.
• Security alerts.
• Audit logs.
• Agent coverage.
• Configuration changes.

The auditor role should provide enough visibility to collect this evidence while preventing modification of the underlying controls.

This creates a useful separation:

Auditor → Review evidence

Security administrator → Modify controls

That separation strengthens both access governance and auditability.

How to Configure Wazuh RBAC Using the Dashboard

The Wazuh Dashboard provides a graphical interface for managing users, roles, role mappings, and security settings.

The exact menu names and available options can differ between Wazuh releases, so use the security-management interface provided by your installed version.

Before making changes in production, create a backup of the relevant security configuration.

Access the Wazuh security configuration

Sign in to the Wazuh Dashboard using an account with sufficient administrative privileges.

Navigate to the security-management functionality available in your Wazuh version.

Depending on the version and deployment, this area may expose functionality for:

• Users.
• Roles.
• Role mappings.
• Index permissions.
• Tenant permissions.
• Security configuration.

If these options are missing, verify that the current account has the required privileges.

Do not immediately assume that the Dashboard is malfunctioning.

A missing security option can simply indicate that the current account is not authorized to manage it.

Create a custom role

Create a new security role and give it a descriptive name based on its intended purpose.

For example:

security_analyst

or:

incident_responder

Avoid naming a role after a specific user.

The role should represent a job function so that it can be reused when additional users join the same team.

Before saving the role, document its intended access boundary.

For example:

Security analysts can investigate authorized security data but cannot modify Wazuh security configuration.

This makes later permission reviews easier.

Configure permissions

Add the permissions required by the role.

Start with the minimum set.

For an analyst role, this might include:

• Read access to relevant indices.
• Read access to required Wazuh resources.
• Dashboard access to investigation views.
• Access to the appropriate tenant.

Avoid adding administrative permissions unless they are explicitly required.

For a responder role, add only the response and agent-management permissions required by the documented incident-response workflow.

For an administrator role, broader permissions may be appropriate, but specialized administrative roles are preferable to unrestricted access whenever possible.

Assign the role to a user

After creating the role, assign it to the appropriate user or users.

Verify that the intended role mapping is actually applied.

If the user already has other roles, review those assignments as well.

For example, suppose the intended analyst permissions are:

Read-only analyst

but the user also has:

Cluster administrator

The user’s effective permissions can be much broader than those defined by the analyst role.

Always review all applicable role assignments.

Configure tenant access

Configure the tenant or tenants that the user should be able to access.

For example:

Role: security_analyst

Tenant: SOC

Data scope: Production security events

If the user should not access the Compliance or Engineering tenants, do not grant those permissions simply because they are available.

Tenant configuration should match the organization’s data-isolation requirements.

Test the configuration

Testing should include both successful and unsuccessful authorization checks.

Log in as the test user and verify that the user can:

• Access the intended Dashboard.
• View authorized alerts.
• Search permitted data.
• Access authorized agents.
• Use permitted investigation functions.

Then verify that the user cannot:

• Modify restricted rules.
• Create users.
• Modify roles.
• Access unauthorized tenants.
• Modify cluster configuration.
• Access restricted indices.

This negative testing is essential.

A role that successfully performs its intended task has not necessarily been configured securely if it can also perform actions outside the user’s responsibility.

If the test user still has excessive privileges, inspect the user’s complete role and role-mapping configuration before modifying the custom role.

How to Configure Wazuh RBAC From the Command Line

Command-line RBAC administration is useful for automation, configuration management, repeatable deployments, and environments where administrators prefer API-driven workflows.

However, Wazuh RBAC is not configured through a single universal configuration file.

Different authorization layers are managed through different Wazuh and Wazuh Indexer security mechanisms.

For that reason, identify the specific layer you are changing before modifying any configuration.

Relevant Wazuh security configuration files

The exact files and paths depend on the Wazuh component and installed version.

Important areas can include:

• Wazuh Manager/API configuration.
• Wazuh RBAC policy definitions.
• Wazuh Indexer security configuration.
• Indexer role mappings.
• Dashboard security configuration.
• Authentication-provider configuration.

For example, Wazuh Server API RBAC policies are part of the Wazuh API security model, while Indexer roles and role mappings are managed through the Indexer’s security plugin.

Do not copy a configuration path from another Wazuh version without verifying that it applies to your installation.

This is particularly important when automating RBAC because security configuration formats and available roles can change between releases.

Managing roles and role mappings

Command-line administration can be performed through the appropriate Wazuh APIs and, where applicable, the Wazuh Indexer security APIs.

A typical automation workflow is:

Authenticate → Create/update role → Define permissions → Create/update mapping → Apply configuration → Test access

For example, an administrator might maintain role definitions in a configuration-management repository and apply them consistently across multiple Wazuh environments.

This can be useful for organizations managing:

• Development Wazuh environments.
• Staging environments.
• Production clusters.
• Multiple SOC instances.
• Managed security environments.

When using API-based administration, use a dedicated administrative credential with the minimum privileges necessary to perform the RBAC changes.

Never embed administrative credentials directly into shell scripts or source-control repositories.

Use protected secrets, environment-specific credential stores, or an appropriate secrets-management system.

Applying configuration changes

After modifying a role or role mapping, apply the change using the mechanism appropriate to the component being modified.

Some Wazuh security changes are applied dynamically through the relevant API or security-management interface, while other configuration changes can require a service reload or restart.

Do not automatically restart every Wazuh component after changing a permission.

Instead:

1. Identify which security layer was changed.
2. Check the Wazuh documentation for that version.
3. Determine whether the change is dynamic.
4. Apply or reload the configuration if required.
5. Verify that the service remains healthy.
6. Test the affected account.

This minimizes unnecessary service disruption.

Restart requirements

RBAC changes do not universally require a full Wazuh restart.

The requirement depends on which component and configuration mechanism was changed.

For example, a role mapping changed through a supported security API may take effect without restarting the Wazuh Manager.

By contrast, manually modifying a configuration file that is read only during service startup may require the corresponding service to be restarted or reloaded.

Therefore, do not use a blanket command such as:

systemctl restart wazuh-manager
systemctl restart wazuh-indexer
systemctl restart wazuh-dashboard

as the default response to every RBAC change.

Restarting multiple production components unnecessarily can introduce avoidable downtime.

Always determine the required reload or restart behavior for the specific Wazuh version and component.

Verifying configuration changes

After applying command-line RBAC changes, verify the result from both the administrative and user perspectives.

First verify that the configuration was accepted.

Then verify the role itself:

• Does the role exist?
• Does it contain the expected permissions?
• Is the role mapping correct?
• Is the intended user associated with it?
• Is tenant access correct?

Finally, test the user’s effective authorization.

For example:

Expected behavior

View alerts             → ALLOWED
Search authorized data  → ALLOWED
View assigned agents    → ALLOWED
Modify detection rules  → DENIED
Create users             → DENIED
Modify cluster settings → DENIED

The final step is important because configuration correctness and authorization correctness are not necessarily the same thing.

A role can be syntactically valid while still granting too much or too little access.

For production environments, record the result of these tests as part of the RBAC change process.

A robust command-line workflow therefore looks like:

Back up configuration → Define role → Apply role → Map user → Configure tenant → Verify role → Test allowed operations → Test denied operations → Monitor for authorization errors

This provides a repeatable process for implementing Wazuh RBAC while minimizing the risk of accidentally granting excessive privileges.

Wazuh RBAC Role Mapping

Role mapping is the mechanism that connects an authenticated identity to one or more authorization roles.

In a Wazuh environment, this relationship is particularly important when authentication is handled externally through LDAP, SAML, OIDC, or another identity provider.

A useful way to think about the relationship is:

Identity → Role Mapping → Role → Permissions → Resources

Authentication establishes who the user is. Role mapping determines which authorization profile applies to that identity.

This distinction becomes especially important in enterprise Wazuh deployments, where administrators may manage hundreds or thousands of users through centralized identity systems.

What role mapping means

Role mapping associates a user, group, or externally authenticated identity with a security role.

For example:

User: alice

Mapped role: security_analyst

Permissions: Read security alerts and authorized endpoint data

The user does not need to have every permission individually assigned.

Instead, the role contains the permissions and the mapping associates the user with that role.

Role mapping becomes even more useful with groups:

IdP Group: SOC-Analysts

↓

Wazuh Role: security_analyst

↓

Permissions: Read-only investigation access

This approach allows administrators to manage access based on organizational membership instead of individual accounts.

Wazuh’s RBAC documentation describes role mappings as part of the authorization model used to determine which policies apply to users and their requests.

Mapping users to Wazuh roles

For local Wazuh users, administrators can associate individual accounts with the appropriate Wazuh security roles.

For example:

The important design principle is to assign users according to their job responsibilities.

Avoid creating a unique role for every user unless there is a specific business requirement.

Instead:

Users represent identities.

Roles represent responsibilities.

This makes the authorization model easier to maintain when employees change positions or new employees join the team.

Mapping groups to roles

Group-based role mapping is generally more scalable than individually mapping hundreds of users.

For example, an organization could maintain these groups in its identity provider:

• SOC-Analysts
• Incident-Responders
• Security-Engineers
• Security-Administrators
• Security-Auditors

Those groups can then correspond to Wazuh authorization roles:

This provides a clean separation between identity lifecycle management and application authorization.

When an employee moves from the SOC to another department, the identity provider can remove the employee from SOC-Analysts.

The corresponding Wazuh authorization can then change without requiring an administrator to manually modify the user’s Wazuh permissions.

Group mappings should be carefully reviewed because membership in a highly privileged IdP group can translate into significant Wazuh permissions.

Mapping externally authenticated identities

External authentication introduces another layer between the user and Wazuh authorization.

A typical flow is:

User → Identity Provider → Authentication → Identity/Group Information → Wazuh Role Mapping → Wazuh Permissions

The exact implementation depends on the authentication protocol and Wazuh version.

When configuring external identity mappings, verify:

• The identity provider returns the expected username or subject.
• Required group or role claims are present.
• Claim names match the configured mapping.
• The external group maps to the intended Wazuh role.
• The mapped role has the correct permissions.
• Tenant access is configured correctly.

A successful SSO login does not prove that role mapping is working.

A user can authenticate successfully and still receive insufficient permissions because the expected group or role claim was not mapped correctly.

RBAC with SAML

SAML can be used to authenticate Wazuh users through an external identity provider and provide attributes that can participate in authorization mapping.

A typical SAML workflow is:

User → Wazuh Dashboard → Identity Provider → SAML Authentication → SAML Assertion → Group/Role Mapping → Wazuh Authorization

The identity provider may return attributes containing information such as:

• Username.
• Email address.
• Group membership.
• Organizational role.
• Other identity attributes.

Wazuh can then use the relevant identity information when determining the user’s authorization.

For example:

SAML group: SOC-Analysts

Mapped Wazuh role: security_analyst

Tenant: SOC

This allows organizations to maintain group membership centrally.

Related Guide: How to Configure Wazuh SAML Authentication

When troubleshooting SAML RBAC, inspect the SAML assertion and verify that the expected group or role attribute is actually being returned.

A common mistake is configuring the identity provider to authenticate the user successfully but failing to include the group information required for authorization.

RBAC with OIDC

OIDC provides another method for integrating centralized identity with Wazuh.

An OIDC authentication flow typically involves:

User → Wazuh → Identity Provider → ID Token/Claims → Role Mapping → Wazuh Authorization

OIDC tokens can contain claims describing the authenticated identity and, depending on the provider configuration, group or role membership.

For example:

sub: 123456789
email: analyst@example.com
groups:
  - SOC-Analysts

The relevant group information can then be used to determine which Wazuh role should apply.

An enterprise might define:

SOC-Analysts
    ↓
security_analyst
    ↓
Read-only SOC access

and:

SOC-Administrators
    ↓
security_admin
    ↓
Wazuh administrative access

Related Guide: How to Configure Wazuh OIDC

When implementing OIDC-based RBAC, verify the actual claims returned by the identity provider rather than assuming that group membership is automatically available.

Also consider token size and group-claim behavior when users belong to many groups.

RBAC with LDAP

LDAP-based authentication can centralize user identities and group membership.

An organization could maintain LDAP groups such as:

• wazuh-analysts
• wazuh-responders
• wazuh-engineers
• wazuh-admins

These groups can then participate in the Wazuh authorization design.

For example:

LDAP group

wazuh-analysts

↓

Wazuh role

security_analyst

↓

Tenant

SOC

↓

Permissions

Read-only investigation access

Related Guide: How to Configure Wazuh LDAP Authentication

LDAP role mapping should be tested using an ordinary test account before applying the configuration to privileged groups.

Pay particular attention to nested groups and directory structures.

Depending on the LDAP implementation, a user’s effective group membership may not be represented exactly as expected by the authentication system.

Wazuh RBAC and SSO

Single sign-on (SSO) centralizes authentication so users can access Wazuh using their existing enterprise identity.

SSO and RBAC solve different problems:

SSO answers:

How does the user authenticate?

RBAC answers:

What is the authenticated user allowed to do?

Combining the two creates an identity-driven authorization model.

A typical enterprise architecture looks like:

Employee

↓

Corporate Identity Provider

↓

SSO Authentication

↓

User/Group Claims

↓

Wazuh Role Mapping

↓

Wazuh Permissions

↓

Tenant and Index Access

This approach can significantly simplify access administration in large Wazuh environments.

How RBAC interacts with SSO

When SSO is enabled, the identity provider becomes responsible for authenticating the user.

Wazuh then uses the authenticated identity and any relevant attributes to determine authorization.

For example:

Authentication

alice@example.com successfully authenticates through the corporate IdP.

Group

SOC-Analysts

Wazuh role

security_analyst

Tenant

SOC

Access

Read-only security investigation

The identity provider does not need to contain every Wazuh permission.

Instead, it can provide reliable identity and group information while Wazuh maintains the application’s authorization model.

This separation makes the system easier to manage.

Mapping identity-provider groups to Wazuh roles

Group-to-role mapping is one of the most useful patterns for enterprise Wazuh deployments.

For example:

This structure allows administrators to manage group membership centrally.

It also makes access reviews easier because an administrator can ask:

Which users belong to the privileged Wazuh administrator group?

rather than having to inspect individual Wazuh permissions for every employee.

Assigning different permissions based on IdP groups

Different groups should receive different Wazuh roles based on their responsibilities.

For example:

SOC-Analysts

• Read alerts.
• Search authorized security data.
• View agents.
• Access investigation dashboards.
• No role administration.

SOC-Responders

• Everything required for investigation.
• Additional agent-management permissions.
• Approved response functionality.
• No unrestricted user administration.

SOC-Administrators

• User management.
• Role management.
• Tenant administration.
• Security configuration.
• Other required administrative functions.

SOC-Auditors

• Read-only access.
• Compliance dashboards.
• Audit information.
• No configuration changes.

This creates a predictable authorization hierarchy without requiring each user’s permissions to be manually maintained.

Designing roles for enterprise SSO

Enterprise SSO deployments should use roles that correspond to stable business functions.

Avoid creating roles based on temporary projects or individual employees.

Good examples include:

• wazuh_soc_analyst
• wazuh_incident_responder
• wazuh_security_engineer
• wazuh_security_admin
• wazuh_auditor

The role should also have a documented purpose and owner.

For each role, document:

• Who should receive it.
• Which IdP group maps to it.
• Which Wazuh permissions it contains.
• Which tenants it can access.
• Which indexes it can access.
• Whether it has write privileges.
• Who approves membership.

This creates an auditable relationship between identity management and Wazuh authorization.

Testing SSO role mappings

Do not consider an SSO implementation complete after confirming that users can log in.

Test the complete authentication-to-authorization chain.

For each important IdP group:

1. Create or identify a test account.
2. Add the account to the appropriate IdP group.
3. Authenticate through SSO.
4. Confirm that the expected Wazuh role is assigned.
5. Confirm tenant access.
6. Verify permitted operations.
7. Verify denied operations.
8. Remove the account from the group.
9. Authenticate again.
10. Confirm that the previous privileges are no longer available.

Test privileged roles separately.

For example, verify that a member of SOC-Analysts cannot access the same administrative functions available to SOC-Admins.

This catches both missing permissions and excessive permissions.

Wazuh RBAC and Multi-Tenancy

Multi-tenancy adds another authorization dimension to Wazuh RBAC.

Instead of asking only:

What can this user do?

the organization must also ask:

Which data and tenant should this user be allowed to access?

A strong multi-tenant design combines:

User → Role → Tenant → Index → Permissions

This is especially important for managed security providers, large enterprises, and organizations with separate security teams.

Tenant-based access control

Tenant-based access control limits which logical Wazuh workspace a user can access.

For example:

This allows different groups to share the same Wazuh infrastructure while maintaining logical boundaries.

Tenant access should be configured in conjunction with Indexer permissions so that the user does not gain access to underlying data outside the intended scope.

Isolating security teams

Large organizations may have multiple security teams with different responsibilities.

For example:

• Enterprise SOC.
• Cloud security.
• Endpoint security.
• Vulnerability management.
• Compliance.
• Incident response.

Each team can receive its own role and tenant where appropriate.

For example:

Cloud Security

cloud_security role

↓

Cloud tenant

Compliance

compliance_auditor role

↓

Compliance tenant

SOC

security_analyst role

↓

SOC tenant

This prevents users from automatically seeing information unrelated to their responsibilities.

It also makes internal access reviews easier because the intended authorization boundary is explicit.

Restricting access to specific indexes

Tenant-level separation should be supported by appropriate index-level access controls.

For example, a production security team might require access to production alert indices while a development team should only access development data.

Conceptually:

Production Analyst
    ↓
SOC-Production role
    ↓
Production tenant
    ↓
Production Wazuh indices

while:

Development Analyst
    ↓
SOC-Development role
    ↓
Development tenant
    ↓
Development Wazuh indices

Do not assume that hiding a Dashboard visualization is sufficient to protect the underlying data.

Authorization should be enforced at the appropriate security layer so that users cannot bypass the Dashboard restriction by directly querying an index or API.

Separating development and production environments

Development and production environments should generally have separate authorization boundaries.

A developer may need to test Wazuh rules, integrations, and dashboards without having permission to modify production security controls.

A practical model could be:

Development

• Security developers.
• Test data.
• Write access.
• Experimental configurations.

Production

• SOC analysts.
• Incident responders.
• Production administrators.
• Restricted write access.

For example:

This reduces the likelihood that development activity will affect production monitoring.

It also supports a controlled promotion process in which detection rules and configuration changes are tested before being deployed to production.

Designing RBAC for multi-tenant SOC environments

Managed Security Service Providers (MSSPs) and large SOCs need particularly careful tenant isolation.

Consider an MSSP monitoring three customers:

1. Customer A

• Tenant: customer_a
• Role: customer_a_analyst

2. Customer B

• Tenant: customer_b
• Role: customer_b_analyst

3. Customer C

• Tenant: customer_c
• Role: customer_c_analyst

The objective is to ensure that Customer A’s analysts cannot access Customer B’s security data.

For internal SOC teams, a similar structure can separate business units:

SOC Analyst
    ↓
Analyst Role
    ↓
Assigned Tenant
    ↓
Authorized Indices
    ↓
Security Data

Avoid relying exclusively on user naming conventions or Dashboard visibility for tenant isolation.

Instead, establish explicit authorization boundaries through roles, tenant permissions, and index permissions.

A mature multi-tenant RBAC design should also account for:

• Tenant ownership.
• Role ownership.
• Customer or business-unit boundaries.
• Administrative access.
• Cross-tenant support requirements.
• Incident-response escalation.
• Audit access.
• Privileged administrator access.
• User lifecycle changes.
• Offboarding.
• Temporary access.
• Access-review procedures.

For example, a central Wazuh administrator may legitimately need cross-tenant administrative access, while a customer-specific analyst should not.

That distinction should be reflected in separate roles rather than giving every user a common administrative role.

A useful final model is:

Authentication

↓

Identity Provider

↓

Group

↓

Wazuh Role

↓

Permissions

↓

Tenant

↓

Index Access

↓

Authorized Security Data

This layered approach allows Wazuh RBAC to scale from a small SOC to complex enterprise or multi-customer deployments while maintaining clear separation between authentication, authorization, and data isolation.

Wazuh RBAC Best Practices

A well-designed Wazuh RBAC implementation should do more than separate administrators from analysts.

It should establish clearly defined authorization boundaries, minimize unnecessary privileges, and provide a repeatable process for reviewing and testing access.

The following best practices can help keep Wazuh RBAC manageable and secure as the environment grows.

Follow the principle of least privilege

The principle of least privilege means giving users only the permissions required to perform their assigned responsibilities.

For example, a security analyst investigating alerts may need read access to alert and agent data but have no reason to modify detection rules or manage users.

A practical RBAC design process is:

Job function → Required resource → Required operation → Minimum permission

Avoid starting with an administrator role and removing permissions until the account appears sufficiently restricted.

It is generally safer to start with minimal access and add permissions as specific requirements are identified.

Least privilege should also apply to service accounts and API clients.

An integration that only needs to retrieve alerts should not receive permissions to modify users, roles, or Wazuh configuration.

Use dedicated roles instead of individual permission assignments

Create roles around stable job functions rather than assigning permissions separately to individual users.

For example:

• security_analyst
• incident_responder
• security_engineer
• security_admin
• security_auditor

This produces a more manageable structure:

User → Role → Permissions

rather than:

User → Permission 1 + Permission 2 + Permission 3 + Permission 4

When a permission needs to change, administrators can update the appropriate role rather than manually modifying every affected account.

Wazuh provides predefined roles and policies while also supporting custom authorization structures.

Avoid granting administrator privileges unnecessarily

Administrator access should be treated as a privileged capability rather than a convenient default.

An administrator role may provide access to functions that can affect the security posture or availability of the Wazuh deployment.

Before granting administrative access, determine whether the user actually needs it.

For example:

Security Analyst

• View alerts.
• Investigate events.
• View authorized agents.

Security Administrator

• Manage users.
• Manage roles.
• Modify security configuration.
• Manage privileged resources.

These should normally be separate roles.

Separate analyst and administrator roles

Separating analyst and administrator functions provides a clear security boundary.

An analyst should generally be able to investigate security events without being able to change the controls used to detect those events.

This reduces the risk of:

• Accidental configuration changes.
• Unauthorized rule modifications.
• Privilege abuse.
• Compromised analyst accounts affecting security controls.

A common structure is:

The exact permissions should be adapted to your environment.

Restrict access to sensitive indexes

Not every Wazuh user should automatically have access to every indexed dataset.

Security data can contain sensitive information about:

• Users.
• Endpoints.
• Authentication activity.
• Network connections.
• Vulnerabilities.
• Internal systems.
• Security incidents.
• Customer environments.

Use index permissions and tenant boundaries to restrict access where appropriate.

For example, a development team may need access to development security data but should not automatically have access to production indexes.

Similarly, a customer-specific analyst in a multi-tenant SOC should only be able to access the indexes associated with that customer.

Use groups for scalable role management

Group-based authorization becomes increasingly valuable as the number of Wazuh users grows.

Instead of assigning roles individually, map identity-provider groups to Wazuh roles.

For example:

SOC-Analysts
    ↓
security_analyst

SOC-Responders
    ↓
incident_responder

SOC-Engineers
    ↓
security_engineer

SOC-Admins
    ↓
security_admin

This makes onboarding and offboarding easier.

When an employee joins the SOC, adding them to the appropriate identity-provider group can automatically provide the required Wazuh authorization.

When they leave the SOC, removing them from the group can remove the corresponding access.

This also centralizes the identity lifecycle while allowing Wazuh to maintain application-specific authorization.

Regularly review user permissions

RBAC should be reviewed periodically rather than configured once and forgotten.

Access reviews should examine:

• Active users.
• Assigned roles.
• Role mappings.
• Tenant access.
• Index permissions.
• API permissions.
• Administrative privileges.
• External group memberships.

Look specifically for users who have accumulated permissions over time.

For example, an analyst who previously worked as a security engineer may retain an engineering role after moving to a different team.

This is a common source of privilege creep.

Remove inactive users

Disable or remove accounts that are no longer required.

This includes:

• Former employees.
• Former contractors.
• Temporary accounts.
• Test accounts.
• Abandoned service accounts.
• Accounts created for completed projects.

For externally authenticated users, ensure that removing or disabling access in the identity provider also results in appropriate Wazuh access removal.

Inactive accounts represent unnecessary attack surface, particularly when they retain privileged roles.

Audit role changes

Role changes should be treated as security-sensitive events.

Record:

• Who changed the role.
• Which user was affected.
• Which role was added or removed.
• Which permissions changed.
• When the change occurred.
• Why the change was made.
• Who approved it.

This provides an audit trail for investigating unexpected privilege changes.

For organizations with formal change-management processes, RBAC changes should be associated with the appropriate change request or approval record.

Document custom roles

Every custom role should have documentation explaining its purpose.

At minimum, document:

• Role name.
• Business purpose.
• Intended users.
• Owner.
• Permissions.
• Tenant access.
• Index access.
• API permissions.
• Administrative capabilities.
• Approval requirements.

For example:

Role: security_analyst
Purpose: SOC alert investigation
Owner: SOC Manager
Access: Read-only
Tenant: SOC
Index scope: SOC security data
Administrative access: None

This makes future permission reviews substantially easier.

Without documentation, administrators may eventually be unable to determine why a custom role exists or whether a permission can safely be removed.

Test RBAC changes before production deployment

Do not introduce a new RBAC role directly into production without testing it.

Use a test account that represents the intended user.

Verify both:

Allowed actions

and:

Denied actions

For example:

View alerts              → ALLOWED
View authorized agents   → ALLOWED
Modify detection rules  → DENIED
Create users             → DENIED
Access restricted tenant → DENIED

This approach catches excessive privileges before they affect production users.

For major RBAC changes, test in a development or staging Wazuh environment first and then promote the validated configuration into production.

How to Test Wazuh RBAC

Testing is an essential part of implementing Wazuh RBAC.

A role should not be considered correctly configured simply because it appears in the Dashboard or because a user can successfully authenticate.

The actual authorization boundary needs to be tested.

A comprehensive RBAC test should verify:

Identity → Role Mapping → Permissions → Tenant → Resource → Operation

Log in as a test user

Create or identify a test account representing the role being evaluated.

Do not perform initial RBAC testing using a production administrator account because administrators may have additional privileges that hide authorization problems.

For example, create a test account for:

security_analyst

Then authenticate using that account through the same mechanism production users will use.

If the environment uses SSO, test through the actual identity provider rather than bypassing SSO with a local account.

Verify permitted resources

Confirm that the test user can access everything required for their job.

For an analyst, this might include:

• Alert data.
• Authorized agents.
• Relevant dashboards.
• Vulnerability information.
• SCA results.
• FIM events.
• Authentication events.

Document the expected result before testing.

For example:

This provides a clear baseline against which the test results can be compared.

Verify restricted resources

Negative testing is just as important as positive testing.

Attempt to access resources the user should not have permission to access.

For example, an analyst account should be tested against:

• Administrative dashboards.
• User-management functions.
• Role-management functions.
• Restricted tenants.
• Restricted indices.
• Security configuration.
• Cluster administration.

The expected result should be a denial or absence of access.

If the user can access a restricted resource, investigate the effective permissions before deploying the role.

Test read and write permissions

Test read and write operations separately.

For a read-only role:

Read operation → Allowed

Write operation → Denied

For example, an analyst may be able to view a detection rule but should not be able to modify it.

This distinction is particularly important for Wazuh security configuration.

A user who can read a resource does not necessarily need permission to modify it.

Test API access

If the role includes Wazuh API access, test the actual API operations required by the user or application.

Verify that:

• Required API requests succeed.
• Unauthorized API requests fail.
• Administrative endpoints remain restricted.
• The API client receives the expected authorization response.

Do not test API access only through the Dashboard.

A user might be correctly restricted in the graphical interface while still having excessive API privileges.

This is why API authorization should be tested independently.

Test tenant isolation

In multi-tenant environments, log in as a test user and attempt to access both the assigned tenant and an unauthorized tenant.

For example:

SOC tenant
    → ALLOWED

Compliance tenant
    → DENIED

Engineering tenant
    → DENIED

Also verify that the user cannot access restricted data through another route.

Tenant isolation should be validated together with index permissions.

Validate role mappings

Confirm that the user received the expected role through the expected mapping mechanism.

For local users, verify the user’s assigned roles.

For SSO users, verify:

• Identity-provider group membership.
• Returned group or role claims.
• Role mapping.
• Effective Wazuh role.
• Tenant assignment.

Example:

IdP group:
SOC-Analysts

Expected Wazuh role:
security_analyst

Expected tenant:
SOC

If the user receives a different role, troubleshoot the mapping before changing the role’s permissions.

Confirm that privilege escalation is not possible

The final test should focus on privilege escalation.

Attempt to determine whether the test user can gain additional privileges by:

• Accessing administrative endpoints.
• Modifying their own roles.
• Creating another privileged user.
• Modifying role mappings.
• Accessing restricted APIs.
• Accessing unauthorized indices.
• Switching to unauthorized tenants.
• Modifying security configuration.

The user should not be able to elevate their privileges beyond the role assigned to them.

This is particularly important for roles that have any write or API permissions.

A successful RBAC test therefore includes both:

Can the user do what they need?

and:

Can the user do what they should not be able to do?

Wazuh RBAC Security Considerations

RBAC is itself a security control, which means the configuration used to manage RBAC must be protected.

A compromised administrator account or improperly secured security configuration can undermine every authorization boundary in the Wazuh deployment.

Protect administrative accounts

Administrative accounts should receive additional protection because compromising one can potentially allow an attacker to modify users, roles, permissions, or security configuration.

Use appropriate controls such as:

• Strong authentication.
• MFA through the organization’s identity provider where supported.
• Dedicated administrator accounts.
• Restricted administrative access.
• Centralized identity management.
• Regular privileged-account reviews.
• Prompt removal of former administrators.

Avoid using a highly privileged administrator account for routine alert investigation.

The fewer activities performed from a privileged account, the smaller the opportunity for accidental or malicious misuse.

Limit access to security configuration

Security configuration should be accessible only to users who need to modify it.

This includes configuration associated with:

• Users.
• Roles.
• Role mappings.
• Authentication.
• Authorization.
• Tenants.
• Index permissions.
• Wazuh Manager security.
• Wazuh Indexer security.
• Dashboard security.

A user who only investigates alerts should not normally have permission to modify these controls.

Secure Wazuh API permissions

API access deserves particular attention because APIs can expose powerful administrative operations.

Create API permissions around specific tasks rather than granting broad access.

For example, an integration that retrieves agent information may only need read access to the relevant API resources.

It should not automatically receive permissions to:

• Create administrators.
• Modify roles.
• Change security settings.
• Modify cluster configuration.

API credentials should also be protected as sensitive secrets.

Never place privileged API credentials directly in publicly accessible source code, documentation, shell history, or version-control repositories.

Protect sensitive alert data

Wazuh alerts can contain sensitive information about users, systems, applications, authentication activity, and network activity.

Restrict access according to business and security requirements.

Use:

• Appropriate roles.
• Tenant restrictions.
• Index permissions.
• Least-privilege access.
• External identity groups.
• Regular access reviews.

For multi-customer environments, ensure that customer-specific users cannot access another customer’s indexed security data.

Related Guide: How to Set Up Wazuh Multi-Tenancy

Monitor privilege changes

Changes to users, roles, mappings, and permissions should be monitored.

Security teams should investigate unexpected changes such as:

• A new administrator account.
• A user receiving an administrative role.
• A role gaining new write permissions.
• A new identity-provider group mapping.
• A user gaining access to an additional tenant.
• A previously restricted index becoming accessible.

Privilege changes can be legitimate administrative activity, but they can also be indicators of account compromise or insider abuse.

Audit authentication and authorization events

Authentication and authorization events provide complementary information.

Authentication logs can help answer:

Who attempted to access Wazuh?

Authorization information helps answer:

What was that user allowed or denied from doing?

Monitor both.

Useful events include:

• Successful authentication.
• Failed authentication.
• Privileged login.
• Role assignment.
• Role removal.
• Permission changes.
• Tenant changes.
• Administrative API requests.
• Authorization failures.

Repeated authorization failures from an account may indicate either a configuration problem or an attempt to access resources outside the user’s assigned privileges.

Related Guide: How to Configure Wazuh Audit Logs

Regularly review role assignments

RBAC should be treated as a lifecycle process.

At regular intervals, review:

• Users.
• Roles.
• Role mappings.
• Group memberships.
• Tenant assignments.
• Index permissions.
• API permissions.
• Privileged accounts.

Ask whether each user’s current permissions still match their current responsibilities.

This is particularly important after:

• Department changes.
• Promotions.
• Employee departures.
• Contractor changes.
• Organizational restructuring.
• New tenant creation.
• New Wazuh integrations.
• Major Wazuh upgrades.

A mature Wazuh RBAC program combines least privilege, centralized identity management, tenant isolation, permission reviews, auditing, and continuous testing rather than relying on role assignments alone.

The ultimate objective is to ensure that every Wazuh identity has the minimum access necessary, that sensitive security data remains isolated, and that changes to authorization can be detected and investigated.

Real-World Wazuh RBAC Example

Consider a large enterprise Security Operations Center (SOC) that uses Wazuh to monitor thousands of endpoints across production, development, and corporate environments.

The organization has four primary security teams:

• Security analysts.
• Incident responders.
• SOC managers.
• Wazuh administrators.

The organization also uses an enterprise identity provider for SSO and wants to ensure that users receive Wazuh permissions based on their existing security-team membership.

The resulting authorization architecture is:

Enterprise IdP → Group Membership → Wazuh Role → Tenant → Index/Data Access

This approach allows the organization to centralize identity management while maintaining granular Wazuh authorization.

Create dedicated roles for each team

The organization creates separate Wazuh roles based on job responsibilities.

The roles are deliberately separated rather than giving every SOC employee the same administrative permissions.

Wazuh’s API RBAC model supports roles containing collections of policies and rules, while the Wazuh Indexer security layer can additionally control index, tenant, document-level, and field-level access.

Restrict analysts to appropriate alert data

Security analysts primarily investigate alerts and security events.

Their role therefore provides read access to the data required for investigation but does not provide unrestricted administrative access.

For example:

soc_analyst
    ├── Read alerts
    ├── Read agent information
    ├── Read vulnerability data
    ├── Read SCA results
    ├── Read FIM events
    └── No user/role administration

If the organization operates multiple environments, the analysts can also be restricted to the appropriate tenant and indices.

This prevents an analyst assigned to one operational environment from automatically receiving access to unrelated security data.

Give incident responders additional operational permissions

Incident responders receive the analyst capabilities plus additional permissions required for incident containment and response.

Their role might provide:

incident_responder
    ├── Analyst read permissions
    ├── Additional agent management
    ├── Approved response operations
    └── Incident-response data

The organization deliberately avoids giving responders unrestricted Wazuh administration.

For example, responders may be authorized to perform an approved response action without being authorized to modify the underlying Active Response configuration.

This separates using a security control from administering the security control.

Related Guide: How to Configure Wazuh Active Response

Give administrators full management access

Wazuh administrators receive the permissions required to manage the platform.

Depending on the organization’s architecture, this can include:

• User management.
• Role management.
• Role mappings.
• Tenant management.
• Wazuh configuration.
• Rules and decoders.
• Agent administration.
• Cluster administration.
• Security configuration.

The organization treats these accounts as privileged identities and protects them accordingly.

Wazuh provides an administrator API role with full access to Wazuh Server API endpoints, illustrating why such privileges should be assigned only when they are actually required.

Use tenants to isolate security data

The enterprise creates separate tenants for different operational areas.

For example:

Production SOC
    → Production tenant

Development Security
    → Development tenant

Compliance
    → Compliance tenant

The organization then maps appropriate roles to the appropriate tenants.

Wazuh custom tenants can be assigned to specific roles, with read or write access controlled through the Dashboard’s security configuration.

Tenant access is combined with appropriate index permissions rather than being treated as the only security boundary.

Integrate RBAC with enterprise SSO

The organization uses its enterprise identity provider to manage group membership.

For example:

SOC-Analysts
    ↓
soc_analyst

SOC-Incident-Responders
    ↓
incident_responder

SOC-Managers
    ↓
soc_manager

Wazuh-Administrators
    ↓
wazuh_admin

When an employee changes departments, the identity provider’s group membership changes.

This allows the user’s Wazuh access to change according to the new organizational role rather than requiring an administrator to manually rebuild permissions.

Wazuh supports external authentication systems including SAML, LDAP, and Active Directory, and its current documentation also provides SSO integrations for multiple identity providers.

Related Guide: How to Configure Wazuh SSO

Test and audit the resulting permissions

Before deploying the roles to the entire SOC, the security team creates test accounts for each role.

For each account, they test:

Allowed operations

• View authorized alerts.
• Access assigned dashboards.
• View permitted agents.
• Perform approved response operations.

Denied operations

• Access restricted tenants.
• Access unauthorized indexes.
• Modify restricted rules.
• Create users.
• Modify roles.
• Access administrator functions.

The organization then records the results and periodically reviews the role assignments.

This produces a repeatable access-control lifecycle:

Design → Implement → Test → Deploy → Monitor → Review → Adjust

Wazuh RBAC vs. Field-Level Security and Document-Level Security

RBAC, field-level security (FLS), and document-level security (DLS) are related security mechanisms, but they operate at different levels.

A simplified model is:

RBAC → What can the user do?

DLS → Which documents can the user see?

FLS → Which fields within those documents can the user see?

These controls can be combined to create much more granular authorization than any one mechanism provides independently.

Wazuh’s current documentation explicitly describes Wazuh Indexer roles as supporting cluster permissions, index permissions, document-level security, field-level security, and tenant permissions.

What RBAC controls

RBAC primarily associates users or identities with roles that contain permissions.

In the Wazuh Server API, policies define:

• Actions.
• Resources.
• Effects.

For example:

Action: agent:read
Resource: agent:id:*
Effect: allow

This determines whether an authenticated user is authorized to perform a particular API operation.

Wazuh’s API RBAC documentation describes roles, policies, rules, actions, resources, and effects as the core components of this authorization model.

RBAC is therefore primarily concerned with authorization to perform operations.

What field-level security controls

Field-level security controls which fields within an indexed document a user can see.

Imagine a Wazuh document contains:

agent.name
agent.ip
user.name
source.ip
command
sensitive.internal_field

A role could potentially be configured so that the user can access the document while certain sensitive fields are excluded.

This is useful when users need the underlying event but should not see every piece of information contained within it.

For example, an analyst may need:

agent.name
agent.ip
rule.description
source.ip

while a more sensitive field is restricted.

FLS is therefore concerned with which attributes of an authorized document are visible.

What document-level security controls

Document-level security restricts which documents a user can retrieve.

For example, suppose the Wazuh Indexer contains alerts from three teams:

Team_A
Team_B
Team_C

A DLS rule can restrict a role to documents associated with Team_A.

Conceptually:

User
  ↓
Role
  ↓
wazuh-alerts*
  ↓
DLS filter
  ↓
Team_A documents only

Wazuh’s own RBAC documentation provides an example of using document-level security to restrict a user to alerts associated with a specific agent group.

DLS is therefore concerned with which records a user can see.

Differences between the three

The three mechanisms operate at different levels.

Consider an analyst who needs access to only Team A security events.

RBAC could establish:

The analyst can read alert data.

DLS could establish:

The analyst can only retrieve Team A documents.

FLS could establish:

The analyst cannot see restricted fields within those documents.

Together, they provide layered authorization.

When to use each approach

Use RBAC when the primary requirement is controlling what users or roles can do.

Examples include:

• Read versus write access.
• API operations.
• User administration.
• Agent management.
• Rule management.
• Cluster administration.

Use DLS when users need access to the same index but should only see specific records.

Examples include:

• Customer-specific alerts.
• Department-specific events.
• Production versus development data.
• Agent-group-specific monitoring.

Use FLS when users need access to the same documents but certain fields should remain hidden.

Examples include:

• Sensitive user information.
• Restricted metadata.
• Internal fields.
• Data requiring additional confidentiality controls.

Combining RBAC with data-level security

The strongest design often combines the mechanisms.

For example:

User
  ↓
SOC Analyst Role
  ↓
RBAC: Read alerts
  ↓
Tenant: Customer A
  ↓
DLS: Customer A documents
  ↓
FLS: Hide restricted fields

This provides several layers of protection.

However, administrators should avoid unnecessary complexity. Every additional security layer increases configuration and testing requirements.

Start with RBAC and least privilege, then add DLS or FLS when the data-separation requirements justify them.

Related Guide: How to Configure Wazuh Field Level Security

Monitoring and Auditing Wazuh RBAC

RBAC should be monitored after deployment because authorization configuration can change over time.

A secure Wazuh environment should track not only authentication events but also changes to the authorization model itself.

Monitor role changes

Monitor changes such as:

• Roles created.
• Roles deleted.
• Permissions added.
• Permissions removed.
• Policies modified.
• Administrative roles assigned.

A sudden change granting broad privileges to a previously restricted role should be investigated.

For example, if soc_analyst unexpectedly receives write access to security configuration, determine who made the change and why.

Monitor user and group changes

User and group membership changes can directly affect Wazuh authorization.

Monitor:

• New users.
• Disabled users.
• Deleted users.
• Group membership changes.
• Privileged-group additions.
• External identity mappings.

This is especially important when Wazuh uses an enterprise IdP.

An attacker who gains control of a privileged identity-provider group could potentially acquire elevated Wazuh access without directly modifying Wazuh roles.

Audit privilege assignments

Maintain an inventory of privileged assignments.

At minimum, identify:

• Wazuh administrators.
• Security administrators.
• Users with write access.
• Users with API administration privileges.
• Users with cross-tenant access.
• Accounts with access to sensitive indexes.

Periodically compare these assignments with current job responsibilities.

Detect unauthorized permission changes

Establish alerts or monitoring processes for unexpected authorization changes.

Potentially suspicious events include:

• A new administrator.
• A role suddenly gaining write access.
• A user receiving multiple privileged roles.
• A new cross-tenant mapping.
• A new external IdP group mapping.
• Changes to DLS or FLS policies.
• Changes to security configuration outside a maintenance window.

These events should be correlated with administrative change records where possible.

Review authentication and authorization failures

Monitor both successful and failed authentication and authorization events.

Repeated authorization failures can indicate:

• A misconfigured role.
• Incorrect SSO mapping.
• Missing tenant permissions.
• An improperly configured index permission.
• An attempted privilege escalation.
• An account attempting to access unauthorized resources.

A sudden increase in 403 responses from an administrative endpoint should therefore be investigated rather than automatically dismissed as a configuration problem.

Establish periodic access reviews

Schedule formal RBAC reviews.

For example:

Monthly

Review privileged accounts and recent role changes.

Quarterly

Review all user-to-role mappings and tenant assignments.

After organizational changes

Review affected users immediately.

After major Wazuh upgrades

Validate security roles, mappings, and permissions.

Each review should determine whether:

• The user still needs access.
• The assigned role is still appropriate.
• The tenant is still appropriate.
• Index permissions remain necessary.
• Privileged access remains justified.
• Temporary access has expired.

This turns Wazuh RBAC from a one-time configuration task into an ongoing access-governance process.

Frequently Asked Questions

Question: What is Wazuh RBAC?

Wazuh RBAC, or Role-Based Access Control, controls access to Wazuh resources according to roles and permissions.

Instead of assigning every permission directly to an individual user, Wazuh groups permissions into roles that can then be assigned to users.

Wazuh’s Server API RBAC model uses users, roles, rules, and policies to determine whether an operation is authorized.

Question: Does Wazuh support role-based access control?

Yes. Wazuh supports RBAC for controlling access to Wazuh Server API endpoints and resources.

Wazuh also provides security roles and role mappings for managing users through the Wazuh Dashboard and Wazuh Indexer security layer.

Question: How does RBAC work in Wazuh?

The basic model is:

User → Role → Policy/Permission → Resource

A user receives one or more roles. Those roles contain permissions that determine which operations the user can perform against specific Wazuh resources.

The Wazuh Server API policies use actions, resources, and effects to define authorization.

Question: How do I create a custom Wazuh role?

A custom role should be created by first identifying the user’s responsibilities and then assigning only the permissions required to perform those responsibilities.

For Wazuh Indexer security, the Dashboard provides a Security → Roles interface where administrators can create custom roles and configure cluster, index, tenant, document-level, and field-level permissions.

For Wazuh Server API RBAC, custom roles are built by associating the required policies and rules with the role.

Question: How do I assign roles to Wazuh users?

For internal users, roles can be assigned through the Wazuh Dashboard’s security-management functionality.

Wazuh’s documented workflow includes creating an internal user, mapping the user to an Indexer role, and creating a Wazuh role mapping that associates the user with the appropriate Wazuh role.

The exact mapping required depends on which Wazuh authorization layer you are configuring.

Question: What are Wazuh security roles?

Wazuh security roles are collections of permissions used to determine what users can access or modify.

Wazuh provides built-in roles such as administrator, agents_admin, agents_readonly, cluster_admin, cluster_readonly, readonly, and users_admin for common Server API authorization requirements.

Organizations can also create custom roles.

Question: Can Wazuh RBAC restrict access to specific indexes?

Yes. Wazuh Indexer security roles can define index-specific permissions.

For example, a role can be granted read access to particular Wazuh indices rather than receiving unrestricted access to every index.

Wazuh’s Indexer security model can also combine index permissions with document-level and field-level security.

Question: Can Wazuh RBAC restrict access to specific tenants?

Yes. Wazuh Dashboard multi-tenancy allows administrators to assign tenant access to specific roles and control whether that access is read-only or writable. Custom tenants can be created for specific groups of users.

Tenant permissions should be combined with appropriate index permissions when strong data isolation is required.

Question: Can I use Wazuh RBAC with SSO?

Yes. Wazuh can integrate with external authentication systems and identity providers.

The identity provider handles authentication while Wazuh authorization determines what the authenticated identity can access.

Wazuh’s current user-administration documentation covers SSO integrations with multiple identity providers.

Question: Can Wazuh RBAC work with SAML and OIDC?

Yes. Wazuh supports external identity-provider integrations, including SAML-based SSO and OIDC integrations, depending on the Wazuh deployment and authentication architecture.

The important distinction is that SAML or OIDC establishes the authenticated identity and can provide identity attributes, while role mapping determines the authorization associated with that identity.

Related Guides:

•  How to Configure Wazuh SAML Authentication
• How to Configure Wazuh OIDC

Question: What is the difference between Wazuh RBAC and field-level security?

RBAC primarily determines what operations a user can perform.

Field-level security determines which fields within an indexed document a user can see.

For example:

RBAC: User can read Wazuh alerts.

FLS: User can see the alert but cannot see a restricted field.

Wazuh Indexer security roles can combine permissions with document-level and field-level security.

Question: How do I troubleshoot Wazuh permission problems?

Start by determining whether the problem is authentication or authorization.

If the user cannot authenticate, investigate credentials, certificates, SSO, LDAP, SAML, OIDC, or identity-provider configuration.

If the user can log in but receives 403 Forbidden, cannot access a tenant, cannot see expected data, or can perform too many operations, investigate:

1. User-role assignments.
2. Role mappings.
3. Effective permissions.
4. Wazuh Server API policies.
5. Index permissions.
6. Tenant permissions.
7. DLS/FLS configuration.
8. SSO or LDAP group mappings.
9. Multiple roles assigned to the same user.

Wazuh’s Dashboard documentation provides separate areas for users, roles, policies, and role mappings, making these components useful starting points when diagnosing authorization problems.

Conclusion

Wazuh RBAC provides the authorization foundation needed to control what users can do within a Wazuh environment.

Instead of giving every user broad access, administrators can create roles based on specific responsibilities and assign users the permissions they actually require.

The most important principles are:

• Use least-privilege access.
• Create roles around job responsibilities.
• Separate analysts from administrators.
• Restrict access to sensitive indexes and tenants.
• Use identity-provider groups for scalable authorization.
• Test both permitted and denied operations.
• Monitor privileged changes.
• Regularly review role assignments.

The relationship between the major authorization components can be summarized as:

User → Role → Permissions → Tenant → Index/Data

For more granular environments, document-level and field-level security can be added:

User → Role → Tenant → Index → Document → Field

This layered approach allows organizations to control both what a user can do and which security data that user can access.

A production Wazuh RBAC implementation should therefore not be considered complete immediately after creating a role.

The configuration should be tested, documented, monitored, and periodically reviewed.

By combining role-based authorization, least privilege, tenant isolation, appropriate data-level controls, centralized identity management, and regular access reviews, organizations can build a Wazuh environment that provides analysts with the visibility they need while limiting unnecessary administrative and data access.