How to Integrate Keycloak with Wazuh

Managing user authentication across multiple security platforms quickly becomes challenging as organizations grow. Security teams often need to manage separate credentials for SIEM platforms, cloud services, ticketing systems, and identity providers, increasing administrative overhead and the risk of weak access controls. Integrating Keycloak with Wazuh solves this problem by allowing Wazuh to delegate user authentication to a centralized Identity and Access Management (IAM) platform.

Instead of maintaining local Wazuh accounts, administrators can authenticate users through Keycloak using modern identity standards such as OpenID Connect (OIDC) or SAML.

This enables Single Sign-On (SSO), centralized user lifecycle management, stronger authentication policies, and seamless integration with enterprise directories such as LDAP and Active Directory.

Whether you’re deploying Wazuh in a small business or a large enterprise Security Operations Center (SOC), integrating Keycloak simplifies identity management while improving security and compliance.

In this guide, you’ll learn how Keycloak works, how Wazuh handles authentication, why organizations choose this integration, and how to configure Keycloak as an identity provider for Wazuh using OpenID Connect.

What Is Keycloak?

Overview of Keycloak

Keycloak is an open-source Identity and Access Management (IAM) platform developed to centralize authentication, authorization, and user management for modern applications and services.

Originally created by Red Hat and now maintained by the open-source community, Keycloak eliminates the need for every application to maintain its own user database.

Instead of authenticating users separately for each application, organizations can authenticate users through a single trusted identity provider while enforcing consistent security policies across their environment.

Keycloak supports both cloud-native applications and traditional enterprise software, making it suitable for organizations of all sizes.

Keycloak as an Identity and Access Management (IAM) Platform

Identity and Access Management (IAM) is responsible for ensuring that only authorized users gain access to organizational resources.

Keycloak provides a centralized IAM solution that includes:

User account management
Group management
Role-based access control
Identity federation
Single Sign-On (SSO)
Multi-factor authentication (MFA)
Password policy enforcement
Session management
Identity brokering

Rather than creating local accounts in every application, administrators define users, groups, and roles once inside Keycloak and allow integrated applications, including Wazuh, to trust Keycloak for authentication.

This approach significantly reduces credential sprawl while simplifying user administration.

Authentication and Authorization Capabilities

Keycloak separates authentication from authorization.

Authentication verifies who a user is.

Examples include:

Username and password
One-time passwords (OTP)
Hardware security keys
Passkeys (WebAuthn)
Smart cards
Identity federation with external providers

Authorization determines what an authenticated user is allowed to do.

Keycloak supports:

Role-based access control (RBAC)
Group-based permissions
Fine-grained authorization policies
Client-specific roles
Attribute-based access control
Token-based authorization

When integrated with Wazuh, Keycloak authenticates the user, while Wazuh maps identity information to its own internal RBAC permissions.

Related Guides:

Supported Identity Protocols (OIDC, OAuth 2.0, SAML)

One of Keycloak’s biggest strengths is its support for widely adopted identity standards.

OpenID Connect (OIDC)

OIDC extends OAuth 2.0 by adding an identity layer that allows applications to authenticate users and receive identity information in JSON Web Tokens (JWTs).

Most modern web applications, including recent Wazuh deployments, prefer OIDC because it is lightweight, secure, and designed for cloud-native environments.

OAuth 2.0

OAuth 2.0 focuses on delegated authorization. It allows applications to obtain limited access to resources without exposing user credentials. OIDC builds upon OAuth 2.0 to provide authentication.

SAML 2.0

SAML remains common in enterprise environments, particularly where legacy applications or existing enterprise identity providers are involved. It exchanges authentication information using XML assertions.

Keycloak allows organizations to support all three standards simultaneously, making migrations significantly easier.

According to the OpenID Foundation, OpenID Connect has become one of the dominant authentication protocols for modern web applications due to its simplicity, interoperability, and strong security model.

Benefits of Centralized Identity Management

Centralized identity management provides significant operational and security advantages.

Some of the biggest benefits include:

One identity across multiple applications
Consistent password policies
Centralized MFA enforcement
Faster employee onboarding
Immediate account deprovisioning
Simplified auditing
Reduced password fatigue
Lower help desk workload
Improved compliance reporting

Industry analysts at Gartner have consistently emphasized Identity and Access Management as a foundational component of Zero Trust architectures, where identity verification becomes the primary security perimeter rather than the traditional network boundary.

Organizations that centralize authentication can also better monitor user access, enforce least-privilege principles, and reduce the likelihood of orphaned accounts remaining active after employees leave the company.

What Is Wazuh?

Overview of Wazuh

Wazuh is an open-source security platform that combines Extended Detection and Response (XDR) capabilities with Security Information and Event Management (SIEM) functionality.

It enables organizations to collect, analyze, and respond to security events from servers, workstations, cloud services, containers, network devices, and applications.

Its modular architecture supports:

Log collection
File Integrity Monitoring (FIM)
Vulnerability detection
Security Configuration Assessment (SCA)
Malware detection
Active response
Threat intelligence integrations
Compliance monitoring

Because Wazuh consolidates security data from numerous systems, controlling who can access the platform becomes critically important.

Wazuh Architecture

A typical Wazuh deployment consists of several core components working together.

Wazuh Agents

Installed on monitored endpoints to collect logs, security events, file integrity data, and system information.

Wazuh Manager

Processes incoming events, evaluates detection rules, correlates activity, and generates alerts.

Wazuh Indexer

Stores alerts and security telemetry for fast searching and long-term retention.

Wazuh Dashboard

Provides the web interface where analysts investigate alerts, perform searches, manage agents, and administer the platform.

Authentication occurs at the Dashboard level, making it the primary integration point for external identity providers like Keycloak.

Related Guides:

Wazuh Dashboard Authentication

By default, Wazuh Dashboard supports local user authentication.

While suitable for testing or smaller deployments, local authentication presents challenges as environments scale:

Multiple credential databases
Manual account creation
Password synchronization issues
Inconsistent MFA enforcement
Difficult user lifecycle management

For these reasons, many organizations configure Wazuh to authenticate users through enterprise identity providers using OpenID Connect, SAML, or LDAP.

Related Guides:

Built-in RBAC System

Wazuh includes a comprehensive Role-Based Access Control (RBAC) system that allows administrators to define exactly what users can access after authentication.

Permissions can be assigned to:

Administrators
Security analysts
Incident responders
Compliance teams
Read-only auditors
Custom operational roles

Even when Keycloak performs authentication, Wazuh continues enforcing authorization through its internal RBAC engine.

For example:

SOC analysts can investigate alerts.
Administrators can modify rules and agents.
Compliance officers can view reports without changing configurations.
Executives may receive read-only dashboard access.

This separation between authentication and authorization follows security best practices and supports the principle of least privilege.

Related Guide: Troubleshooting Wazuh RBAC

Why Organizations Integrate External Identity Providers

As organizations adopt dozens, or even hundreds, of cloud services and security tools, maintaining separate user databases becomes impractical.

External identity providers provide:

Centralized authentication
Corporate directory integration
MFA enforcement
Conditional access policies
Single Sign-On
Password policy consistency
Centralized auditing
Automated provisioning and deprovisioning

Instead of managing users separately inside Wazuh, administrators simply grant or revoke access within Keycloak, and those changes immediately affect authentication.

This significantly reduces administrative effort while improving security.

Why Integrate Keycloak with Wazuh?

Single Sign-On (SSO)

Single Sign-On (SSO) enables users to authenticate once and securely access multiple applications without repeatedly entering credentials.

