The Complete Wazuh Single Sign-On (SSO) Guide

Wazuh SSO allows organizations to connect the Wazuh Dashboard to a centralized identity provider (IdP) instead of requiring users to maintain separate Wazuh credentials. Rather than authenticating directly against an internal Wazuh username and password database, users can authenticate through an enterprise identity platform such as Microsoft Entra ID, Okta, Keycloak, Google Workspace, or another supported identity service. Wazuh’s current documentation supports integrating the platform with multiple identity providers for Single Sign-On, while also providing a separate Active Directory/LDAP integration path for centralized authentication and authorization.

For security teams, this distinction is important. Wazuh SSO does not simply replace a login screen.

It moves primary identity verification to a centralized identity system and allows Wazuh to consume the resulting identity information and apply its own authorization and role-mapping policies.

Related Guides:

What Is Wazuh SSO?

Wazuh SSO is an authentication architecture that allows users to access the Wazuh Dashboard using an identity already established by an external identity provider.

In a traditional deployment, a user enters credentials managed directly by Wazuh.

With SSO, Wazuh delegates the authentication process to an external identity system.

The IdP verifies the user’s identity and returns trusted authentication information to Wazuh.

This architecture is particularly useful in enterprise environments where the same identity provider already controls access to dozens or hundreds of applications.

For example, an organization might use Microsoft Entra ID as its central identity provider.

Employees authenticate to their corporate identity once, and the same identity can then be used to access Wazuh without maintaining another independent password.

Wazuh’s documentation currently lists integrations for providers including Okta, Microsoft Entra ID, Google Workspace, Keycloak, OneLogin, PingOne, JumpCloud, and authentik.

Definition of Wazuh Single Sign-On

Single Sign-On is an identity federation model in which a user authenticates with a centralized identity provider and can subsequently access a trusted service provider without independently authenticating to that application.

In a Wazuh deployment, the major parties are:

User: The person attempting to access the Wazuh Dashboard.
Identity Provider (IdP): The system responsible for authenticating the user.
Wazuh Dashboard: The application the user wants to access.
Wazuh Indexer security layer: The component involved in processing authentication and authorization information for the Wazuh environment.
Role mapping: The mechanism that translates identity attributes or groups into permissions within Wazuh.

The exact protocol depends on the selected authentication architecture. SAML exchanges XML-based assertions, while OpenID Connect uses OAuth 2.0-based authentication and ID tokens.

LDAP takes a different approach by directly communicating with a directory service for authentication and authorization.

How Wazuh SSO Works

At a high level, a Wazuh SSO login follows this sequence:

The user opens the Wazuh Dashboard.
Wazuh determines that authentication must be performed.
The user is redirected to, or otherwise interacts with, the configured identity provider.
The IdP authenticates the user.
The IdP returns an authentication response to Wazuh.
Wazuh validates the response.
Wazuh extracts the user’s identity and relevant attributes.
Role mappings determine what the user is allowed to do.
Wazuh establishes an authenticated dashboard session.
The user accesses the Wazuh resources permitted by the assigned roles.

The important architectural principle is that authentication and authorization are related but separate operations.

The identity provider answers the question:

Who is this user?

Wazuh’s authorization configuration answers the next question:

What is this user allowed to access?

This distinction becomes especially important when implementing SSO role mapping.

Related Guide: How to Configure Wazuh SSO Role Mapping

Benefits of SSO for Wazuh

Wazuh SSO provides several advantages over maintaining isolated application credentials.

Centralized identity management

User identities can be managed through an organization’s existing identity platform rather than manually creating and maintaining independent Wazuh credentials.

Reduced password sprawl

Users do not need another application-specific password solely for Wazuh. This reduces the number of credentials that users and administrators must manage.

Centralized authentication policies

Organizations can enforce authentication controls through their identity provider, including password policies, conditional access policies, and, depending on the IdP, multi-factor authentication.

Simplified employee onboarding and offboarding

When access is tied to centralized identities or groups, administrators can provision and revoke access through the organization’s existing identity-management processes.

Centralized auditing

Authentication events can be correlated with identity-provider logs and Wazuh activity, giving security teams greater visibility into authentication behavior.

Consistent access control

Group membership and identity attributes can be mapped to Wazuh roles. This makes it possible to distinguish administrators, analysts, responders, auditors, and other users without manually configuring every account independently.

Improved enterprise scalability

SSO becomes increasingly valuable as the number of Wazuh users and environments grows. Instead of managing credentials separately in every security application, organizations can centralize identity management.

SSO vs Traditional Wazuh Authentication

The primary difference is where authentication occurs.

Area	Traditional authentication	Wazuh SSO
Primary identity source	Wazuh/internal credentials	External identity provider
Password management	Managed within the Wazuh environment	Managed by the IdP
Authentication	Directly against configured credentials	Delegated to IdP
MFA	Depends on the authentication architecture	Commonly enforced by IdP
User lifecycle	Often application-specific	Centralized through identity platform
Group-based access	Requires local configuration	Can use IdP attributes/groups
Enterprise identity integration	More limited	Designed for federation
Centralized authentication policy	Limited	Stronger integration with IdP policies

LDAP sits between these models conceptually.

Wazuh can integrate with Active Directory or another LDAP server so that the directory becomes the source of authentication and authorization information.

Wazuh’s documentation explicitly separates LDAP integration from its SSO integrations.

SSO Authentication Flow

A simplified Wazuh SSO flow looks like this:

User
  |
  v
Wazuh Dashboard
  |
  | Authentication request
  v
Identity Provider
  |
  | Authenticate user
  | Validate credentials / MFA / policy
  v
Identity Provider
  |
  | SAML Response or OIDC response
  v
Wazuh Dashboard / Indexer Security
  |
  | Validate identity information
  | Map attributes/groups to roles
  v
Authenticated Wazuh Session
  |
  v
Wazuh Dashboard

The exact messages differ depending on whether the environment uses SAML, OIDC, or LDAP.

For SAML, the IdP typically returns a SAML response containing an assertion.

The OASIS SAML specification describes assertions as security information exchanged between trusted parties, including authentication and attribute information.

For OIDC, the identity provider returns an ID token containing claims about the authenticated user. OpenID Connect defines the ID token as a JWT containing claims about the authentication event.

Components Involved in Wazuh SSO

A typical Wazuh SSO architecture contains several logical components.

Wazuh Dashboard

The Dashboard provides the web interface users access and participates in the authentication process.

Wazuh Indexer

The Wazuh Indexer security layer participates in authentication and authorization processing. This is particularly important for understanding role mapping and backend permissions.

Identity Provider

The IdP is responsible for authenticating users and issuing trusted identity information.

Examples include:

Microsoft Entra ID
Okta
Keycloak
Google Workspace
PingOne
OneLogin
JumpCloud
authentik

Authentication protocol

The protocol defines how the identity provider and Wazuh exchange authentication information.

Common architectures include:

SAML 2.0
OpenID Connect
LDAP

Certificates and signing keys

SAML deployments commonly use certificates for signing and validating assertions and metadata. OIDC deployments similarly rely on cryptographic signing keys for validating ID tokens.

Role mappings

Role mappings translate identity attributes, groups, or other identity information into Wazuh permissions.

Session management

After successful authentication, Wazuh establishes the session that allows the user to interact with the Dashboard without repeatedly authenticating for every request.

How Wazuh SSO Authentication Works

Wazuh SSO is easier to troubleshoot when the authentication architecture is understood as a chain of trust.

The identity provider establishes the user’s identity.

Wazuh validates the resulting authentication information.

Wazuh then determines the user’s authorization based on configured roles and mappings.

This means an SSO login can fail at several different points even when the user’s password is correct.

Wazuh Dashboard Authentication Architecture

The Wazuh Dashboard sits at the front of the user-facing authentication process, but it should not be viewed as the sole authentication authority in an SSO deployment.

A simplified architecture is:

                    +----------------------+
                    |   Identity Provider  |
                    |  Entra / Okta /      |
                    |  Keycloak / Google   |
                    +----------+-----------+
                               |
                       Authentication
                       response / token
                               |
                               v
+---------+             +-------------+
|  User   | ----------> |    Wazuh    |
| Browser |             |  Dashboard  |
+---------+             +------+------+
                               |
                               v
                       +---------------+
                       | Wazuh Indexer |
                       | Security      |
                       +-------+-------+
                               |
                               v
                         Role Mapping
                               |
                               v
                       Wazuh Permissions

This layered architecture explains why a successful IdP login does not necessarily mean the user will have the expected Wazuh permissions.

An identity provider can successfully authenticate the user while a Wazuh role-mapping configuration fails to assign the appropriate backend role.

Identity Provider (IdP)

The Identity Provider is the system that authenticates the user.

Depending on the environment, authentication might involve:

Username and password
Multi-factor authentication
Conditional access
Device policies
Network restrictions
Risk-based authentication
Existing IdP sessions

The IdP then provides Wazuh with information that allows the application to establish the user’s identity.

In SAML terminology, the IdP is the party that creates and issues assertions.

OASIS describes the IdP/SP relationship as one of the fundamental components of SAML-based web SSO.

Service Provider (SP)

In a SAML architecture, the application requesting authentication is commonly referred to as the Service Provider.

For Wazuh SSO, the Wazuh application participates as the relying/service-provider side of the federation relationship.

The SP establishes trust with the IdP and validates the authentication information received from it.

This trust relationship normally depends on configuration such as:

Entity identifiers
Redirect or callback endpoints
Certificates
Metadata
Signing requirements
Attribute mappings

The exact terminology varies with the protocol.

OIDC generally uses Relying Party (RP) and OpenID Provider (OP) terminology rather than SAML’s SP and IdP terminology.

Authentication Requests and Responses

Authentication is generally a request-and-response process.

The application initiates authentication by directing the user’s browser toward the identity provider or authorization endpoint.

The IdP authenticates the user and returns the appropriate authentication response.

For SAML, this commonly means an authentication request followed by a SAML response containing an assertion.

OASIS documents the Web Browser SSO flow around these request and response messages.

For OIDC, the client sends an authorization request to the OpenID Provider.

In the Authorization Code Flow, the provider authenticates the user and returns an authorization code, which the client exchanges for an ID token and access token.

The response must be validated before Wazuh treats the user as authenticated.

SAML Authentication Flow

A typical SAML-based Wazuh login follows this sequence:

The user accesses the Wazuh Dashboard.
Wazuh determines that the user needs to authenticate.
The browser is redirected to the configured SAML IdP.
The IdP authenticates the user.
The IdP creates a SAML assertion describing the authenticated identity.
The IdP returns a SAML response to Wazuh.
Wazuh validates the response and assertion.
Wazuh extracts the relevant user attributes.
Wazuh maps those attributes to configured roles.
A Wazuh session is established.

SAML assertions can contain authentication statements and attribute statements.

The OASIS technical overview explains that assertions can communicate information about the subject, including identity and attributes, while metadata can describe endpoints and key material used between federation participants.

One of the most important security controls is assertion validation.

Wazuh should not simply trust arbitrary data returned by a browser.

The response must satisfy the configured trust relationship and validation requirements.

OIDC Authentication Flow

OpenID Connect is an identity layer built on top of OAuth 2.0.

It allows a client to verify an end user’s identity and receive standardized identity claims.

A typical OIDC authentication flow is:

The user opens the Wazuh Dashboard.
Wazuh redirects the user to the OpenID Provider.
The user authenticates with the provider.
The provider returns an authorization response.
Wazuh exchanges the authorization code for tokens when using the Authorization Code Flow.
The provider returns an ID token and, where applicable, an access token.
Wazuh validates the ID token.
Wazuh extracts the relevant claims.
Claims are used to identify the user and potentially determine role membership.
Wazuh establishes the authenticated session.

The OpenID Connect specification identifies the ID token as a JWT containing claims about the authentication event.

Important claims include iss, sub, and aud; other claims can communicate additional identity information.

The nonce claim is also significant because it helps bind an ID token to the authentication request and mitigate replay attacks.

Related Guide: How to Configure Wazuh OIDC

LDAP Authentication Flow

LDAP differs fundamentally from SAML and OIDC.

Instead of exchanging a browser-based federation assertion or OIDC token, Wazuh communicates with an LDAP directory to authenticate and retrieve authorization information.

A simplified flow is:

The user opens the Wazuh Dashboard.
The user provides directory credentials.
Wazuh connects to the configured LDAP server.
The directory validates the credentials.
Wazuh retrieves relevant directory information.
LDAP groups or attributes can be mapped to Wazuh roles.
Wazuh establishes the authenticated session.

Wazuh’s documentation states that LDAP integration can provide both authentication and authorization.

The authc configuration handles authentication, while authz handles authorization and role information.

LDAP can therefore be particularly useful when an organization already operates Active Directory or another LDAP-compatible directory and wants Wazuh to use that directory without introducing a separate SAML or OIDC federation architecture.

Session Management After Authentication

Authentication is only the beginning of a Wazuh SSO login.

After the authentication response has been validated, Wazuh must establish an application session that allows the user to navigate the Dashboard without repeatedly authenticating.

The session effectively represents the authenticated security context.

Several factors affect how this works in practice:

Session lifetime
Authentication timeout
IdP session lifetime
Browser cookies
Token expiration
Logout behavior
Reverse-proxy configuration
Clock synchronization
Authentication errors

This is why users can sometimes encounter symptoms such as an infinite login loop even though the IdP itself reports a successful authentication.

Related Guide: How to Fix Wazuh SSO Login Error

Organizations should also distinguish between authentication session state and authorization state.

A user can have a valid authenticated session but still lack the Wazuh role required to access a particular resource.

Wazuh SSO Authentication Methods

Wazuh environments can use several centralized authentication architectures.

The most important distinction is between SAML, OIDC, and LDAP.

SAML and OIDC are federation-oriented technologies.

LDAP is primarily a directory-access protocol that Wazuh can use for authentication and authorization against an existing directory.

Choosing between them should therefore depend on the organization’s identity architecture rather than simply which protocol is newer.

Wazuh SAML Authentication

SAML 2.0 is an XML-based standard for exchanging authentication, attribute, and authorization information between trusted systems.

