How to Configure Wazuh OIDC

Understanding the OIDC Authentication Flow

Understanding the authentication flow makes configuring and troubleshooting Wazuh OIDC much easier.

Although each Identity Provider has its own interface, they all follow the same OpenID Connect workflow.

Wazuh never authenticates users directly, instead, it delegates authentication to a trusted Identity Provider and validates the returned tokens before granting access.

Step 1: User Requests Access

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

Dashboard Login

A user browses to the Wazuh Dashboard URL.

Rather than displaying a traditional local login form, the Dashboard recognizes that OIDC authentication is enabled and initiates the authentication process.

If the user already has an active session with the Identity Provider, they may not even be prompted to log in again.

Authentication Initiation

The Dashboard generates an authorization request that includes several pieces of information, including:

• Client ID
• Redirect URI
• Requested scopes
• Response type
• State parameter
• Nonce value

The state parameter helps prevent Cross-Site Request Forgery (CSRF) attacks, while the nonce protects against token replay attacks.

Step 2: Redirect to Identity Provider

Once the authentication request is generated, Wazuh redirects the user’s browser to the configured Identity Provider.

Authorization Request

The browser sends an authorization request to the Identity Provider’s authorization endpoint. This request tells the provider:

• Which application is requesting authentication
• Where the user should be redirected afterward
• Which identity information is being requested
• Which authentication flow should be used

No passwords are exchanged with Wazuh during this step.

Authentication Challenge

The Identity Provider determines whether the user is already authenticated.

If not, it displays the organization’s normal sign-in page.

Because authentication occurs entirely through the Identity Provider, organizations can customize login branding, password policies, and authentication requirements without modifying Wazuh.

Step 3: User Authentication

The Identity Provider verifies the user’s identity before issuing any tokens.

Username/Password

The user authenticates using their existing enterprise credentials, such as:

• Microsoft Entra ID account
• Keycloak user
• Okta account
• Google Workspace account
• Auth0 account

Credentials are verified directly by the Identity Provider, not by Wazuh.

Multi-Factor Authentication

If Multi-Factor Authentication (MFA) is enabled, the user completes the required verification step.

Common MFA methods include:

• Microsoft Authenticator
• Google Authenticator
• Push notifications
• Hardware security keys (FIDO2/WebAuthn)
• SMS verification
• Time-based One-Time Passwords (TOTP)

Since MFA is enforced by the Identity Provider, Wazuh automatically benefits from stronger authentication without requiring additional configuration.

Conditional Access

Many enterprise Identity Providers also evaluate Conditional Access policies before allowing authentication.

Examples include:

• Blocking logins from unknown countries
• Requiring MFA on unmanaged devices
• Restricting access outside business hours
• Preventing access from risky IP addresses
• Device compliance verification

This provides an additional layer of protection for Wazuh administrative access.

Step 4: Token Issuance

After successful authentication, the Identity Provider issues tokens that Wazuh will validate.

Authorization Code

Most Wazuh deployments use the Authorization Code Flow, which is considered the most secure OIDC flow for server-side web applications.

Instead of sending tokens directly through the browser, the Identity Provider first returns a temporary authorization code.

Wazuh exchanges this code for tokens over a secure back-channel connection.

This minimizes token exposure and improves overall security.

ID Token

The Identity Provider generates a signed ID Token containing user identity information such as:

• User ID
• Username
• Email address
• Display name
• Groups
• Tenant information
• Authentication timestamp

The token is digitally signed using the Identity Provider’s private key.

Access Token

An access token is also issued during the authentication process.

Although Wazuh primarily relies on the ID token for authentication, the access token may be used when interacting with additional protected resources or APIs supported by the Identity Provider.

Step 5: Wazuh Validates the Token

Receiving a token does not automatically grant access. Wazuh performs several security checks before creating a session.

Signature Verification

The Dashboard downloads the Identity Provider’s public signing keys (JWKS) and verifies the token’s digital signature.

If the signature does not match, authentication immediately fails.

This protects against:

• Token tampering
• Forged identities
• Replay attacks
• Man-in-the-middle attaFVcks

Claims Validation

After verifying the signature, Wazuh validates important claims inside the token, including:

• Issuer (iss)
• Audience (aud)
• Expiration (exp)
• Issued-at (iat)
• Nonce
• Subject (sub)

If any required claims are missing or invalid, the login request is rejected.

Session Creation

Once validation succeeds, Wazuh creates an authenticated session for the user.

Depending on the configured session timeout, users can continue accessing the Dashboard without authenticating again until the session expires or they sign out.

Step 6: Role Mapping and Dashboard Access

Authentication identifies the user. Authorization determines what they can do.

User Claims

The ID token contains claims describing the authenticated user.

Typical claims include:

• Username
• Email
• Department
• Tenant
• Security groups
• Roles

These claims are used to determine the user’s permissions inside Wazuh.

Group Mapping

Wazuh maps external groups from the Identity Provider to internal RBAC roles.

For example:

Centralized group management means administrators only need to maintain memberships in the Identity Provider.

Permission Assignment

After role mapping completes successfully, users receive the permissions associated with their assigned Wazuh role.

These permissions may include:

• Viewing dashboards
• Searching alerts
• Running investigations
• Managing agents
• Editing detection rules
• Configuring integrations
• Administering the platform

Using external identity groups simplifies onboarding, offboarding, and ongoing permission management while ensuring consistent access controls across the organization.

Related Guides:

• Troubleshooting Wazuh RBAC
• How to Set Up Wazuh Multi-Tenancy

Register an OIDC Application

Before Wazuh can authenticate users with an Identity Provider, you must register it as an OIDC client.