By integrating Keycloak with Wazuh, security analysts can use the same enterprise identity they already use for services such as email, ticketing systems, VPNs, and internal applications.

Benefits include:

Faster login experience
Fewer password resets
Improved user productivity
Reduced password reuse
Centralized session management

SSO also minimizes the number of credentials users must remember, lowering the risk of insecure password practices.

Centralized User Management

Instead of maintaining local Wazuh accounts, administrators manage users directly within Keycloak.

This provides:

One user directory
Centralized role assignments
Unified password policies
Consistent authentication settings
Easier permission reviews

Identity changes automatically propagate to integrated applications, greatly simplifying administration.

Multi-Factor Authentication (MFA)

One of the biggest security improvements is centralized MFA enforcement.

Keycloak supports numerous authentication factors, including:

Time-based One-Time Passwords (TOTP)
WebAuthn passkeys
FIDO2 security keys
Smart cards
Mobile authenticators
Recovery codes

Once MFA is enforced in Keycloak, Wazuh benefits without requiring additional MFA configuration.

The U.S. Cybersecurity and Infrastructure Security Agency (CISA) identifies MFA as one of the most effective defenses against account compromise.

Simplified Onboarding and Offboarding

Employee lifecycle management becomes much easier.

When a new employee joins:

Create the account in Keycloak.
Assign groups or roles.
Access becomes available automatically.

When someone leaves:

Disable or delete the account.
Access to Wazuh is immediately revoked.
No forgotten local accounts remain active.

This reduces the likelihood of orphaned accounts becoming security risks.

Improved Security Posture

Centralized identity management strengthens overall security by enabling organizations to consistently enforce authentication policies.

Examples include:

Strong password policies
MFA requirements
Account lockout policies
Login monitoring
Session expiration
Identity federation
Token expiration controls

Security teams gain greater visibility into authentication activity while reducing the attack surface created by unmanaged local accounts.

Better Compliance and Auditing

Many regulatory frameworks require organizations to demonstrate strong identity management and access controls.

Keycloak integration helps support compliance efforts by providing:

Centralized authentication logs
Consistent access policies
Complete login histories
Easier access reviews
Faster forensic investigations
Simplified evidence collection

This is particularly valuable for organizations working toward standards such as ISO 27001, SOC 2, PCI DSS, HIPAA, or NIST Cybersecurity Framework requirements.

Reduced Administrative Overhead

Without centralized IAM, administrators often perform repetitive tasks across multiple applications.

Keycloak reduces this burden by centralizing:

User creation
Password resets
Role assignments
MFA management
Session control
Authentication policies

This allows security teams to spend less time on account management and more time on threat detection and incident response.

Scalability for Enterprise Deployments

As organizations grow, identity management becomes increasingly complex.

A Keycloak-Wazuh integration scales well because it supports:

Thousands of users
Multiple authentication realms
Federated identity providers
Multiple LDAP directories
High-availability deployments
Hybrid cloud environments
Multi-site authentication

For enterprises operating large Security Operations Centers, centralized authentication significantly improves operational consistency while reducing identity-related risks.

Related Guides:

How Keycloak Authentication Works with Wazuh

Understanding how authentication works behind the scenes makes it much easier to configure, troubleshoot, and secure your Keycloak-Wazuh integration.

Wazuh relies on OpenID Connect (OIDC) to delegate user authentication to Keycloak while continuing to enforce its own Role-Based Access Control (RBAC).

At a high level, the authentication process follows this sequence:

A user attempts to access the Wazuh Dashboard.
Wazuh redirects the user to Keycloak.
Keycloak authenticates the user.
Keycloak issues signed security tokens.
Wazuh validates those tokens.
Wazuh maps the user’s identity to internal RBAC permissions.
The user gains access based on assigned roles.

Because authentication is centralized, password policies, MFA requirements, account lockouts, and user lifecycle management are handled by Keycloak rather than Wazuh.

Authentication Flow Overview

The authentication flow between Keycloak and Wazuh is based on the OpenID Connect Authorization Code Flow, which is considered the recommended authentication flow for confidential web applications.

The process works as follows:

User
   │
   ▼
Wazuh Dashboard
   │
   ▼
Redirect to Keycloak Login
   │
   ▼
User Authenticates
   │
   ▼
Keycloak Issues Authorization Code
   │
   ▼
Wazuh Exchanges Code for Tokens
   │
   ▼
Keycloak Returns Signed Tokens
   │
   ▼
Wazuh Validates Tokens
   │
   ▼
RBAC Role Mapping
   │
   ▼
Dashboard Access Granted

Unlike older authentication mechanisms that require passwords to be shared with every application, only Keycloak ever sees the user’s credentials.

This architecture greatly reduces credential exposure and aligns with Zero Trust security principles.

OpenID Connect (OIDC) Process

OpenID Connect (OIDC) is an identity layer built on top of OAuth 2.0 that enables applications like Wazuh to verify a user’s identity without handling passwords directly.

The OIDC authentication process typically includes:

User requests the Wazuh Dashboard.
Wazuh redirects the browser to Keycloak.
User authenticates with Keycloak.
Keycloak verifies credentials and MFA (if enabled).
Keycloak returns an authorization code.
Wazuh exchanges the authorization code for tokens.
Tokens are validated.
User information is extracted.
RBAC permissions are applied.
Dashboard session begins.

The OpenID Foundation recommends the Authorization Code Flow for server-side web applications because client secrets remain protected on the server and tokens are exchanged securely.

User Login Sequence

When an analyst visits the Wazuh Dashboard, the following events occur:

The user opens the Wazuh Dashboard.
Wazuh detects that the user is unauthenticated.
The browser is redirected to the Keycloak login page.
The user enters corporate credentials.
If configured, Keycloak requests MFA.
Authentication succeeds.
Keycloak generates an authorization code.
Wazuh exchanges the authorization code for tokens.
Token signatures are validated.
User claims are read.
Wazuh assigns RBAC permissions.
The Dashboard loads.

If the user already has an active Keycloak session through another application, authentication may occur transparently without prompting for credentials again.

Token Issuance

After successful authentication, Keycloak generates signed JSON Web Tokens (JWTs).

These tokens commonly include:

User ID
Username
Email address
Groups
Assigned roles
Token expiration time
Issuer
Audience
Session ID

Keycloak digitally signs each token, allowing Wazuh to verify that it has not been modified during transmission.

JWTs eliminate the need for repeated authentication requests while maintaining strong cryptographic security.

ID Tokens vs Access Tokens

Although both are JWTs, ID tokens and access tokens serve different purposes.

Token	Purpose
ID Token	Confirms the authenticated user’s identity.
Access Token	Authorizes access to protected APIs and resources.
Refresh Token	Obtains new access tokens without requiring the user to log in again.

For Wazuh authentication:

The ID token identifies the user.
The Access token authorizes API requests.
The Refresh token helps maintain user sessions without frequent reauthentication.

Proper separation of token types improves both security and scalability.

Token Validation

Before granting access, Wazuh performs several validation checks.

Typical validation includes:

Digital signature verification
Token expiration check
Issuer validation
Audience validation
Nonce validation (when applicable)
Client ID verification
Token integrity verification

If any validation fails, authentication is denied.

Common causes include:

Expired tokens
Incorrect issuer URL
Invalid client secret
Clock synchronization issues
Modified JWTs
Incorrect realm configuration

These validation steps help prevent replay attacks, forged tokens, and unauthorized access.

Role Mapping

Authentication only establishes who the user is. Authorization determines what the user can do.