OASIS defines SAML as a framework for exchanging security information and provides standardized mechanisms for assertions, protocols, bindings, profiles, and metadata.

For Wazuh, SAML is particularly relevant in enterprise environments where an organization’s identity provider already supports SAML-based application federation.

How SAML Works With Wazuh

Wazuh establishes a trust relationship with the SAML identity provider.

During authentication:

User
  |
  v
Wazuh Dashboard
  |
  | SAML Authentication Request
  v
SAML Identity Provider
  |
  | Authenticate user
  |
  | SAML Response + Assertion
  v
Wazuh
  |
  | Validate assertion
  | Extract attributes
  | Map roles
  v
Authenticated Session

SAML metadata can communicate important federation configuration information, including service endpoints and key material.

This makes metadata and certificates central to many SAML deployments.

SAML Assertions

A SAML assertion is a structured statement made by a trusted authority about a subject.

An assertion can communicate information such as:

The identity of the user
Authentication information
User attributes
Group or organizational information
Authentication timing
Conditions under which the assertion is valid

OASIS defines authentication statements and attribute statements as core types of information that can be carried by SAML assertions.

For Wazuh, the attributes contained within an assertion can become especially important when configuring role mappings.

A successful SAML login therefore does not necessarily mean that the user has the desired Wazuh permissions.

The assertion must contain the expected identity information, and Wazuh must correctly map that information to the appropriate roles.

Metadata and Certificates

SAML metadata provides standardized configuration information that federation participants can use to establish communication and trust.

Certificates are used to validate digitally signed information and establish cryptographic trust between the parties.

Common SAML problems therefore involve:

Incorrect metadata
Expired certificates
Incorrect entity IDs
Incorrect assertion consumer service URLs
Certificate mismatches
Incorrect signing configuration
Clock differences
Incorrect attribute mappings

These issues are especially important because SAML authentication can fail even when the user’s credentials at the IdP are completely valid.

Related Guide: How to Fix Wazuh Certificate Errors

When to Use SAML

SAML is generally a strong choice when:

Your organization already uses SAML extensively.
Your IdP has mature SAML application integration.
Enterprise application federation is based around SAML.
You need standardized assertions and attributes.
Your identity team already manages SAML metadata and certificates.

SAML is particularly common in enterprise and workforce identity environments.

Wazuh OIDC Authentication

OpenID Connect is an authentication protocol built on top of OAuth 2.0.

Unlike OAuth 2.0 alone, OIDC adds an identity layer that enables a client to verify who authenticated and obtain standardized claims about that user.

For modern identity platforms, OIDC is widely used for web applications and APIs.

How OIDC Works With Wazuh

A simplified OIDC architecture is:

User
  |
  v
Wazuh Dashboard
  |
  | Authorization Request
  v
OpenID Provider
  |
  | User Authentication
  |
  | Authorization Code
  v
Wazuh
  |
  | Token Exchange
  v
OpenID Provider
  |
  | ID Token
  | Access Token
  v
Wazuh
  |
  | Validate ID Token
  | Extract Claims
  | Map Roles
  v
Authenticated Session

The OpenID Connect specification describes this general model: the relying party sends an authentication request, the provider authenticates the user, and the provider returns an ID token and typically an access token.

Related Guide: How to Configure Wazuh OIDC

OpenID Connect Discovery

OIDC providers can publish configuration information that allows clients to discover important endpoints and cryptographic information.

Discovery can provide information such as:

Authorization endpoint
Token endpoint
UserInfo endpoint
Issuer
Supported scopes
Supported response types
Signing algorithms
JSON Web Key Set information

This reduces the need to manually configure every endpoint and makes interoperability between clients and identity providers easier.

In practice, administrators should still verify that the discovered issuer, endpoints, redirect URI, and signing keys correspond to the intended Wazuh configuration.

ID Tokens and Claims

The ID token is one of the defining components of OpenID Connect.

The specification defines it as a JWT containing claims about the authentication event. Standard claims include:

iss — identifies the issuer
sub — identifies the subject
aud — identifies the intended audience
exp — identifies the expiration time
iat — identifies when the token was issued
auth_time — can identify when authentication occurred
nonce — binds the token to an authentication request

Claims are important in Wazuh because they can provide identity information used during authentication and authorization.

Incorrect claim configuration can produce a situation where the user successfully authenticates with the IdP but Wazuh cannot correctly identify the user or assign the expected permissions.

When to Use OIDC

OIDC is generally a strong choice when:

Your identity provider has first-class OIDC support.
Your organization prefers modern OAuth 2.0-based identity federation.
You need standardized JWT-based identity tokens.
Your identity architecture already uses OIDC.
You want an authentication protocol well suited to modern web applications.

The OpenID Foundation’s specification describes OIDC as an identity layer over OAuth 2.0 specifically designed to communicate authentication information and claims.

Wazuh LDAP Authentication

LDAP authentication uses a directory service as the source of user authentication and authorization information.

This is different from SAML and OIDC because the Wazuh environment communicates with the directory rather than relying on a federated authentication assertion or OIDC identity token.

Wazuh supports integration with LDAP and Microsoft Active Directory.

Its documentation explains that LDAP can provide both authentication and authorization for Wazuh Dashboard users.

How LDAP Authentication Works

A simplified LDAP authentication flow is:

User
  |
  | Username + Password
  v
Wazuh
  |
  | LDAP bind / directory query
  v
LDAP / Active Directory
  |
  | Authentication result
  | User attributes / groups
  v
Wazuh
  |
  | Group / role mapping
  v
Authenticated Wazuh Session

The directory validates the user’s credentials and can provide information used for authorization.

Wazuh’s LDAP documentation specifically describes separate authentication and authorization configuration and supports mapping LDAP roles to Wazuh roles.

LDAP Servers and Directory Services

LDAP is commonly associated with enterprise directory services such as Microsoft Active Directory.

A Wazuh LDAP deployment may use:

Microsoft Active Directory
OpenLDAP
Other LDAP-compatible directory services

For secure deployments, LDAPS can be used to encrypt communication between Wazuh and the directory server.

Wazuh’s documentation identifies port 389 as the typical LDAP port and 636 as the typical LDAPS port.

LDAP Users and Groups

LDAP becomes particularly useful when users and groups are already centrally maintained.

For example, an organization might have groups such as:

Wazuh-Administrators
Wazuh-Analysts
Wazuh-Responders
Wazuh-Auditors

Those groups can then be mapped to appropriate Wazuh roles.

This means administrators can manage group membership in the directory rather than manually changing every user’s Wazuh permissions.

When to Use LDAP

LDAP is generally appropriate when:

Active Directory is already the organization’s central directory.
Users and groups are managed through LDAP.
Direct directory authentication is preferred.
The organization does not require SAML or OIDC federation.
Existing directory groups need to map directly to Wazuh permissions.

LDAP is particularly attractive for organizations that already have a mature Active Directory infrastructure.

SAML vs OIDC vs LDAP

The three approaches solve related but different identity-management problems.

Feature	SAML	OIDC	LDAP
Primary purpose	Federated authentication	Federated authentication	Directory authentication
Data format	XML	JSON/JWT	LDAP protocol
Identity token/assertion	SAML assertion	ID token	Directory response
Typical architecture	IdP + SP	OP + RP	Directory + client
Enterprise federation	Excellent	Excellent	Limited
Modern web/API integration	Good	Excellent	Limited
Certificate dependence	High	Cryptographic signing keys	TLS certificates when using LDAPS
Group/attribute mapping	Yes	Yes	Yes
Common enterprise use	Workforce SSO	Modern identity platforms	Active Directory
Configuration complexity	Moderate to high	Moderate	Moderate
Best fit	Enterprise SSO federation	Modern identity federation	Existing directory infrastructure

Authentication Architecture

SAML and OIDC are federation protocols.

The identity provider authenticates the user and provides the application with trusted information about that authentication.

LDAP is different. Wazuh connects directly to the directory and uses the directory’s authentication and authorization data.

This distinction affects infrastructure design.

SAML:

Wazuh <---- Federation ----> SAML IdP

OIDC:

Wazuh <---- OIDC / OAuth 2.0 ----> OpenID Provider

LDAP:

Wazuh <---- LDAP / LDAPS ----> Directory

Security Considerations

All three architectures require careful security configuration.

For SAML, administrators should protect and validate metadata, certificates, signatures, audience values, assertion conditions, and endpoints.

For OIDC, administrators should validate issuer, audience, redirect URIs, token signatures, expiration, and other relevant claims.

The OIDC specification specifically requires clients to validate ID tokens and defines security mechanisms such as the nonce claim for binding tokens to authentication requests.

For LDAP, administrators should protect directory communications with TLS where appropriate, use secure service-account credentials, restrict directory access, and validate certificate trust.

Regardless of protocol, role mapping deserves equal attention. Authentication should not automatically imply administrative access.

A user who successfully authenticates should receive only the Wazuh permissions required for their job.

Related Guides:

Configuration Complexity

SAML can require more federation-specific configuration because administrators must coordinate metadata, entity identifiers, endpoints, certificates, assertions, and attribute mappings.

OIDC generally uses a more API-oriented configuration model involving:

Client ID
Client secret where applicable
Issuer
Discovery information
Redirect URI
Scopes
Claims
Signing keys

LDAP configuration focuses more heavily on:

LDAP server connectivity
Bind credentials
Distinguished Names
User search bases
Group search bases
LDAP attributes
TLS/LDAPS
Role mappings

The complexity therefore depends heavily on the organization’s existing identity infrastructure.

Identity-Provider Compatibility

Compatibility is another major factor.

Wazuh’s current documentation provides dedicated SSO integration guides for several identity providers, including Okta, Microsoft Entra ID, Google Workspace, Keycloak, PingOne, JumpCloud, OneLogin, and authentik.

The best protocol is usually the one that aligns with the identity provider already deployed by the organization.

Enterprise Use Cases

Different environments tend to favor different approaches.

Large enterprise with an established SAML IdP

SAML is often appropriate when the organization’s identity team already manages enterprise applications through SAML federation.

Modern cloud identity environment

OIDC can be a strong choice when the organization’s identity infrastructure is built around OAuth 2.0 and OpenID Connect.

Microsoft Active Directory environment

LDAP can be appropriate when Wazuh needs to authenticate directly against an existing directory and use directory groups for authorization.

Hybrid identity environment

An organization can also use different identity mechanisms for different purposes.

For example, SSO can handle workforce authentication while LDAP remains relevant for other directory-dependent services.

The key is to design the authentication architecture around the organization’s identity lifecycle, security requirements, role model, and existing infrastructure rather than selecting a protocol in isolation.

For Wazuh specifically, understanding this distinction makes the rest of an SSO deployment much easier to troubleshoot: SAML validates assertions, OIDC validates tokens and claims, while LDAP validates directory credentials and retrieves directory-based authorization information.

That foundation also makes role mapping, provider-specific configuration, and SSO troubleshooting considerably easier to understand.

Wazuh SSO Prerequisites

Before configuring Wazuh SSO, verify that the Wazuh deployment, identity provider, network, certificates, and user directory are ready for integration.

Most SSO failures are not caused by the authentication protocol itself.

They result from mismatched URLs, incorrect certificates, missing attributes, DNS problems, or incompatible configuration between Wazuh and the identity provider.

Wazuh Version Compatibility

Start by confirming the exact Wazuh version running in your environment.

SSO capabilities, configuration parameters, supported identity providers, and security-plugin behavior can change between Wazuh releases.

Avoid copying authentication settings from an older Wazuh deployment without checking the documentation for your installed version.

Check the installed Wazuh components and make sure the versions of the Dashboard, Indexer, and Manager are compatible with one another.

A useful starting point is the official Wazuh user administration documentation: Wazuh User Administration Documentation

If you are upgrading an existing environment before implementing SSO, take a configuration backup first.

Authentication changes can affect Dashboard access, role mappings, and administrative accounts.

Wazuh Dashboard Requirements

The Wazuh Dashboard is the primary user-facing component involved in web authentication.

Before enabling SSO, verify that:

The Wazuh Dashboard is installed and operational.
Users can access the Dashboard normally.
The Dashboard can communicate with the Wazuh Indexer.
The Dashboard’s hostname resolves correctly.
The configured HTTPS URL matches the hostname users will actually use.
Reverse proxies are forwarding the required authentication traffic correctly.
Firewall rules allow communication between required components.
The Dashboard certificate is valid and trusted by clients.

Do not introduce SSO while the Dashboard itself is already experiencing connectivity or certificate problems.

Resolve those issues first.

Identity Provider Requirements

Your identity provider must support the authentication protocol you intend to use.

Depending on your architecture, this may be:

SAML 2.0
OpenID Connect
LDAP/Active Directory

For SAML and OIDC, you generally need administrative access to create and configure an application or client representing Wazuh.

The IdP configuration may require values such as:

Application name
Client ID
Client secret
Entity ID
Redirect URI
Assertion Consumer Service URL
Sign-on URL
Logout URL
Issuer URL
Group or role claims
User attributes
Signing certificates

The exact values depend on the authentication protocol and identity provider.

Wazuh provides provider-specific documentation for several identity platforms.

DNS and Network Connectivity

DNS must work consistently across the Wazuh environment, identity provider, and users.

At minimum, verify that:

The Wazuh Dashboard hostname resolves correctly.
The IdP hostname resolves from the Wazuh environment where required.
Users can resolve and reach the Wazuh Dashboard.
Required firewall ports are open.
Proxies are configured correctly.
NAT does not alter authentication callback URLs unexpectedly.
Reverse proxies preserve the required HTTP headers.
The configured hostname matches the hostname presented to users.

SSO redirects are particularly sensitive to incorrect hostnames.

For example, suppose users access Wazuh through:

https://wazuh.example.com

but the identity provider is configured to redirect users to:

https://wazuh-internal.example.local

The authentication process may fail even though both addresses point to the same server.

The externally accessible URL should therefore be treated as a critical part of the SSO configuration.

TLS Certificates

Use properly configured TLS certificates throughout the authentication architecture.