This registration establishes trust between Wazuh and the Identity Provider and generates the credentials required for secure authentication.

Although the interface differs between providers, every registration includes redirect URIs, client credentials, and authentication scopes.

Configure Redirect URIs

Redirect URIs tell the Identity Provider where users should be sent after successfully authenticating.

Callback URL

The callback URL is where the Identity Provider returns the authorization code after login.

A typical callback URL resembles:

https://wazuh.example.com/auth/openid/login

The URL configured in Wazuh must exactly match the URL registered with the Identity Provider.

Common mistakes include:

• Incorrect hostname
• Wrong port number
• Missing HTTPS
• Trailing slash mismatches
• Reverse proxy URL differences

Logout URL

Most providers also allow a logout or post-logout redirect URI.

After users sign out, they can be redirected back to:

• The Wazuh login page
• A company portal
• An application landing page

Configuring logout URLs improves the user experience and prevents session inconsistencies.

HTTPS Requirements

Production deployments should always use HTTPS.

Many Identity Providers refuse to register insecure HTTP redirect URIs because redirect endpoints exchange authentication codes that must remain protected during transit.

Create Client Credentials

Every registered application receives credentials that uniquely identify Wazuh.

Client ID

The Client ID identifies the Wazuh Dashboard during the authentication process.

It is included in every authorization request but is not considered secret.

Client Secret

The Client Secret functions similarly to an application password.

During the Authorization Code Flow, Wazuh presents the Client ID and Client Secret when exchanging the authorization code for tokens.

Never expose this secret publicly.

Secret Management Best Practices

Protect client credentials using established security practices:

• Store secrets outside version control.
• Restrict access to administrators only.
• Rotate secrets regularly.
• Replace compromised secrets immediately.
• Use a dedicated secrets manager whenever possible.
• Monitor for unauthorized access attempts.

The Open Worldwide Application Security Project (OWASP) recommends treating client secrets like any other privileged credential and rotating them periodically as part of a broader secrets management strategy.

Configure Scopes

Scopes define which information Wazuh requests from the Identity Provider during authentication.

openid

The openid scope is mandatory for every OpenID Connect authentication request.

Without it, the request is treated as standard OAuth 2.0 rather than OIDC.

profile

The profile scope returns common user attributes, including:

• Display name
• Username
• Preferred language
• Profile information

email

The email scope provides the authenticated user’s email address and verification status.

Many organizations use email addresses as unique login identifiers.

groups

The groups scope allows Wazuh to receive security group memberships.

These groups are commonly mapped directly to Wazuh RBAC roles, enabling centralized authorization management.

Custom Scopes

Some Identity Providers support custom scopes for additional claims, such as:

• Department
• Employee ID
• Business unit
• Organization
• Geographic region
• Custom application roles

Custom scopes can simplify advanced RBAC implementations in large enterprises.

Configure the Identity Provider

Once the application has been registered, configure your Identity Provider so it can securely authenticate Wazuh users and provide the claims required for authorization.

Although the configuration process varies slightly among providers, the overall workflow is similar.

Microsoft Entra ID Configuration

Register the Application

In the Microsoft Entra admin center:

1. Navigate to App registrations.
2. Select New registration.
3. Enter an application name such as Wazuh Dashboard.
4. Choose the supported account types.
5. Configure the callback (redirect) URI.
6. Complete the registration.

Microsoft generates the application’s Client ID and Tenant ID after registration.

Configure Authentication

Under the application’s Authentication settings:

• Add the production redirect URI.
• Configure the logout URL if desired.
• Enable ID token issuance.
• Enable Authorization Code Flow.

Verify that HTTPS is used for all production redirect URIs.

Configure Token Claims

Open the Token configuration page and add the required optional claims, such as:

• Email
• Preferred username
• Name
• Groups (if required)
• Tenant information

These claims allow Wazuh to identify authenticated users correctly.

Add Group Claims

Group claims allow Wazuh to perform role mapping based on Microsoft Entra security groups.

You can choose to include:

• Security groups
• Directory roles
• Groups assigned to the application

Using application-assigned groups reduces token size in large environments.

Create Client Secret

Under Certificates & secrets:

• Create a new client secret.
• Copy the generated value immediately.
• Store it securely.
• Record its expiration date.
• Plan for periodic secret rotation.

Keycloak Configuration

Create a Realm

Begin by creating a dedicated realm for your organization or Wazuh deployment.

A realm provides isolated identity management, authentication policies, and user directories.

Create a Client

Within the realm:

• Create a new client.
• Select OpenID Connect as the protocol.
• Configure the Client ID.
• Enable standard Authorization Code Flow.
• Configure valid redirect URIs.
• Configure post-logout redirect URIs.

Configure Client Settings

Review client settings, including:

• Confidential client mode
• Client authentication
• HTTPS requirements
• Session timeouts
• PKCE (if applicable)

These settings determine how securely Wazuh communicates with Keycloak.

Create Users and Groups

Create users or synchronize identities from LDAP or Active Directory.

Organize users into security groups that align with your planned Wazuh RBAC roles.

Related Guide: How to Configure Wazuh LDAP Authentication

Configure Protocol Mappers

Protocol mappers determine which user attributes are included in issued tokens.

Common mappings include:

• Username
• Email
• Display name
• Group memberships
• Organization
• Custom roles

Proper protocol mapping ensures Wazuh receives all required claims during authentication.

Okta Configuration

Create an OIDC Application

From the Okta Administrator Console:

1. Create a new application integration.
2. Select OIDC.
3. Choose Web Application.
4. Configure the Authorization Code Flow.
5. Save the application.

Okta generates the Client ID and Client Secret after creation.

Configure Redirect URIs

Configure:

• Sign-in redirect URI
• Sign-out redirect URI

These should exactly match the URLs configured in Wazuh.

Assign Users

Grant application access to:

• Individual users
• Security groups
• Organizational units

Only assigned users can authenticate successfully.

Configure Groups

Create or reuse Okta groups that correspond to Wazuh roles.

Examples include:

• Wazuh Administrators
• SOC Analysts
• Incident Response
• Security Operations

Group-based authorization simplifies long-term administration.

Generate Client Credentials

Finally, record the generated:

• Client ID
• Client Secret
• Issuer URL
• Discovery endpoint

These values will be used in the next section when configuring Wazuh to trust the Identity Provider.

Configure Wazuh for OIDC Authentication

Once your Identity Provider has been configured and your OIDC application has been registered, the next step is to configure Wazuh to trust that provider.

This involves updating the Dashboard authentication settings, specifying the OIDC endpoints, enabling secure TLS communication, and restarting the required services.

Always perform these changes during a maintenance window whenever possible to avoid disrupting active Dashboard users.

Locate the Authentication Configuration

The Wazuh Dashboard uses the OpenSearch Security plugin for authentication, so OIDC-related settings are configured within the Dashboard and OpenSearch Security configuration files.

Note: The exact file names and configuration syntax may vary slightly depending on your Wazuh and OpenSearch versions. Always refer to the documentation for your installed release.

Relevant Configuration Files

Depending on your deployment, you may modify configuration files such as:

• Dashboard configuration
• OpenSearch Security authentication configuration
• Security role mapping configuration
• TLS certificate configuration

Review your deployment architecture before making changes, particularly if you’re using Docker, Kubernetes, or a multi-node Wazuh cluster.

Related Guide: How to Set Up a Multi-Node Wazuh Cluster

Backup Existing Configuration

Before editing any authentication settings:

• Back up all configuration files.
• Export current OpenSearch Security settings.
• Save existing role mappings.
• Record current authentication providers.
• Verify you have console or SSH access.

Authentication misconfigurations can prevent all Dashboard logins, so having a rollback plan is essential.

Configure OIDC Settings

The Dashboard must know how to communicate with your Identity Provider.

Most of the required values come directly from the OIDC application registration you completed earlier.

Issuer URL

The Issuer URL uniquely identifies your Identity Provider.

Examples include:

• Microsoft Entra ID tenant issuer
• Keycloak realm URL
• Okta authorization server
• Auth0 tenant domain
• Google Identity issuer

Wazuh validates this value against the iss claim contained in every ID token.

If the values do not match exactly, authentication fails.

Discovery Endpoint

Most Identity Providers expose an OpenID Connect Discovery document.

The discovery endpoint automatically provides:

• Authorization endpoint
• Token endpoint
• JWKS endpoint
• Supported scopes
• Signing algorithms
• UserInfo endpoint

Using the discovery document reduces manual configuration and simplifies future endpoint changes.

The endpoint typically resembles:

https://your-provider/.well-known/openid-configuration

Client ID

Configure the Client ID generated when registering the Wazuh application.

This identifies Wazuh during every authentication request.

Client Secret

Add the Client Secret associated with the registered application.

Because this credential authenticates Wazuh to the Identity Provider, it should be stored securely and never committed to version control.

Whenever possible:

• Restrict file permissions.
• Rotate secrets regularly.
• Store secrets in a secure vault.
• Limit administrator access.

Redirect URI

Configure the same callback URL that was registered with the Identity Provider.

The redirect URI configured in Wazuh and the Identity Provider must match exactly.

Common causes of login failures include:

• Incorrect hostname
• Missing HTTPS
• Reverse proxy URL mismatches
• Different ports
• Trailing slash differences

Logout Endpoint

If your Identity Provider supports single logout, configure the logout endpoint.

This allows users to:

• End their Wazuh session.
• Terminate the Identity Provider session.
• Prevent automatic reauthentication.

Single logout provides a cleaner user experience, especially on shared administrative workstations.

Configure TLS Settings

OIDC exchanges authentication tokens over HTTPS, making TLS configuration a critical security requirement.

Certificate Validation

Always enable certificate validation when connecting to your Identity Provider.

Disabling certificate verification exposes authentication traffic to potential man-in-the-middle attacks and should never be used in production.

Verify that:

• Certificates are valid.
• Hostnames match.
• Certificates are not expired.
• Certificate chains are complete.

Custom CA Certificates

Organizations using private Certificate Authorities may need to import their internal CA certificates into the Dashboard’s trust store.

This enables secure validation of internally issued certificates without disabling TLS verification.

Keep internal CA certificates updated whenever certificate authorities are renewed or replaced.

Secure HTTPS Communication

Ensure that all communication between:

• User browsers
• Reverse proxies
• Wazuh Dashboard
• Identity Provider

uses HTTPS with modern TLS versions and strong cipher suites.

The OWASP Transport Layer Security Cheat Sheet recommends disabling outdated protocols and enforcing secure TLS configurations to protect authentication traffic.

Related Guides:

• How to Fix Wazuh Certificate Errors
• How to Configure a Wazuh Proxy

Restart Wazuh Services

After updating the authentication configuration, restart the necessary services so the new settings are loaded.

Restart Dashboard

In most deployments, restarting the Wazuh Dashboard is sufficient for authentication changes to take effect.

If you also modified OpenSearch Security configuration, you may need to reload or restart additional services depending on your deployment architecture.

Perform restarts one service at a time in clustered environments to minimize downtime.

Related Guide: The Complete Wazuh Cluster Architecture Guide

Verify Configuration Loads Successfully

After the restart:

• Review Dashboard logs.
• Confirm no configuration parsing errors appear.
• Verify successful connection to the Identity Provider.
• Confirm the discovery document loads successfully.
• Ensure signing keys are retrieved.
• Verify the login page redirects correctly.

Only proceed to user testing after confirming that startup completed without authentication errors.

Configure Role Mapping

Authentication confirms a user’s identity, but authorization determines what they are allowed to do within Wazuh.

Role mapping connects user information received from the Identity Provider with Wazuh’s Role-Based Access Control (RBAC) system.

This ensures users receive only the permissions required for their job responsibilities.

Understanding Claims

OIDC tokens contain claims, which are pieces of information describing the authenticated user.

Wazuh evaluates these claims when assigning permissions.

sub

The sub (subject) claim uniquely identifies the user within the Identity Provider.

Unlike usernames or email addresses, the subject identifier is intended to remain stable even if other user attributes change.

email

The email claim contains the user’s email address.

Many organizations use this value as the primary login identifier and for auditing authenticated sessions.

preferred_username

The preferred_username claim usually represents the username displayed within the Dashboard.

Examples include:

• jsmith
• admin
• analyst01

Some Identity Providers use this instead of email for interactive logins.

groups

The groups claim lists the security groups assigned to the authenticated user.

This is the most common claim used for Wazuh role mapping because administrators can manage permissions centrally without modifying Wazuh.

Examples:

• SOC
• Incident Response
• Security Engineering
• Wazuh Administrators

roles

Some Identity Providers expose application-specific roles instead of groups.

Role claims can also be mapped directly to Wazuh RBAC permissions, depending on your organization’s identity model.

Map Identity Provider Groups to Wazuh Roles

Role mappings define how external users receive internal Wazuh permissions.

A common enterprise mapping might resemble the following:

Keeping authorization centralized within the Identity Provider significantly simplifies onboarding and offboarding.

Administrator

Administrator roles typically receive permissions to:

• Manage users
• Configure integrations
• Modify detection rules
• Manage agents
• Configure authentication
• Administer the Dashboard

Also, administrator access should be granted only to trusted personnel following the principle of least privilege.

SOC Analyst

SOC analysts generally require permissions to:

• Search alerts
• Investigate incidents
• View dashboards
• Analyze telemetry
• Manage investigations

Most organizations restrict configuration changes for analyst roles.

Read-Only User

Read-only users commonly include:

• Auditors
• Compliance teams
• Executives
• Security managers

These users can review dashboards and reports without modifying the environment.

Custom RBAC Roles

Many organizations create custom roles tailored to operational responsibilities.

Examples include:

• Threat Hunting
• Vulnerability Management
• Detection Engineering
• Cloud Security
• MSSP Customer Administrators

Custom roles allow organizations to implement least-privilege access while accommodating complex security teams.

Related Guide:

• Troubleshooting Wazuh RBAC
• How to Set Up Wazuh Multi-Tenancy

Test Authorization

After configuring role mappings, verify that authorization behaves exactly as expected.

Verify Assigned Roles

Log in using accounts from different Identity Provider groups.

Confirm that each user receives the expected Wazuh role.

For example:

• Administrator account
• SOC analyst account
• Read-only account
• Custom RBAC account

Testing multiple accounts helps identify incorrect group mappings before production rollout.

Confirm Dashboard Permissions

Verify that users only see the features permitted by their assigned role.

Examples include:

• Dashboard visibility
• Alert searches
• Rule management
• Agent management
• Administrative menus
• Integration settings

Users should neither receive excessive privileges nor encounter unnecessary restrictions.

Validate Index Access

Finally, verify that OpenSearch index permissions align with assigned Wazuh roles.

Users should only access the indices required for their responsibilities.

Review:

• Alert indices
• Archive indices
• Security indices
• Tenant-specific indices (if applicable)

Proper index-level authorization protects sensitive security data while supporting compliance requirements.

Testing the OIDC Integration

Before deploying OIDC authentication to production, thoroughly validate both authentication and authorization.

Testing should confirm that users can log in successfully, receive the correct permissions, and terminate sessions securely.

Verify User Login

Begin by testing the complete authentication workflow using one or more test accounts.

Successful Authentication

Navigate to the Wazuh Dashboard and select the OIDC login option.

A successful test should:

• Redirect to the Identity Provider.
• Prompt for authentication (if necessary).
• Complete any MFA requirements.
• Return to the Dashboard without errors.

If authentication fails, review both the Wazuh Dashboard logs and the Identity Provider’s sign-in logs to identify the failure point.

Dashboard Access

After authentication, verify that the Dashboard loads normally.

Check that:

• Navigation menus appear correctly.
• Dashboards load successfully.
• Searches execute without authorization errors.
• User information displays correctly.

Any unexpected access restrictions may indicate incorrect role mappings rather than authentication failures.

Session Creation

Confirm that Wazuh creates an authenticated session after login.

Verify:

• Session timeout behavior.
• Browser session persistence.
• Automatic reauthentication after expiration.
• Session renewal (if configured).

Long-lived sessions should balance usability with organizational security requirements.

Validate User Claims

Next, verify that the claims issued by the Identity Provider match your authorization design.

Inspect ID Token

Decode the ID token using a trusted JWT inspection tool or your Identity Provider’s debugging utilities.

Confirm expected claims such as:

• iss
• sub
• aud
• email
• preferred_username
• groups
• roles

Never modify production tokens during testing.

Verify Group Membership

Ensure the expected security groups appear in the token.

If groups are missing:

• Review token claim configuration.
• Verify protocol mappers (Keycloak).
• Check optional claims (Microsoft Entra ID).
• Confirm group assignment (Okta).