Keycloak can include user roles or group memberships within JWT claims. Wazuh reads these claims and maps them to its internal RBAC roles.

For example:

Keycloak Group	Wazuh Role
SOC_Admins	Administrator
SOC_Analysts	Analyst
Compliance	Read-only Auditor
Incident_Response	Incident Responder

This allows organizations to manage user memberships centrally while continuing to use Wazuh’s built-in permission model.

Related Guide: Troubleshooting Wazuh RBAC

Session Management

Once authentication succeeds, both Keycloak and Wazuh maintain session information.

Administrators can configure:

Session timeout
Idle timeout
Maximum session lifetime
Remember Me functionality
Concurrent session limits
Token refresh intervals

Proper session management reduces unnecessary logins while limiting exposure if an active session is compromised.

Security best practices recommend using shorter session lifetimes for privileged administrator accounts than for standard analyst accounts.

Logout Flow

When a user logs out of Wazuh, the logout process should also terminate the Keycloak session.

A typical logout sequence is:

User selects Log Out.
Wazuh ends its local session.
Browser redirects to Keycloak.
Keycloak invalidates authentication tokens.
Refresh tokens are revoked.
Browser session is cleared.
User returns to the login screen.

Single Logout (SLO) helps prevent situations where a user signs out of Wazuh but remains authenticated with the identity provider.

Prerequisites

Before configuring Keycloak as an identity provider for Wazuh, verify that both environments meet the necessary software, networking, and security requirements.

Spending a few minutes validating these prerequisites can prevent many of the authentication issues commonly encountered during deployment.

Supported Wazuh Version

OpenID Connect integration is supported in modern Wazuh releases that include external authentication capabilities through the Wazuh Dashboard.

Before proceeding:

Verify your Wazuh version.
Review the release notes for authentication-related changes.
Ensure all cluster nodes run the same version.
Upgrade older deployments if necessary.

Running unsupported or mixed versions may result in authentication failures or compatibility issues.

Related Guide: How to Upgrade a Wazuh Agent

Supported Keycloak Version

Use a supported and actively maintained Keycloak release.

Older versions may:

Use deprecated authentication flows
Lack newer security features
Have incompatible configuration interfaces
Receive limited security updates

Whenever possible, deploy the latest stable Long-Term Support (LTS) release recommended by the Keycloak project.

Administrative Access

You’ll need administrative privileges for both platforms.

Specifically, ensure you have:

Keycloak administrator account
Wazuh administrator account
Access to Wazuh configuration files
Access to restart Wazuh services
Permissions to modify RBAC settings
Access to DNS and certificate management if required

Without sufficient privileges, you may be unable to create clients, configure identity providers, or update authentication settings.

HTTPS Certificates

OIDC should always be deployed over HTTPS.

TLS certificates protect:

Login credentials
Authorization codes
JWT tokens
Session cookies
API communications

Using trusted certificates from a recognized Certificate Authority (CA) is strongly recommended for production environments.

Self-signed certificates may be acceptable for testing but often require additional trust configuration.

DNS Configuration

Reliable DNS resolution is essential because Wazuh redirects users to Keycloak during authentication.

Verify that:

The Keycloak hostname resolves correctly.
The Wazuh Dashboard hostname resolves correctly.
Reverse proxies resolve expected hostnames.
Public URLs match configured redirect URIs.

Hostname mismatches are a common cause of redirect and callback errors.

Time Synchronization (NTP)

JWT validation relies on accurate system clocks.

Ensure that:

Wazuh servers use NTP.
Keycloak servers use NTP.
Reverse proxies use synchronized time.
Virtual machines maintain accurate clocks.

Even small clock differences can cause newly issued tokens to appear expired or not yet valid.

Expert guidance from identity providers consistently recommends keeping clock drift within a few seconds to avoid token validation failures.

Network Connectivity

Verify that Wazuh can communicate with Keycloak.

Typical connectivity requirements include:

HTTPS connectivity between Wazuh and Keycloak
DNS resolution
Bidirectional communication where applicable
Access through reverse proxies or load balancers
Stable latency between systems

Simple connectivity tests using tools like curl or openssl s_client can quickly identify SSL or networking problems before configuration begins.

Firewall Requirements

Firewalls should permit the required HTTPS traffic between the relevant components.

Review firewall rules for:

Keycloak HTTPS port
Wazuh Dashboard
Reverse proxies
Load balancers
Internal security zones

Avoid exposing administrative interfaces directly to the public internet unless they are protected by additional security controls such as VPNs or access gateways.

Backup Existing Configuration

Before making authentication changes, create backups of your current configuration.

Recommended backups include:

Wazuh Dashboard configuration
Authentication settings
RBAC configuration
Keycloak realm export
Client configuration
TLS certificates

If an authentication issue occurs, backups allow you to restore a known-good configuration quickly and minimize downtime.

Related Guide: How to Backup Wazuh Manager Configuration

Prepare Your Keycloak Environment

Before configuring Wazuh, you’ll need to prepare Keycloak by creating a dedicated realm, registering Wazuh as an OpenID Connect client, defining users and roles, and configuring the token claims that Wazuh will use during authentication.

Keeping Wazuh isolated within its own realm simplifies administration and reduces the risk of configuration conflicts with other applications.

Create a Realm

A realm is the top-level container in Keycloak that isolates users, clients, roles, authentication flows, and security policies.

To create a new realm:

Log in to the Keycloak Administration Console.
Open the Realm selector.
Click Create Realm.
Enter a descriptive name (for example, wazuh or security).
Save the new realm.

Using a dedicated realm makes it easier to manage authentication settings independently from other applications.

Create a Confidential Client for Wazuh

Next, register Wazuh as a Confidential Client.

Confidential clients securely store a client secret and are intended for server-side applications like the Wazuh Dashboard.

When creating the client:

Client Type: OpenID Connect
Client Authentication: Enabled
Standard Flow: Enabled
Direct Access Grants: Disabled (unless specifically required)
Implicit Flow: Disabled
Service Accounts: Disabled unless needed

Using the Authorization Code Flow with a confidential client follows current OIDC security best practices.

Configure Redirect URIs

Redirect URIs specify where Keycloak can safely return users after authentication.

For Wazuh:

Add the exact Dashboard callback URL.
Include HTTPS.
Match hostname, port, and path exactly.
Avoid unnecessary wildcard entries in production.

An incorrect redirect URI is one of the most common causes of failed OIDC authentication.

Configure Web Origins

Web Origins control which browser origins may interact with the client.

Configure only the required Wazuh Dashboard origin.

For production environments:

Prefer explicit origins.
Avoid using *.
Include HTTPS.
Match the Dashboard URL exactly.

Restricting origins helps mitigate Cross-Origin Resource Sharing (CORS) risks.

Configure Client Authentication

Enable Client Authentication so that Wazuh authenticates itself when exchanging authorization codes for tokens.

This protects the token endpoint from unauthorized requests and ensures only the registered Wazuh client can obtain tokens.

Typical settings include:

Client Authentication: Enabled
Client Secret Authentication
Authorization Code Flow
PKCE (if supported and appropriate for your deployment)

Generate or Copy the Client Secret

After creating the confidential client, Keycloak generates a client secret.

You’ll need this value later when configuring Wazuh.

Treat the client secret like a password:

Store it securely.
Do not commit it to version control.
Rotate it periodically.
Replace it immediately if compromised.

Many organizations use dedicated secret management solutions such as HashiCorp Vault or cloud-native secret managers for production deployments.

Create Users

Create the users who will access Wazuh.

For each user, configure:

Username
Email address
First and last name
Initial password
Password reset requirements
MFA enrollment (if required)