For the Wazuh Dashboard, verify:

Certificate validity
Certificate expiration date
Subject Alternative Names (SANs)
Certificate chain
Trusted CA
Hostname matching
Private-key permissions

For SAML, certificates may also be required to validate digitally signed authentication information.

Wazuh must be able to validate the identity provider’s signing keys and establish trusted HTTPS communication with the provider. for OIDC.

For LDAP, LDAPS requires appropriate certificate validation between Wazuh and the directory service.

A certificate that works in a browser does not automatically mean every component in the Wazuh environment trusts the same CA chain.

Related Guide: How to Fix Wazuh Certificate Errors

Time Synchronization

Accurate system time is critical for SSO.

SAML assertions and OIDC tokens contain time-related information that can affect whether authentication information is considered valid.

Check the system time on:

Wazuh Manager nodes
Wazuh Indexer nodes
Wazuh Dashboard nodes
Identity-provider infrastructure where applicable
LDAP servers wher
e applicable

Use a reliable NTP configuration and verify that the systems are synchronized.

Time drift can produce confusing errors such as:

Expired assertion
Assertion not yet valid
Invalid token
Authentication timeout
Session failures
Repeated login redirects

If SSO authentication suddenly starts failing after working previously, checking system time should be part of the initial troubleshooting process.

Related Guide: How to Fix Wazuh SSO Login Error

Required User and Group Attributes

Before configuring role mapping, identify exactly which user attributes and groups Wazuh will receive from the identity provider.

Common identity attributes include:

Username
Email address
First name
Last name
Subject identifier
Group membership
Roles

For example, your identity provider might return:

username = alice
email = alice@example.com
groups = Wazuh-Analysts

Wazuh can then use the relevant identity information to determine which roles should be assigned.

Do not assume that every IdP calls the same attribute by the same name. One provider might return:

groups

while another uses a custom claim or attribute.

This becomes especially important when implementing group-to-role mappings.

Related Guide: How to Configure Wazuh SSO Role Mapping

Backup and Recovery Considerations

Create a backup of the relevant Wazuh configuration before changing authentication settings.

At minimum, document:

Current authentication configuration
Existing users
Existing roles
Role mappings
Certificates
Trusted CA certificates
Identity-provider configuration
Dashboard configuration
Reverse-proxy configuration
DNS records
SSO application/client settings

Maintain at least one tested administrative recovery path.

This is particularly important when modifying the authentication mechanism used by administrators.

A configuration mistake can potentially prevent normal Dashboard access.

If your environment uses custom RBAC configuration, include that configuration in your backup and disaster-recovery procedures.

Related Guide: How to Backup Wazuh RBAC Configurations

How to Configure Wazuh SSO

Wazuh SSO configuration should be performed in a controlled sequence.

Configure the identity provider and Wazuh so that both sides agree on the protocol, endpoints, certificates, user attributes, and authorization mappings.

The exact configuration syntax depends on the Wazuh version and authentication method, so use the current Wazuh documentation alongside your deployment.

Prepare Wazuh

Before changing authentication settings, verify that the existing Wazuh environment is healthy.

Check the Dashboard, Indexer, and Manager services and confirm that users can currently access the Dashboard.

Also record the current configuration so that you can roll back if necessary.

Confirm:

Wazuh components are healthy.
The Dashboard is reachable over HTTPS.
DNS resolves correctly.
Certificates are valid.
System clocks are synchronized.
Required firewall rules are in place.
Configuration backups exist.
An administrative recovery method is available.

Do not make several unrelated configuration changes simultaneously.

If authentication fails afterward, isolating the cause becomes substantially more difficult.

Choose an Authentication Method

Select the authentication mechanism based on your existing identity infrastructure.

Use SAML when your organization already relies heavily on SAML-based enterprise federation.

OIDC should be used when your identity platform is based around modern OAuth 2.0/OpenID Connect authentication.

Use LDAP when Wazuh needs to authenticate users directly against an existing LDAP or Active Directory directory.

For example:

Environment	Recommended starting point
Enterprise SAML infrastructure	SAML
Modern OIDC identity platform	OIDC
Existing Active Directory directory	LDAP
Keycloak deployment	SAML or OIDC
Centralized cloud identity platform	OIDC or SAML
Existing LDAP directory	LDAP

Do not select a protocol solely because it is newer.

The identity provider’s capabilities, existing security policies, and operational requirements should drive the decision.

Related Guides:

Configure the Identity Provider

Create the Wazuh application, relying-party configuration, or client in the identity provider.

The configuration depends on the selected protocol.

1. For SAML, configure items such as:

Entity ID
Assertion Consumer Service URL
Sign-on URL
Logout configuration
Signing requirements
User attributes
Gro
up attributes

2. For OIDC, configure items such as:

- - - Client ID
    - Client secret, if applicable
    - Redirect URI
    - Issuer

3. For LDAP, configure the directory connection and identify:

LDAP server
Port
Bind account
User search base
Group search base
User attributes
Group attributes
TLS settings

The values must correspond exactly with the Wazuh configuration.

Configure Wazuh Dashboard

Next, configure the Wazuh environment to use the selected authentication mechanism.

The Dashboard’s authentication configuration must correspond with the identity provider’s application or client configuration.

Pay particular attention to URLs.

For example, if the IdP expects:

https://wazuh.example.com/auth/callback

but Wazuh is configured to use a different callback location, the authentication transaction can fail.

The same principle applies to:

Entity IDs
Issuer values
Client IDs
Certificates
Redirect URIs
Authentication endpoints
Logout endpoints
Attribute names

Configure Authentication Settings

Configure the authentication settings appropriate to the selected method.

At this stage, define how Wazuh should:

Identify users
Validate authentication responses
Retrieve identity attributes
Process group membership
Map identities to roles
Establish authenticated sessions

Keep authentication and authorization logically separate.

First confirm that Wazuh can identify the user successfully. Then verify that the user receives the correct permissions.

This makes troubleshooting considerably easier.

Related Guide: How to Configure Wazuh RBAC

Configure Certificates and Trusted CAs

Install and configure the certificates and trusted CA material required by the authentication architecture.

For example, an SSO deployment may need to trust:

Corporate Root CA
      |
      +--- Intermediate CA
               |
               +--- Identity Provider Certificate

Verify the complete certificate chain rather than only the leaf certificate.

For SAML, confirm that the certificate used to validate signed assertions corresponds to the certificate configured by the identity provider.

For OIDC, confirm that Wazuh can retrieve and validate the provider’s signing keys and communicate with the provider over trusted HTTPS.

Verify the CA used to validate the LDAPS server certificate for LDAP.

Restart Required Wazuh Services

Some authentication configuration changes require Wazuh services to be restarted before they become active.

The exact services and restart procedure depend on the Wazuh version and the component whose configuration was changed.

Before restarting production services:

Validate the configuration syntax where supported.
Confirm that your configuration backup exists.
Schedule the change if required by your organization’s change-management process.
Restart only the necessary components.
Monitor service status immediately afterward.
Check logs for authentication or configuration errors.

Avoid blindly restarting every Wazuh component. Restart only the services required by the configuration change.

Verify the Configuration

Before testing with a production administrator account, verify the configuration from both sides.

Check the Wazuh side for:

- - Authentication configuration
  - Certificate paths
  - Trusted CAs
  - Role mappings
  - Service status
  - Authentication logs

Check the IdP side for:

Application/client configuration
Redirect URIs
Entity IDs
Claims
Group assignments
Signing certificates
Authentication events

A useful troubleshooting strategy is to determine the exact point where the transaction fails.

For example:

Browser
   |
   v
Wazuh Dashboard
   |
   v
Identity Provider
   |
   v
Authentication succeeds?
   |
   +---- No ----> Troubleshoot IdP
   |
   +---- Yes
          |
          v
Wazuh validates response?
          |
          +---- No ----> Troubleshoot SAML/OIDC validation
          |
          +---- Yes
                 |
                 v
Correct Wazuh role?
                 |
                 +---- No ----> Troubleshoot role mapping
                 |
                 +---- Yes
                        |
                        v
                  Dashboard access

Test SSO Login

Use a dedicated test account before rolling SSO out to every Wazuh user.

The test should verify:

Initial Dashboard access
IdP redirection
User authentication
MFA, if configured
Return to Wazuh
User identification
Role assignment
Dashboard access
Logout behavior
Reauthentication

Test both a normal user and an administrative user if your role model requires different permissions.

Also test an account that should not receive administrative privileges.

This validates that your role mappings enforce least privilege rather than merely proving that authentication works.

How to Configure Wazuh SSO

If you need the complete implementation procedure, including the detailed Wazuh configuration, identity-provider setup, authentication settings, testing, and troubleshooting, continue with our dedicated guide:

How to Configure Wazuh SSO

That guide provides the step-by-step configuration procedure, while this pillar guide focuses on the broader Wazuh SSO architecture, authentication methods, prerequisites, and enterprise design considerations.

How to Configure Wazuh SAML Authentication

SAML is one of the most common federation technologies used for enterprise Single Sign-On.

In a Wazuh deployment, the SAML identity provider authenticates the user and returns a signed SAML response that Wazuh validates before establishing the user’s session.

The configuration must be consistent on both sides of the federation relationship.

SAML Configuration Overview

A Wazuh SAML deployment generally involves four major areas:

Wazuh Dashboard configuration
Identity provider configuration
SAML metadata
Certificates and trust
User and group attributes
Wazuh role mappings

The overall architecture looks like this:

                   +-------------------+
                   |   SAML Identity   |
                   |      Provider     |
                   +---------+---------+
                             |
                    Signed SAML Response
                             |
                             v
+--------+          +-------------------+
|  User  | -------> | Wazuh Dashboard  |
+--------+          +---------+---------+
                              |
                              v
                       Wazuh Security
                              |
                              v
                         Role Mapping

Configure Wazuh as a SAML Service Provider

The Wazuh side must be configured to participate in the SAML federation.

The configuration normally identifies the Wazuh service-provider information and defines how SAML responses should be processed.

Important values include:

Service Provider Entity ID
Assertion Consumer Service URL
Identity Provider Entity ID
Identity Provider SSO URL
Identity Provider certificate
Attribute mappings
Role mappings

The values must match what has been configured in the identity provider.

If the IdP expects a specific entity ID or callback URL, use exactly that value in the Wazuh configuration.

Configure the Identity Provider

Create a SAML application representing Wazuh within the identity provider.

The application configuration normally includes:

Entity ID
Reply URL / Assertion Consumer Service URL
Sign-on URL
Name ID format
User attributes
Group attributes
Assertion-signing settings

Assign the appropriate users or groups to the application.

For example:

Wazuh-Administrators
        |
        +---- Wazuh application
        |
        +---- Wazuh administrative role

Wazuh-Analysts
        |
        +---- Wazuh application
        |
        +---- Wazuh analyst role

The IdP should not automatically grant every user access to Wazuh unless that is explicitly intended.

Configure SAML Metadata

SAML metadata allows federation participants to exchange standardized configuration information.

Depending on the identity provider, you may receive metadata containing information such as:

Entity ID
SSO endpoints
Logout endpoints
Certificates
Supported bindings

Use the metadata supplied by the identity provider rather than manually guessing these values.

After importing or configuring metadata, verify that the entity identifiers and endpoints correspond to the intended Wazuh deployment.

Configure Certificates

SAML relies heavily on cryptographic trust.

Configure the certificate required to validate the identity provider’s signed assertions and ensure that Wazuh trusts the appropriate certificate authority.

Check:

Certificate validity
Expiration date
Issuer
Subject
Certificate chain
Signature algorithm
Key compatibility
File permissions

If the identity provider rotates its signing certificate, update the Wazuh configuration accordingly.

Certificate rotation should be treated as an operational procedure rather than an emergency fix.

Document the expected certificate lifecycle and monitor expiration dates.

Related Guide: How to Fix Wazuh Certificate Errors

Configure User Attributes

Determine which attributes the IdP will send in the SAML assertion.

Common attributes include:

username
email
firstName
lastName
groups
roles

The exact names vary between identity providers.

For example, the IdP might return:

NameID = alice@example.com
groups = Wazuh-Analysts

Wazuh then needs to know which attribute identifies the user and which attribute contains group membership.

Incorrect attribute names are a common reason why authentication appears successful but role assignment fails.

Test SAML Authentication

After configuring both sides, test the complete authentication flow.

Verify:

Wazuh redirects to the IdP.
The user authenticates successfully.
The IdP generates a SAML response.
The browser returns the response to Wazuh.
Wazuh validates the assertion.
Wazuh identifies the user.
Wazuh maps the user to the expected role.
The Dashboard establishes a session.
The user can access the expected resources.

Use browser developer tools and identity-provider audit logs when necessary to identify where the transaction stops.

Do not expose SAML responses containing sensitive identity information in public troubleshooting forums or screenshots.

Troubleshoot Common SAML Issues

Common Wazuh SAML problems include:

Invalid SAML assertion

Often caused by an invalid signature, incorrect certificate, malformed assertion, or mismatched configuration.

Incorrect entity ID

The entity ID configured in Wazuh and the identity provider must correspond.

Incorrect Assertion Consumer Service URL

The IdP must send the SAML response to the URL expected by Wazuh.

Certificate validation failure

Check the certificate, CA chain, expiration date, and signing configuration.

User authenticates but receives incorrect permissions

Check the SAML attributes and Wazuh role mappings.

Infinite login loop

Check callback URLs, session cookies, reverse-proxy configuration, authentication settings, and system time.

Assertion expired

Verify time synchronization across the participating systems.

Missing group information

Confirm that the identity provider is configured to include the required group or role attribute in the SAML assertion.

Related Guide: How to Fix Wazuh SSO Login Error

How to Configure Wazuh SAML Authentication

For the complete implementation, including the exact SAML configuration workflow, identity-provider setup, metadata, certificates, attributes, role mapping, testing, and troubleshooting, see our dedicated guide:

How to Configure Wazuh SAML Authentication

That cluster article provides the detailed step-by-step SAML implementation, while this pillar page connects SAML to the larger Wazuh SSO architecture and explains when and why to use each authentication method.

