How to Configure Wazuh SSO Role Mapping

Single sign-on (SSO) simplifies access to Wazuh by allowing users to authenticate through an existing identity provider (IdP) instead of maintaining separate credentials inside the Wazuh platform. However, authentication alone does not determine what an authenticated user is allowed to do. A Wazuh deployment also needs an authorization mechanism that determines which dashboards, APIs, indices, tenants, and administrative functions each user can access. This is where Wazuh SSO role mapping becomes important.

How Wazuh SSO Role Mapping is Used

Role mapping connects identities managed by an external identity provider with roles defined in Wazuh.

For example, an organization might authenticate security analysts through Microsoft Entra ID, Okta, Keycloak, or another SAML/OIDC-compatible provider.

The identity provider can return attributes such as a username, email address, group membership, or role claim.

Wazuh can then use those attributes to determine which RBAC permissions should be assigned to the user.

This creates a separation between authentication and authorization:

• Authentication determines who the user is.
• Authorization determines what that user can access.
• SSO provides the centralized authentication mechanism.
• RBAC determines permissions within Wazuh.
• Role mapping connects the external identity to the appropriate Wazuh role.
• Multi-tenancy can further restrict which security data a user can access.

This model is particularly useful in larger security operations centers (SOCs), where manually creating and maintaining local accounts for every analyst, responder, auditor, and administrator can become difficult to manage.

For example, an organization could maintain groups such as Wazuh-Admins, Wazuh-Analysts, and Wazuh-Auditors in its identity provider.

Instead of manually assigning permissions to individual Wazuh users, administrators can map those groups to appropriate Wazuh roles.

When an employee changes departments, their identity-provider membership can be changed and the corresponding Wazuh access can change automatically.

This approach also supports the principle of least privilege, which recommends giving users only the permissions required to perform their responsibilities.

The National Institute of Standards and Technology (NIST) describes least privilege as restricting access to the minimum necessary to accomplish authorized tasks.

What This Guide Covers

This guide explains how Wazuh SSO role mapping works and how the different components fit together.

It covers SAML and OpenID Connect (OIDC), identity-provider attributes and groups, Wazuh roles, RBAC, multi-tenancy, testing, and common troubleshooting scenarios.

If you are building a broader Wazuh access-control architecture, this guide complements our existing How to Configure Wazuh RBAC and How to Set Up Wazuh Multi-Tenancy guides.

What Is Wazuh SSO Role Mapping?

Wazuh SSO role mapping is the process of taking identity information supplied by an external identity provider and using that information to determine which Wazuh roles and permissions should be assigned to an authenticated user.

The identity provider is responsible for establishing the user’s identity.

Wazuh then uses information supplied during the SSO process to determine what that identity is permitted to do.

A simplified relationship looks like this:

User
  ↓
Identity Provider
  ↓
Authentication
  ↓
SAML Assertion / OIDC Token
  ↓
User Attributes / Groups / Claims
  ↓
Wazuh Role Mapping
  ↓
Wazuh RBAC Role
  ↓
Permissions + Tenant Access

For example, suppose an employee belongs to the Wazuh-Analysts group in an organization’s identity provider.

After the employee successfully authenticates, the IdP can include that group as part of the SAML assertion or OIDC token.

Wazuh can use that group information to map the user to an analyst role.

IdP Group:
Wazuh-Analysts

        ↓

Wazuh Role Mapping

        ↓

Role:
Wazuh Analyst

        ↓

Permissions:
Read security data
View alerts
Access assigned tenant

The important distinction is that the identity provider does not necessarily need to understand every Wazuh permission.

Its primary responsibility is to authenticate the user and provide trusted identity information.

Wazuh’s authorization layer interprets that information and applies the appropriate permissions.

Authentication vs. Authorization

Firstly, authentication and authorization are separate security functions.

Authentication answers:

Who are you?

Authorization answers:

What are you allowed to access?

For example, an analyst might successfully authenticate through Okta.

That proves the identity provider has verified the user’s identity. It does not automatically mean that the user should have administrator access to Wazuh.

Role mapping provides the connection between the authenticated identity and the authorization model.

Authentication
"mike@example.com successfully authenticated."

                ↓

Role Mapping
"mike@example.com belongs to Wazuh-Analysts."

                ↓

Authorization
"Assign the analyst role."

                ↓

Access Control
"Allow the permissions associated with that role."

This separation is a fundamental part of modern access-control architectures.

NIST’s digital identity guidance distinguishes authentication from subsequent authorization decisions, reinforcing the importance of treating identity verification and access decisions as separate functions.

How the Identity Provider Authenticates Users

An identity provider acts as the centralized authentication authority.

Depending on the integration, Wazuh SSO can use protocols such as:

• SAML 2.0
• OpenID Connect (OIDC)

The user typically accesses the Wazuh Dashboard and is redirected to the identity provider.

The IdP authenticates the user using whatever authentication mechanisms the organization has configured, such as a password, multifactor authentication (MFA), security key, or another authentication method.

After successful authentication, the IdP returns identity information to the application.

With SAML, this information is contained in a SAML assertion.

With OIDC, it is typically contained in an ID token, with additional information potentially available through the UserInfo endpoint.

The identity information may contain values such as:

username
email
first_name
last_name
groups
roles
department

The exact attributes depend on the identity provider and its configuration.

How Wazuh Maps Authenticated Identities to Roles

Once Wazuh receives the authenticated identity and its associated attributes, role mapping determines which Wazuh role applies.

For example:

User:
alice@example.com

IdP group:
Wazuh-Responders

        ↓

Role mapping rule

        ↓

Wazuh role:
Incident Responder

        ↓

Assigned permissions

Another user could belong to:

Wazuh-Auditors

and therefore receive a more restrictive role:

Wazuh Auditor

This means the same SSO system can authenticate many different types of Wazuh users while their authorization remains differentiated.

The Role of User Attributes, Groups, and Claims

Role mapping typically relies on identity information referred to as attributes, groups, or claims, depending on the authentication protocol.

A SAML assertion might contain attributes such as:

<saml:Attribute Name="groups">
    <saml:AttributeValue>
        Wazuh-Analysts
    </saml:AttributeValue>
</saml:Attribute>

An OIDC identity token could contain a claim conceptually similar to:

{
  "sub": "123456789",
  "email": "alice@example.com",
  "groups": [
    "Wazuh-Analysts"
  ]
}

The actual syntax and claim names vary between identity providers.

The important point is that the value being mapped must be supplied consistently by the IdP.

For example, if Wazuh expects:

groups = Wazuh-Analysts

but the identity provider sends:

group = wazuh_analysts

the mapping may not match.

This is one of the most common sources of SSO role-mapping problems: the authentication succeeds, but the expected role is never assigned because the attribute, claim, group name, or value does not match the configured mapping.

How SSO Role Mapping Integrates With Wazuh RBAC

SSO role mapping and Wazuh RBAC perform different but complementary functions.

SSO establishes the user’s identity.

Role mapping determines which Wazuh role corresponds to that identity.

RBAC determines what permissions that role provides.

A simplified architecture is:

                 Identity Provider
                        │
                Authentication
                        │
             SAML / OIDC Response
                        │
                        ▼
                Wazuh SSO Layer
                        │
                  Role Mapping
                        │
                        ▼
                  Wazuh RBAC
                        │
          ┌─────────────┴─────────────┐
          ▼                           ▼
     Permissions                 Tenants
          │                           │
          └─────────────┬─────────────┘
                        ▼
                 Wazuh Dashboard

This is why configuring SSO alone does not necessarily provide the desired access-control model.

You also need to determine how authenticated identities map to the Wazuh authorization system.

For background on defining Wazuh roles and permissions independently of SSO: How to Configure Wazuh RBAC 

How Role Mapping Differs From Local Wazuh Users

Traditional local authentication requires administrators to create and maintain users directly within the Wazuh environment.

With SSO, the identity lifecycle can instead be managed by the organization’s centralized identity provider.

Consider a local-user deployment:

Administrator
     ↓
Create Wazuh user
     ↓
Assign Wazuh role
     ↓
Manage password
     ↓
Review account
     ↓
Disable account when employee leaves

With SSO:

Administrator
     ↓
Create/manage identity in IdP
     ↓
Assign IdP group
     ↓
SSO authentication
     ↓
Wazuh role mapping
     ↓
Wazuh permissions

The latter model can reduce duplicated identity-management work and make access changes easier to centralize.

However, SSO does not eliminate the need for careful authorization design.

A poorly configured mapping can grant excessive privileges just as a poorly configured local account can.

For example, mapping a broad IdP group such as Employees to a Wazuh administrator role would effectively give every member of that group administrative access.

Role mappings should therefore use narrowly defined groups or claims and follow least-privilege principles.

How Wazuh SSO Role Mapping Works

The complete Wazuh SSO role-mapping process involves several systems working together.

Although the exact configuration differs between SAML and OIDC deployments, the underlying authorization workflow is similar.

At a high level:

1. User opens Wazuh Dashboard
             ↓
2. Wazuh redirects user to IdP
             ↓
3. IdP authenticates user
             ↓
4. IdP generates SAML assertion or OIDC token
             ↓
5. Identity information is returned to Wazuh
             ↓
6. Wazuh extracts identity attributes
             ↓
7. Role mapping evaluates those attributes
             ↓
8. Matching Wazuh role is assigned
             ↓
9. RBAC permissions are applied
             ↓
10. Tenant restrictions are applied
             ↓
11. User receives authorized Dashboard access

Understanding this sequence makes troubleshooting substantially easier because a failure can be isolated to a specific stage.

User Authentication Flow

The process begins when a user attempts to access the Wazuh Dashboard.

Instead of authenticating directly against a local Wazuh account, the user is redirected to the configured identity provider.

For example:

User
  ↓
Wazuh Dashboard
  ↓
Identity Provider

The user then authenticates through the organization’s centralized authentication system.

Depending on the IdP configuration, this could involve:

• Username and password
• Multifactor authentication
• Hardware security keys
• Passkeys
• Conditional access policies
• Device-based authentication
• Existing IdP sessions

Once authentication succeeds, the identity provider returns an authentication response to the Wazuh environment.

Identity Provider Authentication

The identity provider is responsible for verifying the user’s identity.

For SAML, the IdP generates a signed SAML response containing an assertion about the authenticated user.

For OIDC, the IdP issues tokens according to the OpenID Connect flow being used.

In either case, Wazuh receives information that can identify the user and potentially provide additional authorization-related attributes.

This distinction is important: the IdP establishes the identity, while Wazuh uses the resulting identity information to make authorization decisions.

SAML Assertion or OIDC Token Generation

The next step depends on the protocol being used.

A SAML deployment returns a SAML assertion containing attributes about the authenticated user.

An OIDC deployment uses JSON Web Tokens (JWTs) and claims to communicate identity information.

Conceptually, the returned information could look like:

SAML

NameID:
alice@example.com

Groups:
Wazuh-Analysts

or:

{
  "sub": "123456789",
  "email": "alice@example.com",
  "groups": [
    "Wazuh-Analysts"
  ]
}

The exact structure depends on the IdP configuration.

Passing Username, Email, Groups, or Roles as Claims

The identity provider can expose different pieces of information about the user.

Common values include:

For role mapping, groups and roles are particularly useful because they allow administrators to manage authorization through centralized identity-management systems.

For example:

IdP

Wazuh-Admins
Wazuh-Analysts
Wazuh-Responders
Wazuh-Auditors

could correspond to:

Wazuh-Admins     → Wazuh administrator role
Wazuh-Analysts   → Wazuh analyst role
Wazuh-Responders  → Wazuh responder role
Wazuh-Auditors   → Wazuh auditor role

This approach allows changes to group membership to drive changes in Wazuh access without requiring administrators to manually edit every local account.

Wazuh Receiving Identity Attributes

After authentication, Wazuh receives the identity information supplied by the configured SSO mechanism.

At this stage, administrators should verify that the attributes required for role mapping are actually being returned.

For example, the expected mapping might require:

groups = Wazuh-Analysts

If the IdP instead sends:

groups = ["Wazuh Analysts"]

or:

roles = ["analyst"]

the configured mapping may not match.

This is why examining the actual SAML assertion or OIDC claims is an important troubleshooting step.

Authentication can succeed while role mapping fails.

Mapping Identity Attributes to Wazuh Roles

Once Wazuh has access to the identity attributes, the configured role-mapping rules determine which role should be applied.

Conceptually:

IF group == "Wazuh-Admins"
    → Administrator

IF group == "Wazuh-Analysts"
    → Analyst

IF group == "Wazuh-Auditors"
    → Auditor

More complex environments may use multiple attributes or mappings.

For example:

Department = Security
AND
Group = Wazuh-Analysts
        ↓
Wazuh Analyst

The exact mapping syntax depends on the Wazuh version and the authentication integration being configured.

Therefore, role mappings should always be validated against the Wazuh documentation for the specific release being deployed.

Applying Permissions and Tenant Access

After the user’s identity has been mapped to a Wazuh role, the corresponding RBAC permissions are applied.

Those permissions determine what the user can do within Wazuh.

For example, an analyst might be allowed to:

• View alerts
• Search security events
• Access assigned dashboards
• Investigate detections
• View security data

An administrator might additionally be allowed to:

• Manage users
• Configure roles
• Modify Wazuh settings
• Manage integrations
• Access administrative interfaces

If multi-tenancy is configured, the user’s access can also be constrained by tenant permissions.

This produces another layer of authorization:

SSO Identity
     ↓
Role Mapping
     ↓
Wazuh RBAC Role
     ↓
Permissions
     ↓
Tenant Access
     ↓
Authorized Wazuh Resources

For organizations separating security data between teams, this distinction is especially important.

A user can have a valid Wazuh role while still being restricted to particular tenants.

Related Guide: Mastering Wazuh Security: The Complete Access Control Guide

Complete SSO Role-Mapping Workflow

Putting everything together, a typical Wazuh SSO role-mapping workflow looks like this:

┌──────────────────────┐
│        User          │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│   Wazuh Dashboard    │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│ Identity Provider    │
│ SAML / OIDC          │
└──────────┬───────────┘
           │
           │ Authenticate
           ▼
┌──────────────────────┐
│ SAML Assertion or    │
│ OIDC Token           │
└──────────┬───────────┘
           │
           │ Claims / Attributes
           ▼
┌──────────────────────┐
│ Wazuh SSO Processing │
└──────────┬───────────┘
           │
           │ Role Mapping
           ▼
┌──────────────────────┐
│     Wazuh RBAC       │
└──────────┬───────────┘
           │
           ├──────────────► Permissions
           │
           └──────────────► Tenant Access
                          │
                          ▼
                 ┌─────────────────┐
                 │ Authorized Wazuh│
                 │     Access      │
                 └─────────────────┘

The key takeaway is that Wazuh SSO role mapping is the bridge between centralized identity management and Wazuh authorization.

The identity provider determines who successfully authenticates and supplies the relevant attributes; Wazuh then uses those attributes to map the identity to roles, permissions, and potentially tenant access.

This architecture is especially valuable in larger deployments because administrators can manage identity and group membership centrally while retaining granular authorization inside Wazuh.

For the practical configuration that follows, the most important prerequisites are a correctly configured SAML or OIDC integration, predictable user/group claims from the identity provider, appropriate Wazuh RBAC roles, and a clear mapping between external groups and internal Wazuh permissions.

Wazuh SSO Role Mapping Architecture

Wazuh SSO role mapping sits between the organization’s identity provider and Wazuh’s authorization layer.

Understanding this architecture before configuring SSO helps explain where authentication occurs, where roles are assigned, and where permissions are ultimately enforced.

A typical architecture contains several components:

                         ┌──────────────────────┐
                         │        User          │
                         └──────────┬───────────┘
                                    │
                                    ▼
                         ┌──────────────────────┐
                         │   Wazuh Dashboard   │
                         └──────────┬───────────┘
                                    │
                              SAML / OIDC
                                    │
                                    ▼
                         ┌──────────────────────┐
                         │ Identity Provider    │
                         │ Okta / Entra /       │
                         │ Keycloak / Google    │
                         └──────────┬───────────┘
                                    │
                              User / Groups
                                    │
                                    ▼
                         ┌──────────────────────┐
                         │   Role Mapping       │
                         └──────────┬───────────┘
                                    │
                                    ▼
                         ┌──────────────────────┐
                         │ Wazuh Indexer        │
                         │ Security Plugin      │
                         └──────────┬───────────┘
                                    │
                         Roles / Permissions
                                    │
                    ┌───────────────┴───────────────┐
                    ▼                               ▼
             Tenant Permissions                Wazuh Data
                    │                               │
                    └───────────────┬───────────────┘
                                    ▼
                            Authorized Access

Each component has a different responsibility.

Wazuh Dashboard

The Wazuh Dashboard provides the primary web interface through which analysts, administrators, responders, and auditors interact with Wazuh.

In an SSO deployment, users typically initiate authentication from the Dashboard.

The Dashboard redirects the authentication request to the configured identity provider and processes the response after successful authentication.

The Dashboard is therefore the visible entry point for SSO, but it is not the component that should be thought of as the entire authorization system.

The authenticated identity ultimately needs to be associated with appropriate permissions in the underlying security infrastructure.

This distinction becomes important when troubleshooting.

A user successfully reaching the Dashboard does not necessarily mean that role mapping has worked correctly.

Wazuh Indexer Security Plugin

The Wazuh Indexer provides the storage and search layer for Wazuh security data, while its security functionality is responsible for important authentication and authorization operations.

The security layer manages concepts such as:

• Users
• Roles
• Permissions
• Role mappings
• Authentication mechanisms
• Backend roles
• Tenant access

Consequently, the Indexer security configuration is a critical part of Wazuh SSO role mapping.

A successful SSO authentication does not automatically mean the user has the correct Indexer permissions.

The authenticated identity must ultimately correspond to the appropriate security roles.

This is also why SSO role-mapping problems can sometimes appear as authorization errors rather than authentication errors.

Wazuh Manager and API

The Wazuh Manager is responsible for core security monitoring functions such as agent management, event processing, rules, decoders, vulnerability detection, and active response.

The Wazuh API provides programmatic access to many Wazuh Manager capabilities.

SSO role mapping primarily concerns the authentication and authorization path used by the Wazuh Dashboard and Indexer, but the Manager and API remain important components of the overall Wazuh security architecture.

For example, a user may successfully authenticate to the Dashboard but still lack permission to perform particular Manager or API operations.

This reinforces an important principle:

Successful SSO authentication does not equal unrestricted Wazuh access.

For more information about the Wazuh API authentication layer, see: Wazuh API Authentication Failed? Causes and Solutions

Identity Provider

The identity provider (IdP) is the centralized system responsible for authenticating users and supplying identity information to Wazuh.

Common enterprise identity providers include:

• Microsoft Entra ID
• Okta
• Keycloak
• Google Workspace
• Other SAML- or OIDC-compatible identity platforms

The IdP typically maintains the organization’s users, groups, and authentication policies.

For example:

Wazuh-Admins
Wazuh-Analysts
Wazuh-Responders
Wazuh-Auditors

Instead of individually configuring every Wazuh user, an organization can manage membership in these groups through its existing identity-management system.

The identity provider then communicates the relevant information to Wazuh during authentication.

Related Guides:

• How to Integrate Wazuh with Okta 
• How to Integrate Keycloak with Wazuh  

SAML or OIDC Protocol

Wazuh SSO integrations commonly use established federation protocols such as Security Assertion Markup Language (SAML) or OpenID Connect (OIDC).

The two protocols serve a similar high-level purpose, federating identity, but their technical mechanisms differ.

With SAML:

User
 ↓
Wazuh
 ↓
Identity Provider
 ↓
SAML Authentication
 ↓
SAML Assertion
 ↓
Wazuh

With OIDC:

User
 ↓
Wazuh
 ↓
Identity Provider
 ↓
OIDC Authentication
 ↓
ID Token / Claims
 ↓
Wazuh

SAML commonly represents identity information through assertions and attributes, whereas OIDC represents identity information through claims contained in tokens and, depending on the flow, information obtained from the UserInfo endpoint.

The choice between SAML and OIDC generally depends on the identity provider, Wazuh version, organizational requirements, and existing authentication infrastructure.

User and Group Directory

The identity provider normally obtains user and group information from a directory or identity store.

The directory might contain:

Users
 ├── Alice
 ├── Bob
 ├── Carol
 └── David

Groups
 ├── Wazuh-Admins
 ├── Wazuh-Analysts
 ├── Wazuh-Responders
 └── Wazuh-Auditors

Groups are particularly useful for role mapping because they allow authorization decisions to be managed at the organizational level.

For example:

Alice
 ↓
Wazuh-Analysts
 ↓
Wazuh Analyst Role

If Alice later moves from the SOC analyst team to an auditing team, the administrator can remove her from Wazuh-Analysts and add her to Wazuh-Auditors.

The next SSO authentication can then result in different Wazuh permissions.

This creates a cleaner identity lifecycle than manually modifying local Wazuh accounts for every personnel change.

Role Mapping Layer

The role-mapping layer connects external identity information to Wazuh’s authorization model.

Conceptually:

External Identity
       ↓
Group / Role / Claim
       ↓
Role Mapping
       ↓
Wazuh Role
       ↓
Permissions

For example:

IdP Group                  Wazuh Role

Wazuh-Admins       →       Administrator
Wazuh-Analysts     →       Analyst
Wazuh-Responders   →       Responder
Wazuh-Auditors     →       Auditor

The mapping layer is where a large portion of Wazuh SSO configuration work occurs.

Administrators need to ensure that:

1. The IdP sends the expected attribute.
2. The attribute contains the expected value.
3. Wazuh receives the attribute.
4. The role-mapping rule matches that value.
5. The mapped Wazuh role exists.
6. The role has the intended permissions.

A failure at any of these stages can cause users to authenticate successfully but receive incorrect or insufficient permissions.

Multi-Tenancy and Tenant Permissions

Role mapping can also interact with Wazuh multi-tenancy.

Multi-tenancy allows organizations to separate access to Wazuh resources between different teams, departments, customers, or security functions.

For example:

                    Wazuh
                      │
       ┌──────────────┼──────────────┐
       ▼              ▼              ▼
   SOC Tenant    Compliance      Engineering
       │              │              │
   Analysts         Auditors       Analysts

A user’s role determines their permissions, while tenant configuration can further restrict which data or Dashboard resources they can access.

This is especially useful for managed security service providers (MSSPs), large enterprises, or organizations with multiple security teams.

Related Guide: How to Set Up Wazuh Multi-Tenancy 

Role mapping should therefore be designed with both permissions and tenant access in mind.

A mapping that grants an analyst role but unintentionally exposes a broader tenant can still violate the organization’s access-control requirements.

Example Enterprise SSO Architecture

Consider an enterprise SOC with four primary groups:

Wazuh-Admins
Wazuh-Analysts
Wazuh-Responders
Wazuh-Auditors

The identity provider maintains those groups.

The Wazuh role mappings could conceptually look like:

Wazuh-Admins
       ↓
Wazuh Administrator
       ↓
Administrative permissions

Wazuh-Analysts
       ↓
Wazuh Analyst
       ↓
Investigation permissions

Wazuh-Responders
       ↓
Wazuh Responder
       ↓
Response permissions

Wazuh-Auditors
       ↓
Wazuh Auditor
       ↓
Read-only / audit permissions

The resulting architecture might look like:

                         Enterprise Users
                                │
                                ▼
                    ┌─────────────────────┐
                    │ Identity Provider    │
                    │                     │
                    │ Users + Groups      │
                    └──────────┬──────────┘
                               │
                         SAML / OIDC
                               │
                               ▼
                    ┌─────────────────────┐
                    │   Wazuh Dashboard   │
                    └──────────┬──────────┘
                               │
                               ▼
                    ┌─────────────────────┐
                    │ Role Mapping Layer  │
                    └──────────┬──────────┘
                               │
                               ▼
                    ┌─────────────────────┐
                    │ Indexer Security    │
                    │ Plugin / RBAC       │
                    └──────────┬──────────┘
                               │
                    ┌──────────┴──────────┐
                    ▼                     ▼
                Wazuh Roles          Tenants
                    │                     │
                    └──────────┬──────────┘
                               ▼
                       Authorized Access

This architecture separates identity management from Wazuh authorization while still allowing the two systems to work together.

Prerequisites for Wazuh SSO Role Mapping

Before configuring Wazuh SSO role mapping, verify that the underlying Wazuh deployment, identity provider, network configuration, and authorization model are ready.

SSO configuration should not be treated as an isolated Dashboard setting.

It depends on several components working together.

Supported Wazuh Deployment

Start by confirming the Wazuh version and deployment architecture.

At minimum, you should understand which components are installed:

Wazuh Manager
Wazuh Indexer
Wazuh Dashboard
Wazuh API

If you operate a multi-node environment, identify the relevant cluster nodes and determine where security configuration changes need to be applied.

Always verify the SSO configuration against the documentation corresponding to your installed Wazuh version.

Configuration syntax and supported authentication features can change between releases.

Wazuh Dashboard and Indexer Configured

The Wazuh Dashboard and Indexer should already be operational before implementing SSO role mapping.

Verify that:

• The Dashboard loads normally.
• The Indexer is healthy.
• Dashboard-to-Indexer communication works.
• Existing authentication works.
• Required certificates are valid.
• The Wazuh security configuration is functioning.

If the Dashboard is already experiencing authentication or connectivity problems, resolve those issues first.

Related Guides:

• Wazuh Dashboard Not Loading? Complete Troubleshooting Guide 
• How to Build a Wazuh Indexer Cluster 

Administrative Access

You need sufficient administrative privileges to configure the components involved in SSO.

Depending on the deployment, this may include access to:

• Wazuh Dashboard
• Wazuh Indexer security configuration
• Wazuh configuration files
• Identity provider administration
• DNS
• TLS certificates
• System services

Do not begin role mapping configuration using an account that cannot modify the underlying security configuration.

You should also retain a separate administrative recovery path whenever possible.

If a new SSO mapping accidentally removes access to your normal administrative account, an independent recovery mechanism can prevent a complete lockout.

Working SSO Identity Provider

Your identity provider should already be operational.

Examples include:

• Microsoft Entra ID
• Okta
• Keycloak
• Google Workspace
• Other compatible enterprise IdPs