Alternatively, users can be synchronized automatically from LDAP or Active Directory through Keycloak identity federation.

Create Groups

Groups simplify administration by allowing permissions to be assigned collectively rather than individually.

Examples include:

SOC Administrators
Security Analysts
Incident Response
Compliance
Read-Only Users

Users inherit permissions through their group memberships, reducing repetitive administrative work.

Create Roles

Roles define what users are allowed to do.

Example roles include:

wazuh_admin
wazuh_analyst
incident_responder
auditor
readonly

These roles will later be mapped to Wazuh’s internal RBAC roles.

Assign Roles to Users

Assign the appropriate roles directly to users or indirectly through groups.

For example:

User	Group	Assigned Role
Alice	SOC Administrators	`wazuh_admin`
Bob	Security Analysts	`wazuh_analyst`
Carol	Compliance	`auditor`
David	Incident Response	`incident_responder`

Using group-based assignments makes ongoing administration much more efficient as teams grow.

Configure Token Claims

Finally, configure the token claims that Wazuh will consume during authentication.

Common claims include:

sub
preferred_username
email
name
groups
roles
realm_access
resource_access

These claims allow Wazuh to identify users and map them to the appropriate RBAC roles.

Carefully review the claims included in your ID and access tokens to ensure they expose only the information required for authentication and authorization, following the principle of least privilege.

Configure Wazuh for Keycloak Authentication

With your Keycloak environment prepared, the next step is to configure the Wazuh Dashboard to use Keycloak as its OpenID Connect (OIDC) identity provider.

This involves enabling OIDC, specifying your Keycloak endpoints, configuring client credentials, and verifying that authentication works correctly.

The exact configuration parameters may vary slightly depending on your Wazuh version, but the overall process remains the same.

Locate the Authentication Configuration

The Wazuh Dashboard authentication settings are typically stored within the Dashboard configuration files.

Before making any changes:

Back up the existing configuration.
Document the current authentication settings.
Verify you have administrative access.
Confirm the Dashboard service can be restarted if required.

If your deployment uses configuration management tools such as Ansible or Puppet, update the source configuration rather than modifying files directly to avoid losing changes during future deployments.

Related Guide: How to Backup Wazuh Manager Configuration

Enable OpenID Connect

Enable OpenID Connect (OIDC) authentication within the Wazuh Dashboard configuration.

This tells Wazuh to delegate authentication requests to an external identity provider instead of relying solely on locally managed accounts.

When OIDC is enabled:

Users are redirected to Keycloak.
Keycloak authenticates the user.
Wazuh validates the returned tokens.
RBAC permissions are applied.
Access is granted according to assigned roles.

Most production environments disable local authentication for standard users after verifying that OIDC authentication is functioning correctly.

However, maintaining at least one emergency administrative account for disaster recovery is a recommended best practice.

Configure Issuer URL

The Issuer URL identifies the trusted identity provider.

Wazuh uses this URL to:

Verify the identity provider.
Validate JWT signatures.
Retrieve discovery metadata.
Confirm token issuer information.

The issuer URL should exactly match the value configured within the Keycloak realm.

Common mistakes include:

Missing HTTPS
Incorrect realm name
Trailing slash mismatches
Typographical errors
Using internal URLs instead of externally accessible URLs

Even minor differences can cause token validation to fail.

Configure Client ID

The Client ID identifies the Wazuh Dashboard application within Keycloak.

This value must exactly match the Client ID created when registering Wazuh as a confidential client.

Recommendations include:

Use descriptive names.
Keep the Client ID consistent across environments where practical.
Avoid unnecessary changes after deployment.

If the Client ID configured in Wazuh does not match the registered Keycloak client, authentication requests will be rejected.

Configure Client Secret

The Client Secret authenticates Wazuh when exchanging authorization codes for tokens.

Best practices include:

Store the secret securely.
Restrict file permissions.
Never expose the secret in screenshots or documentation.
Rotate secrets periodically.
Replace compromised secrets immediately.

Many organizations use centralized secret management platforms instead of storing secrets directly in configuration files.

Configure Discovery Endpoint

OpenID Connect supports automatic configuration through a Discovery Endpoint, which publishes authentication metadata.

This metadata includes:

Authorization endpoint
Token endpoint
UserInfo endpoint
JWKS endpoint
Supported scopes
Supported signing algorithms

Using discovery simplifies configuration because Wazuh can automatically retrieve the required endpoints instead of requiring each URL to be entered manually.

The OpenID Connect Discovery specification defines a standardized metadata format that improves interoperability between identity providers and client applications.

Configure Redirect URL

The Redirect URL tells Keycloak where users should return after successful authentication.

To avoid login failures:

Use HTTPS.
Match the configured Keycloak Redirect URI exactly.
Verify hostname and port.
Ensure reverse proxies preserve the correct host headers.
Test the callback URL from a browser.

Redirect URI mismatches are among the most common causes of OIDC configuration errors.

Configure Logout Endpoint

Configuring the logout endpoint allows Wazuh to participate in Single Logout (SLO).

A proper logout flow should:

End the Wazuh session.
Redirect users to Keycloak.
Invalidate authentication tokens.
Destroy refresh tokens.
Clear browser sessions.

Without a configured logout endpoint, users may appear logged out of Wazuh while still maintaining an active Keycloak session.

Restart Wazuh Services

After updating the authentication configuration, restart the affected Wazuh services so the changes take effect.

Depending on your deployment, this may include:

Wazuh Dashboard
Reverse proxy (if applicable)
Supporting authentication services

For clustered deployments, restart nodes according to your organization’s maintenance procedures to minimize user disruption.

After restarting, monitor service logs for startup errors before allowing users to authenticate.

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

Verify Configuration

Before rolling the integration into production, verify that authentication functions correctly.

A basic validation checklist includes:

User is redirected to Keycloak.
Login page loads successfully.
Authentication succeeds.
MFA is requested when required.
Tokens are issued.
Dashboard loads successfully.
Correct RBAC permissions are applied.
Logout invalidates the session.

Also test failure scenarios such as:

Invalid credentials
Expired passwords
Disabled accounts
Incorrect role assignments
Expired tokens
Network interruptions

Testing both successful and unsuccessful authentication paths helps identify configuration issues before they impact end users.

Configure Role-Based Access Control (RBAC)

Authenticating users through Keycloak only confirms their identity.

Wazuh’s Role-Based Access Control (RBAC) system determines what authenticated users are permitted to view and manage within the platform.

A well-designed RBAC strategy ensures users receive only the permissions necessary to perform their responsibilities, reducing the risk of accidental or malicious misuse.

Understanding Wazuh RBAC

Wazuh includes a built-in RBAC framework that controls access to:

Dashboard features
Agent management
Rule management
Decoder configuration
Alert investigation
API operations
Cluster administration
Index management

Authentication and authorization remain separate processes:

Keycloak verifies identity.
Wazuh authorizes actions.

This separation allows organizations to centralize authentication while retaining granular control over platform permissions.

Related Guide: Troubleshooting Wazuh RBAC

Mapping Keycloak Roles to Wazuh Roles

Keycloak roles or group memberships can be included within JWT claims.

Wazuh reads these claims and maps them to internal RBAC roles.

Example mapping:

Keycloak Role	Wazuh Role
`wazuh_admin`	Administrator
`soc_analyst`	SOC Analyst
`incident_response`	Incident Responder
`auditor`	Read-Only User
`threat_hunter`	Custom Threat Hunter

Using group-based mappings generally scales better than assigning permissions to individual users.