How to Configure Wazuh OIDC

OpenID Connect provides another way to implement Wazuh SSO.

Unlike SAML, which uses XML-based assertions, OIDC uses the OAuth 2.0 framework and JSON Web Tokens (JWTs) to communicate identity information.

The general OIDC architecture consists of Wazuh acting as the relying-party application and an OpenID Provider handling user authentication.

OIDC Configuration Overview

A Wazuh OIDC deployment typically requires:

An OIDC application/client at the identity provider
Client ID
Client secret where required
Issuer
Authorization endpoint
Token endpoint
Redirect URI
Scopes
Claims
Signing-key configuration
Wazuh authentication settings
Role mappings

The basic flow is:

User
  |
  v
Wazuh Dashboard
  |
  | Authorization Request
  v
OpenID Provider
  |
  | Authenticate user
  |
  | Authorization Code
  v
Wazuh
  |
  | Token Exchange
  v
OpenID Provider
  |
  | ID Token
  | Access Token
  v
Wazuh
  |
  | Validate token
  | Extract claims
  | Map roles
  v
Authenticated Session

OIDC’s standardized identity layer is defined by the OpenID Foundation.

Create an OIDC Application

Start by creating an OIDC application or client in your identity provider.

The exact interface varies by provider, but you will generally select a web application or equivalent client type.

Record the values generated by the IdP, especially:

Client ID
Client secret
Issuer
Authorization endpoint
Token endpoint
UserInfo endpoint, if applicable
JWKS endpoint
Redirect URI

The client should be restricted to the intended Wazuh users or groups.

Do not expose the client secret in browser-side code, public repositories, screenshots, or documentation.

Configure Client ID and Secret

The client ID identifies the Wazuh application to the OIDC provider.

The client secret, where used, authenticates the confidential client to the provider.

Store the client secret securely.

A common configuration mistake is using the client ID from one OIDC application together with the client secret from another.

These values belong to the same client registration and should always be verified together.

If the secret is rotated, update the Wazuh configuration accordingly.

Configure Redirect URIs

The redirect URI is one of the most important OIDC settings.

After authentication, the identity provider sends the authorization response back to the registered redirect URI.

The URI configured at the IdP must match the URI expected by Wazuh.

For example:

https://wazuh.example.com/<configured-callback>

Do not assume that the following are interchangeable:

https://wazuh.example.com/callback
https://wazuh.example.com/callback/
https://wazuh-internal.example.com/callback
http://wazuh.example.com/callback

Differences in hostname, scheme, path, or trailing slash can cause an OIDC provider to reject the request.

If Wazuh is behind Nginx or another reverse proxy, make sure the externally visible URL is consistent throughout the configuration.

Configure Scopes and Claims

OIDC uses scopes to request particular categories of information.

Common scopes include:

openid
profile
email

The openid scope is fundamental to an OIDC authentication request.

Claims provide identity information about the user.

Common claims include:

sub
iss
aud
email
name
preferred_username
Group or role claims

The exact claims available depend on the identity provider.

For Wazuh role mapping, make sure the IdP sends the group or role information required by your authorization model.

For example:

preferred_username = alice
email             = alice@example.com
groups            = ["Wazuh-Analysts"]

Wazuh can then use the appropriate claim when determining authorization.

Configure Wazuh

Configure Wazuh with the OIDC information supplied by the identity provider.

Depending on the deployment and Wazuh version, this can involve settings associated with:

OpenID provider
Issuer
Client ID
Client secret
Redirect URI
Scopes
User claims
Group claims
Role mappings
Trusted certificates

Verify every value against the IdP configuration.

For providers that support OIDC discovery, verify that the issuer and discovered endpoints are correct.

The OIDC provider’s signing keys must also be available so that Wazuh can validate signed ID tokens.

Test OIDC Authentication

Perform a controlled test with a dedicated account.

Verify:

Wazuh redirects to the correct provider.
The provider displays the expected authentication page.
The test user authenticates successfully.
The provider returns the authorization response.
Wazuh exchanges the authorization code successfully.
Wazuh validates the ID token.
The expected user identity is extracted.
The expected role is assigned.
The Dashboard becomes accessible.
Logout and reauthentication work correctly.

If MFA is configured at the IdP, test it as part of the complete authentication flow.

Troubleshoot Common OIDC Issues

Common OIDC problems include:

Invalid client

Verify the client ID and client secret.

Redirect URI mismatch

Compare the redirect URI in Wazuh with the exact URI registered at the IdP.

Invalid issuer

Make sure the configured issuer corresponds to the intended OIDC provider.

Invalid audience

The ID token’s audience must correspond to the intended client.

Expired ID token

Check token lifetime and system time.

Invalid signature

Verify that Wazuh can retrieve and trust the identity provider’s signing keys.

Missing claims

Check the scopes and claim configuration at the IdP.

User authenticates but receives the wrong Wazuh role

Inspect group/role claims and Wazuh role mappings.

Infinite authentication redirect

Check redirect URIs, proxy configuration, browser cookies, session configuration, and system clocks.

Related Guide: How to Fix Wazuh SSO Login Error

If you want the complete OIDC implementation, including client registration, redirect URI configuration, scopes, claims, Wazuh configuration, testing, and troubleshooting, continue with our dedicated guide.

Related Guide: How to Configure Wazuh OIDC

How to Configure Wazuh LDAP Authentication

LDAP authentication is a different architecture from SAML and OIDC.

Instead of redirecting the user to a federated identity provider and receiving an assertion or token, Wazuh communicates with an LDAP-compatible directory.

This makes LDAP particularly useful for organizations that already use Active Directory or another centralized directory service.

LDAP Authentication Architecture

A typical Wazuh LDAP architecture looks like this:

+--------+
|  User  |
+----+---+
     |
     | Username + Password
     v
+----------------+
| Wazuh Dashboard|
+-------+--------+
        |
        | LDAP / LDAPS
        v
+-----------------------+
| LDAP / Active Directory|
+-----------+-----------+
            |
            | User / Group Information
            v
+-----------------------+
| Wazuh Authorization   |
| and Role Mapping      |
+-----------------------+

The directory performs authentication, while Wazuh uses directory information to determine authorization.

Wazuh documents LDAP integration as supporting both authentication and authorization.

Configure the LDAP Server

Before changing Wazuh, identify the LDAP directory information required for the integration.

Document:

LDAP server hostname
LDAP port
LDAP protocol
Base DN
User search base
Group search base
Bind DN
Bind password
User attribute
Group attribute
Group membership attribute
TLS configuration

For an Active Directory environment, you may also need to determine the appropriate directory structure and group membership attributes.

For example:

dc=example,dc=com
    |
    +-- ou=Users
    |
    +-- ou=Groups

The exact directory structure varies by organization.

Configure LDAP Connectivity

Wazuh must be able to communicate with the LDAP server.

Verify:

DNS resolution
Network routing
Firewall rules
LDAP/LDAPS port availability
TLS connectivity
Bind-account credentials
Certificate trust

Typical LDAP deployments use port 389, while LDAPS commonly uses port 636.

A connectivity problem should be resolved before troubleshooting user authentication.

For example, if Wazuh cannot establish a TCP connection to the directory, changing the LDAP user search filter will not solve the problem.

Configure User Search

Wazuh needs to know where and how to find users in the directory.

This typically involves:

User base DN
User search filter
Username attribute
Bind account
Search scope

For example, the directory might contain:

uid=alice,ou=Users,dc=example,dc=com

or an Active Directory-style distinguished name.

The search configuration must match the actual directory structure.

A common mistake is using the correct LDAP server but searching the wrong organizational unit.

Configure Group Search

Group information is important when Wazuh permissions are managed through directory groups.

For example:

Wazuh-Administrators
Wazuh-Analysts
Wazuh-Auditors

The LDAP configuration must be able to locate the relevant groups and determine group membership.

You can then map directory groups to Wazuh roles.

For example:

LDAP Group              Wazuh Role
-----------             ----------
Wazuh-Administrators -> administrator
Wazuh-Analysts       -> analyst
Wazuh-Auditors       -> read-only

The exact Wazuh roles and mappings should reflect your organization’s least-privilege model.

Related Guide: How to Configure Wazuh SSO Role Mapping

Configure TLS

Whenever credentials are transmitted to an LDAP service, protect the connection appropriately.

LDAPS encrypts LDAP communication using TLS. StartTLS is another approach supported by LDAP implementations.

Verify:

Correct CA certificate
Certificate chain
Hostname validation
Certificate expiration
TLS protocol compatibility
LDAP server certificate
Wazuh trust configuration

Do not disable certificate validation simply to make an LDAP connection work.

If certificate validation fails, identify and correct the trust-chain or hostname problem instead.

Related Guide: How to Fix Wazuh Certificate Errors

Test LDAP Authentication

Test LDAP authentication with a dedicated directory account.

Verify:

Wazuh can reach the LDAP server.
The bind account works.
Wazuh can locate the test user.
The user’s credentials are accepted.
Group membership is detected.
The expected Wazuh role is assigned.
The user can access the appropriate Dashboard resources.
Logout and reauthentication work.

Test multiple directory groups if your authorization model depends on them.

For example:

Test User 1 -> Wazuh-Administrators
Test User 2 -> Wazuh-Analysts
Test User 3 -> Wazuh-Auditors

This confirms that both authentication and authorization are working.

Troubleshoot LDAP Connection and Authentication Problems

Common LDAP failures include:

Connection refused

Check the LDAP server address, port, firewall, and network connectivity.

DNS resolution failure

Verify that the Wazuh host can resolve the LDAP hostname.

Invalid bind credentials

Check the bind DN and password.

User not found

Verify the user search base, search filter, and username attribute.

Group not found

Verify the group search base and group membership configuration.

Authentication succeeds but authorization fails

Check group-to-role mappings.

TLS certificate failure

Verify the CA chain, server certificate, hostname, and certificate expiration.

LDAP timeout

Check network latency, firewall rules, routing, and LDAP server availability.

Users can authenticate but cannot access expected Dashboard features

The authentication layer is probably working, but the Wazuh authorization or role-mapping configuration needs to be reviewed.

Related Guides:

For a complete implementation walkthrough, including LDAP connectivity, user and group searches, TLS, authentication testing, and troubleshooting, continue with the dedicated How to Configure Wazuh LDAP Authentication guide.

Wazuh SSO Identity Provider Integrations

Wazuh SSO becomes particularly useful when it is connected to an organization’s existing identity provider.

Instead of creating a completely separate identity system for Wazuh, security teams can integrate the Dashboard with platforms that already manage employee identities, groups, authentication policies, and MFA.

The integration method varies by provider.

Some platforms support both SAML and OIDC, while others may be better suited to one protocol depending on the organization’s existing identity architecture.

The most important principle is to keep the identity-provider configuration and Wazuh configuration synchronized.

The IdP determines who the user is, while Wazuh determines what that user can access.

Keycloak

Keycloak is an open-source identity and access management platform that can act as an identity provider for Wazuh.

It supports both SAML and OpenID Connect, making it particularly flexible for organizations that want to operate their own identity infrastructure.

A Keycloak integration can centralize Wazuh authentication while allowing administrators to manage users, groups, roles, clients, and authentication policies from Keycloak.

Keycloak SSO Architecture

A simplified Keycloak-to-Wazuh architecture looks like this:

                     +----------------+
                     |    Keycloak    |
                     |      IdP       |
                     +-------+--------+
                             |
                   SAML or OIDC
                             |
                             v
+--------+            +-------------+
|  User  | ----------> |    Wazuh    |
| Browser|             |  Dashboard  |
+--------+             +------+------+ 
                               |
                               v
                        Wazuh Indexer
                         Security
                               |
                               v
                         Role Mapping

Keycloak authenticates the user and supplies the identity information required by Wazuh.

The integration can use:

SAML 2.0
OpenID Connect
Keycloak users
Keycloak groups
Keycloak roles
Custom identity attributes

The choice between SAML and OIDC should be based on the organization’s broader identity architecture.

SAML vs OIDC With Keycloak

Keycloak can act as either a SAML identity provider or an OIDC provider.

SAML with Keycloak can be useful when:

The organization already uses SAML applications.
Enterprise federation is standardized around SAML.
Existing Wazuh SAML configuration is preferred.
Identity attributes are already exposed through SAML assertions.

OIDC with Keycloak can be useful when:

The organization uses modern OAuth 2.0/OIDC applications.
JWT-based identity tokens are preferred.
Keycloak is already the organization’s central OIDC provider.
The identity architecture is heavily API and web-application oriented.

Both approaches can provide centralized authentication.

The main differences are the protocols, configuration models, tokens/assertions, and troubleshooting procedures.

Related Guide:

Configure Keycloak for Wazuh

At a high level, configuring Keycloak for Wazuh involves:

Create or select a Keycloak realm.
Create a client representing Wazuh.
Select SAML or OIDC.
Configure the Wazuh endpoint or redirect URI.
Configure client authentication.
Configure user attributes.
Configure groups or roles.
Assign test users.
Configure Wazuh to trust Keycloak.
Test authentication.

For OIDC, the Keycloak client configuration typically includes client identifiers, redirect URIs, scopes, and token-related settings.

For SAML, the configuration involves entity identifiers, endpoints, bindings, certificates, and SAML attributes.

Make sure the hostname users access for Wazuh is the same hostname represented in the relevant redirect or callback configuration.

Map Users and Groups

Keycloak groups can provide a convenient way to organize Wazuh users.

For example:

Wazuh-Administrators
Wazuh-Analysts
Wazuh-Responders
Wazuh-Auditors

These groups can then be exposed through SAML attributes or OIDC claims and mapped to corresponding Wazuh roles.

A typical design might look like:

Keycloak Group           Wazuh Role
---------------          ----------------
Wazuh-Administrators ->  Administrator
Wazuh-Analysts       ->  Analyst
Wazuh-Responders     ->  Responder
Wazuh-Auditors       ->  Read-only

Keep these mappings deliberately narrow. A user should not receive administrative privileges simply because they belong to a broad corporate group.