Missing groups are one of the most common causes of authorization failures.

Confirm Role Mappings

Verify that every expected group maps to the appropriate Wazuh RBAC role.

Test multiple users with different permission levels to ensure mappings remain consistent across departments and business units.

Test Logout

Authentication testing is incomplete until logout behavior has also been verified.

Local Logout

Sign out of the Wazuh Dashboard.

Verify that:

• The local session is destroyed.
• Protected pages require authentication again.
• Browser back-button navigation does not restore access.

Identity Provider Logout

If single logout is configured, confirm that signing out of Wazuh also ends the user’s Identity Provider session.

This prevents users from being silently reauthenticated when revisiting the Dashboard.

Session Termination

Finally, verify complete session termination by:

• Closing the browser.
• Opening a new browser session.
• Revisiting the Dashboard.
• Confirming that authentication is required again.

Completing these tests helps ensure that your Wazuh OIDC deployment provides secure authentication, accurate authorization, and predictable session management before it is rolled out to production users.

Troubleshooting Common OIDC Issues

Even when configured correctly, OIDC authentication can fail due to configuration mismatches, certificate problems, token validation errors, or network issues.

Fortunately, most authentication problems can be isolated by reviewing the Wazuh Dashboard logs alongside your Identity Provider’s authentication logs.

A structured troubleshooting approach, verifying redirect URIs, client credentials, token claims, certificates, and system clocks, can resolve the vast majority of login failures.

Invalid Redirect URI

One of the most common OIDC errors is an invalid or mismatched redirect URI.

Redirect URI Mismatch

The redirect URI configured in Wazuh must exactly match the URI registered with the Identity Provider.

Differences as small as the following can cause authentication to fail:

• Missing trailing slash
• Different hostname
• Different port
• HTTP instead of HTTPS
• Incorrect path
• Reverse proxy URL mismatch

Most Identity Providers return an “Invalid Redirect URI” or “redirect_uri_mismatch” error when this occurs.

Incorrect Callback URL

Verify that:

• The callback URL is correctly configured in Wazuh.
• The same URL exists in the registered OIDC application.
• Reverse proxies preserve the original HTTPS URL.
• DNS records resolve correctly.

If Wazuh is deployed behind NGINX, Apache, or HAProxy, ensure forwarded headers preserve the original host and protocol.

Related Guide:

• How to Configure a Wazuh Proxy
• Fixing Nginx Upstream Timeouts When Proxying Wazuh Dashboard Traffic

Invalid Client Credentials

Authentication cannot proceed if Wazuh cannot authenticate itself to the Identity Provider.

Incorrect Client ID

Verify that the configured Client ID matches the registered OIDC application.

Common mistakes include:

• Typographical errors
• Using the wrong environment (test vs. production)
• Copying the application name instead of the Client ID
• Registering multiple applications with similar names

Expired Client Secret

Many Identity Providers automatically expire client secrets.

If authentication suddenly stops working after previously functioning correctly:

• Check the secret expiration date.
• Generate a new client secret.
• Update the Wazuh configuration.
• Restart affected services.

Maintain a documented secret rotation schedule to avoid unexpected outages.

Token Validation Errors

Receiving a token does not guarantee successful authentication.

Wazuh validates every token before granting access.

Issuer Mismatch

The token’s iss (issuer) claim must exactly match the configured issuer URL.

Even minor differences, such as missing trailing slashes or incorrect tenant identifiers, cause validation failures.

Audience Mismatch

The token’s aud (audience) claim must contain the Client ID registered for Wazuh.

If another application receives the token, Wazuh correctly rejects it.

Signature Validation Failures

Signature validation failures usually indicate one of the following:

• Incorrect JWKS endpoint
• Rotated signing certificates
• Cached signing keys
• TLS connectivity problems
• Corrupted tokens

If your Identity Provider recently rotated signing certificates, force Wazuh to refresh the public signing keys.

Missing User Groups

Successful authentication does not always guarantee successful authorization.

If users authenticate successfully but receive incorrect permissions, group claims are often the cause.

Incorrect Claims

Inspect the ID token and verify it contains:

• groups
• roles
• preferred_username
• email

Missing claims prevent Wazuh from assigning the correct RBAC roles.

Group Synchronization Issues

Verify that:

• Users belong to the expected groups.
• Group synchronization has completed.
• Directory synchronization is functioning properly.
• Nested groups are supported if required.

Cloud identity providers may require additional configuration before group memberships appear inside issued tokens.

Protocol Mapper Configuration

For Keycloak deployments, protocol mappers determine which claims are included in ID tokens.

Verify that:

• Group protocol mappers exist.
• Mapper names match expected claim names.
• Claims are included in the ID token.
• Tokens contain current group memberships.

Improper mapper configuration is one of the most common authorization issues in Keycloak deployments.

Related Guide: Troubleshooting Wazuh RBAC

Login Loop

Repeated redirects between Wazuh and the Identity Provider usually indicate session or cookie problems.

Cookie Issues

Verify browser cookies are not being blocked.

Problems can occur due to:

• Third-party cookie restrictions
• SameSite settings
• Secure cookie requirements
• Browser privacy extensions

Modern browsers enforce increasingly strict cookie policies that may affect authentication flows.

Session Configuration

Review session settings, including:

• Session timeout
• Idle timeout
• Authentication timeout
• Cookie expiration

Conflicting timeout values between Wazuh and the Identity Provider can trigger repeated login prompts.

Reverse Proxy Configuration

Reverse proxies should correctly forward:

• Host headers
• HTTPS headers
• Original client IP
• Forwarded protocol

Improper proxy configuration frequently causes redirect loops because Wazuh generates incorrect callback URLs.

 Related Guide: Fixing Wazuh API SameSite Cookie Errors