Verify that users can authenticate successfully before introducing Wazuh-specific role mappings.

For example:

User
 ↓
IdP Login
 ↓
MFA
 ↓
Authentication Successful

If authentication itself fails, role mapping is not yet the problem.

Related Guide: How to Configure Wazuh SSO 

SAML or OIDC Configuration

Determine which federation protocol your environment will use.

For SAML, prepare the relevant:

• Entity ID
• Assertion Consumer Service URL
• IdP metadata
• Signing certificates
• NameID configuration
• Attribute mappings

For OIDC, prepare the relevant:

• Issuer
• Client ID
• Client secret, where applicable
• Redirect URI
• Required scopes
• Claims
• Discovery configuration

The exact values depend on your IdP and Wazuh deployment.

Related Guides:

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

Required User and Group Attributes

Determine exactly which identity attributes Wazuh will use for role mapping.

For example:

username
email
groups
roles

If groups are being used, define the expected group names before configuring the mapping.

Example:

Wazuh-Admins
Wazuh-Analysts
Wazuh-Responders
Wazuh-Auditors

Then verify that the IdP actually sends those values.

Do not assume that an IdP’s internal group membership automatically becomes available to Wazuh.

The relevant attribute or claim must be configured for inclusion in the authentication response.

This is one of the most important prerequisites for successful Wazuh SSO role mapping.

Existing Wazuh Roles

Create or identify the Wazuh roles that users should receive after authentication.

For example:

IdP Group                  Wazuh Role

Wazuh-Admins       →       Admin
Wazuh-Analysts     →       Analyst
Wazuh-Responders   →       Responder
Wazuh-Auditors     →       Auditor

Do not start by mapping every identity-provider group to a highly privileged role.

Instead, define the required access for each job function first and then create mappings that provide only those permissions.

Related Guide: How to Configure Wazuh RBAC 

DNS and TLS Configuration

SSO depends heavily on correct DNS and TLS configuration.

Verify that:

Wazuh Dashboard hostname
        ↓
Correct IP address
        ↓
Valid TLS certificate

The certificate should contain the hostname users actually access.

Also verify that the identity provider can reach the required Wazuh endpoint and that Wazuh can reach the identity provider when required by the authentication flow.

Common problems include:

• Incorrect DNS records
• Expired certificates
• Missing certificate SANs
• Incorrect redirect URLs
• TLS trust failures
• Reverse-proxy configuration errors
• HTTP/HTTPS mismatches

Related Guides:

• How to Fix Wazuh Certificate Errors 
• Fixing Nginx Upstream Timeouts When Proxying Wazuh Dashboard Traffic 

Accurate System Time

All systems participating in federated authentication should maintain accurate system time.

This is particularly important for SAML because assertions contain time-related conditions such as validity windows.

An environment with significant clock drift can produce authentication failures even when the SSO configuration appears correct.

Check the time on:

Wazuh Dashboard
Wazuh Indexer
Wazuh Manager
Identity provider infrastructure

Use NTP or another reliable time-synchronization mechanism to maintain consistent system time.

Clock synchronization is also important for TLS and token-based authentication.

Backup of Existing Security Configuration

Before changing authentication or authorization configuration, create a backup of the existing security configuration.

This is particularly important when modifying:

• Roles
• Role mappings
• Authentication settings
• Security plugin configuration
• Certificates
• SSO configuration
• Tenant permissions

A backup gives you a recovery path if an incorrect mapping prevents administrators from accessing the Dashboard.

This is especially important for production environments.

Related Guide: How to Backup Wazuh RBAC Configurations

Understanding Wazuh Roles Before Configuring SSO

SSO role mapping should be designed after you understand the roles and permissions that users need.

A common mistake is to configure the identity provider first and then attempt to determine what each group should be allowed to do.

A better approach is to design the Wazuh authorization model first and map external identities to it afterward.

The basic relationship is:

Identity Provider Group
          ↓
    Role Mapping
          ↓
      Wazuh Role
          ↓
     Permissions
          ↓
   Tenant / Resource Access

Built-In Wazuh Roles

Wazuh deployments include predefined security roles intended to provide common permission sets.

The exact roles and available permissions depend on the Wazuh version and security configuration.

Before creating custom roles, review the existing roles and determine whether one already provides the required access.

Using an existing role can be preferable to creating a custom role unnecessarily because it reduces configuration complexity.

Custom Wazuh Roles

Custom roles allow administrators to implement more precise authorization policies.

For example, suppose the SOC has a specialized malware-analysis team that needs access to certain security data but should not have administrative permissions.

Instead of assigning a broad administrator role, you can create a role containing only the required capabilities.

Conceptually:

Malware Analysts
      ↓
Custom Malware Analyst Role
      ↓
Read + Investigation Permissions
      ↓
Specific Tenant

Custom roles become particularly useful when the organization’s responsibilities do not map neatly onto the default role structure.

Administrator Roles

Administrator roles should be reserved for users who actually need to manage the Wazuh environment.

Administrators may require permissions to:

• Manage security configuration
• Manage users and roles
• Configure Wazuh components
• Modify integrations
• Manage tenants
• Troubleshoot infrastructure

Avoid mapping a broad identity-provider group to an administrator role unless every member genuinely requires those privileges.

For example, this is generally a poor design:

Company Employees
        ↓
Wazuh Administrator

A more appropriate structure would be:

Wazuh-Platform-Admins
        ↓
Wazuh Administrator

The narrower group makes the authorization boundary explicit.

Analyst Roles

Analysts typically need access to security data for investigation and monitoring but do not necessarily need administrative privileges.

An analyst role might provide access to:

• Alerts
• Security events
• Dashboards
• Investigative searches
• Relevant agent information
• Assigned tenants

while excluding capabilities such as:

• User administration
• Role administration
• Security configuration
• Infrastructure management

A corresponding mapping might be:

Wazuh-Analysts
       ↓
Wazuh Analyst

Incident Responder Roles

Incident responders may require additional permissions compared with read-only analysts.

For example, responders may need to initiate or manage response actions while investigating security incidents.

A dedicated responder role can separate operational response privileges from general monitoring privileges:

Wazuh-Responders
       ↓
Wazuh Responder
       ↓
Investigation + Response Permissions

This separation makes it easier to apply least privilege.

An analyst who only investigates alerts does not necessarily need the same permissions as someone authorized to execute response actions.

Auditor Roles

Auditors generally need visibility without modification capabilities.

A typical auditor model might be:

Wazuh-Auditors
       ↓
Wazuh Auditor
       ↓
Read / Review Permissions

Auditors may need to review:

• Alerts
• Security events
• Configuration information
• Audit information
• Compliance-related data

but should generally not be able to modify security settings or manage users.

This makes auditor access a good candidate for a dedicated read-oriented role.

Read-Only Roles

Read-only access is useful when users need visibility into Wazuh but should not be able to make changes.

Examples include:

• Security managers
• Compliance personnel
• External reviewers
• Help-desk personnel
• Security stakeholders

A read-only role can reduce the risk of accidental configuration changes.

For example:

Security-Reviewers
        ↓
Read-Only Role
        ↓
View permitted security information

The role should still be scoped carefully. “Read-only” does not necessarily mean “read everything.”

A user can have no write permissions while still having excessive visibility into sensitive data.

Tenant restrictions and resource-level permissions should therefore be considered alongside the read-only designation.

Tenant-Specific Roles

In environments using Wazuh multi-tenancy, role design should account for both what a user can do and where they can do it.

For example:

SOC Analyst
   │
   ├── Analyst Permissions
   │
   └── SOC Tenant

Compliance Analyst
   │
   ├── Read Permissions
   │
   └── Compliance Tenant

Two users may have similar capabilities but different tenant access.

This allows organizations to create boundaries between:

• Departments
• Business units
• Customers
• Geographic regions
• Security teams
• Compliance environments

Related Guide: How to Configure Wazuh Field Level Security 

Least-Privilege Role Design

The most important principle when designing roles for SSO mapping is least privilege.

The goal is not simply to make authentication convenient.

The goal is to make centralized authentication compatible with tightly controlled authorization.

NIST’s access-control guidance recommends enforcing least privilege by restricting users and processes to the minimum privileges necessary to perform assigned tasks.

A practical role structure could look like:

The important principle is to avoid using a single powerful role for every SSO user.

Instead:

           Identity Provider
                  │
        ┌─────────┼─────────┐
        ▼         ▼         ▼
     Groups     Groups     Groups
        │         │         │
        ▼         ▼         ▼
      Roles      Roles      Roles
        │         │         │
        ▼         ▼         ▼
   Permissions Permissions Permissions
        │         │         │
        ▼         ▼         ▼
     Tenants    Tenants    Tenants

This model gives administrators a predictable authorization structure and makes the subsequent SSO role-mapping configuration much easier to manage.

It also makes access reviews more straightforward: instead of asking why an individual user has a particular permission, administrators can trace the access path from IdP group → Wazuh role → permissions → tenant.

Related Guide: Mastering Wazuh Security: The Complete Access Control Guide

Configure Wazuh SSO Role Mapping with SAML

SAML-based SSO allows Wazuh to delegate user authentication to an external identity provider while using identity attributes from the SAML response to determine the user’s Wazuh permissions.

The exact configuration files and security-plugin syntax can vary by Wazuh release, so verify the syntax against the documentation for the version running in your environment.

The architecture, however, follows the same general pattern:

User
  ↓
Identity Provider
  ↓
SAML Authentication
  ↓
SAML Assertion
  ↓
User / Group Attributes
  ↓
Wazuh Role Mapping
  ↓
Wazuh RBAC Role
  ↓
Permissions / Tenants

If SAML authentication itself is not configured yet, complete the base SAML integration before implementing group-to-role mappings.

Related Guide: How to Configure Wazuh SAML Authentication 

Configure the Identity Provider

Begin by creating the Wazuh application or service-provider configuration in your identity provider.

The IdP configuration needs to know:

• Which application is requesting authentication
• Where SAML responses should be sent
• Which entity identifies Wazuh
• Which attributes should be returned
• Which groups or roles should be included
• How assertions should be signed

The exact terminology differs between identity providers.

For example, one provider may call the application identifier the Entity ID, while another may refer to it as an Audience URI or Identifier.

The important requirement is that the values configured on both sides match.

Create a Wazuh SSO Application

Create a dedicated enterprise application or SAML application for Wazuh.

Avoid reusing an unrelated application configuration because Wazuh requires specific SAML endpoints and identity attributes.

A dedicated application also makes it easier to:

• Control which users can access Wazuh
• Assign identity-provider groups
• Configure claims
• Rotate certificates
• Audit authentication activity
• Disable Wazuh access independently

A typical application structure is:

Identity Provider
       │
       └── Wazuh SAML Application
                │
                ├── Users
                ├── Groups
                ├── Claims
                └── SAML Configuration

Configure the Assertion Consumer Service URL

The Assertion Consumer Service (ACS) URL identifies where the identity provider sends the SAML response after authentication.

The URL must correspond to the SAML endpoint configured for your Wazuh deployment.

Conceptually:

User
 ↓
IdP Authentication
 ↓
SAML Response
 ↓
Wazuh ACS Endpoint

The ACS URL must be configured consistently between the identity provider and Wazuh.

A mismatch can result in errors such as:

• Invalid recipient
• Invalid destination
• Redirect URI mismatch
• SAML response rejected
• Authentication loop

Do not copy an ACS URL from another Wazuh installation unless the hostname and deployment architecture are identical.

Configure the Entity ID

The Entity ID uniquely identifies the Wazuh SAML service provider.

The identity provider uses this identifier to determine which application is requesting authentication.

Conceptually:

Wazuh Entity ID
        ↓
Identity Provider
        ↓
"This SAML request belongs to Wazuh."

The Entity ID configured in the IdP must match the value expected by the Wazuh SAML configuration.

Configure SAML Bindings

SAML bindings determine how SAML messages are transported between the service provider and identity provider.

Common bindings include:

• HTTP-Redirect
• HTTP-POST

The appropriate binding depends on the Wazuh implementation and IdP configuration.

When configuring SAML, ensure that the selected binding corresponds to what the Wazuh SAML service expects.

A binding mismatch can prevent an otherwise valid authentication request from being processed correctly.

Configure Signing Certificates

SAML assertions and responses can be cryptographically signed so that Wazuh can verify that they originated from the trusted identity provider and were not modified in transit.

Configure the appropriate IdP signing certificate in Wazuh.

Certificate validation should include:

• Correct certificate
• Valid certificate chain
• Correct certificate format
• Current certificate expiration date
• Matching IdP configuration

Certificate rotation should also be planned before the existing certificate expires.

Related Guide: How to Fix Wazuh Certificate Errors

Configure User Attributes

Determine which SAML attribute identifies the user.

Depending on the IdP configuration, this might be:

username
email
NameID
userPrincipalName

For example:

NameID = alice@example.com

The same identity should be represented consistently across authentication and authorization.

Avoid relying on an attribute that can change unexpectedly, particularly when a stable identifier is available.

Configure Group or Role Attributes

Role mapping requires more than identifying the user.

Wazuh also needs access to the information used to determine the user’s role.

A common design is to send a group attribute:

groups = Wazuh-Analysts

A user belonging to multiple groups might receive:

groups =
    Wazuh-Analysts
    Security-Operations