If you want the complete Keycloak implementation, including the client configuration, protocol selection, user/group mapping, and Wazuh-side configuration, continue with the dedicated Keycloak integration guide.

Okta

Okta can provide centralized authentication for Wazuh through enterprise federation.

Depending on the organization’s architecture and Okta configuration, Wazuh can be integrated using SAML or OIDC.

The basic architecture is:

User
 |
 v
Wazuh Dashboard
 |
 v
Okta
 |
 | Authentication + claims
 v
Wazuh
 |
 v
Role Mapping
 |
 v
Dashboard Access

Configure an Okta Application

Start by creating an application in Okta that represents the Wazuh Dashboard.

The application configuration should correspond to the authentication protocol selected for Wazuh.

For SAML, configure the appropriate:

Single sign-on URL
Audience URI
Name ID
Attribute statements
Group statements
Signing configuration

For OIDC, configure:

Client ID
Client secret
Redirect URI
Grant type
Scopes
Claims

Assign only the users and groups that should be permitted to authenticate to Wazuh.

Configure SAML or OIDC

Choose SAML when your organization already uses Okta for SAML-based enterprise applications or when the Wazuh deployment is designed around SAML.

Choose OIDC when your identity architecture is based on OpenID Connect and your Okta environment is already configured to provide OIDC clients.

Regardless of protocol, verify that the Wazuh and Okta configurations agree on:

URLs
Entity identifiers or issuer
Client/application identifiers
Certificates or signing keys
User attributes
Group information

Configure Claims and Groups

Claims and group information become particularly important when Okta is responsible for supplying Wazuh authorization information.

For example, Okta might return:

username = alice@example.com
groups = ["Wazuh-Analysts"]

Wazuh can use the group information to assign the corresponding role.

Avoid passing unnecessary identity information.

Send the claims required by the authentication and authorization design and avoid exposing unrelated attributes.

Test Okta Authentication

Test the integration with a dedicated Okta user.

Confirm that:

Wazuh redirects the user to Okta.
Okta authenticates the user.
Any configured MFA requirements are enforced.
Okta returns the expected authentication response.
Wazuh validates the response.
The expected user identity is established.
The correct Wazuh role is assigned.
Dashboard access works.
Logout and reauthentication work.

If the user can authenticate with Okta but cannot access expected Wazuh resources, investigate role mapping rather than the primary authentication process.

For the complete Okta implementation, including application creation, SAML/OIDC configuration, claims, groups, and testing, continue with the dedicated integration guide.

Microsoft Entra ID (Azure AD)

Microsoft Entra ID, formerly Azure Active Directory, is widely used as a centralized workforce identity platform.

A Wazuh integration can allow organizations to use existing Entra identities and groups instead of maintaining separate Wazuh credentials.

This is particularly useful when the organization already uses Entra ID for employee authentication and wants Wazuh to participate in the same identity ecosystem.

Create the Wazuh Enterprise Application

Create an enterprise application representing Wazuh in Microsoft Entra ID.

The application should be configured according to the selected protocol and Wazuh deployment architecture.

Depending on the protocol, you may configure:

Identifier
Reply URL
Redirect URI
Sign-on URL
Client ID
Client secret
Claims
Group assignments
Signing certificates

Restrict application assignment to the appropriate users and groups.

For example:

Wazuh-Administrators
Wazuh-SOC-Analysts
Wazuh-Auditors

This gives the identity platform a first layer of access control before Wazuh applies its own role mappings.

Configure SAML or OIDC

Entra ID supports both SAML-based enterprise applications and OAuth 2.0/OpenID Connect-based application authentication.

The appropriate choice depends on your Wazuh configuration and broader identity strategy.

For SAML, ensure that the identifier, reply URL, claims, and certificate configuration correspond to Wazuh.

For OIDC, configure the application registration, client credentials, redirect URI, issuer, scopes, and claims.

Configure Claims

Claims determine what identity information Entra ID sends to Wazuh.

Depending on your configuration, useful information can include:

User principal name
Email
Name
Subject identifier
Group membership
Application roles

When group information is used for Wazuh authorization, make sure the expected groups are actually included in the authentication response or token.

This is an important troubleshooting point because a user can successfully authenticate while receiving no Wazuh role if the expected group claim is missing.

Assign Users and Groups

Assign only the users and groups that should have access to the Wazuh application.

For example:

Entra Group               Wazuh Purpose
------------------        ------------------
Wazuh-Administrators      Administrative access
Wazuh-Analysts            SOC analyst access
Wazuh-Responders          Incident response
Wazuh-Auditors            Audit/read-only access

Use dedicated security groups where possible rather than mapping broad organizational groups directly to privileged Wazuh roles.

Test Authentication

Test at least one account from every important access tier.

Verify:

Entra authentication
MFA
Conditional access, if applicable
Redirect behavior
Wazuh identity recognition
Group claims
Wazuh role mapping
Dashboard permissions
Logout behavior

If authentication succeeds but the user is assigned the wrong role, examine the claims and Wazuh role mappings.

For the complete Entra ID integration process, including enterprise application creation, protocol configuration, claims, group assignment, and testing, continue with the dedicated guide.

Google Workspace

Google Workspace can function as an identity provider for organizations that manage workforce identities through Google’s administrative platform.

A SAML-based integration allows Google Workspace users to authenticate to Wazuh using their existing organizational accounts.

Configure Google as the Identity Provider

Create a custom SAML application in the Google Workspace administration environment.

The Wazuh service-provider configuration must provide the information Google needs to send authentication responses to the correct destination.

Depending on the configuration, you will work with values such as:

ACS URL
Entity ID
Start URL
Name ID
Name ID format
Attribute mappings
Group information

The values must correspond with the Wazuh configuration.

Configure SAML

Configure Google Workspace as the SAML identity provider and Wazuh as the service provider.

The Google configuration generally involves importing or entering the Wazuh service-provider information and configuring the appropriate signing and attribute settings.

Pay particular attention to the ACS URL.

An incorrect ACS URL can result in authentication failures even when the user’s Google credentials are valid.

Configure User Attributes

Configure Google Workspace to provide the attributes Wazuh needs.

Depending on the role-mapping design, these may include:

Email
Username
Name
Groups
Custom attributes

Keep attribute mappings consistent between Google Workspace and Wazuh.

For example:

Google Workspace
       |
       +-- email
       +-- username
       +-- groups
              |
              v
        Wazuh Role Mapping

If groups are used for authorization, make sure the relevant group information is available to the SAML application.

Assign Users

Assign the Wazuh SAML application only to the users who should access Wazuh.

You can organize access through Google Workspace groups.

For example:

Wazuh-Administrators
Wazuh-Analysts
Wazuh-Auditors

This makes access management easier as the organization grows.

Instead of changing individual application permissions repeatedly, administrators can manage group membership and allow the Wazuh role-mapping configuration to determine the corresponding authorization.

Test Wazuh Authentication

Test with a dedicated Google Workspace account.

Verify:

The Wazuh Dashboard opens.
Google Workspace authentication is initiated.
The user authenticates successfully.
Google returns the SAML response.
Wazuh validates the response.
User attributes are recognized.
Group membership is recognized.
The expected Wazuh role is assigned.
Dashboard access works.
Logout and reauthentication work.

If the user authenticates successfully but receives incorrect permissions, focus on SAML attributes and Wazuh role mapping.

For the complete Google Workspace integration procedure, including SAML application creation, attributes, user assignment, and testing, continue with the dedicated guide.

Wazuh SSO Role Mapping

Authentication establishes the user’s identity. Role mapping determines what that authenticated identity can actually do inside Wazuh.

This makes role mapping one of the most important parts of a secure Wazuh SSO deployment.

A well-designed implementation should ensure that users receive the minimum permissions necessary for their responsibilities.

What Wazuh SSO Role Mapping Is

Wazuh SSO role mapping is the process of translating identity information received from an external authentication system into Wazuh roles and permissions.

The identity provider might provide:

User: alice@example.com
Group: Wazuh-Analysts

Wazuh can then use the group information to determine that Alice should receive the analyst role.

Conceptually:

Identity Provider
       |
       | User + Groups / Claims
       v
Wazuh Authentication
       |
       | Role Mapping
       v
Wazuh Role
       |
       | Permissions
       v
Dashboard / Indexer Resources

This creates a clear separation between identity management and application authorization.

How Identity-Provider Groups Map to Wazuh Roles

A common enterprise model is to create dedicated groups in the identity provider.

For example:

Wazuh-Administrators
Wazuh-Analysts
Wazuh-Responders
Wazuh-Auditors

Those groups are then mapped to appropriate Wazuh roles.

This approach provides several advantages:

Centralized user management
Easier onboarding
Easier offboarding
Consistent authorization
Reduced manual account management
Easier auditing

However, avoid creating overly broad mappings.

A group such as All-Employees should generally not map to an administrative Wazuh role.

Mapping SAML Groups

With SAML, group membership is generally passed through SAML attributes.

For example:

groups = Wazuh-Analysts

Wazuh can then map that attribute to an appropriate role.

The important variables are:

Attribute name
Group value
Case sensitivity
Group formatting
Wazuh role mapping
Multiple-group behavior

If a user authenticates successfully but receives no expected permissions, inspect the actual SAML assertion and verify that the expected group information is present.

Mapping OIDC Claims

OIDC uses claims rather than SAML assertions.

A token might contain information such as:

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

The relevant claim must be configured and mapped appropriately.

Be careful with group claims in large organizations.

Some identity providers impose limits on how many groups can be included in a token.

If a user belongs to a large number of groups, the IdP may use a different mechanism to communicate group membership.

Mapping LDAP Groups

LDAP role mapping uses groups from the directory.

For example:

LDAP Group
    |
    +-- Wazuh-Administrators
    +-- Wazuh-Analysts
    +-- Wazuh-Auditors
             |
             v
        Wazuh Roles

This is particularly useful in Active Directory environments where security groups already form the organization’s authorization structure.

The Wazuh LDAP configuration must correctly locate groups and determine user membership.

Administrator Roles

Administrator roles should be assigned sparingly.

An administrative Wazuh role can provide extensive access to configuration, users, roles, security settings, and other sensitive resources.

A dedicated group such as:

Wazuh-Administrators

is generally easier to audit than assigning administrative permissions individually to numerous users.

Where possible, separate day-to-day analyst accounts from privileged administrative accounts.

Analyst Roles

SOC analysts typically require substantial visibility into alerts, events, dashboards, agents, vulnerabilities, and other security information without necessarily requiring complete administrative control.

Create an analyst-specific role that reflects actual operational requirements.

For example:

SOC Analyst
   |
   +-- View alerts
   +-- Investigate events
   +-- View agents
   +-- Access approved dashboards
   +-- Perform permitted investigations

Avoid simply assigning administrator permissions because an analyst needs access to several Dashboard features.

Read-Only and Auditor Roles

Auditors often need visibility without modification privileges.

A read-only design can restrict users from changing:

Rules
Users
Roles
Configuration
Agents
Security settings

This is particularly useful for compliance teams, external auditors, managers, and security reviewers.

A dedicated audit group can therefore map to a read-only Wazuh role.

Least-Privilege Role Mapping

Least privilege should be the default design principle for Wazuh SSO.

A useful model is:

Identity Provider Group
          |
          v
    Wazuh Role
          |
          v
Minimum Required Permissions

Do not start by assigning administrator permissions and removing them later.

Instead:

Identify the user’s job responsibilities.
Identify the Wazuh resources they need.
Create or select the narrowest suitable role.
Map the identity-provider group to that role.
Test the user’s access.
Add permissions only when a legitimate requirement exists.

This reduces the potential impact of compromised credentials.

Related Guide: How to Configure Wazuh RBAC

Troubleshoot Users Who Authenticate but Cannot Access Wazuh

A successful SSO login followed by an authorization error usually indicates that authentication and authorization should be investigated separately.

Check the following:

1. Confirm that authentication succeeded

Verify that the IdP reports a successful authentication.

2. Verify the user identity

Make sure Wazuh is receiving the expected username, email, subject, or other identity identifier.

3. Inspect groups or claims

Confirm that the expected group or role information is actually being returned.

4. Check role mappings

Compare the received group/claim value with the configured Wazuh mapping.

5. Check role permissions

The user may have received a valid Wazuh role that simply does not contain the required permission.

6. Check multi-tenancy

If the user can log in but cannot see expected data, verify that the assigned roles and tenants provide access to the relevant resources.

7. Check capitalization and exact values

Group and role mappings can be sensitive to exact attribute values. Check spelling, capitalization, prefixes, and formatting.

8. Test with a known-good account

A second account can help determine whether the issue is global or specific to a user’s group membership.

9. Review Wazuh logs

Authentication and authorization logs can help establish whether the problem occurred during identity validation or role assignment.

If you need a detailed implementation of SAML and OIDC group-to-role mappings, including how to structure identity-provider groups and troubleshoot users who authenticate but receive the wrong permissions, continue with the dedicated guide.

Wazuh SSO and Access Control

Wazuh SSO should be designed as part of the organization’s broader access-control architecture rather than treated as an isolated login feature.

SSO determines how users authenticate. Wazuh RBAC, roles, permissions, and multi-tenancy determine what authenticated users can access.

Authentication vs Authorization

Authorization and authentication answer different questions.

Authentication asks:

Who are you?

Authorization asks:

What are you allowed to do?

For example:

Microsoft Entra ID
       |
       | Authenticates Alice
       v
Wazuh
       |
       | Alice belongs to Wazuh-Analysts
       v
Wazuh Analyst Role
       |
       v
Approved Wazuh Resources

Alice’s successful authentication does not automatically make her a Wazuh administrator.

This distinction should remain central to your SSO architecture.

Wazuh RBAC

Role-Based Access Control (RBAC) allows permissions to be assigned through roles rather than individually configuring every user.

In an SSO environment, identity-provider groups can become the bridge between centralized identity management and Wazuh RBAC.

For example:

IdP Group
   |
   v
Wazuh Role
   |
   v
Permissions

This makes access easier to manage as users join, leave, or change responsibilities.

Related Guide: How to Configure Wazuh RBAC