Whenever possible, manage access through organizational groups instead of user-specific assignments.

Administrator Access

Administrator accounts require unrestricted access to manage the Wazuh platform.

Typical permissions include:

Create and modify rules
Configure decoders
Manage agents
Configure integrations
Manage cluster settings
Create RBAC roles
View all alerts
Configure authentication

Because administrator accounts have extensive privileges, they should always be protected with MFA and closely monitored.

Limit administrator access to personnel with operational responsibility for the platform.

SOC Analyst Permissions

Most users only require analyst-level permissions.

SOC analysts typically need to:

Investigate alerts
Search security events
Review dashboards
Examine endpoint data
Launch investigations
View agent status

However, they generally do not require permission to:

Modify authentication
Delete agents
Change RBAC policies
Edit detection rules
Modify integrations

Restricting administrative functions reduces operational risk while allowing analysts to perform day-to-day monitoring.

Read-Only Users

Read-only roles are useful for users who need visibility without administrative capabilities.

Examples include:

Compliance auditors
Executive leadership
Risk management teams
External assessors
Security consultants

These users can:

View dashboards
Review alerts
Generate reports
Search historical data

They should not be able to modify any configuration or operational settings.

Custom Security Roles

Large organizations often require specialized roles beyond the default permission sets.

Examples include:

Role	Typical Responsibilities
Threat Hunter	Search historical telemetry and perform investigations
Incident Responder	Manage active incidents and containment actions
Detection Engineer	Develop rules and decoders
Platform Administrator	Maintain infrastructure and integrations
Compliance Officer	Review evidence and generate reports

Creating narrowly scoped custom roles improves security while allowing teams to work efficiently.

Least Privilege Principles

The Principle of Least Privilege (PoLP) recommends granting users only the permissions required to perform their assigned duties.

Applying PoLP within Wazuh helps:

Reduce insider threats
Limit accidental configuration changes
Minimize attack impact
Improve compliance
Simplify auditing

The U.S. National Institute of Standards and Technology (NIST) identifies least privilege as a fundamental access control principle in its cybersecurity guidance.

Review permissions regularly to ensure users do not retain unnecessary access as responsibilities change.

Testing Role Assignments

Always validate RBAC mappings before production deployment.

Test each role by:

Logging in as a representative user.
Confirming dashboard access.
Verifying visible menus.
Attempting authorized actions.
Attempting unauthorized actions.
Reviewing API permissions.
Confirming audit logs record authentication events.

Testing should also include negative scenarios to ensure unauthorized users cannot access privileged functions.

Enable Multi-Factor Authentication in Keycloak

One of the primary benefits of integrating Keycloak with Wazuh is the ability to enforce Multi-Factor Authentication (MFA) centrally.

Rather than configuring MFA separately within every application, administrators can define authentication policies once in Keycloak and apply them consistently across all integrated services.

This significantly strengthens account security by requiring users to present more than one form of authentication before accessing the Wazuh Dashboard.

Supported MFA Methods

Keycloak supports several authentication factors that can be combined to meet an organization’s security requirements.

Common MFA methods include:

Time-Based One-Time Passwords (TOTP)
WebAuthn passkeys
FIDO2 security keys
Hardware tokens
Smart cards
Recovery authentication codes
X.509 client certificates (where applicable)

Organizations often choose different methods for different user groups based on security requirements and available hardware.

Configure TOTP

Time-Based One-Time Passwords (TOTP) are the most commonly deployed MFA method in Keycloak.

Users typically enroll using an authenticator application that generates rotating verification codes.

The enrollment process generally involves:

User logs in.
Keycloak prompts for MFA enrollment.
User scans a QR code.
Authenticator generates verification codes.
User confirms a generated code.
TOTP becomes associated with the account.

Popular authenticator applications include:

Google Authenticator
Microsoft Authenticator
Authy
FreeOTP

Once enrolled, users provide both their password and a time-based verification code during login.

Enforce MFA Policies

Keycloak allows administrators to require MFA for selected users, groups, or entire realms.

Common enforcement strategies include:

Require MFA for all users.
Require MFA only for administrators.
Require MFA for privileged roles.
Require MFA for remote access.
Require MFA after password changes.
Require MFA for sensitive administrative functions.

For Wazuh deployments, administrator and SOC analyst accounts should generally be protected by mandatory MFA because of their access to sensitive security data.

Conditional MFA

Conditional MFA enables organizations to request additional authentication only when specific conditions are met.

Examples include:

Login from an unknown device
New geographic location
High-risk IP address
Administrative role
External network
Untrusted browser
Elevated security event

This risk-based approach improves usability while maintaining strong protection for higher-risk authentication attempts.

Recovery Methods

Users occasionally lose access to their MFA devices.

To avoid account lockouts, organizations should define secure recovery procedures.

Recovery options may include:

One-time recovery codes
Administrator-assisted recovery
Hardware backup security keys
Secondary enrolled authenticators
Identity verification procedures

Recovery mechanisms should be protected by strict administrative processes to prevent unauthorized account recovery.

User Enrollment

Successful MFA deployment depends on a smooth enrollment experience.

A recommended enrollment process includes:

User receives an account.
Initial password is set.
User logs in.
MFA enrollment is required.
Recovery methods are configured.
Enrollment is verified.
Access to Wazuh is granted.

Provide users with clear enrollment documentation and encourage them to register backup authentication methods where supported.

This reduces help desk requests and minimizes disruptions if a primary authenticator is lost or replaced.

Test the Integration

Before allowing users to authenticate through Keycloak in production, thoroughly test every stage of the authentication process.

Successful testing confirms that Keycloak and Wazuh communicate correctly, tokens are validated properly, RBAC permissions are applied as expected, and sessions are managed securely.

Testing should include both positive scenarios (valid logins) and negative scenarios (invalid credentials, expired tokens, incorrect role assignments, and revoked accounts).

Verify Login

The first step is confirming that users can successfully authenticate using their Keycloak credentials.

Verify the following:

Navigating to the Wazuh Dashboard redirects users to the Keycloak login page.
The correct Keycloak realm is displayed.
Valid credentials authenticate successfully.
Invalid credentials are rejected.
Multi-factor authentication (if enabled) is prompted.
Users are redirected back to the Wazuh Dashboard after successful authentication.

If authentication fails before the user reaches the Dashboard, examine both the Wazuh Dashboard logs and the Keycloak server logs for authentication or OIDC-related errors.

Verify Token Exchange

After authentication, Wazuh exchanges the authorization code for OpenID Connect tokens.

Confirm that:

The authorization code is issued successfully.
Wazuh receives the ID token.
Wazuh receives the access token.
Refresh tokens are issued (if configured).
Token signatures validate successfully.
Tokens contain the expected claims.

Inspecting the JWT payload using a JWT decoding tool (without exposing sensitive production tokens publicly) can help verify that required claims such as usernames, groups, and roles are present.

Verify Role Mapping

Authentication only confirms identity. The next step is ensuring authorization works correctly.

Create several test users with different Keycloak roles or group memberships.

Examples:

Test User	Expected Wazuh Role
Alice	Administrator
Bob	SOC Analyst
Carol	Read-Only User
David	Incident Responder

Verify that:

Correct RBAC roles are assigned.
Unauthorized permissions are denied.
Group membership changes are reflected after reauthentication.
Users cannot access administrative functions without the appropriate role.

Related Guide: Troubleshooting Wazuh RBAC

Verify Dashboard Access

After authentication, ensure users can access only the features appropriate for their assigned roles.

Examples include:

Administrator:

Manage agents
Configure rules
Modify integrations
Create RBAC roles