The identity provider must therefore be configured to include the appropriate group or role information in the SAML assertion.

The attribute name is important.

For example, these are not equivalent from a mapping perspective:

groups
group
memberOf
roles
http://example.com/claims/groups

The Wazuh mapping must reference the actual attribute being returned.

Configure Wazuh for SAML

Once the IdP is configured, configure Wazuh’s SAML authentication and authorization components.

The exact file locations and configuration syntax depend on your Wazuh release and deployment topology.

Before modifying production security configuration, back up the current configuration.

Related Guide: How to Backup Wazuh RBAC Configurations

Configure SAML Authentication

Enable SAML authentication in the appropriate Wazuh security configuration.

The configuration establishes Wazuh as the service provider and tells the security layer which identity provider should be trusted.

Conceptually, the configuration contains information such as:

SAML enabled
    ↓
Identity provider
    ↓
IdP metadata
    ↓
Signing certificate
    ↓
Authentication attributes

Do not treat authentication and role mapping as the same configuration step.

First verify that a user can authenticate successfully.

Then verify that the correct Wazuh role is assigned.

Define the Identity Provider

Wazuh needs information about the identity provider it should trust.

This can include:

• IdP entity identifier
• SSO endpoint
• IdP metadata
• Signing certificate
• Authentication settings

The identity-provider metadata should come from the actual IdP configuration rather than being manually recreated wherever possible.

Using authoritative IdP metadata reduces configuration errors involving URLs, certificates, and identifiers.

Configure Certificate Validation

Wazuh should validate the SAML response or assertion against the expected signing certificate.

This prevents an arbitrary or modified assertion from being treated as trusted authentication information.

Verify:

IdP
 ↓
Signed SAML response
 ↓
Certificate validation
 ↓
Trusted identity

If certificate validation fails, investigate:

• Expired certificate
• Incorrect certificate
• Missing certificate
• Incorrect certificate chain
• Certificate rotation
• Incorrect metadata

Do not disable certificate validation merely to make SSO work.

Configure Authentication Attributes

Define which attributes Wazuh should use to identify the authenticated user.

For example:

Username attribute:
email

or:

Username attribute:
NameID

The selected attribute should correspond to the value actually returned by the identity provider.

Configure Role-Related Attributes

Next, identify the attribute containing authorization information.

For example:

Attribute:
groups

Values:
Wazuh-Admins
Wazuh-Analysts
Wazuh-Responders
Wazuh-Auditors

The most important troubleshooting rule here is:

Do not configure the role mapping based on what the IdP administrator thinks the claim contains. Verify the actual SAML assertion.

If the assertion contains a different claim name or value format, the mapping will not work as expected.

Configure SAML Metadata

SAML metadata allows the service provider and identity provider to exchange configuration information.

Depending on your architecture, this can contain:

• Entity identifiers
• SSO endpoints
• Certificates
• Supported bindings
• Service-provider endpoints

Use the metadata supplied by your identity provider and verify that the endpoints and certificates correspond to the intended Wazuh deployment.

Configure SAML Role Mapping

Once SAML authentication is working, configure the mapping between the external identity information and Wazuh roles.

The conceptual flow is:

SAML Attribute
      ↓
Group / Role Value
      ↓
Wazuh Role Mapping
      ↓
Wazuh RBAC Role
      ↓
Permissions

Identify the SAML Group Claim

First determine exactly which SAML attribute contains group membership.

For example:

Attribute:
groups

with:

Wazuh-Analysts
Wazuh-Responders

Another IdP might return a URI-style attribute name instead.

Do not assume the claim is always called groups.

This is one of the most important values to verify before creating a mapping.

Map Identity-Provider Groups to Wazuh Roles

Create explicit mappings between IdP groups and Wazuh roles.

For example:

IdP Group              Wazuh Role

Wazuh-Admins      →    Administrator
Wazuh-Analysts    →    Analyst
Wazuh-Responders  →    Responder
Wazuh-Auditors    →    Auditor

This creates a clear authorization chain:

Alice
 ↓
Wazuh-Analysts
 ↓
Analyst Role
 ↓
Analyst Permissions

Map Administrators

Create a dedicated administrator group rather than mapping a broad organizational group.

For example:

Wazuh-Platform-Admins
        ↓
Wazuh Administrator

Limit membership in this group to users who actually need administrative privileges.

Administrator mappings deserve particular scrutiny because an incorrect mapping can unintentionally provide access to security configuration, user management, and other privileged functions.

Map Analysts

Create a dedicated analyst group:

Wazuh-Analysts
       ↓
Wazuh Analyst

The associated role should provide investigation and monitoring capabilities without unnecessarily granting administrative privileges.

Map Responders

Create a dedicated responder group:

Wazuh-Responders
       ↓
Wazuh Responder

This allows incident-response personnel to receive the additional permissions required for response operations without automatically making them platform administrators.

Map Auditors

Create an auditor group:

Wazuh-Auditors
       ↓
Wazuh Auditor

Auditor permissions should generally emphasize visibility and review rather than configuration changes.

Configure Default Roles

A default role determines what happens when an authenticated user does not match one of the intended role mappings.

This setting requires particular care.

A permissive default role can accidentally grant access to users who were never intended to access Wazuh.

A safer conceptual model is:

Recognized group
      ↓
Specific role

Unrecognized group
      ↓
Restricted / denied access

If a default role is required by the implementation, make it as restrictive as practical.

Handle Users With Multiple Groups

Users frequently belong to more than one identity-provider group.

For example:

Alice
 ├── Wazuh-Analysts
 └── Wazuh-Auditors

Before deploying the mapping, determine what should happen when multiple mappings match.

Do not assume that the desired outcome is automatically “highest privilege wins.”

Instead, explicitly design the precedence and resulting permissions.

For sensitive administrative roles, consider using dedicated groups and avoiding overlapping memberships wherever possible.

Configure Wazuh SSO Role Mapping with OIDC

OpenID Connect provides another mechanism for integrating Wazuh with an external identity provider.

The architecture is similar to SAML:

User
 ↓
Wazuh Dashboard
 ↓
OIDC Provider
 ↓
Authentication
 ↓
ID Token / Claims
 ↓
Role Mapping
 ↓
Wazuh Role
 ↓
Permissions

The primary difference is how identity information is exchanged.

With OIDC, claims contained in ID tokens,and, depending on the implementation, information obtained from the UserInfo endpoint, can provide the identity and group information required for role mapping.

Configure the Identity Provider

Begin by creating an OIDC application or client in the identity provider.

The application establishes:

• Wazuh’s client identity
• Allowed redirect URLs
• Authentication methods
• Requested scopes
• Available claims
• Group or role information

Use a dedicated OIDC client for Wazuh rather than sharing credentials with another application.

Register the Wazuh Application

Register Wazuh as an OIDC application or client.

The IdP typically provides values such as:

Client ID
Client Secret
Issuer
Authorization Endpoint
Token Endpoint
UserInfo Endpoint
JWKS URI

Not every provider exposes these values in exactly the same way.

The issuer and discovery metadata are particularly important because they allow the OIDC client to identify the correct authorization infrastructure and signing keys.

Configure Redirect URIs

Configure the Wazuh redirect URI in the identity provider.

The URI must match what Wazuh uses for the OIDC authentication flow.

A mismatch can cause errors such as:

redirect_uri mismatch
invalid_request
unauthorized_client

Treat redirect URIs as exact values. Differences in:

• Hostname
• Scheme
• Port
• Path
• Trailing slash

can matter.

Configure Client Authentication

Configure the authentication method required by the OIDC provider.

Depending on the provider and flow, this can involve a client secret or another supported client-authentication mechanism.

Store client credentials securely and avoid placing secrets in documentation, screenshots, source repositories, or publicly accessible configuration files.

Define Scopes

OIDC uses scopes to request specific categories of information.

A common baseline includes:

openid
profile
email

Additional scopes may be necessary depending on where group or role information is exposed.

The important principle is to request only the scopes needed by the Wazuh integration.

Configure Group Claims

Configure the IdP to include group membership in the claims available to Wazuh.

For example:

{
  "sub": "123456",
  "email": "alice@example.com",
  "groups": [
    "Wazuh-Analysts"
  ]
}

The actual claim name can vary.

Possible implementations may use:

groups
roles
memberOf

or a provider-specific claim URI.

Always verify the actual token or user-information response.

Configure Role Claims

Some identity providers expose application roles rather than directory groups.

For example:

roles:
  - wazuh_analyst

The Wazuh mapping can then conceptually become:

wazuh_admin     → Administrator
wazuh_analyst   → Analyst
wazuh_responder → Responder
wazuh_auditor   → Auditor

Using application-specific roles can be useful when the same directory groups are shared across many applications.

Configure Wazuh for OIDC

After configuring the identity provider, configure Wazuh to trust the OIDC provider and process the returned identity claims.

Configure the OIDC Provider

Define the identity provider’s OIDC information in the appropriate Wazuh security configuration.

This establishes the relationship:

Wazuh
 ↓
Trusted OIDC Issuer
 ↓
Identity Provider

Configure Issuer and Discovery Information

The OIDC issuer identifies the identity provider.

Where supported, OIDC discovery information can provide endpoints and signing-key information automatically.

Verify that the configured issuer corresponds exactly to the intended provider.

An incorrect issuer can result in token-validation failures even when the user’s authentication succeeds at the IdP.

Configure Client Credentials

Configure the client ID and any required client credentials.

Treat client secrets as sensitive credentials.

For production environments, establish a credential-rotation process before deployment.

Configure Requested Scopes

Configure the scopes required by your Wazuh integration.

At minimum, the OIDC flow generally needs the openid scope. Additional identity information may require profile, email, or provider-specific scopes.

If groups are not appearing in the resulting claims, verify whether the identity provider requires an additional scope or application setting.

Configure Authentication Claims

Configure Wazuh to identify the authenticated user from the appropriate OIDC claim.

Common identity claims include:

sub
email
preferred_username

The most appropriate choice depends on the identity provider and the organization’s identity lifecycle.

Configure OIDC Role Mapping

Once authentication claims are working, configure role mapping.

Conceptually:

OIDC Claim
    ↓
Group / Role
    ↓
Wazuh Role
    ↓
Permissions

Map Groups to Wazuh Roles

For group-based authorization:

Wazuh-Admins
      ↓
Administrator

Wazuh-Analysts
      ↓
Analyst

Wazuh-Responders
      ↓
Responder

Wazuh-Auditors
      ↓
Auditor

Map Role Claims

For application-role-based authorization:

wazuh_admin
     ↓
Administrator

wazuh_analyst
     ↓
Analyst

wazuh_responder
     ↓
Responder

wazuh_auditor
     ↓
Auditor

Choose either groups or application roles as the primary authorization source where practical rather than creating unnecessarily complicated mappings from several overlapping claim types.

Map Administrator Access

Use a dedicated role or group for administrative access:

Wazuh-Platform-Admins
        ↓
Administrator

Avoid mapping generic groups such as Employees, Users, or Security to administrator privileges.

Map Analyst Access

Map the dedicated analyst group or role:

Wazuh-Analysts
       ↓
Analyst

Review the resulting permissions before assigning the group to production users.

Map Responder Access

Map incident responders separately:

Wazuh-Responders
       ↓
Responder

This provides a clear distinction between investigation and response responsibilities.

Map Auditor Access

Map auditing personnel to a restricted role:

Wazuh-Auditors
       ↓
Auditor

The role should provide sufficient visibility for audit requirements without granting unnecessary modification privileges.

Configure Default Access

Treat unmatched identities conservatively.

A useful design principle is:

Known identity + recognized group
        ↓
Authorized Wazuh role

Known identity + no recognized group
        ↓
Restricted / denied access

Do not use a powerful default role to solve mapping failures.

If users who should be analysts are falling into the default role, fix the group claim or mapping instead.

Handle Multiple Group Memberships

Users can belong to multiple groups simultaneously.

For example:

Alice
 ├── Wazuh-Analysts
 ├── Security-Team
 └── Compliance-Reviewers

Determine which of those groups should affect Wazuh authorization.

If only Wazuh-Analysts is intended to control Wazuh access, do not create mappings for unrelated groups.

For privileged roles, consider using mutually exclusive administrative groups where possible.

Map Identity Provider Groups to Wazuh Roles

Whether you use SAML or OIDC, group-based role mapping follows the same fundamental authorization model:

Identity Provider Group
          ↓
    Wazuh Role Mapping
          ↓
      Wazuh Role
          ↓
      Permissions
          ↓
   Tenant / Resource Access

This model provides a clean separation between identity administration and Wazuh authorization.

Create Security Groups in the Identity Provider

Start by creating dedicated groups for Wazuh access.

For example:

Wazuh-Admins
Wazuh-Analysts
Wazuh-Responders
Wazuh-Auditors
Wazuh-Viewers

Keep these groups application-specific.

A dedicated Wazuh-Admins group is preferable to reusing a broad group such as IT-Staff, because the former explicitly expresses the intended Wazuh authorization boundary.

Create Corresponding Wazuh Roles

Next, identify or create the Wazuh roles corresponding to those groups.

For example:

Do not create roles simply because a group exists. Each role should have a defined business and security purpose.

Map Groups to Roles

Create the mappings explicitly.

Conceptually:

Wazuh-Admins
      ↓