Role-Based Permissions

Design roles around actual job functions.

Common roles might include:

Wazuh administrators
SOC analysts
Incident responders
Security auditors
Read-only users

Each role should have only the permissions necessary to perform its assigned responsibilities.

For example, an analyst might need to investigate alerts but not modify authentication configuration.

An administrator might require access to configuration and user management.

An auditor might require visibility into security data without modification privileges.

Multi-Tenancy

Multi-tenancy provides another layer of access control by separating data and resources between logical tenants.

This can be useful for:

- - Managed security service providers
  - Large enterprises
  - Multiple business units
  - Separate security teams
<l

i>Environments requiring data isolation

SSO and multi-tenancy solve different problems.

SSO determines who the user is.

Multi-tenancy can help determine which data or environment the user can access.

Role mapping can connect the two concepts when identity-provider groups are used to assign users to appropriate roles and tenants.

Related Guides:

Restricting Administrative Access

Administrative access should be tightly controlled.

Use dedicated identity-provider groups for privileged Wazuh administrators rather than mapping broad groups to administrative roles.

Additional controls can include:

MFA
Conditional access
Privileged identity management
Dedicated administrator accounts
Network restrictions
Administrative access logging
Regular access reviews

The identity provider should enforce strong authentication, while Wazuh should enforce appropriate authorization.

Related Guide: How to Configure a Wazuh IP Whitelist

Applying Least Privilege

Least privilege means giving each user or service only the access required to perform its intended function.

For Wazuh SSO, implement least privilege at several levels:

Identity
   |
   +-- Who can authenticate?
          |
          v
Group Assignment
   |
   +-- Which users receive Wazuh access?
          |
          v
Role Mapping
   |
   +-- Which Wazuh role?
          |
          v
Permissions
   |
   +-- What can the role do?
          |
          v
Tenant / Data Access
   |
   +-- Which resources are visible?

This layered approach is considerably stronger than relying on authentication alone.

Separating Administrators, Analysts, Responders, and Auditors

A mature Wazuh deployment should distinguish between different SOC responsibilities.

Administrators

Administrators manage Wazuh infrastructure, configuration, users, roles, and security settings.

Analysts

Analysts investigate alerts, events, agents, vulnerabilities, and security telemetry.

Responders

Responders require the permissions necessary to investigate and respond to security incidents, including approved response capabilities.

Auditors

Auditors generally require visibility into relevant security information without broad modification privileges.

A practical identity-provider structure might therefore look like:

Wazuh-Administrators
        |
        v
Wazuh Administrator Role

Wazuh-Analysts
        |
        v
Wazuh Analyst Role

Wazuh-Responders
        |
        v
Wazuh Responder Role

Wazuh-Auditors
        |
        v
Wazuh Read-Only / Auditor Role

This structure makes the relationship between identity, authentication, authorization, and operational responsibility explicit.

It also makes future access reviews easier because administrators can determine why a user has a particular Wazuh role by examining the identity-provider group that granted it.

How to Test Wazuh SSO

Testing Wazuh SSO should cover more than simply confirming that a user can log in.

A complete validation should verify the entire authentication and authorization chain, from the identity provider through the Wazuh Dashboard and into the user’s assigned roles and permissions.

A useful testing sequence is:

Identity Provider

Authentication

Wazuh Dashboard

User Attributes / Claims

Group Membership

Wazuh Role Mapping

Permissions / Tenant Access

Logout

Testing each layer separately makes it much easier to determine where an SSO problem originates.

Test IdP Authentication

Start by confirming that the identity provider can authenticate the test account independently.

Depending on your IdP, verify:

Username and password
MFA
Conditional access policies
Account status
Application assignment
Group membership
Authentication policy
Sign-in restrictions

If the user cannot authenticate directly with the identity provider, troubleshoot the IdP before investigating Wazuh.

For example, an account that has not been assigned to the Wazuh application may never reach the Wazuh authentication flow.

Test Wazuh Dashboard Login

Open the Wazuh Dashboard and initiate SSO.

Verify that:

Wazuh displays or initiates the SSO login.
The browser is redirected to the expected IdP.
The IdP displays the correct authentication page.
The test user successfully authenticates.
The IdP redirects the browser back to Wazuh.
Wazuh accepts the authentication response.
The Dashboard loads successfully.

If the browser continuously moves between Wazuh and the IdP, investigate redirect URIs, cookies, reverse-proxy settings, and session configuration.

Verify User Attributes

After authentication succeeds, verify that Wazuh receives the expected identity information.

Depending on the authentication protocol, this might include:

Username
Email address
Name ID
Subject identifier
Preferred username
Other configured claims

For SAML, inspect the attributes contained in the SAML assertion.

For OIDC, inspect the relevant ID-token claims.

When it comes to LDAP, verify that Wazuh can locate the user using the configured search parameters.

The identity value received by Wazuh should correspond to the account you intended to authenticate.

Verify Group Membership

Group membership is especially important when SSO is being used for authorization.

For example:

User: alice@example.com

Groups:

– Wazuh-Analysts

– Security-Team

Verify that the relevant Wazuh group is actually being transmitted by the IdP or discovered through LDAP.

Do not assume that because a user belongs to a group in the identity provider, Wazuh necessarily receives that group information.

The group must be included in the appropriate SAML attribute, OIDC claim, or LDAP directory lookup.

Verify Role Mapping

Once group membership is confirmed, verify that Wazuh maps the group to the intended role.

For example:

Wazuh-Administrators -> Administrator

Wazuh-Analysts -> Analyst

Wazuh-Auditors -> Read-only

If the user authenticates successfully but receives unexpected permissions, role mapping is one of the first areas to investigate.

Check for:

Incorrect group names
Incorrect claim names
Case differences
Missing group attributes
Conflicting mappings
Incorrect Wazuh roles
Multiple group memberships

Related Guide: How to Configure Wazuh SSO Role Mapping

Test Different User Roles

Do not test SSO with an administrator account alone.

Create or identify dedicated test users representing each important access level.

For example:

Test account	Expected role	What to verify
Admin	Administrator	Administrative access
Analyst	Analyst	Investigation access
Responder	Responder	Response permissions
Auditor	Read-only	Restricted access

This validates both authentication and authorization.

A successful login by an administrator does not prove that analyst or auditor role mappings work correctly.

Verify Logout Behavior

Test the logout process after successful authentication.

Verify that:

The Wazuh session terminates.
The browser no longer has an active Wazuh session.
Reopening the Dashboard does not unexpectedly restore an unauthorized session.
IdP session behavior matches your organization’s requirements.
Reauthentication works correctly.

Remember that Wazuh session termination and identity-provider session termination are related but not necessarily identical operations.

Review Authentication Logs

Logs can provide valuable information when the browser only reports a generic SSO failure.

Review the relevant Wazuh components and logs for:

Authentication failures
Invalid assertions
Invalid tokens
Certificate errors
Claim-processing errors
User lookup failures
Group lookup failures
Role-mapping failures
Session errors

When troubleshooting, reproduce the problem immediately before reviewing the logs so that the relevant entries are easier to identify.

How to Fix Wazuh SSO Login Errors

Wazuh SSO failures can originate in several different layers.

The identity provider, Wazuh Dashboard, certificates, DNS, network connectivity, browser session, or role-mapping configuration can all cause authentication problems.

The most effective troubleshooting approach is to determine where the authentication flow stops.

Wazuh Dashboard

Identity Provider

Authentication

SAML / OIDC Response

Wazuh Validation

Identity Attributes

Role Mapping

Dashboard Access

SSO Redirects Back to the Login Page

An infinite login loop usually means authentication is not producing a valid Wazuh session.

Check:

Redirect URI
Assertion Consumer Service URL
OIDC callback configuration
Cookies
Session settings
Reverse-proxy configuration
Dashboard URL
HTTPS configuration
System time

Also verify that the externally accessible Wazuh hostname matches the hostname used throughout the SSO configuration.

If Wazuh is behind Nginx or another reverse proxy, make sure the proxy is correctly forwarding the required headers and HTTPS information.

SAML Assertion Is Invalid

An invalid SAML assertion can result from several configuration mismatches.

Check:

Issuer
Audience
Entity ID
ACS URL
Assertion validity period
Signing certificate
Signature
Name ID
Required attributes
System time

The identity provider may report a successful authentication while Wazuh rejects the resulting assertion.

This generally means that the user’s credentials are not the problem; the federation configuration is.

OIDC Authentication Fails

For OIDC failures, verify:

Client ID
Client secret
Issuer
Authorization endpoint
Token endpoint
Redirect URI
Scopes
Claims
ID-token signature
Audience
Token expiration

Also verify that the Wazuh host can communicate with the OIDC provider.

If the provider supports OpenID Connect discovery, verify that the configured issuer resolves to the expected discovery metadata.

Related Guide: How to Configure Wazuh OIDC

Certificate Errors

Certificate problems can affect both SAML and OIDC deployments.

Check:

Certificate expiration
Certificate chain
Trusted CA
Identity-provider signing certificate
Wazuh certificate paths
File permissions
Certificate rotation
Hostname validation

Certificate rotation is especially important.

If an IdP begins signing SAML assertions with a new certificate but Wazuh still trusts the previous certificate, authentication can fail immediately.

Related Guide: How to Fix Wazuh Certificate Errors

Incorrect Redirect URI

An incorrect redirect URI is a common OIDC failure.

Compare the URI configured in Wazuh against the URI registered with the identity provider.

Check every component:

Scheme: https

Hostname: wazuh.example.com

Port: 443

Path: /callback

Even seemingly minor differences can matter.

For SAML, perform the equivalent comparison with the Assertion Consumer Service URL.

Incorrect Issuer or Audience

SAML and OIDC both use identifiers that help prevent authentication responses from being accepted by the wrong application.

For SAML, verify:

Issuer
Entity ID
Audience

For OIDC, verify:

Issuer
Audience (aud)
Client ID

A token or assertion can be correctly signed and still be rejected if it was issued for another application.

Invalid Client Credentials

OIDC integrations using confidential clients require valid client credentials.

Verify:

Client ID
Client secret
Client status
Client authentication method
Secret expiration
Secret rotation

Make sure the client ID and secret belong to the same application registration.

If the secret was recently regenerated, update Wazuh with the new value.

User Authenticates but Cannot Access Wazuh

This is an important distinction: successful authentication does not guarantee successful authorization.

If the user reaches the Dashboard but receives an access-denied error or cannot see expected resources, investigate:

Wazuh role assignment
Group membership
SAML attributes
OIDC claims
LDAP groups
RBAC permissions
Multi-tenancy
Index permissions

Related Guides:

Group or Role Mapping Failures

If the user authenticates but receives the wrong Wazuh permissions, verify the entire mapping chain:

Identity Provider Group

SAML Attribute /

OIDC Claim /

LDAP Group

Wazuh Role Mapping

Wazuh Role

Permissions

Check the exact group value being returned.

For example, these may not be equivalent in your mapping:

Wazuh-Analysts

wazuh-analysts

Wazuh_Analysts

Wazuh Analysts

Review capitalization, spaces, prefixes, claim names, and group formatting.

Related Guide: How to Configure Wazuh SSO Role Mapping

DNS and Network Problems

Wazuh SSO depends on connectivity between the relevant systems.

Verify that the Wazuh host can resolve and reach:

Identity-provider hostname
LDAP server, if applicable
OIDC discovery endpoint
OIDC token endpoint
Certificate or JWKS endpoints, where applicable

Also check:

DNS records
Firewall rules
Proxy settings
Routing
TLS inspection
Outbound HTTPS access

A valid SSO configuration cannot work if Wazuh cannot communicate with the identity provider.

Time Synchronization Problems

Clock differences can cause SAML assertions and OIDC tokens to appear invalid.

Verify time synchronization on:

Wazuh manager
Wazuh Dashboard host
Wazuh indexer hosts, where relevant
Identity-provider infrastructure
LDAP infrastructure, where applicable

Check the system clock and configured NTP synchronization.

Pay particular attention to errors involving:

Not yet valid assertions
Expired assertions
Expired tokens
Invalid timestamps

Time synchronization is especially important in distributed Wazuh deployments.

Browser Session and Cookie Problems

Sometimes the server-side configuration is correct but the browser is holding stale authentication state.

Test with:

Private/incognito browsing
A fresh browser profile
Cleared Wazuh cookies
Cleared IdP session cookies
Another browser

If SSO works in a private window but not in the normal browser session, stale cookies or an existing IdP session may be contributing to the problem.

For a dedicated troubleshooting walkthrough covering redirect loops, SAML failures, OIDC problems, certificates, role mapping, and other common Wazuh SSO failures, continue with How to Fix Wazuh SSO Login Error.

Wazuh SSO Troubleshooting Checklist

When troubleshooting Wazuh SSO, work from the authentication foundation toward authorization rather than changing multiple settings simultaneously.

Use the following checklist.

Check Wazuh Dashboard Configuration

Verify:

SSO is enabled as intended.
Authentication protocol is correct.
Identity-provider endpoints are correct.
Client identifiers are correct.
Redirect or ACS URLs are correct.
Authentication settings match the installed Wazuh version.
Configuration files contain no syntax or formatting errors.

Check IdP Configuration

Verify:

Wazuh is registered as an application.
The application is enabled.
Test users are assigned.
Test users are not blocked by access policies.
SAML or OIDC configuration matches Wazuh.
Claims and attributes are configured.
Groups are assigned correctly.
Certificates or signing keys are current.

Verify Certificates

Check:

Expiration dates
Certificate chain
Trusted CA
IdP signing certificate
Wazuh certificate paths
Hostname validation
Recent certificate rotations

If the IdP recently changed its signing certificate, verify that Wazuh has the corresponding trust configuration.

Verify DNS

Confirm that all relevant hostnames resolve correctly.

Check:

Wazuh hostname

IdP hostname

LDAP hostname

OIDC endpoints

JWKS endpoints

DNS problems can appear as authentication failures because Wazuh may be unable to reach the system responsible for validating or completing authentication.

Verify Network Connectivity

Confirm connectivity between Wazuh and the required authentication infrastructure.