SOC Analyst:

Search alerts
Investigate incidents
View dashboards

Read-Only User:

View dashboards
Search alerts
Generate reports

Users should never see administrative menus unless explicitly authorized.

Verify Session Timeout

Session timeout testing ensures authentication sessions expire according to organizational security policies.

Test scenarios include:

Idle timeout
Maximum session lifetime
Refresh token expiration
Automatic logout after inactivity
Reauthentication requirements

Verify that users are prompted to authenticate again after the configured timeout period.

Shorter session lifetimes are generally recommended for privileged administrative accounts.

Verify Logout

A proper logout process should terminate sessions in both Wazuh and Keycloak.

Verify that:

Clicking Log Out ends the Wazuh session.
Keycloak invalidates authentication tokens.
Refresh tokens are revoked.
Browser cookies are cleared.
Revisiting the Dashboard requires authentication again.

If users can immediately access Wazuh without logging in again, the Keycloak session may still be active, indicating that Single Logout (SLO) is not configured correctly.

Common Integration Issues

Although integrating Keycloak with Wazuh is relatively straightforward, configuration mistakes involving URLs, certificates, tokens, or role mappings are common.

Understanding these issues can significantly reduce deployment time and simplify troubleshooting.

Invalid Redirect URI

Symptoms

Login fails immediately after authentication.
Keycloak displays an “Invalid Redirect URI” error.
Browser is redirected to an error page.

Possible causes

Redirect URI configured incorrectly.
Hostname mismatch.
Incorrect port number.
Missing HTTPS.
Typographical errors.
Trailing slash mismatch.

Resolution

Verify that the Redirect URI configured in Keycloak exactly matches the callback URL configured within the Wazuh Dashboard.

Even small differences, including capitalization or trailing slashes, can cause authentication to fail.

Client Authentication Failed

Symptoms

Token exchange fails.
HTTP 401 or HTTP 403 responses.
Authentication stops after login.

Possible causes

Incorrect Client ID.
Client Authentication disabled.
Wrong authentication method.
Confidential client configured incorrectly.

Resolution

Confirm that:

The Client ID matches exactly.
Client Authentication is enabled.
The client is configured as a Confidential Client.
Authorization Code Flow is enabled.

Invalid Client Secret

Symptoms

Authorization succeeds.
Token exchange fails.
Invalid client credentials error appears.

Possible causes

Incorrect secret copied.
Secret rotated but not updated.
Leading or trailing whitespace.
Configuration file formatting issues.

Resolution

Generate a new client secret if necessary and update the Wazuh configuration.

Store secrets securely and avoid manually retyping them whenever possible.

Unable to Discover OIDC Configuration

Symptoms

Metadata retrieval fails.
Discovery endpoint errors.
Authentication initialization fails.

Possible causes

Incorrect discovery URL.
DNS resolution failures.
Firewall restrictions.
HTTPS certificate errors.
Reverse proxy configuration issues.

Resolution

Open the discovery endpoint in a browser or use a command-line tool such as curl to verify that the metadata document is accessible and returns valid JSON.

Token Validation Errors

Symptoms

Login succeeds.
Access immediately fails.
Invalid token errors appear.

Possible causes

Incorrect issuer URL.
Expired tokens.
Audience mismatch.
Invalid signature.
Incorrect realm configuration.
Clock drift.

Resolution

Verify:

Issuer URL
Audience
Client ID
Signing keys
System time
Token expiration settings

Review JWT claims carefully to identify mismatched values.

SSL Certificate Problems

Symptoms

TLS handshake failures.
Discovery endpoint inaccessible.
Certificate validation errors.
Browser trust warnings.

Possible causes

Self-signed certificates.
Expired certificates.
Missing intermediate CA certificates.
Incorrect hostname.
Certificate chain issues.

Resolution

Deploy trusted TLS certificates and ensure the complete certificate chain is installed on the Keycloak server or reverse proxy.

Use tools such as OpenSSL to validate certificate chains during troubleshooting.

Clock Synchronization Issues

Symptoms

Newly issued tokens appear expired.
Tokens are reported as “not yet valid.”
Authentication fails intermittently.

Possible causes

Unsynchronized servers.
Incorrect system clocks.
Virtual machine time drift.
NTP service failures.

Resolution

Configure Network Time Protocol (NTP) on:

Keycloak servers
Wazuh servers
Reverse proxies
Virtual machines

Time synchronization should be monitored continuously in production environments.

Users Cannot Log In

Symptoms

Authentication consistently fails.
Login page reloads.
Users receive access denied messages.

Possible causes

Disabled user account.
Incorrect password.
Missing realm roles.
Expired password.
User not assigned to required groups.
Identity federation synchronization issues.

Resolution

Verify:

User account status
Password validity
Group membership
Assigned roles
Realm configuration
Identity provider synchronization

Incorrect Role Mapping

Symptoms

Users authenticate successfully.
Dashboard loads.
Permissions are missing or incorrect.

Possible causes

Missing JWT claims.
Incorrect role mapping.
Wrong claim names.
Group mapper misconfiguration.
RBAC mapping errors.

Resolution

Inspect the ID token and access token to ensure the expected role or group claims are present, then verify that Wazuh is configured to map those claims correctly.

Related Guide: Troubleshooting Wazuh RBAC

Login Redirect Loop

Symptoms

Browser repeatedly redirects between Wazuh and Keycloak.
Users never reach the Dashboard.

Possible causes

Invalid session cookies.
Redirect URI mismatch.
Proxy header misconfiguration.
Cookie SameSite settings.
Authentication callback failures.

Resolution

Check:

Reverse proxy configuration
Redirect URLs
Cookie settings
Browser developer tools
Authentication logs

Redirect loops are frequently caused by proxy or cookie configuration rather than OIDC itself.

Related Gide: Fixing Wazuh API SameSite Cookie Errors

Logout Does Not End Session

Symptoms

User logs out.
Dashboard immediately logs back in.
Authentication appears to persist.

Possible causes

Single Logout not configured.
Refresh tokens remain valid.
Browser cookies not cleared.
Keycloak session remains active.

Resolution

Configure the appropriate logout endpoint in Wazuh, verify that Keycloak invalidates refresh tokens, and confirm browser cookies are removed during logout.

Security Best Practices

A Keycloak-Wazuh integration centralizes authentication, but its security depends on proper configuration and ongoing maintenance.

The following best practices help reduce the risk of credential compromise, unauthorized access, and configuration errors while supporting compliance requirements.

Always Use HTTPS

All communication between users, Wazuh, reverse proxies, and Keycloak should be protected with TLS.

HTTPS encrypts:

User credentials
Authorization codes
JWTs
Session cookies
API traffic

Never deploy production authentication services over unencrypted HTTP.

The Open Worldwide Application Security Project (OWASP) recommends HTTPS for all authentication-related traffic to protect against interception and session hijacking.

Protect Client Secrets

Treat the Client Secret like any other privileged credential.

Recommendations include:

Store secrets in a dedicated secrets manager.
Restrict filesystem permissions.
Never include secrets in Git repositories.
Avoid sharing secrets through email or chat.
Rotate secrets when administrators change roles.

Compromised client secrets can allow unauthorized applications to impersonate trusted clients.

Rotate Credentials Regularly

Credential rotation limits the impact of compromised authentication material.

Develop a rotation schedule for:

Client secrets
Administrative passwords
Service account credentials
API keys
TLS certificates

Automating credential rotation where possible reduces operational overhead while improving security.

Enable MFA