Administrator

Wazuh-Analysts
      ↓
Analyst

Wazuh-Responders
      ↓
Responder

Wazuh-Auditors
      ↓
Auditor

Document these mappings so that administrators can understand the authorization model without inspecting every configuration file.

Map Multiple Groups to Multiple Roles

Some organizations require several groups to map to the same role.

For example:

SOC-Tier1
      ───────┐
SOC-Tier2   ├──→ Wazuh Analyst
SOC-Tier3   ┘

This can be appropriate when different organizational groups require identical Wazuh permissions.

However, avoid creating unnecessary mapping complexity.

If five groups all provide exactly the same Wazuh access, consider whether a single dedicated Wazuh group could simplify administration.

Avoid Granting Excessive Privileges

Do not automatically map a user’s highest-privilege group simply because the user belongs to it.

For example:

User
 ├── Wazuh-Analysts
 └── Wazuh-Admins

This user may receive administrator-level access depending on the role-mapping implementation.

Before deploying the configuration, explicitly test overlapping memberships and understand how multiple roles are combined.

The safest approach is to keep privileged groups tightly controlled and avoid unnecessary overlap.

Use Dedicated Groups for Administrative Access

Administrative access deserves a separate group.

Prefer:

Wazuh-Platform-Admins

over:

IT-Employees

The dedicated group creates an explicit security boundary and makes access reviews easier.

It also allows identity administrators to answer a simple question:

Who currently has permission to administer Wazuh?

The answer should be the membership of the dedicated administrative group, subject to any additional role mappings.

Handle Nested Groups

Enterprise identity providers frequently support nested groups.

For example:

Security Department
      │
      ├── SOC Team
      │      ├── Tier 1
      │      └── Tier 2
      │
      └── Incident Response

Do not assume that nested membership will automatically appear in the SAML or OIDC claims consumed by Wazuh.

The identity provider must be configured to emit the relevant effective group membership in a form that the Wazuh role mapping understands.

Test nested groups explicitly before depending on them for authorization.

If nested-group expansion is inconsistent, dedicated direct-membership Wazuh groups are often easier to audit and troubleshoot.

Handle Users Without a Recognized Group

Define what happens when a user successfully authenticates but does not belong to a recognized Wazuh group.

For example:

User authenticates
        ↓
No Wazuh group
        ↓
No privileged role
        ↓
Restricted or denied access

This is safer than automatically assigning an administrator, analyst, or other broad role.

An authentication success should never be interpreted as permission to access all Wazuh functionality.

Document the Mapping Structure

Document the entire authorization chain.

A useful mapping document might contain:

Also document:

• SAML or OIDC protocol
• IdP name
• Claim name
• Role-mapping rules
• Default role behavior
• Tenant assignments
• Administrative groups
• Certificate expiration dates
• Client credential rotation dates
• Exceptions and special mappings

The resulting structure should be easy to trace:

User
 ↓
IdP Group
 ↓
SAML Attribute / OIDC Claim
 ↓
Wazuh Role Mapping
 ↓
Wazuh Role
 ↓
Permissions
 ↓
Tenant

That traceability is valuable during both access reviews and incident response.

If a user has unexpected Wazuh privileges, administrators can follow the chain backward and determine whether the problem originated from group membership, an identity claim, a role mapping, a Wazuh role, or tenant configuration.

Related Guide:

• Troubleshooting Wazuh RBAC
• How to Configure Wazuh Field Level Security 

Configure Wazuh SSO Role Mapping with Common Identity Providers

The general Wazuh SSO role-mapping model remains the same regardless of which identity provider you use:

Identity Provider
       ↓
User Authentication
       ↓
Groups / Roles / Claims
       ↓
Wazuh Role Mapping
       ↓
Wazuh RBAC Role
       ↓
Permissions
       ↓
Tenant Access

What changes is how each identity provider creates applications, exposes group membership, and sends claims to Wazuh.

The following examples focus on the four identity platforms commonly encountered in enterprise environments: Microsoft Entra ID, Okta, Keycloak, and Google Workspace.

For the actual Wazuh-side configuration, use the SAML or OIDC procedure appropriate to your Wazuh version.

Related Guide: How to Configure Wazuh SSO

Microsoft Entra ID

Microsoft Entra ID can provide centralized authentication and group-based authorization for Wazuh users.

A typical architecture is:

Microsoft Entra ID
      │
      ├── Wazuh-Admins
      ├── Wazuh-Analysts
      ├── Wazuh-Responders
      └── Wazuh-Auditors
             │
             ▼
        SAML / OIDC
             │
             ▼
           Wazuh

The important part is ensuring that the groups or application roles required for Wazuh authorization are actually included in the authentication claims.

Related Guide: How to Integrate Wazuh with Azure AD

Configure Enterprise Application

Create a dedicated enterprise application for Wazuh in Microsoft Entra ID.

For SAML, configure Wazuh as a non-gallery enterprise application when an appropriate preconfigured application is unavailable.

The application should define the relevant Wazuh endpoints and identify the users and groups permitted to access the application.

For OIDC, register Wazuh as an application/client according to the supported Wazuh authentication architecture.

Keep the application restricted to the users and groups that actually need Wazuh access.

Configure SAML or OIDC Claims

Configure the claims that Wazuh needs to identify users and determine their roles.

For example:

Name / Subject:
user.email

Groups:
Wazuh-Admins
Wazuh-Analysts
Wazuh-Responders
Wazuh-Auditors

For OIDC, the equivalent information may be exposed through claims such as:

sub
preferred_username
email
groups
roles

The exact claim names and formats depend on the Entra configuration.

Do not configure Wazuh based solely on the names displayed in the Entra administrative interface.

Verify what is actually included in the SAML assertion or OIDC token.

Map Entra ID Groups to Wazuh Roles

Create dedicated Entra groups:

Wazuh-Admins       → Administrator
Wazuh-Analysts     → Analyst
Wazuh-Responders   → Responder
Wazuh-Auditors     → Auditor

This provides a direct authorization chain from centralized identity management to Wazuh.

Avoid mapping broad Entra groups such as All Employees or All Users to privileged Wazuh roles.

Test Administrator and Analyst Access

Test at least two accounts:

Test Administrator
    ↓
Wazuh-Admins
    ↓
Administrator

Test Analyst
    ↓
Wazuh-Analysts
    ↓
Analyst

Verify both authentication and authorization.

The administrator should receive the intended administrative capabilities, while the analyst should not inherit administrator privileges.

Also test an account with no Wazuh group membership to verify that your default-access behavior is secure.

Okta

Okta can act as the identity provider for Wazuh using SAML or OIDC.

A typical Okta-based architecture is:

Okta
 │
 ├── Wazuh-Admins
 ├── Wazuh-Analysts
 ├── Wazuh-Responders
 └── Wazuh-Auditors
          │
          ▼
      Wazuh SSO

Related Guide: How to Integrate Wazuh with Okta

Configure the Wazuh Application

Create an application integration specifically for Wazuh.

For SAML, configure:

• Single sign-on URL
• Audience URI / Entity ID
• NameID format
• Group attributes
• Signing settings

For OIDC, configure:

• Client ID
• Client secret where required
• Redirect URIs
• Scopes
• Claims

Use the values generated by the Wazuh configuration rather than assuming that URLs from another environment are interchangeable.

Configure Groups and Claims

Create dedicated Okta groups such as:

Wazuh-Admins
Wazuh-Analysts
Wazuh-Responders
Wazuh-Auditors

Configure the Wazuh application to receive the appropriate group information.

For example:

groups:
[
  "Wazuh-Analysts"
]

If Okta sends groups through a custom claim or attribute, configure Wazuh’s role mapping to use that exact claim.

Map Okta Groups to Wazuh Roles

A straightforward mapping is:

Okta Group             Wazuh Role

Wazuh-Admins      →    Administrator
Wazuh-Analysts    →    Analyst
Wazuh-Responders  →    Responder
Wazuh-Auditors    →    Auditor

Keep administrative groups narrowly scoped.

If an employee needs temporary elevated access, prefer controlled membership in the appropriate privileged group rather than permanently changing the user’s Wazuh role.

Validate Authentication and Authorization

Test the complete path:

Okta Login
    ↓
Authentication
    ↓
Claim / Group
    ↓
Wazuh Mapping
    ↓
Wazuh Role
    ↓
Permissions

If authentication succeeds but the expected role is missing, inspect the group claim before changing Wazuh permissions.

Keycloak

Keycloak is particularly useful when an organization wants to operate its own identity and access-management infrastructure.

It can provide both SAML and OIDC federation, depending on the Wazuh integration being used.

Related Guide: How to Integrate Keycloak with Wazuh

Create the Wazuh Client

Create a dedicated Wazuh client in Keycloak.

For OIDC, this generally involves configuring the client as an OpenID Connect client.

For SAML, create the appropriate SAML client configuration.

The client should define the Wazuh endpoints, allowed redirect behavior, and authentication settings required by your deployment.

Configure SAML or OIDC

For OIDC, configure:

• Client ID
• Client authentication
• Redirect URIs
• Allowed scopes
• Protocol mappers
• Group or role claims

For SAML, configure:

• Client/service-provider identifiers
• Assertion endpoints
• Signing configuration
• Attribute mappings
• Group or role attributes

Keycloak’s protocol mappers are particularly important when the claims required by Wazuh are not included by default.

Configure Groups and Role Claims

Create groups such as:

Wazuh-Admins
Wazuh-Analysts
Wazuh-Responders
Wazuh-Auditors

Then configure Keycloak to expose those groups or appropriate role claims to Wazuh.

For example:

groups:
[
  "/Wazuh-Analysts"
]

The leading slash or other formatting is significant if it is actually included in the claim. Wazuh’s mapping must match the value that Keycloak sends.

Map Keycloak Groups to Wazuh Roles

Map the external values to the corresponding Wazuh roles:

Keycloak Group              Wazuh Role

/Wazuh-Admins          →    Administrator
/Wazuh-Analysts        →    Analyst
/Wazuh-Responders      →    Responder
/Wazuh-Auditors        →    Auditor

If you use Keycloak roles instead of groups, map the role claim values using the same principle.

Google Workspace

Google Workspace can provide centralized identity management and SSO for organizations using Google as their identity platform.

A Google-based deployment can use the same fundamental group-to-role model:

Google Workspace
      ↓
Google Groups
      ↓
SAML / OIDC
      ↓
Wazuh
      ↓
Wazuh Roles

Related Guide: How to Integrate Wazuh with Google Workspace

Configure the SSO Application

Create the appropriate SSO application or application integration in the Google administration environment.

For a SAML integration, configure the Wazuh service-provider details, including the appropriate ACS URL and Entity ID.

Ensure that the Google-side values exactly match the Wazuh configuration.

Configure User and Group Attributes

Determine which attributes Google will send to Wazuh.

For example:

Email:
alice@example.com

Group:
Wazuh-Analysts

If groups are not included in the authentication response, Wazuh cannot use those groups for group-based role mapping.

Map Google Groups to Wazuh Roles

Create dedicated groups:

Wazuh-Admins
Wazuh-Analysts
Wazuh-Responders
Wazuh-Auditors

Then map them:

Google Group          Wazuh Role

Wazuh-Admins     →    Administrator
Wazuh-Analysts   →    Analyst
Wazuh-Responders →    Responder
Wazuh-Auditors   →    Auditor

Test Group-Based Access

Test one account from each major group.

For example:

Administrator
    ↓
Wazuh-Admins
    ↓
Administrator role

Analyst
    ↓
Wazuh-Analysts
    ↓
Analyst role

Auditor
    ↓
Wazuh-Auditors
    ↓
Auditor role

Also test group removal.

Remove a test user from a Wazuh group, sign in again, and verify that the expected access change occurs.

This validates not only authentication but the entire authorization lifecycle.

Configure Wazuh SSO Role Mapping for Different SOC Teams

A successful SSO architecture should reflect how the SOC actually operates.

Different teams require different levels of access. Mapping every user to one generic Wazuh role defeats the purpose of RBAC.

A better model is:

                    Wazuh SSO
                        │
       ┌────────────────┼────────────────┐
       ▼                ▼                ▼
    Admins           Analysts         Responders
       │                │                │
       ▼                ▼                ▼
 Administrator       Analyst          Responder
       │                │                │
       └────────────────┼────────────────┘
                        ▼
                    Wazuh RBAC

Wazuh Administrators

Administrators manage the Wazuh platform itself.

Use a dedicated identity-provider group:

Wazuh-Platform-Admins
        ↓
Administrator

Keep this group small and review its membership regularly.

Administrative access should not be granted merely because a user works in IT or security.

Security Analysts

Analysts investigate alerts, review events, search security data, and monitor the environment.

A dedicated mapping might be:

Wazuh-Analysts
       ↓
Analyst

Analysts should not automatically inherit permissions for user administration, role management, or infrastructure configuration.

Incident Responders

Responders may need capabilities that analysts do not have, particularly when carrying out response actions.

Use a dedicated group:

Wazuh-Responders
       ↓
Responder

This creates an explicit distinction between investigation and response authority.

SOC Managers

SOC managers may need broad visibility without needing every administrative permission.

For example:

SOC-Managers
      ↓
Management / Read-Oriented Role
      ↓
SOC Tenant

The exact role should reflect their responsibilities.