Check:

Firewall rules
TCP ports
Routing
Proxy configuration
Outbound HTTPS
TLS inspection
Network ACLs

For LDAP, verify the appropriate LDAP/LDAPS connectivity.

For OIDC, verify access to the provider’s authorization and token infrastructure.

Verify System Time

Check time synchronization on all systems involved in the authentication flow.

Verify:

Current system time
Time zone configuration
NTP status
Clock drift

Time synchronization should be treated as a prerequisite rather than an optional troubleshooting step.

Check Authentication Logs

Review the relevant Wazuh logs immediately after reproducing the failure.

Look for:

Authentication failures
Assertion validation errors
Token validation errors
Certificate failures
User lookup errors
Group lookup errors
Authorization errors
Session errors

Use the timestamp of the failed login to isolate the relevant entries.

Check User Attributes and Claims

Confirm that the identity provider returns the expected information.

For SAML, verify the assertion attributes.

data-end=”15226″>For OIDC, verify token claims.

For LDAP, verify the attributes returned by the directory search.

Look specifically for the fields Wazuh uses for identity and role mapping.

Check Group Membership

Confirm that the test account belongs to the expected identity-provider group.

Then verify that the group is actually being passed to Wazuh.

A user being a member of an IdP group is not sufficient if that group is omitted from the SAML assertion or OIDC claims.

Check Role Mappings

Compare the actual identity-provider group or claim value against the configured Wazuh mapping.

For example:

Actual IdP value:

Wazuh-Analysts

Expected mapping:

Wazuh-Analysts -> Analyst

Result:

Analyst role assigned

If there is no matching mapping, authentication may succeed while authorization fails.

Clear Stale Browser Sessions

Test using a private browser session.

If necessary, clear:

Wazuh cookies
Identity-provider cookies
Cached authentication state

Then initiate a completely new SSO session.

This is particularly useful when testing configuration changes because an existing IdP session can obscure whether the new authentication flow is actually being exercised.

Test With a Dedicated SSO Account

Maintain dedicated test accounts for SSO validation.

Ideally, create separate test identities for:

SSO Administrator
SSO Analyst
SSO Responder
SSO Auditor

This allows you to validate both authentication and authorization without modifying production users.

A dedicated test account also makes troubleshooting safer because you can repeatedly authenticate, change group membership, and test role mappings without disrupting operational accounts.

Wazuh SSO Troubleshooting Sequence

When an SSO login fails, use this sequence:

1. Can the user authenticate at the IdP?

2. Does Wazuh redirect correctly?

3. Does the IdP return a response?

4. Does Wazuh validate the response?

5. Is the user identity correct?

6. Are groups / claims present?

7. Does role mapping succeed?

8. Does the role provide the expected access?

9. Does logout and reauthentication work?

This approach separates identity-provider authentication, federation validation, and Wazuh authorization instead of treating every SSO problem as a generic login failure.

Wazuh SSO Security Best Practices

Wazuh SSO centralizes authentication, but enabling SSO does not automatically make a Wazuh deployment secure.

The identity provider, Wazuh Dashboard, certificates, role mappings, sessions, and administrative interfaces all need to be protected.

A secure Wazuh SSO architecture should follow defense-in-depth principles:

1. strong authentication at the identity provider, encrypted communications
2. least-privilege authorization
3. protected credentials
4. continuous monitoring.

Use HTTPS/TLS Everywhere

Use HTTPS for Wazuh Dashboard access and TLS-protected connections wherever authentication information or credentials are transmitted.

This is particularly important for:

Wazuh Dashboard
SAML communication
OIDC communication
LDAP authentication
LDAPS
Identity-provider endpoints
Reverse proxies
Administrative interfaces

Never configure an authentication architecture that sends credentials or sensitive authentication information over unencrypted HTTP when HTTPS is available.

Verify that certificates are valid, trusted, unexpired, and issued for the correct hostnames.

Protect IdP Credentials and Client Secrets

OIDC client secrets, LDAP bind credentials, and other authentication credentials should be treated as sensitive secrets.

Do not:

Commit secrets to Git repositories.
Place secrets in public documentation.
Include secrets in screenshots.
Share credentials through unsecured messaging.
Store secrets in world-readable configuration files.

Use appropriate operating-system permissions and secret-management mechanisms where available.

If a credential is accidentally exposed, rotate it rather than assuming that obscuring or deleting the visible copy is sufficient.

Use Strong Identity-Provider Authentication

The identity provider should enforce strong authentication policies for Wazuh users.

Consider:

Strong passwords
MFA
Risk-based authentication
Conditional access
Device policies
Geographic or network restrictions
Account lockout policies
Session controls

Centralizing authentication through an IdP allows these controls to be applied consistently instead of independently configuring authentication policies for Wazuh users.

Enable MFA Through the IdP

Multi-factor authentication adds another authentication factor beyond the user’s password.

A typical flow becomes:

User

| Username + Password

Identity Provider

| MFA Challenge

User

| MFA Success

Identity Provider

| SAML / OIDC Response

Wazuh

The advantage of enforcing MFA at the identity-provider layer is that the same policy can protect Wazuh alongside other enterprise applications.

For privileged Wazuh administrators, consider stronger authentication requirements than those applied to ordinary users.

Apply Least-Privilege Role Mappings

Do not map broad identity-provider groups to powerful Wazuh roles.

Instead, create dedicated groups such as:

Wazuh-Administrators

Wazuh-Analysts

Wazuh-Responders

Wazuh-Auditors

Then map each group to the minimum Wazuh permissions required.

Avoid Unnecessary Administrator Access

Administrator access should be limited to users who actually need it.

An analyst who needs to investigate alerts does not necessarily need permission to:

Modify authentication configuration
Manage Wazuh users
Modify roles
Change security settings
Alter infrastructure configuration

Separating administrative and operational responsibilities reduces the potential impact of compromised accounts.

Protect SAML Certificates and Signing Keys

SAML signing certificates are part of the trust relationship between Wazuh and the identity provider.

Protect:

Private keys
Signing certificates
Certificate authorities
Certificate files
Key-storage locations
Configuration files containing certificate paths

Restrict access to private keys to only the accounts and services that require them.

A compromised signing key can undermine the trust relationship between the identity provider and service provider, making key protection particularly important.

Rotate Secrets and Certificates

Build credential and certificate rotation into your operational procedures.

Review:

OIDC client secrets
SAML signing certificates
TLS certificates
LDAP bind credentials
API credentials
Other authentication-related secrets

Before rotating a production certificate or secret, determine whether Wazuh and the identity provider need to be updated simultaneously.

Maintain a documented rollback procedure so authentication can be restored if the new credential or certificate does not work as expected.

Restrict Administrative Interfaces

Do not expose administrative interfaces to the public Internet unnecessarily.

Where appropriate, use:

Firewall restrictions
VPN access
Private networks
Reverse proxies
IP allowlists
Network segmentation
Administrative jump hosts

Related Guide: How to Configure a Wazuh IP Whitelist

The goal is to ensure that even if an identity account is compromised, access to sensitive administrative interfaces remains constrained by additional controls.

Monitor Authentication Events

Monitor authentication activity for unusual behavior.

Useful events include:

Successful logins
Failed logins
Repeated authentication failures
Privileged-user logins
New SSO users
Role changes
Group changes
Certificate failures
Authentication configuration changes

Correlating identity-provider events with Wazuh authentication events can provide better visibility into suspicious activity.

Review SSO Permissions Regularly

SSO access should not be configured once and then forgotten.

Periodically review:

Users assigned to the Wazuh application
Identity-provider groups
Wazuh role mappings
Privileged users
Dormant accounts
Former employees
Service accounts
Multi-tenant access
Administrator privileges

Remove obsolete assignments promptly.

A user who changes jobs may retain membership in a privileged security group unless access reviews are performed.

Maintain Configuration Backups

Back up the configuration required to reconstruct the Wazuh SSO environment.

Depending on your architecture, this can include:

Wazuh authentication configuration
Dashboard configuration
Certificates
CA certificates
Role mappings
RBAC configuration
Identity-provider application configuration
Documented redirect URIs
Client identifiers
Recovery procedures

Do not blindly back up plaintext secrets into unsecured storage.

Sensitive credentials should be handled according to your organization’s secret-management policy.

Related Guide: How to Backup Wazuh RBAC Configurations

A good backup strategy should allow you to reconstruct the authentication architecture after a failed upgrade, configuration error, certificate rotation problem, or infrastructure failure.

Wazuh SSO vs Wazuh API Authentication

Wazuh SSO and Wazuh API authentication solve different problems.

SSO primarily provides an interactive authentication mechanism for users accessing the Wazuh Dashboard.

API authentication is intended for programmatic access to the Wazuh API.

A useful distinction is:

Human User

Wazuh Dashboard

SSO / SAML / OIDC / LDAP

Interactive Session

Automation

Wazuh API

API Authentication

Programmatic Operation

Trying to use interactive SSO as a replacement for machine-to-machine API authentication can create unnecessary complexity.

Dashboard SSO vs API Authentication

Dashboard SSO is designed around human users.

It provides:

Centralized authentication
Identity-provider integration
MFA
Enterprise identity management
Interactive browser sessions
Group and role mapping

API authentication is designed for applications, scripts, integrations, and automation.

It provides a mechanism for software to authenticate when making API requests without requiring an interactive browser-based SSO flow.

When SSO Is Appropriate

SSO is generally appropriate when a human user needs to access the Wazuh Dashboard.

Examples include:

SOC analysts
Security administrators
Incident responders
Auditors
Security managers

SSO allows these users to use existing enterprise identities and authentication policies.

When API Tokens Are Appropriate

API credentials are more appropriate for automated workloads.

Examples include:

Automation scripts
CI/CD pipelines
Monitoring systems
Custom integrations
Scheduled jobs
SOAR workflows
External applications

An automated process should not normally depend on a human user’s browser session or MFA interaction.

Automating Wazuh API Access

API authentication allows applications to perform Wazuh operations programmatically.

For example, an automation workflow might:

Scheduled Job

Authenticate to Wazuh API

Retrieve Alerts

Analyze Events

Trigger External Workflow

Use a dedicated service identity where possible rather than embedding a human administrator’s credentials in automation.

The service identity should have only the API permissions required for its task.

Securing API Credentials

API credentials should be protected with the same discipline applied to SSO secrets.

Avoid:

Hardcoding tokens in source code
Committing credentials to Git
Sharing tokens between unrelated applications
Giving automation administrator privileges unnecessarily
Storing plaintext credentials in publicly accessible files

Rotate credentials periodically and immediately revoke compromised credentials.

Combining SSO With API-Based Automation

SSO and API authentication can coexist in the same Wazuh environment.

For example:

SOC Analysts

Microsoft Entra ID

Wazuh SSO

Wazuh Dashboard

Automation

Dedicated API Credential

Wazuh API

This provides a clean separation between human authentication and machine authentication.

The identity provider controls human access, while dedicated API credentials control automated workloads.

If you need the implementation details for generating and using Wazuh API tokens, including cURL, Postman, Python, permissions, and troubleshooting, the dedicated API guide provides the deeper walkthrough.

Real-World Wazuh SSO Deployment Example

Consider an enterprise SOC with several security teams that need access to a centralized Wazuh deployment.

The organization already uses an enterprise identity provider, requires MFA, and wants different Wazuh permissions for administrators, analysts, incident responders, and auditors.

A suitable architecture could look like this:

| Identity Provider |

| SAML / OIDC |

+———-+———–+

Authentication

+ Claims/Groups

+————-+ +——————+

| SOC Users | ———-> | Wazuh Dashboard |

+————-+ +——–+———+

Wazuh RBAC

+——————–+——————-+

| | |

v v v

Administrator Analyst Auditor

| | |

v v v

Full privileges SOC permissions Read-only

Enterprise SOC Architecture

Assume the organization operates:

One or more Wazuh managers
A Wazuh indexer cluster
Wazuh Dashboard
An enterprise identity provider
Multiple SOC teams
Centralized logging and monitoring

The Wazuh Dashboard is exposed through a controlled HTTPS endpoint:

https://wazuh.example.com

Users access the Dashboard through that endpoint rather than directly connecting to internal Wazuh infrastructure.

The identity provider remains the authoritative source for workforce identity.

Identity Provider Configuration

Create dedicated groups for Wazuh access:

Wazuh-Administrators

Wazuh-Analysts

Wazuh-Responders

Wazuh-Auditors

Assign users to these groups according to their job responsibilities.

The identity provider application should be restricted to the appropriate users and groups rather than made available to the entire workforce.

Wazuh Dashboard Configuration

Configure the Dashboard to use the selected SSO protocol.

For a SAML deployment, configure the relevant:

Identity-provider metadata
Entity ID
ACS URL
Signing certificate
User attributes
Group attributes

For an OIDC deployment, configure:

Issuer
Client ID
Client secret
Redirect URI
Scopes
Claims
Signing-key trust

The Wazuh configuration must match the identity-provider application exactly.

SAML/OIDC Authentication

Suppose this enterprise chooses OIDC.

The authentication flow becomes:

Alice

Wazuh Dashboard

| OIDC Authorization Request

Identity Provider

| Password + MFA

Identity Provider

| Authorization Code

Wazuh

| Token Exchange

Identity Provider

| ID Token

Wazuh

| Validate Identity

Role Mapping

Alternatively, the organization could implement the same overall architecture with SAML.

The protocol changes, but the underlying security model remains similar: authenticate the user centrally and then apply Wazuh authorization.

Group-to-Role Mapping

The identity provider returns group information associated with the authenticated user.

For example:

User:

alice@example.com

Group:

Wazuh-Analysts

Wazuh maps that group to the appropriate analyst role.

A complete mapping might look like:

Identity-provider group	Wazuh role	Purpose
Wazuh-Administrators	Administrator	Wazuh administration
Wazuh-Analysts	Analyst	SOC investigation
Wazuh-Responders	Responder	Incident response
Wazuh-Auditors	Read-only	Auditing and review

This model allows identity administrators to manage group membership while Wazuh administrators control the permissions associated with each role.