Certificate Validation Problems

TLS issues often prevent Wazuh from communicating with the Identity Provider.

Self-Signed Certificates

Production environments should avoid self-signed certificates whenever possible.

If internal certificates are required:

• Import the issuing CA.
• Configure trusted certificate authorities.
• Enable certificate validation.
• Avoid disabling TLS verification.

Missing CA Bundle

Private Certificate Authorities require corresponding CA certificates to be installed on the Wazuh Dashboard server.

Without the correct CA bundle, HTTPS connections to the Identity Provider cannot be validated.

TLS Handshake Failures

TLS handshake failures may result from:

• Unsupported TLS versions
• Incorrect certificates
• Expired certificates
• Hostname mismatches
• Cipher suite incompatibilities

Review Dashboard logs and use TLS diagnostic tools to identify the specific handshake failure.

Related Guide: How to Fix Wazuh Certificate Errors

Clock Synchronization Issues

OIDC relies heavily on accurate timestamps.

Token Expiration

Tokens contain expiration (exp) and issued-at (iat) claims.

If the Dashboard’s system clock differs significantly from the Identity Provider, otherwise valid tokens may appear expired.

NTP Configuration

Configure all participating systems to synchronize with reliable Network Time Protocol (NTP) servers.

Synchronize:

• Wazuh Dashboard
• Wazuh Indexer
• Identity Provider
• Reverse proxies
• Load balancers

Time Drift

Even small amounts of clock drift can produce intermittent authentication failures.

Monitor system time regularly and investigate any persistent drift between infrastructure components.

OIDC Security Best Practices

Correct configuration is only the first step.

Following established security best practices helps protect authentication infrastructure, reduce attack surfaces, and improve regulatory compliance.

Always Use HTTPS

All OIDC communication should occur over HTTPS.

Encryption protects:

• Authorization codes
• Authentication tokens
• Session cookies
• User credentials

Never disable TLS validation in production environments.

Enable Multi-Factor Authentication

Require MFA for all privileged users and strongly consider enforcing it for every Wazuh user.

According to Microsoft, enabling MFA blocks the overwhelming majority of password-based account compromise attempts, making it one of the most effective security controls available.

Protect Client Secrets

Treat client secrets like privileged credentials.

Recommended practices include:

• Store secrets securely.
• Restrict administrator access.
• Never expose secrets publicly.
• Avoid storing secrets in source code.
• Use enterprise secrets management platforms when possible.

Use Short Token Lifetimes

Short-lived ID and access tokens reduce the impact of compromised credentials.

Organizations commonly configure:

• Short access token lifetimes
• Reasonable session durations
• Automatic token renewal
• Periodic reauthentication for privileged accounts

Rotate Client Secrets Regularly

Client secrets should be rotated on a regular schedule.

Rotation should also occur immediately following:

• Administrative staff changes
• Suspected compromise
• Security incidents
• Certificate renewals

Documented rotation procedures reduce operational risk.

Apply Least Privilege Access

Only grant users the permissions required for their responsibilities.

Avoid assigning administrator privileges to users who only need to:

• View dashboards
• Search alerts
• Generate reports
• Review investigations

Least-privilege authorization significantly reduces the potential impact of compromised accounts.

Restrict Administrative Accounts

Limit administrative access to a small number of trusted personnel.

Administrative accounts should:

• Require MFA
• Use dedicated administrator identities
• Avoid shared credentials
• Be monitored closely
• Be reviewed regularly

Validate Token Signatures

Always verify:

• Digital signatures
• Issuer
• Audience
• Expiration
• Nonce
• Required claims

Never disable signature validation, even during troubleshooting.

Monitor Authentication Logs

Regularly review authentication logs from both:

• Wazuh Dashboard
• Identity Provider

Look for:

• Failed login attempts
• MFA failures
• Excessive authentication requests
• Privilege escalation attempts
• Geographic anomalies
• Unusual login times

Authentication monitoring supports both incident detection and compliance reporting.

Keep Wazuh Updated

Security updates frequently include:

• Authentication improvements
• OpenSearch compatibility fixes
• TLS enhancements
• Vulnerability patches
• Performance optimizations

Keeping Wazuh, OpenSearch, and your Identity Provider current reduces exposure to known vulnerabilities.

Related Guide: Step-by-Step Wazuh Manager Scaling Guide

Performance and High Availability Considerations

Large organizations often authenticate hundreds or thousands of users each day.

Proper planning helps maintain reliable authentication performance while avoiding unnecessary login delays or service interruptions.

Identity Provider Redundancy

OIDC authentication depends on the availability of the Identity Provider.

For production deployments:

• Deploy redundant identity servers where supported.
• Configure high-availability clusters.
• Use geographic redundancy when appropriate.
• Monitor authentication endpoints continuously.
• Test failover procedures regularly.

Cloud-hosted Identity Providers typically provide built-in redundancy, while self-hosted platforms such as Keycloak require administrators to design highly available deployments.

Token Validation Performance

Every authentication requires token validation.

To improve performance:

• Use OIDC discovery documents.
• Cache JWKS signing keys appropriately.
• Minimize unnecessary validation requests.
• Reduce network latency between Wazuh and the Identity Provider.
• Monitor authentication response times.

Proper JWKS caching can significantly reduce authentication overhead during periods of heavy login activity.

Session Timeout Configuration

Balance usability with security by configuring appropriate session durations.

Consider:

• Idle session timeout
• Maximum session lifetime
• Administrative session duration
• Automatic logout policies

Excessively short sessions frustrate users, while excessively long sessions increase security risk.

Token Refresh Strategy