Do not automatically assign administrator privileges simply because a user manages the SOC.

Auditors

Auditors generally need access to review security information and configuration evidence.

A dedicated mapping can provide:

Wazuh-Auditors
      ↓
Auditor
      ↓
Compliance Tenant

Restrict modification privileges unless an auditor’s responsibilities explicitly require them.

Read-Only Users

Users who only need visibility can be assigned to a read-only group:

Wazuh-Viewers
      ↓
Read-Only Role

This is useful for stakeholders who need to monitor security status without modifying the Wazuh environment.

External Security Teams

External consultants or security teams should receive explicitly scoped access.

For example:

External-Security-Team
        ↓
Restricted Analyst Role
        ↓
External / Project Tenant

Avoid giving external users permanent administrator access unless there is a documented requirement.

Time-limited identity-provider group membership can also be useful for temporary engagements.

Managed Security Service Provider Users

MSSP environments require particularly careful role and tenant design.

A simplified model is:

                   Wazuh
                     │
          ┌──────────┼──────────┐
          ▼          ▼          ▼
       Customer A Customer B Customer C
          │          │          │
       Tenant A   Tenant B   Tenant C

MSSP analysts may require access to multiple customer tenants, while customer users should generally be restricted to their own tenant.

This makes tenant-aware role mapping essential.

Wazuh SSO Role Mapping and Multi-Tenancy

SSO role mapping becomes significantly more powerful when combined with Wazuh multi-tenancy.

Role mapping answers:

What can this user do?

Multi-tenancy adds:

Which security data can this user access?

Together, they provide a more complete authorization model.

SSO Identity
     ↓
Role Mapping
     ↓
Wazuh Role
     ↓
Permissions
     ↓
Tenant Access
     ↓
Authorized Data

Related Guide: How to Set Up Wazuh Multi-Tenancy

Explain Wazuh Multi-Tenancy

Multi-tenancy allows a Wazuh environment to separate security resources between different logical users, teams, or organizations.

For example:

Wazuh
 │
 ├── SOC Tenant
 ├── Compliance Tenant
 ├── Engineering Tenant
 └── Customer Tenant

A user can have a valid Wazuh account and role while still being restricted to one or more specific tenants.

This distinction is important because RBAC and tenant isolation solve different problems.

Map SSO Groups to Tenants

Identity-provider groups can be used as part of the process for determining tenant access.

For example:

Wazuh-SOC-Analysts
       ↓
Analyst Role
       ↓
SOC Tenant

while:

Wazuh-Compliance-Auditors
       ↓
Auditor Role
       ↓
Compliance Tenant

The resulting authorization path becomes:

IdP Group
   ↓
Wazuh Role
   ↓
Tenant

Assign Roles Within Tenants

A user may need different permissions depending on the tenant.

For example:

Alice
 │
 ├── SOC Tenant
 │      └── Analyst
 │
 └── Compliance Tenant
        └── Auditor

This is more granular than assigning Alice a single global role.

It allows an organization’s authorization model to reflect actual responsibilities.

Isolate Organizational Data

Tenant isolation is particularly important when multiple departments share the same Wazuh infrastructure.

For example:

Finance
  ↓
Finance Tenant

Engineering
  ↓
Engineering Tenant

Security Operations
  ↓
SOC Tenant

Users should only be able to access the data required for their responsibilities.

This becomes especially important when security events contain sensitive operational information.

Separate Customer Environments

MSSPs can use tenant boundaries to separate customer environments.

For example:

MSSP Wazuh
     │
     ├── Customer-A
     ├── Customer-B
     ├── Customer-C
     └── Customer-D

A Customer A user should not gain access to Customer B merely because both users authenticate through the same identity infrastructure.

Customer-specific groups can help establish these boundaries:

Customer-A-Analysts
        ↓
Analyst Role
        ↓
Customer-A Tenant

Prevent Cross-Tenant Access

Cross-tenant access should be explicitly tested rather than assumed.

For example:

Customer-A User
       ↓
Customer-A Tenant
       ↓
Attempt Customer-B Access
       ↓
DENIED

Perform the same testing with:

• Analysts
• Responders
• Auditors
• Managers
• External users
• Administrative users

The goal is to confirm that role mapping does not accidentally expand tenant access.

Design Tenant-Aware Role Mappings

A tenant-aware design can combine identity-provider groups, Wazuh roles, and tenant assignments.

For example:

This structure makes the authorization model explicit.

A user can therefore be traced through:

Identity
   ↓
Group
   ↓
Wazuh Role
   ↓
Tenant
   ↓
Allowed Data

For larger deployments, avoid relying on ambiguous group names such as Analysts.

Instead, prefer names that encode the intended boundary:

SOC-Analysts
Customer-A-Analysts
Customer-B-Analysts
Compliance-Auditors

This reduces the likelihood of accidentally assigning a user to the wrong environment.

Test Tenant Isolation

Tenant isolation should be tested using dedicated test accounts.

A useful test matrix is:

Also test changes to group membership.

For example:

User initially:
Customer-A-Analysts
        ↓
Customer A access

Change group:
Customer-B-Analysts
        ↓
Customer B access

After the change, verify that access to the previous tenant is removed as intended.

This is particularly important because SSO role mapping and multi-tenancy form a combined authorization boundary.

Testing only whether a user can log in does not prove that the user’s data access is correctly isolated.

Related Guides:

• Mastering Wazuh Security: The Complete Access Control Guide 
• How to Configure Wazuh Field Level Security 

Configure Default and Fallback Roles

Default and fallback roles are an important part of a secure Wazuh SSO role-mapping design.

They determine what happens when a user successfully authenticates through the identity provider but does not match any of the expected role-mapping rules.

This situation can occur when:

• A new employee has not yet been added to a Wazuh group.
• A user belongs to an unexpected group.
• An identity-provider group was renamed.
• A group claim is missing.
• A claim contains an unexpected value.
• A role-mapping rule was deleted or changed.
• A user’s group membership was removed.

A secure design should assume that unmatched identities are possible and handle them deliberately.

Why Default Roles Matter

Authentication establishes that a user has successfully proven their identity. It does not establish that the user should have a particular level of Wazuh access.

For example:

User authenticates successfully
          ↓
No matching Wazuh role mapping
          ↓
What happens next?

The answer depends on the configured default or fallback behavior.

A poorly designed default can turn an authentication success into an unintended authorization grant.

A safer model is:

Authenticated user
       ↓
Role mapping
       │
       ├── Match → Intended Wazuh role
       │
       └── No match → Restricted / denied access

Prevent Unauthorized Access

Do not use a broad default role simply to ensure that every authenticated user can access the Dashboard.

For example, this is dangerous:

Any authenticated IdP user
          ↓
Default Analyst

If the Wazuh application is accidentally assigned to a large directory group, every member of that group could receive analyst access.

An even more dangerous configuration would be:

Any authenticated IdP user
          ↓
Default Administrator

Default administrator access should never be used as a workaround for role-mapping failures.

Configure Restricted Default Access

Where the deployment supports a restricted or deny-by-default authorization model, prefer it over a permissive default.

The desired behavior is:

Known group
    ↓
Known role
    ↓
Authorized access

Unknown group
    ↓
No privileged mapping
    ↓
Restricted / denied access

This means a role-mapping failure produces an authorization problem rather than an unexpected privilege escalation.

Handle Users Without Matching Groups

Consider a user who successfully authenticates through Microsoft Entra ID but does not belong to any Wazuh-specific group.

For example:

alice@example.com
       ↓
Entra authentication successful
       ↓
Groups:
Engineering
       ↓
No Wazuh group

The user should not automatically become an analyst simply because authentication succeeded.

Instead, the access policy should require explicit membership in a Wazuh authorization group.

For example:

Wazuh-Analysts
       ↓
Analyst

Wazuh-Admins
       ↓
Administrator

Membership in unrelated organizational groups should not provide Wazuh privileges.

Avoid Automatically Assigning Administrator Privileges

Administrator access should always require an explicit authorization condition.

Use a dedicated group such as:

Wazuh-Platform-Admins

rather than relying on a default mapping.

The authorization chain should therefore be:

User
 ↓
Wazuh-Platform-Admins
 ↓
Explicit administrator mapping
 ↓
Administrator role

This makes privileged access easier to audit and reduces the impact of an incorrectly configured identity-provider claim.

Test Unmatched Identities

Create a dedicated test account that:

1. Can authenticate to the identity provider.
2. Is assigned to the Wazuh application.
3. Does not belong to any Wazuh authorization group.

Then authenticate with that account.

Verify that it receives the intended restricted behavior.

This test is particularly valuable after changing:

• Default roles
• Group claims
• SAML mappings
• OIDC mappings
• Identity-provider application assignments
• Wazuh RBAC configuration

Test Wazuh SSO Role Mapping

Testing should validate the entire authorization chain, not simply whether the user can log in.

A successful SSO test should answer four questions:

1. Did authentication succeed?
2. Was the correct identity received?
3. Was the correct Wazuh role assigned?
4. Are permissions and tenant restrictions correct?

The complete test path is:

User
 ↓
Identity Provider
 ↓
SAML / OIDC
 ↓
Identity Claims
 ↓
Wazuh Role Mapping
 ↓
Wazuh Role
 ↓
Permissions
 ↓
Tenant Access

Test Successful Authentication

Start with a standard test user.

Verify:

• The user can reach the Wazuh Dashboard.
• The user is redirected to the IdP.
• Authentication succeeds.
• The user returns to Wazuh.
• The expected username or identity appears.
• No authentication loop occurs.

This confirms the basic SSO path.

It does not yet prove that role mapping is working.

Test Administrator Access

Use a test account belonging to the dedicated administrator group.

For example:

Wazuh-Platform-Admins
       ↓
Administrator

Verify that the account can perform the administrative operations it is expected to perform.

Also verify that administrative access does not extend beyond the intended tenant or resource scope.

Do not use your only production administrator account for initial testing.

Test Analyst Access

Use an account belonging only to the analyst group.

Wazuh-Analysts
       ↓
Analyst

Verify that the analyst can perform investigation tasks but cannot access administrative functions that should be restricted.

Test both allowed and denied operations.

For example:

View alerts             → Allowed
Search events           → Allowed
Modify security roles   → Denied
Manage users            → Denied

The exact results depend on the role configuration.

Test Responder Access

Use a dedicated responder account.

Wazuh-Responders
       ↓
Responder

Verify that the responder receives the additional capabilities required for incident response without inheriting unrelated administrator privileges.

Test Auditor Access

Use an account belonging to the auditor group:

Wazuh-Auditors
       ↓
Auditor

Verify that the user can access the information required for auditing but cannot modify security configuration unless explicitly authorized.

Test Read-Only Access

Use a dedicated read-only test account:

Wazuh-Viewers
       ↓
Read-only

Verify that the user can view the intended security information but cannot perform modification operations.

This test is useful for detecting accidental write privileges inherited through another role.

Test Multi-Tenant Access

If multi-tenancy is enabled, test both permitted and prohibited tenants.

For example:

Customer-A-Analysts
        ↓
Analyst
        ↓
Customer A Tenant

Verify:

Customer A → Allowed
Customer B → Denied

Do not consider tenant configuration validated until cross-tenant access has been explicitly tested.

Test Users Belonging to Multiple Groups

Create a test account with multiple memberships.

For example:

User
 ├── Wazuh-Analysts
 └── Wazuh-Auditors

Determine which permissions the user receives.

Then test a more sensitive combination:

User
 ├── Wazuh-Analysts
 └── Wazuh-Admins

Verify that the resulting permissions match the organization’s intended policy.

This test is important because overlapping group memberships can produce unexpected authorization results.

Test Users Without Mapped Groups

Create an authenticated user with no Wazuh-specific group membership.

Verify that the user receives the configured restricted behavior.

This validates your fallback policy and ensures that a missing mapping does not accidentally produce elevated access.

Verify Dashboard Permissions

Test permissions through the actual Wazuh Dashboard.

Check whether users can:

• View dashboards
• Search data
• View alerts
• Access administration
• Manage users
• Modify configuration
• Access intended tenants

Do not rely solely on the Dashboard’s visual appearance. A hidden or unavailable menu does not necessarily prove that the underlying API or Indexer permissions are correctly restricted.

Verify API Permissions

Test the same identity through the Wazuh API where applicable.

This is important because a user may have restricted Dashboard functionality while still possessing unexpected API privileges.

For example:

Analyst
  ↓
Dashboard permissions
  ↓
Expected

Analyst
  ↓
API request
  ↓
Expected authorization result

API authorization should be tested independently.

Related Guide: Wazuh API Authentication Failed? Causes and Solutions

Verify Indexer Permissions

Finally, verify the permissions enforced by the Wazuh Indexer security layer.

This is especially important for:

• Index access
• Tenant access
• Read permissions
• Write permissions
• Administrative security operations

The goal is to ensure that the Wazuh role assigned through SSO actually produces the expected effective permissions.

Troubleshooting Wazuh SSO Role Mapping

Most Wazuh SSO role-mapping problems fall into one of four categories:

Authentication failure
        ↓
Claims / attributes failure
        ↓
Role-mapping failure
        ↓
Authorization / tenant failure

The most efficient troubleshooting approach is to identify which layer is failing instead of changing multiple security settings simultaneously.