Administrator and Analyst Access

An administrator receives only the permissions necessary for Wazuh administration.

An analyst receives access to security data and investigation capabilities without automatically receiving administrative privileges.

For example:

Administrator

+– User/role administration

+– Security configuration

+– Wazuh configuration

+– Approved administrative functions

Analyst

+– Alert investigation

+– Event analysis

+– Agent visibility

+– Security dashboards

+– Approved investigation functions

This separation helps reduce the consequences of a compromised analyst account.

MFA Enforcement

The identity provider enforces MFA before issuing the SSO response.

For example:

Username + Password

MFA Check

Authentication Successful

SAML / OIDC Response

Wazuh

Privileged administrators can be subjected to stronger authentication policies than ordinary users.

This allows the enterprise to centralize authentication policy rather than implementing independent MFA systems for every application.

Authentication Testing

Before deploying the configuration to all users, test each access tier.

Use dedicated accounts:

Admin Test Account

Analyst Test Account

Responder Test Account

Auditor Test Account

For each account, verify:

IdP authentication
MFA
Wazuh login
User identity
Group membership
Role assignment
Dashboard access
Expected restrictions
Logout
Reauthentication

Also test a user who should not have Wazuh access.

That negative test is important because it confirms that application assignment and access controls are actually restricting unauthorized users.

Monitoring and Maintenance

Once SSO is operational, treat it as an ongoing security control rather than a one-time configuration.

Regularly review:

Successful authentications
Failed authentication attempts
Privileged logins
New group assignments
Role changes
Certificate expiration
Secret expiration
Identity-provider application assignments
Wazuh role mappings
Inactive accounts

Establish a documented process for certificate and secret rotation.

Also maintain backups of the Wazuh authentication and authorization configuration while protecting any sensitive credentials contained within the backup.

Finally, periodically test the SSO recovery procedure.

A Wazuh SSO configuration is only operationally reliable if administrators know how to recover from an expired certificate, failed identity-provider configuration, corrupted configuration, or other authentication outage.

Related Guides:

A well-designed enterprise Wazuh SSO deployment therefore combines centralized identity, strong authentication, MFA, encrypted communication, least-privilege RBAC, controlled administrative access, and continuous monitoring rather than treating SSO as simply a replacement for the Wazuh login screen.

Wazuh SSO Maintenance and Administration

Configuring Wazuh SSO is only the beginning.

Identity providers, certificates, credentials, user accounts, group memberships, and Wazuh configuration can all change over time.

Without ongoing maintenance, an SSO deployment that initially works correctly can eventually produce authentication failures or excessive access privileges.

A practical maintenance process should combine configuration management, credential rotation, access reviews, monitoring, and disaster recovery testing.

Certificate Renewal

Track the expiration dates of every certificate involved in the Wazuh SSO architecture.

Depending on the authentication method, this may include:

Wazuh Dashboard TLS certificates
Identity-provider signing certificates
SAML certificates
Certificate authority certificates
LDAP/LDAPS certificates
Reverse-proxy certificates
OIDC signing-key trust configuration

Do not wait until a certificate expires before replacing it.

For production environments, establish reminders well before expiration and document the renewal procedure.

Certificate rotation should also be tested in a non-production environment whenever possible.

Client-Secret Rotation

OIDC applications may use client secrets to authenticate Wazuh to the identity provider.

Client secrets should be rotated according to your organization’s credential-management policy and immediately replaced if they are suspected of being exposed.

Before rotating a production secret:

Generate the new secret.
Confirm the new secret’s validity.
Update the Wazuh configuration.
Restart the required service if necessary.
Test authentication.
Revoke the old secret.

Avoid deleting the old credential before confirming that the replacement works, unless your identity provider requires immediate invalidation.

Identity-Provider Changes

Changes to the identity provider can affect Wazuh even when no Wazuh configuration has been modified.

Examples include:

Changing the IdP hostname
Changing an application registration
Rotating signing certificates
Changing client secrets
Modifying claims
Changing group attributes
Changing MFA policies
Changing application assignments
Modifying conditional-access policies

Maintain documentation showing which IdP settings correspond to each Wazuh configuration value.

This makes it easier to identify the source of a failure after an identity-provider change.

User Lifecycle Management

Wazuh SSO should follow the organization’s normal identity lifecycle.

When employees join, change roles, or leave the organization, their Wazuh access should change accordingly.

A typical lifecycle looks like:

New Employee

Assigned to IdP Group

Wazuh SSO Access

Role Changes

Group Membership Updated

Wazuh Permissions Updated

Employee Leaves

IdP Access Revoked

Centralizing access through identity-provider groups can make this process considerably easier than manually managing individual Wazuh accounts.

Group and Role Reviews

Regularly review the relationship between identity-provider groups and Wazuh roles.

Look for:

Obsolete groups
Duplicate mappings
Excessive administrator assignments
Users with unexpected roles
Former employees
Inactive accounts
Unused roles
Overly broad permissions

Pay particular attention to administrator mappings.

A single identity-provider group accidentally mapped to a highly privileged Wazuh role can grant excessive access to every member of that group.

Monitoring Authentication Failures

Monitor authentication failures for both operational and security reasons.

Repeated failures may indicate:

Incorrect configuration
Expired credentials
Expired certificates
Broken role mappings
An unavailable identity provider
Network problems
Clock synchronization issues
Password attacks
Compromised accounts

Establish a baseline for normal authentication behavior so unusual activity is easier to identify.

For example, a sudden increase in failed SSO attempts across multiple users may indicate an infrastructure problem, while repeated failures against one account may warrant security investigation.

Updating Wazuh SSO Configuration

When changing Wazuh SSO configuration:

Document the current configuration.
Back up relevant configuration files.
Make one logical change at a time.
Validate syntax and configuration.
Restart only the required services.
Test SSO authentication.
Test authorization and role mapping.
Monitor logs for errors.

Avoid making multiple unrelated authentication changes simultaneously.

If something breaks, isolated changes make troubleshooting substantially easier.

Wazuh upgrades should also be treated as potential SSO-impacting events.

Before upgrading production systems, verify that the configured authentication method remains compatible with the target Wazuh version.

Disaster Recovery Considerations

Your disaster-recovery plan should account for authentication dependencies.

Document how to recover:

Wazuh Dashboard configuration
SSO configuration
Certificates
Certificate authorities
Role mappings
RBAC configuration
Identity-provider application settings
OIDC client credentials
SAML configuration
LDAP connectivity
DNS records

Do not assume that restoring Wazuh alone will restore SSO.

The identity provider is an external dependency, and the Wazuh authentication architecture may fail if its application registration, certificates, claims, or endpoints are unavailable or inconsistent.

Maintain secure backups and document an emergency authentication-recovery procedure for administrators.

Frequently Asked Questions

Question: What is Wazuh SSO?

Wazuh SSO, or Wazuh Single Sign-On, is an authentication architecture that allows users to authenticate through an external identity provider and then access the Wazuh Dashboard without maintaining a separate Wazuh login credential for each user.

Depending on the deployment, Wazuh can integrate with authentication technologies such as SAML, OIDC, and LDAP.

Question: Does Wazuh support Single Sign-On?

Yes. Wazuh supports enterprise authentication integrations that allow organizations to centralize user authentication instead of relying exclusively on local Wazuh credentials.

The exact configuration depends on the Wazuh version and authentication method being deployed.

Related Guide: How to Configure Wazuh SSO

Question: Does Wazuh support SAML SSO?

Yes. Wazuh can be configured to use SAML-based authentication with an external identity provider.

SAML is particularly useful when an organization’s existing identity infrastructure is built around enterprise SAML applications and centralized access management.

Question: Does Wazuh support OIDC?

Yes. Wazuh supports OpenID Connect (OIDC) authentication.

OIDC is built on OAuth 2.0 and uses identity tokens and claims to communicate information about the authenticated user.

Related Guide: How to Configure Wazuh OIDC

Question: Does Wazuh support LDAP authentication?

Yes. Wazuh can integrate with LDAP directory services for centralized authentication.

LDAP can be useful when an organization already maintains users and groups in a directory service and wants Wazuh authentication to use that existing directory.

Question: What Identity Providers work with Wazuh SSO?

Wazuh can be integrated with identity providers and directory services that support the authentication protocols and configuration requirements supported by the relevant Wazuh version.

Common enterprise integrations include:

Keycloak
Okta
Microsoft Entra ID
Google Workspace
LDAP-compatible directory services

The appropriate protocol depends on the capabilities of the identity provider and your organization’s requirements.

Question: Can Wazuh integrate with Keycloak?

Yes. Keycloak can act as an identity provider for Wazuh.

It can be used to centralize authentication and, depending on the configuration, provide SAML or OIDC authentication.

Related Guide: How to Integrate Keycloak with Wazuh

Question: Can Wazuh integrate with Okta?

Yes. Okta can be used as an identity provider for Wazuh using supported federation protocols such as SAML or OIDC.

The integration requires the Wazuh configuration and Okta application configuration to use matching endpoints, identifiers, credentials, claims, and certificates.

Related Guide: How to Integrate Wazuh with Okta

Question: Can Wazuh integrate with Microsoft Entra ID?

Yes. Microsoft Entra ID can be configured as an identity provider for Wazuh.

Depending on the architecture, you can configure an enterprise application using SAML or an OIDC application registration.

Related Guide: How to Integrate Wazuh with Azure AD

Question: Can Wazuh integrate with Google Workspace?

Yes. Google Workspace can be used as an identity provider for Wazuh, including SAML-based authentication.

Users and access can be managed through Google Workspace while Wazuh handles the resulting authentication and authorization.

Question: Can Wazuh map SSO groups to Wazuh roles?

Yes. Group-to-role mapping can allow identity-provider groups to determine the Wazuh role assigned to an authenticated user.

For example:

Wazuh-Administrators -> Administrator

Wazuh-Analysts -> Analyst

Wazuh-Auditors -> Read-only

The exact mapping mechanism depends on whether you are using SAML, OIDC, or LDAP.

Question: Does Wazuh SSO support MFA?

MFA can be enforced through the identity provider used for Wazuh authentication.

This is one of the major advantages of centralized SSO: the organization can apply its existing MFA policies to Wazuh users instead of maintaining an isolated authentication system.

For privileged Wazuh administrators, consider requiring stronger MFA policies where supported.

Question: What is the difference between Wazuh SSO and API authentication?

Wazuh SSO is primarily intended for interactive human access to the Wazuh Dashboard.

API authentication is intended for programmatic access by scripts, applications, integrations, and automation.

A typical deployment may therefore use:

Human users -> SSO -> Wazuh Dashboard

Automation -> API credentials -> Wazuh API

Do not use a human administrator’s credentials as a substitute for properly managed API credentials in automated workflows.

Related Guide: Wazuh API Token: Authentication and Setup Guide

Question: Why does Wazuh SSO redirect back to the login page?

An SSO redirect loop can have several causes, including:

Incorrect redirect URI
Incorrect SAML ACS URL
Incorrect OIDC configuration
Invalid session cookies
Reverse-proxy configuration
HTTPS configuration problems
Incorrect issuer or audience
Session configuration
Clock synchronization problems

Test with a private browser session and inspect Wazuh and identity-provider logs to determine where the authentication flow stops.

Related Guide: How to Fix Wazuh SSO Login Error

Question: Why does Wazuh SSO authentication fail?

Authentication failures can originate from either Wazuh or the identity provider.

Common causes include:

Invalid SAML assertion
Invalid OIDC token
Incorrect client credentials
Incorrect issuer
Incorrect audience
Expired certificates
Missing claims
Incorrect redirect URI
DNS failures
Network connectivity problems
Clock differences
Incorrect LDAP configuration

Start by determining whether the user can successfully authenticate with the identity provider.

Then follow the authentication response through to Wazuh.

Question: Why can a user authenticate but not access Wazuh?

This usually indicates an authorization problem rather than an authentication problem.

The user has proven their identity, but Wazuh may not have assigned the expected role or permissions.

Check:

Group membership
SAML attributes
OIDC claims
LDAP groups
Role mappings
RBAC configuration
Multi-tenancy
Assigned permissions

Related Guides:

Question: How do I troubleshoot Wazuh SSO certificate errors?

Start by checking the certificate expiration date, certificate chain, trusted CA, hostname, configured certificate paths, and recent certificate rotations.

For SAML, verify that Wazuh trusts the certificate used to validate the identity provider’s signed assertions.

For HTTPS and LDAP/LDAPS, verify that the relevant CA chain is trusted by the Wazuh system.

Also review Wazuh logs immediately after reproducing the authentication failure.

Conclusion

Wazuh SSO provides a centralized authentication architecture that can significantly simplify access to the Wazuh Dashboard while allowing organizations to apply existing identity, MFA, and access-control policies.

The architecture typically consists of:

User

Identity Provider

| SAML / OIDC / LDAP

Wazuh Dashboard

Wazuh Authorization

RBAC / Multi-Tenancy

Wazuh Resources

The appropriate authentication method depends on the organization’s existing identity infrastructure and requirements.

SAML is a strong choice for organizations built around enterprise federation and traditional SSO integrations.

OIDC provides a modern identity layer built around OAuth 2.0 and is particularly useful when the identity provider has strong OpenID Connect support.

LDAP is useful when Wazuh needs to authenticate against an existing directory service.

Regardless of the protocol, authentication is only one part of the security model.

Role mapping and authorization are equally important.

A user successfully authenticating to Wazuh does not mean that user should automatically receive administrative access.

Use dedicated identity-provider groups, map them to narrowly defined Wazuh roles, and follow least-privilege principles when designing access.

You should also test the complete SSO flow before deploying it broadly.

Verify authentication, user attributes, group membership, role mapping, authorization, logout behavior, certificates, and authentication logs.

Continue monitoring the environment after deployment and periodically review users, groups, roles, certificates, and credentials.

Relevant Guides

For implementation-specific guidance, continue with the relevant guides:

Together, these guides provide the provider-specific configuration, role-mapping, troubleshooting, and API-authentication details needed to build and maintain a production-ready Wazuh authentication architecture.