Refresh tokens allow users to remain authenticated without repeatedly entering credentials.

A well-designed refresh strategy should:

• Minimize unnecessary logins.
• Respect organizational security policies.
• Revoke compromised sessions promptly.
• Support seamless user experiences.

Avoid issuing refresh tokens with unnecessarily long lifetimes for privileged accounts.

Certificate Lifecycle Management

OIDC deployments rely on multiple certificates throughout the authentication process.

Monitor and maintain:

• Identity Provider signing certificates
• TLS certificates
• Internal Certificate Authorities
• Reverse proxy certificates
• Certificate expiration dates

Automated certificate monitoring helps prevent unexpected authentication outages caused by expired certificates.

Scaling Large Enterprise Deployments

Large enterprise environments may support:

• Multiple business units
• Thousands of users
• Numerous geographic locations
• Multiple Wazuh clusters
• Multiple Identity Providers

To improve scalability:

• Deploy highly available Dashboard nodes.
• Load balance authentication traffic.
• Use redundant reverse proxies.
• Optimize network connectivity to the Identity Provider.
• Continuously monitor authentication latency and failure rates.
• Regularly test disaster recovery and failover scenarios.

A resilient authentication architecture ensures that Wazuh OIDC continues to provide fast, secure, and reliable access even as organizational requirements grow.

Related Guides:

• The Complete Wazuh Cluster Architecture Guide
• Step-by-Step Wazuh Manager Scaling Guide
• How to Build a Wazuh Indexer Cluster

Real-World Example

A large enterprise security team manages a centralized Wazuh deployment used by multiple security teams, including SOC analysts, incident responders, threat hunters, and security administrators.

The organization previously relied on locally managed Wazuh accounts, which created challenges around account provisioning, password management, and maintaining consistent access permissions across different business units.

To improve security and simplify identity management, the security team decides to implement Wazuh OIDC authentication using Microsoft Entra ID as the Identity Provider.

The organization already uses Microsoft Entra ID for employee authentication, making it a natural choice for integrating Wazuh into its existing identity ecosystem.

Centralized Identity Provider Integration

The security team begins by registering the Wazuh Dashboard as an OIDC application inside Microsoft Entra ID.

During application registration, administrators configure:

• Wazuh Dashboard redirect URI
• Logout redirect URI
• Client ID
• Client Secret
• Required OIDC scopes
• Token claims

The organization enables the following claims:

• Username
• Email address
• Security groups
• User roles

These claims allow Wazuh to identify users and assign appropriate permissions automatically.

For organizations using self-hosted identity infrastructure, the same approach could be implemented with Keycloak by creating an OIDC client, configuring protocol mappers, and exposing group information inside issued tokens.

Related Guide: How to Configure Wazuh LDAP Authentication

Synchronizing Security Groups With Wazuh RBAC Roles

Instead of manually creating users inside Wazuh, the security team manages permissions through Microsoft Entra ID security groups.

They create groups that align with operational responsibilities:

When a new analyst joins the SOC, administrators only need to add the employee to the appropriate Entra ID group.

During the next login, Wazuh automatically receives the user’s group claims and applies the correct permissions.

This eliminates manual account creation and reduces the risk of inconsistent access assignments.

Related Guide: Troubleshooting Wazuh RBAC

Enforcing Multi-Factor Authentication

Because authentication is handled by Microsoft Entra ID, the organization can enforce MFA without modifying Wazuh.

The security team requires MFA for:

• All Wazuh administrators
• Incident responders
• Users accessing sensitive security dashboards

Authentication policies require users to verify their identity using:

• Microsoft Authenticator
• Hardware security keys
• Passwordless authentication
• Device-based authentication

This protects Wazuh access even if a user’s password is compromised.

Implementing Conditional Access Policies

The enterprise security team also configures Conditional Access policies to control when and how users can access Wazuh.

Examples include:

• Requiring compliant corporate devices
• Blocking authentication from high-risk locations
• Requiring MFA outside trusted networks
• Blocking legacy authentication methods
• Requiring additional verification for administrators

These policies provide additional protection around a security monitoring platform that contains sensitive information.

Validating Token Claims Before Production Deployment

Before enabling OIDC for all users, the security team performs extensive validation.

They verify that issued ID tokens contain the required claims:

• iss (issuer)
• aud (audience)
• sub (subject identifier)
• email
• preferred_username
• groups
• roles

They confirm that:

• Tokens are signed correctly.
• The issuer matches the configured Identity Provider.
• Group claims appear correctly.
• Expiration timestamps are valid.
• Wazuh can map claims to internal roles.

This prevents authorization problems after rollout.

Testing Role Assignments

The team creates test accounts representing different security responsibilities.

They validate:

Administrator Account

The administrator should be able to:

• Manage agents
• Configure integrations
• Modify security settings
• Manage users and roles

SOC Analyst Account

The analyst should be able to:

• View alerts
• Search events
• Investigate incidents
• Access dashboards

Read-Only Account

The auditor should only be able to:

• View dashboards
• Review reports
• Access approved information

Testing ensures users receive the correct permissions before production deployment.

Production Deployment Benefits

After deploying OIDC authentication, the organization gains several operational improvements.

Simplified Identity Management

User lifecycle management becomes centralized.

When employees:

• Join the company
• Change departments
• Leave the organization

administrators update access through Microsoft Entra ID instead of manually modifying Wazuh accounts.

Improved Security

OIDC improves security by enabling:

• Centralized authentication controls
• MFA enforcement
• Conditional Access policies
• Strong token validation
• Reduced password exposure

Security teams no longer need to manage separate Wazuh passwords.

Reduced Administrative Overhead

Previously, administrators manually managed:

• User accounts
• Password resets
• Role assignments
• Access reviews

After implementing OIDC, these processes are handled through the existing identity platform.

Compliance Support

Centralized authentication improves compliance reporting by providing:

• Consistent access controls
• Authentication audit trails
• User activity tracking
• Easier access reviews
• Documented permission management

This supports security frameworks that require strong identity governance and access control processes.

Frequently Asked Questions

Question: What is Wazuh OIDC?

Wazuh OIDC is an authentication integration that allows the Wazuh Dashboard to authenticate users through an OpenID Connect Identity Provider instead of using locally managed accounts.

OIDC enables Single Sign-On (SSO), centralized identity management, MFA support, and external role-based access control.

Question: Does Wazuh support OpenID Connect?

Yes. Wazuh supports OpenID Connect authentication through its OpenSearch Dashboard authentication framework.

Organizations can integrate Wazuh with OIDC-compatible Identity Providers to provide centralized authentication.

Question: What is the difference between OIDC and SAML?

Both OIDC and SAML provide Single Sign-On, but they use different technologies.

OIDC is often preferred for modern cloud-native environments, while SAML remains widely used in enterprise applications.

Question: Which identity providers work with Wazuh OIDC?

Wazuh OIDC can work with any Identity Provider that supports the OpenID Connect standard.

Common providers include:

• Microsoft Entra ID
• Keycloak
• Okta
• Auth0
• Google Identity Platform

Quesiton: Can I use Microsoft Entra ID with Wazuh OIDC?

Yes. Microsoft Entra ID is one of the most common enterprise Identity Providers used with OIDC.

Organizations can configure:

• Application registration
• Redirect URIs
• Client credentials
• Token claims
• Group mappings
• Conditional Access policies

to integrate Entra ID with Wazuh.

Question: Does Wazuh OIDC support multi-factor authentication?

Yes.

MFA is handled by the Identity Provider rather than Wazuh itself.

If your Identity Provider supports MFA, Wazuh automatically benefits from those authentication policies.

Examples include:

• Microsoft Entra MFA
• Okta Verify
• Hardware security keys
• TOTP applications

Question: Can I map OIDC groups to Wazuh RBAC roles?

Yes.

OIDC group claims can be mapped to Wazuh RBAC roles.

For example:

• Wazuh-Admins → Administrator
• SOC-Team → Analyst
• Auditors → Read-only

This allows centralized permission management through the Identity Provider.

Related Guide: How to Set Up Wazuh Multi-Tenancy

Question: What scopes are required for Wazuh OIDC?

The minimum required scope is:

openid

Common additional scopes include:

profile
email
groups

Organizations may also configure custom scopes for additional claims.

Question: How do I troubleshoot OIDC login failures?

Common troubleshooting steps include:

1. Verify redirect URIs.
2. Confirm Client ID and Client Secret values.
3. Validate issuer and audience claims.
4. Check token expiration timestamps.
5. Verify group claims exist.
6. Review Wazuh Dashboard logs.
7. Review Identity Provider authentication logs.
8. Confirm TLS certificates are trusted.

Question: Is OIDC more secure than LDAP authentication?

OIDC and LDAP solve different problems.

LDAP authentication directly connects applications to directory services, while OIDC delegates authentication to a dedicated Identity Provider.

OIDC often provides additional security capabilities, including:

• MFA support
• Conditional Access
• Token-based authentication
• Modern SSO workflows
• Reduced password exposure

LDAP can still be appropriate for environments that require direct directory authentication.

Related Guide: How to Configure Wazuh LDAP Authentication

Question: Can multiple identity providers be used with Wazuh?

In many deployments, Wazuh is configured with a primary authentication provider.

Supporting multiple Identity Providers depends on your OpenSearch Security configuration and deployment requirements.

Organizations needing multiple identity sources typically centralize identities through an enterprise Identity Provider.

Question: What happens if the identity provider becomes unavailable?

If the Identity Provider becomes unavailable:

• New users cannot authenticate.
• Existing sessions may continue until expiration.
• Token validation may fail depending on configuration.
• Administrative access may be impacted.

For production environments, deploy highly available identity infrastructure and maintain emergency administrative access procedures.

Conclusion

Configuring Wazuh OIDC authentication allows organizations to integrate their security monitoring platform with modern identity management systems while improving security, usability, and operational efficiency.

The configuration process involves several key steps:

1. Registering Wazuh as an OIDC application.
2. Configuring an Identity Provider such as Microsoft Entra ID, Keycloak, or Okta.
3. Setting up redirect URIs, client credentials, and scopes.
4. Configuring Wazuh authentication settings.
5. Mapping identity claims to Wazuh RBAC roles.
6. Testing authentication, authorization, and logout workflows.

By implementing OIDC-based Single Sign-On, organizations can centralize user management, enforce MFA, apply Conditional Access policies, and reduce the administrative burden of managing individual Wazuh accounts.

Secure role mapping is especially important because authentication only confirms identity, the assigned RBAC permissions determine what users can access.

Furthermore, carefully designed group mappings and least-privilege roles help prevent excessive permissions while maintaining efficient security operations.

Organizations should regularly review:

• Authentication logs
• User permissions
• Client secret expiration dates
• Certificate lifecycles
• Identity Provider configurations

Regular testing and monitoring ensure that Wazuh authentication remains secure, reliable, and aligned with organizational requirements.

For additional Wazuh authentication and access-control guidance, explore these related guides:

• How to Configure Wazuh SSO
•  How to Configure Wazuh SAML Authentication
• How to Configure Wazuh LDAP Authentication
• Troubleshooting Wazuh RBAC
• How to Set Up Wazuh Multi-Tenancy