User Can Log In but Has the Wrong Role

This is one of the most common Wazuh SSO role-mapping problems.

The authentication flow succeeds, but the user receives:

• The wrong role
• A default role
• Insufficient permissions
• Unexpected privileges

Start by examining the identity information returned by the IdP.

Check Group Attributes

Determine whether the SAML assertion or OIDC token contains the expected group.

For example:

Expected:
Wazuh-Analysts

Received:
Security-Analysts

The mapping will not match unless the configured rule accounts for the actual value.

Check SAML Assertions or OIDC Claims

Inspect the authentication response and verify:

Username
Email
Groups
Roles

For SAML, verify the attributes contained in the assertion.

For OIDC, inspect the relevant token claims or user-information response according to the authentication flow.

The goal is to establish what Wazuh actually receives rather than what the identity provider’s administration interface appears to show.

Check Role Mappings

Review each mapping rule.

For example:

Wazuh-Admins
      ↓
Administrator

Wazuh-Analysts
      ↓
Analyst

Look for:

• Typographical errors
• Wrong claim names
• Wrong group values
• Incorrect role names
• Disabled mappings
• Conflicting mappings

Check Attribute Names

The attribute name must match what the IdP sends.

For example:

Configured:
groups

Received:
http://schemas.example.com/claims/groups

Those values are not automatically interchangeable.

Verify the actual attribute name and configure the mapping accordingly.

Check Group Membership

Verify that the user actually belongs to the expected group.

For example:

alice@example.com
       ↓
Wazuh-Analysts

Also check whether the user was recently added or removed from a group and whether the IdP has propagated the change.

User Can Authenticate but Cannot Access Wazuh

This scenario is different from a failed login.

The IdP authenticates the user successfully, but the user cannot access the expected Wazuh resources.

Check Default Role

Determine whether the user is falling into the default role because no explicit mapping matched.

A common pattern is:

Authentication successful
        ↓
No role match
        ↓
Default / restricted role

If this is happening, investigate the claim and mapping rather than simply making the default role more permissive.

Check Mapped Roles

Verify that the target Wazuh role exists and has the required permissions.

A correct group mapping is not enough if the underlying role is incorrectly configured.

Check Tenant Permissions

If the role appears correct but data is unavailable, check tenant permissions.

For example:

Correct role
      ↓
Wrong tenant
      ↓
No expected data

This can make an otherwise successful SSO integration appear broken.

Check Indexer Security Configuration

Review the Indexer security configuration for:

• Role definitions
• Role mappings
• Backend roles
• Tenant permissions
• Index permissions
• Authentication settings

An SSO identity can be valid while the corresponding Indexer authorization is incorrect.

Check Dashboard Configuration

If the Indexer permissions appear correct, inspect the Dashboard configuration.

Check:

• Authentication configuration
• SSO settings
• Security plugin configuration
• Tenant settings
• TLS connectivity
• Reverse-proxy configuration

If the Dashboard itself is having broader availability problems, resolve those independently.

Related Guide: Wazuh Dashboard Not Loading? Complete Troubleshooting Guide 

SSO Groups Are Not Being Detected

If users authenticate successfully but Wazuh never sees the expected groups, focus on the identity-provider claim configuration.

Verify Group Claims

Confirm that the SAML assertion or OIDC response actually contains group information.

For example:

groups:
  - Wazuh-Analysts

If the claim is absent, Wazuh cannot perform group-based role mapping.

Check Identity-Provider Configuration

Verify that the Wazuh application is configured to send group information.

Identity providers often have separate settings controlling:

• Which groups are included
• Which groups are assigned to an application
• Claim names
• Group filtering
• Application roles
• Token claims

A user being a member of a group does not necessarily mean the group will be emitted in every SSO response.

Check Token Contents

For OIDC, inspect the relevant token claims.

For example:

{
  "sub": "123456",
  "email": "alice@example.com",
  "groups": [
    "Wazuh-Analysts"
  ]
}

If the groups claim is absent, investigate the IdP configuration before changing Wazuh mappings.

Check SAML Assertions

For SAML, inspect the assertion attributes.

Look for:

Attribute Name:
groups

Attribute Value:
Wazuh-Analysts

Also check whether the value is:

• A single string
• A list
• A URI
• A fully qualified group name
• A provider-specific identifier

The mapping must account for the actual representation.

Check OIDC Scopes and Claims

OIDC claims may depend on requested scopes, client configuration, protocol mappers, or provider-specific settings.

Verify that the required scope has been requested and that the IdP is configured to expose group or role claims to the Wazuh client.

User Receives Excessive Permissions

Excessive permissions are potentially more serious than insufficient permissions because they represent an authorization vulnerability.

For example:

Expected:
Analyst

Actual:
Administrator

Treat this as a security issue and investigate immediately.

Check Overlapping Mappings

Look for users who belong to multiple Wazuh-related groups.

For example:

User
 ├── Wazuh-Analysts
 └── Wazuh-Admins

Determine how the security configuration combines those memberships.

Review Role Inheritance

Inspect whether the assigned role inherits permissions from another role.

A seemingly restrictive role can become powerful if it inherits a privileged role or backend permission.

Review the effective permissions rather than only the role’s name.

Review Group Membership

Check the user’s complete identity-provider membership.

An administrator may believe the user belongs only to:

Wazuh-Analysts

while the IdP actually reports:

Wazuh-Analysts
Wazuh-Admins
Security-Administrators

Those additional memberships may affect authorization.

Check Administrator Mappings

Review every mapping that leads to an administrator role.

Look for overly broad conditions such as:

Security*
    ↓
Administrator

A safer design uses a dedicated administrative group.

Remove Unnecessary Privileges

Once the cause is identified:

1. Remove unnecessary group membership.
2. Remove overly broad mappings.
3. Reduce role permissions.
4. Review tenant access.
5. Reauthenticate the user.
6. Repeat the authorization tests.

Do not solve excessive permissions by adding additional restrictions elsewhere without understanding the original cause.

SSO Login Redirects or Authentication Fails

Redirect failures generally occur before role mapping is reached.

If the user cannot complete the authentication flow, first troubleshoot the federation configuration.

Verify Redirect URLs

Check the exact redirect or callback URL configured in both systems.

Compare:

Wazuh configuration
       ↕
Identity Provider

Pay attention to:

• HTTPS vs HTTP
• Hostnames
• Ports
• Paths
• Trailing slashes
• Reverse-proxy URLs

Verify Certificates

Check certificates on both sides of the authentication relationship.

Verify:

• Certificate validity
• Expiration
• Trust chain
• Subject/SAN
• Signing certificate
• Certificate rotation

Certificate problems can cause SAML validation and TLS failures.

Related Guide: How to Fix Wazuh Certificate Errors

Verify Entity IDs and Issuer Values

For SAML, verify that the service-provider and identity-provider entity identifiers are correct.

For OIDC, verify the issuer value.

Conceptually:

SAML:
Entity ID
        ↕
IdP configuration

OIDC:
Issuer
        ↕
Wazuh configuration

An incorrect identifier can cause Wazuh to reject an otherwise valid authentication response.

Check Clock Synchronization

Check the system time on the Wazuh infrastructure and identity-provider environment.

Clock drift can cause:

• Expired assertions
• Not-yet-valid assertions
• Invalid token timestamps
• TLS-related failures

Ensure systems use reliable time synchronization.

Review Dashboard and Indexer Logs

Finally, inspect the relevant Wazuh Dashboard and Indexer logs.

Look for messages involving:

SAML
OIDC
authentication
authorization
role mapping
certificate
token
claim
tenant
security plugin

Correlate the log timestamp with a fresh login attempt.

A useful troubleshooting sequence is:

1. Can the user reach the Dashboard?
              ↓
2. Does the IdP authenticate the user?
              ↓
3. Does Wazuh receive the SAML/OIDC response?
              ↓
4. Are the expected claims present?
              ↓
5. Does role mapping match?
              ↓
6. Does the mapped role exist?
              ↓
7. Are permissions correct?
              ↓
8. Is tenant access correct?

This approach prevents administrators from changing RBAC permissions when the actual problem is a missing group claim, incorrect SAML attribute, invalid OIDC issuer, or broken redirect configuration.

Monitor and Audit Wazuh SSO Role Mapping

Wazuh SSO role mapping should be treated as an ongoing authorization control rather than a one-time configuration task.

Authentication changes, identity-provider group changes, role modifications, and tenant assignments can all change what an authenticated user is allowed to do.

Wazuh’s RBAC system controls access to Wazuh resources through assigned roles and policies, while the Dashboard provides the interface for managing RBAC and SSO-related security controls.

A useful monitoring model is:

Identity Provider
       ↓
Authentication Events
       ↓
Groups / Claims
       ↓
Wazuh Role Mapping
       ↓
Effective Role
       ↓
Tenant / Resource Access
       ↓
Audit and Monitoring

Monitor Successful SSO Authentication

Track successful SSO authentication events so you can establish who is accessing Wazuh and when.

Useful fields to retain include:

• Username
• Email address
• Authentication timestamp
• Identity provider
• Source IP address
• Authentication method
• SAML or OIDC authentication status
• Assigned identity-provider groups or roles, where available

Successful authentication by itself does not prove that authorization is correct.

It should be correlated with the user’s effective Wazuh role and tenant access.

For example:

Alice
 ↓
Entra ID authentication successful
 ↓
Wazuh-Analysts
 ↓
Analyst role
 ↓
SOC tenant

This provides a much more useful audit trail than simply recording that Alice logged in.

Monitor Failed Authentication

Failed SSO authentication can identify both configuration problems and potentially suspicious activity.

Monitor for:

• Repeated failed logins
• Authentication failures involving privileged accounts
• Unusual login locations
• Repeated authentication attempts within a short period
• Failed certificate validation
• Invalid SAML assertions
• OIDC authentication failures
• Unexpected authentication-provider errors

A single failed login may simply indicate a configuration mistake.

Repeated failures involving the same privileged account deserve additional investigation.

Related Guide: Wazuh API Authentication Failed? Causes and Solutions 

Audit Administrator Access

Privileged SSO groups deserve additional monitoring.

For example:

Wazuh-Platform-Admins
        ↓
Administrator

Track:

• Administrator logins
• Changes to administrator group membership
• Changes to administrator mappings
• Changes to privileged Wazuh roles
• Changes to tenant permissions
• Changes to authentication configuration

An administrator being added to the identity provider’s privileged group can effectively change their Wazuh authorization without changing anything directly inside Wazuh.

That makes the identity provider an important part of the Wazuh authorization audit trail.

Track Role-Assignment Changes

Monitor changes to:

• Wazuh role mappings
• Custom roles
• Role permissions
• Backend roles
• Identity-provider mappings
• Tenant assignments
• Default or fallback roles

For example:

Before:
Wazuh-Analysts → Analyst

After:
Wazuh-Analysts → Administrator

That change should be treated as a significant security event.

Wazuh supports custom roles and role mappings, so changes to these objects can materially alter access to the platform.

Monitor Identity-Provider Group Changes

Group membership changes are particularly important when groups drive Wazuh authorization.

For example:

Employee
   ↓
Wazuh-Analysts
   ↓
Analyst access

If the same employee is added to:

Wazuh-Admins

their effective privileges may change substantially.

Monitor:

• Users added to privileged groups
• Users removed from privileged groups
• Group creation
• Group deletion
• Group renaming
• Changes to application assignments
• Changes to group-to-application mappings

Identity-provider audit logs should therefore be considered part of the Wazuh SSO audit process.

Detect Unexpected Privilege Escalation

Look for authorization changes that do not correspond to an approved administrative action.

Examples include:

Analyst → Administrator
Auditor → Responder
Customer A → Customer B
Read-only → Write access

A particularly useful detection strategy is to compare a user’s previous effective access against their current access.

For example:

Previous:
Wazuh-Analysts
        ↓
Analyst
        ↓
SOC

Current:
Wazuh-Admins
        ↓
Administrator
        ↓
SOC

The addition of the administrator group should generate an alert or at least appear in a privileged-access review.

Review Wazuh Authentication Logs

Regularly review Wazuh Dashboard, Indexer, and related authentication/security logs for evidence of:

• Successful authentication
• Failed authentication
• Authorization failures
• Role-mapping failures
• SAML errors
• OIDC errors
• Certificate problems
• Tenant-access failures

Correlating these events can help distinguish an SSO configuration problem from an actual authorization problem.

Integrate SSO Events with Wazuh Monitoring

Where practical, forward relevant identity-provider and authentication logs into Wazuh itself.

This creates an additional monitoring layer:

Identity Provider
      ↓
Authentication / Audit Logs
      ↓
Wazuh
      ↓
Detection Rules
      ↓
Alerts

You can then create detections for events such as:

• Administrator group membership changes
• Repeated failed SSO authentication
• Unexpected role changes
• Privileged group additions
• Authentication from unusual sources
• Changes to SSO configuration

This is especially useful in enterprise environments where identity-provider activity is otherwise separated from SIEM monitoring.

Periodically Review Role Mappings

Perform scheduled reviews of every mapping.

A review should identify:

• Active mappings
• Obsolete mappings
• Duplicate mappings
• Overlapping mappings
• Privileged mappings
• Default mappings
• Tenant assignments
• Identity-provider groups that no longer exist