Multi-Factor Authentication (MFA) significantly reduces the risk of account compromise caused by stolen passwords.

Prioritize MFA for:

Wazuh administrators
SOC analysts
Incident responders
Privileged service accounts (where applicable)

The U.S. Cybersecurity and Infrastructure Security Agency (CISA) identifies MFA as one of the most effective safeguards against credential-based attacks.

Enforce Strong Password Policies

Even with MFA, strong passwords remain essential.

Configure Keycloak password policies that require:

Sufficient minimum length
Complexity requirements where appropriate
Password history enforcement
Protection against common or breached passwords
Account lockout after repeated failures

Avoid overly complex policies that encourage predictable password reuse or insecure storage.

Use Short-Lived Access Tokens

Access tokens should remain valid only for the minimum time necessary.

Benefits include:

Reduced replay attack window
Lower impact of stolen tokens
Improved session security

Organizations commonly configure relatively short-lived access tokens while relying on refresh tokens for longer user sessions.

Configure Refresh Token Policies

Refresh tokens should be governed by clear security policies.

Consider configuring:

Maximum refresh lifetime
Refresh token rotation
Token revocation on logout
Automatic expiration after inactivity
Session revocation after password changes

These controls help prevent long-lived sessions from being abused.

Limit Administrative Accounts

Administrative accounts should be kept to an absolute minimum.

Recommendations include:

Separate administrator and analyst accounts.
Avoid shared administrative accounts.
Require MFA.
Monitor privileged activity.
Review administrator access periodically.

Using dedicated administrative accounts improves accountability and auditability.

Audit Authentication Events

Authentication logs provide valuable insight into user activity and potential security incidents.

Monitor events such as:

Successful logins
Failed logins
MFA failures
Password changes
Session creation
Session termination
Role modifications
Administrative actions

These logs can support incident response investigations and compliance reporting.

Related Guide: How to Configure Wazuh Audit Logs

Monitor Failed Login Attempts

Repeated authentication failures may indicate:

Password spraying
Credential stuffing
Brute-force attacks
Misconfigured clients
Automated attack tools

Configure alerts within Wazuh to notify administrators when authentication thresholds are exceeded.

Related Guide: Wazuh Brute Force Detection Guide

Review Role Assignments Regularly

User responsibilities change over time, making periodic access reviews essential.

Conduct regular audits to:

Remove unnecessary permissions.
Disable inactive accounts.
Verify group memberships.
Confirm least-privilege access.
Review privileged roles.

Scheduled reviews reduce the likelihood of excessive or outdated permissions remaining in place.

Keep Keycloak and Wazuh Updated

Regular updates ensure both platforms receive the latest security patches, bug fixes, and protocol improvements.

Establish a maintenance process that includes:

Monitoring security advisories
Testing updates in a staging environment
Applying supported releases promptly
Verifying authentication after upgrades
Reviewing release notes for configuration changes

Keeping both Keycloak and Wazuh current helps protect against known vulnerabilities while maintaining compatibility with evolving authentication standards.

Performance and High Availability Considerations

A production Keycloak-Wazuh deployment should be designed with availability, scalability, and reliability in mind.

Authentication becomes a critical dependency once Wazuh relies on Keycloak as its identity provider.

If Keycloak becomes unavailable, users may be unable to access the Wazuh Dashboard, even if the Wazuh infrastructure itself remains healthy.

Enterprise deployments should treat identity infrastructure as a highly available security service by implementing redundancy, monitoring, backup strategies, and proper scaling practices.

Deploy Redundant Keycloak Instances

A single Keycloak server creates a single point of failure.

For production environments, deploy multiple Keycloak instances behind a load balancer.

A highly available Keycloak architecture typically includes:

Multiple Keycloak application nodes
Shared database backend
Load balancer
Distributed session management
Health monitoring
Automated failover

A redundant deployment ensures authentication remains available during:

Server maintenance
Hardware failures
Software upgrades
Unexpected outages

For enterprise SOC environments where analysts require continuous access to security monitoring systems, authentication availability is just as important as Wazuh availability.

Configure Load Balancing

A load balancer distributes authentication requests across multiple Keycloak nodes.

Common load balancer responsibilities include:

Traffic distribution
Health checks
TLS termination
Failover handling
Connection management

Recommended health checks should verify that Keycloak is:

Running successfully
Accepting HTTPS requests
Able to communicate with its database
Returning valid responses

Popular load balancing solutions include:

HAProxy
NGINX
Apache HTTP Server
Cloud-native load balancers

Ensure that the URL configured in Wazuh points to the load-balanced Keycloak endpoint rather than an individual Keycloak node.

Session Persistence Considerations

Session handling is an important consideration when multiple Keycloak nodes are deployed.

Keycloak supports distributed session management, allowing users to authenticate through different nodes while maintaining active sessions.

However, environments using external load balancers should properly configure:

Sticky sessions when required
Session replication
Shared caches
Consistent hostname configuration

Poor session configuration may cause:

Repeated login prompts
Authentication failures
Unexpected session expiration
Redirect loops

For large deployments, use Keycloak’s recommended clustering architecture rather than relying only on load balancer persistence.

Token Caching

Token caching reduces unnecessary authentication requests and improves performance.

Caching strategies may include:

Access token reuse
Refresh token management
Session caching
Distributed cache configuration

Benefits include:

Lower authentication latency
Reduced Keycloak workload
Improved user experience
Better scalability

However, tokens should not remain valid longer than necessary. Security requirements should always determine token lifetime settings.

Authentication Latency

Authentication performance depends on several components:

User location
Network latency
Keycloak server capacity
Database response time
MFA provider response time
Load balancer performance
Token processing overhead

Slow authentication can affect:

SOC analyst productivity
Incident response speed
Dashboard availability
User experience

To reduce authentication latency:

Deploy Keycloak close to Wazuh infrastructure.
Optimize database performance.
Use efficient token lifetimes.
Monitor authentication response times.
Scale Keycloak nodes as user volume increases.

Scaling Large Environments

Large organizations may have hundreds or thousands of Wazuh users across multiple teams.

Scaling considerations include:

Number of concurrent users
Authentication requests per second
Number of realms
Number of clients
Role complexity
Database performance
MFA transaction volume

Enterprise environments should load test authentication workflows before production deployment.

Testing should simulate:

Multiple simultaneous logins
Peak SOC activity periods
MFA verification requests
User provisioning events
Token refresh operations

Database Availability

Keycloak stores important identity information in its database, including:

Users
Groups
Roles
Clients
Sessions
Authentication settings

A database outage can prevent users from authenticating.

Production deployments should consider:

Database replication
Automated backups
High availability database clusters
Monitoring database performance
Disaster recovery procedures

Common enterprise database platforms used with Keycloak include PostgreSQL and other supported relational databases.

Backup and Disaster Recovery

Identity infrastructure should be included in disaster recovery planning.

Back up:

Keycloak realms
Users
Client configurations
Roles
Authentication policies
MFA configurations
Database contents
TLS certificates

Recovery testing is equally important.

A backup strategy is only effective if the organization can successfully restore Keycloak and restore authentication services during an outage.

Monitoring Authentication Services

Authentication services should be monitored like any other security-critical application.

Monitor:

Keycloak availability
Authentication failures
Login latency
Database health
Certificate expiration
Token errors
Failed MFA attempts
Unusual authentication patterns

Security teams can integrate Keycloak logs into Wazuh to create detections for suspicious identity activity.

Examples include:

Multiple failed administrator logins
Authentication attempts from unusual locations
Disabled accounts attempting access
Privilege escalation attempts