A simple review table can help:

Delete or disable obsolete mappings rather than allowing them to accumulate.

Wazuh SSO Role Mapping Security Best Practices

A secure Wazuh SSO deployment should follow the same fundamental principle as other enterprise authorization systems: authenticate centrally, authorize explicitly, and grant only the access required for the user’s responsibilities.

NIST’s access-control guidance includes least privilege as a core security principle, making it a useful framework for designing Wazuh roles and identity-provider mappings.

Follow Least-Privilege Principles

Give users the minimum Wazuh permissions necessary to perform their jobs.

A practical hierarchy might look like:

Read-only
    ↓
Analyst
    ↓
Responder
    ↓
Administrator

Do not automatically move users upward in this hierarchy simply because they need additional visibility.

Instead, identify the specific permission they require and provide it through an appropriate role.

Use Dedicated Identity-Provider Groups

Create Wazuh-specific groups instead of mapping generic organizational groups.

Prefer:

Wazuh-Admins
Wazuh-Analysts
Wazuh-Responders
Wazuh-Auditors

over:

IT
Security
Employees
Managers
Engineering

Dedicated groups make the authorization model easier to understand and audit.

Avoid Mapping Broad Groups to Administrator Roles

Never map a broad group directly to an administrator role.

For example, avoid:

Security Department
        ↓
Administrator

Instead:

Wazuh-Platform-Admins
        ↓
Administrator

The narrower group makes privileged access intentional.

Use Separate Administrator and Analyst Groups

Do not combine administrative and investigative responsibilities into one identity-provider group unless there is a documented requirement.

Use:

Wazuh-Admins
      ↓
Administrator

and:

Wazuh-Analysts
      ↓
Analyst

This also makes access reviews considerably easier.

Restrict Default Access

Prefer an explicit mapping model in which users receive access because they belong to an authorized group.

Avoid:

Any authenticated user
        ↓
Analyst

unless there is a very specific business requirement and the identity-provider application itself is tightly restricted.

A safer model is:

Authenticated
     ↓
Authorized Wazuh group?
     ├── Yes → mapped role
     └── No → restricted / denied

Minimize Custom Role Complexity

Custom roles are useful when built-in roles do not provide the required level of granularity.

Wazuh supports both built-in roles and custom roles, but every additional role increases the complexity of your authorization model.

Avoid creating many nearly identical roles.

Instead, use a small number of well-defined roles such as:

Wazuh-Admin
Wazuh-Analyst
Wazuh-Responder
Wazuh-Auditor
Wazuh-ReadOnly

Add custom roles only when there is a clear permission difference that cannot be represented cleanly with the existing roles.

Protect SAML Certificates and OIDC Credentials

Treat SSO credentials as security-sensitive configuration.

Protect:

• SAML signing certificates
• SAML private keys
• OIDC client secrets
• Identity-provider metadata
• Wazuh security configuration
• Backup copies of authentication configuration

Do not store client secrets or private keys in publicly accessible repositories.

Rotate credentials and certificates according to your organization’s security policy.

Use TLS for All SSO Communication

SSO authentication should use HTTPS/TLS.

Protect the communication paths between:

User ↔ Identity Provider
User ↔ Wazuh Dashboard
Wazuh ↔ Identity Provider
Wazuh Dashboard ↔ Wazuh Indexer

Verify certificates rather than disabling TLS validation to work around certificate errors.

Related Guides How to Fix Wazuh Certificate Errors

Review Group Membership Regularly

Because identity-provider groups can directly control Wazuh privileges, group membership should be included in access reviews.

Pay particular attention to:

• Administrators
• Responders
• External users
• MSSP users
• Users with multiple privileged groups

Remove unnecessary memberships promptly.

Remove Inactive Users

Disable or remove users who no longer require Wazuh access.

This is especially important when SSO access is controlled through application assignments and groups.

A user leaving the SOC should not remain in:

Wazuh-Analysts

indefinitely.

Automated identity lifecycle management can reduce this risk where the identity provider supports it.

Audit Role Mappings Periodically

Review the complete chain:

IdP group
   ↓
Claim / backend role
   ↓
Wazuh role
   ↓
Wazuh permissions
   ↓
Tenant

Do not review only the Wazuh role name.

A role named Analyst could still have excessive permissions if its underlying policies or tenant assignments are overly broad.

Back Up SSO and RBAC Configuration

Back up the configuration required to reconstruct the SSO and authorization architecture.

Depending on your deployment, this can include:

• Wazuh Dashboard configuration
• Wazuh Indexer security configuration
• Role definitions
• Role mappings
• SAML configuration
• OIDC configuration
• Identity-provider metadata
• Certificates
• Relevant tenant configuration

Wazuh’s own documentation recommends backing up security configuration before making certain authentication and role-mapping changes.

Related Guide: How to Backup Wazuh RBAC Configurations

Test Mappings After Identity-Provider Changes

Do not assume an identity-provider change is isolated from Wazuh.

Changes to:

• Group names
• Group membership
• Claims
• Application roles
• Client configuration
• SAML certificates
• OIDC scopes
• Redirect URLs

can affect Wazuh authentication or authorization.

Run a predefined SSO test suite after significant changes.

Document the Authorization Model

Document the entire authorization chain.

For example:

Microsoft Entra ID
        ↓
Wazuh-Admins
        ↓
SAML role claim
        ↓
Wazuh administrator role
        ↓
SOC tenant

Document the equivalent mappings for analysts, responders, auditors, and read-only users.

This makes troubleshooting and security reviews substantially easier.

Real-World Wazuh SSO Role Mapping Example

Consider an enterprise SOC with several hundred employees, a dedicated security operations team, and multiple departments sharing a centralized Wazuh deployment.

The organization wants to eliminate separate Wazuh credentials and manage authentication through its existing identity provider.

For this example, the organization uses Microsoft Entra ID with SAML.

Wazuh’s official Entra ID documentation demonstrates using Entra application roles and SAML claims as backend roles that can then be mapped to Wazuh roles.

Describe the Enterprise SOC Deployment

The environment contains:

                    Microsoft Entra ID
                           │
                           │ SAML
                           ▼
                    Wazuh Dashboard
                           │
             ┌─────────────┴─────────────┐
             ▼                           ▼
       Wazuh Indexer               Wazuh Manager
             │                           │
             └─────────────┬─────────────┘
                           ▼
                    Enterprise SOC

The SOC has four primary user categories:

• Platform administrators
• Security analysts
• Incident responders
• Auditors

The organization also uses separate Wazuh tenants for different operational functions.

Use Microsoft Entra ID as the Identity Provider

The security team creates a dedicated Wazuh enterprise application in Microsoft Entra ID.

The application is configured for SAML authentication.

The organization then creates four dedicated authorization groups:

Wazuh-Admins
Wazuh-Analysts
Wazuh-Responders
Wazuh-Auditors

Only users who require Wazuh access are assigned to these groups.

Create Groups for Administrators, Analysts, Responders, and Auditors

The resulting directory structure is:

Microsoft Entra ID

├── Wazuh-Admins
│
├── Wazuh-Analysts
│
├── Wazuh-Responders
│
└── Wazuh-Auditors

The organization avoids mapping broad groups such as All Employees or Security Department directly to Wazuh roles.

Create Corresponding Wazuh Roles

The Wazuh authorization model is:

Where the built-in roles do not provide sufficient granularity, the organization creates custom roles with narrowly defined permissions.

Wazuh supports role mappings that associate identities or backend roles with Wazuh roles.

Configure SAML

The Wazuh enterprise application is configured with the Wazuh SAML endpoints.

The organization configures the appropriate:

• Entity ID
• Assertion Consumer Service URL
• Sign-on URL
• SAML certificate
• Identity-provider metadata
• Role-related claims

For example, the Wazuh SAML configuration might conceptually receive:

User:
alice@example.com

Role claim:
Wazuh-Analysts

Wazuh then uses that backend role value during role mapping.

Microsoft’s Entra example in the Wazuh documentation uses a SAML role claim based on an assigned application role and maps that backend role to a Wazuh role.

Map Identity-Provider Groups to Wazuh Roles

The mappings are defined as:

Wazuh-Admins
      ↓
Administrator

Wazuh-Analysts
      ↓
Analyst

Wazuh-Responders
      ↓
Responder

Wazuh-Auditors
      ↓
Auditor

This creates a clear separation between authentication and authorization.

Entra ID answers:

Who is this user?

The Wazuh role mapping answers:

What can this authenticated user do?

Configure Multi-Tenancy

The organization creates separate Dashboard tenants:

Global
Private
SOC
Compliance

Wazuh supports custom tenants that can be assigned to specific roles, allowing organizations to create separate spaces for different groups of users.

The resulting authorization model might be:

Wazuh-Admins
      ↓
Administrator
      ↓
SOC + Administrative scope

Wazuh-Analysts
      ↓
Analyst
      ↓
SOC

Wazuh-Responders
      ↓
Responder
      ↓
SOC

Wazuh-Auditors
      ↓
Auditor
      ↓
Compliance

This means a user can have a valid Wazuh role without automatically gaining access to every tenant.

Test Each Team’s Permissions

The security team creates one test account for each role.

Administrator Test

Test Admin
    ↓
Wazuh-Admins
    ↓
Administrator

Verify administrative operations.

Analyst Test

Test Analyst
    ↓
Wazuh-Analysts
    ↓
Analyst

Verify that the user can investigate security events but cannot perform restricted administrative actions.

Responder Test

Test Responder
    ↓
Wazuh-Responders
    ↓
Responder

Verify that response capabilities are available while unrelated administrative privileges remain restricted.

Auditor Test

Test Auditor
    ↓
Wazuh-Auditors
    ↓
Auditor

Verify access to the intended compliance and security information while confirming that modification privileges remain restricted.

Verify Least-Privilege Access

The SOC then tests both positive and negative authorization scenarios.

For example:

The team also tests a user who belongs to no Wazuh group.

The expected result is restricted or denied access rather than automatic administrator or analyst access.

Document the Final SSO Role-Mapping Architecture

The completed architecture is documented as:

                         Microsoft Entra ID
                                │
                    ┌───────────┴───────────┐
                    │      Wazuh App        │
                    └───────────┬───────────┘
                                │
                              SAML
                                │
                                ▼
                        Wazuh Dashboard
                                │
                         Role Mapping
                                │
          ┌─────────────┬───────┼────────┬─────────────┐
          ▼             ▼       ▼        ▼             ▼
       Admins        Analysts Responders Auditors   Unmatched
          │             │       │        │             │
          ▼             ▼       ▼        ▼             ▼
   Administrator     Analyst  Responder Auditor   Restricted
          │             │       │        │
          ▼             ▼       ▼        ▼
      SOC/Admin        SOC     SOC    Compliance
                                │
                                ▼
                         Wazuh Indexer

This documentation should identify:

• Identity provider
• SSO protocol
• Application configuration
• Claims or backend roles
• Identity-provider groups
• Wazuh role mappings
• Custom roles
• Tenant assignments
• Default/fallback behavior
• Administrator groups
• Certificate locations
• OIDC credentials, if applicable
• Backup locations
• Testing procedures
• Change-management requirements

The result is an authorization architecture that can be understood and audited from the identity provider all the way through to the Wazuh Dashboard and Indexer.

Related Guides:

• Mastering Wazuh Security: The Complete Access Control Guide
• How to Configure Wazuh RBAC 

Microsoft Entra ID
      ↓
Wazuh-Analysts group
      ↓
SSO claim
      ↓
Wazuh role mapping
      ↓
Analyst role

Wazuh-Admins
     ↓
Administrator

Wazuh-Analysts
     ↓
Analyst

Wazuh-Auditors
     ↓
Auditor

Entra ID group
      ↓
Application role / claim
      ↓
Wazuh backend role
      ↓
Wazuh role

Keycloak group
      ↓
SAML / OIDC claim
      ↓
Wazuh backend role
      ↓
Wazuh role

Wazuh-Admins
Wazuh-Analysts
Wazuh-Responders
Wazuh-Auditors

Wazuh-Admins → Administrator
Wazuh-Analysts → Analyst
Wazuh-Responders → Responder
Wazuh-Auditors → Auditor

{
  "sub": "123456",
  "email": "analyst@example.com",
  "groups": [
    "Wazuh-Analysts"
  ]
}

User
 ├── Wazuh-Analysts
 └── Wazuh-Auditors

Wazuh-Analysts
+
Wazuh-Admins

Identity Provider
      ↓
User identity + groups/roles
      ↓
SSO role mapping
      ↓
Wazuh RBAC role
      ↓
Permissions

Wazuh-Analysts
      ↓
Analyst
      ↓
Security investigation permissions

Entra ID
   ↓
Wazuh-Client-A-Analysts
   ↓
Analyst role
   ↓
Client A tenant

Authenticated user
       ↓
No matching Wazuh group
       ↓
Restricted / denied access

Authentication
      ↓
SAML / OIDC response
      ↓
Claims / attributes
      ↓
Group membership
      ↓
Role mapping
      ↓
Wazuh role
      ↓
Permissions
      ↓
Tenant access

Identity Provider
       ↓
SAML / OIDC authentication
       ↓
User identity + claims
       ↓
Group / role mapping
       ↓
Wazuh RBAC
       ↓
Permissions
       ↓
Tenant access