Related Guide: How to Configure Wazuh Audit Logs

Real-World Example

A large enterprise organization operates a Security Operations Center (SOC) responsible for monitoring thousands of endpoints, cloud workloads, and network devices using Wazuh.

The SOC includes security analysts, incident responders, threat hunters, compliance teams, and platform administrators.

Previously, users accessed the Wazuh Dashboard using locally managed accounts.

As the security team expanded, administrators faced challenges maintaining user accounts, enforcing consistent security policies, and removing access when employees changed roles.

To solve these challenges, the organization integrated Keycloak with Wazuh to centralize authentication.

Creating a Dedicated Keycloak Environment

The security team creates a dedicated Keycloak realm specifically for security operations.

The realm contains:

Wazuh Dashboard client configuration
SOC user accounts
Security groups
Authentication policies
MFA requirements
Role mappings

Separating Wazuh authentication into its own realm prevents configuration conflicts with other enterprise applications and simplifies administration.

Configuring OIDC Authentication

The organization registers Wazuh as an OpenID Connect client inside Keycloak.

The security team configures:

Confidential client authentication
Authorization Code Flow
Redirect URIs
Client secrets
Discovery endpoints
Token claims

When analysts access the Wazuh Dashboard, they are automatically redirected to Keycloak for authentication.

After successful login:

Keycloak verifies the user’s identity.
MFA is performed.
Tokens are generated.
Wazuh validates the tokens.
Dashboard access is granted.

This provides analysts with a seamless Single Sign-On experience.

Mapping Keycloak Groups to Wazuh RBAC Roles

The organization creates Keycloak groups based on job responsibilities.

Example:

Keycloak Group	Wazuh Permission
SOC Administrators	Full administrative access
Security Analysts	Alert investigation access
Incident Responders	Incident management permissions
Compliance Team	Read-only reporting access

Users receive permissions automatically based on their group membership.

This eliminates manual permission assignment inside Wazuh and ensures access follows organizational roles.

Enabling Multi-Factor Authentication

Because Wazuh contains sensitive security information, the organization requires MFA for all SOC users.

Keycloak enforces:

TOTP authentication
Hardware security keys for administrators
Strong authentication policies
Account protection controls

MFA policies are managed centrally, allowing the organization to protect Wazuh without implementing separate MFA systems.

Enforcing Conditional Access Policies

The organization implements conditional access controls to increase security.

Examples include:

Requiring MFA for administrator accounts.
Blocking authentication from unknown locations.
Requiring additional verification for privileged actions.
Restricting access from unmanaged devices.
Monitoring unusual authentication behavior.

These policies strengthen security while maintaining a smooth experience for normal SOC operations.

Validating Permissions Before Production Deployment

Before enabling the integration for all users, the security team performs extensive testing.

They validate:

Administrator access
Analyst permissions
Read-only access
MFA enrollment
Token claims
Session expiration
Logout behavior
Failed authentication scenarios

Testing confirms that users receive the correct permissions and prevents accidental over-privileged access.

Operational Benefits After Deployment

After deploying Keycloak authentication, the organization achieves several improvements:

Simplified administration

Security administrators manage users and permissions from a central identity platform instead of maintaining separate Wazuh accounts.

Improved security

MFA, centralized policies, and stronger authentication controls reduce the risk of account compromise.

Faster provisioning and deprovisioning

New analysts receive access through group membership, while departing employees can be disabled immediately.

Better compliance

Centralized authentication logs and access controls simplify audits for frameworks such as SOC 2, ISO 27001, and NIST-based security programs.

Seamless user experience

Analysts authenticate using existing enterprise credentials while maintaining secure access to Wazuh.

Frequently Asked Questions

Question: Can Wazuh integrate directly with Keycloak?

Yes. Wazuh can integrate with Keycloak by using OpenID Connect (OIDC) authentication.

Keycloak acts as the external identity provider while Wazuh handles authorization through its internal RBAC system.

Question: Does Wazuh use OpenID Connect or SAML with Keycloak?

Wazuh can integrate with external identity providers using supported authentication protocols. For Keycloak deployments, OpenID Connect is commonly used because it is designed for modern web applications and uses lightweight token-based authentication.

SAML may also be appropriate in environments that already rely on enterprise SAML-based identity systems.

Question: Can I enable single sign-on for the Wazuh Dashboard?

Yes. Integrating Keycloak with Wazuh enables Single Sign-On (SSO), allowing users to authenticate through Keycloak instead of managing separate Wazuh credentials.

Question: How do I map Keycloak roles to Wazuh RBAC roles?

Keycloak roles or groups can be included in OIDC token claims. Wazuh reads these claims and maps them to internal RBAC permissions.

A common approach is:

Create groups in Keycloak.
Assign users to groups.
Include group claims in tokens.
Map claims to Wazuh roles.
Test permissions.

Question: Does Keycloak support multi-factor authentication for Wazuh?

Yes. Keycloak provides centralized MFA capabilities, including TOTP, WebAuthn, and security keys.

Once MFA is configured in Keycloak, users authenticating to Wazuh can be required to complete MFA before accessing the Dashboard.

Question: What happens if the Keycloak server becomes unavailable?

If Keycloak becomes unavailable, new users may be unable to authenticate to Wazuh.

Existing sessions may continue until their tokens expire, depending on session configuration.

For production deployments, use:

Multiple Keycloak nodes
Load balancing
Database redundancy
Monitoring
Disaster recovery procedures

Question: Can multiple Keycloak realms be used with Wazuh?

A single Wazuh deployment typically authenticates against a configured identity provider endpoint.

Organizations with multiple realms may need additional architecture considerations, such as separate clients, identity federation, or dedicated authentication endpoints.

Question: How do I troubleshoot OIDC login failures?

Common troubleshooting steps include:

Verify Keycloak discovery endpoint availability.
Check Redirect URI configuration.
Validate Client ID and Client Secret.
Review token claims.
Check TLS certificates.
Verify system time synchronization.
Review Wazuh and Keycloak logs.

Authentication logs are usually the fastest way to identify the failure point.

Question: Keycloak integration supported in clustered Wazuh deployments?

Yes. Keycloak authentication works with clustered Wazuh deployments.

Large environments should ensure:

All Dashboard nodes use consistent authentication configuration.
Keycloak remains highly available.
Load balancers are configured correctly.
Session handling is tested.

Related Guide: How to Build a Wazuh Indexer Cluster

Question: How do I securely rotate the Keycloak client secret?

To rotate the client secret:

Generate a new secret in Keycloak.
Update the Wazuh authentication configuration.
Restart affected services.
Test authentication.
Revoke the old secret.

Perform rotations during maintenance windows and always verify access afterward.

Conclusion

Integrating Keycloak with Wazuh provides organizations with a centralized, secure, and scalable authentication solution for security monitoring environments.

By connecting Wazuh to Keycloak through OpenID Connect, organizations can replace isolated user accounts with centralized identity management while gaining powerful capabilities such as:

Single Sign-On (SSO)
Multi-factor authentication
Centralized user lifecycle management
Enterprise RBAC integration
Improved auditing
Stronger access controls

The integration process involves preparing Keycloak, creating an OIDC client, configuring Wazuh authentication, mapping roles, enabling MFA, and validating permissions before production rollout.

However, successful deployment requires ongoing maintenance.

Security teams should regularly review role assignments, monitor authentication activity, rotate credentials, maintain updated software versions, and test disaster recovery procedures.

When properly implemented, a Keycloak-Wazuh integration gives organizations a seamless authentication experience while strengthening security, simplifying administration, and supporting modern compliance requirements.