Wazuh SSO with SAML identity providers guide

Why Wazuh SSO with SAML needs more planning than the login screen suggests

Wazuh supports SAML single sign-on alongside its internal user database, so a security team running self-hosted Wazuh can move analysts onto the corporate identity provider and retire shared local accounts. The work itself is mainly identity trust, group-to-role mapping and access testing. The login redirect is the smallest part of the project, and the decisions that determine whether access is correct and provable sit around it.

The first hard part is agreeing the attribute and group claims with the identity team before anyone configures the dashboard. Wazuh can only assign administrator or read-only roles from what the identity provider actually sends in the SAML assertion, so the team needs to confirm which attribute carries the username, whether group membership is included at all, how group names are formatted, and whether nested or inherited groups are flattened. Documented guides exist for Okta, Microsoft Entra ID, PingOne, Google Workspace, JumpCloud, OneLogin, Keycloak and authentik. Confirm the exact steps and field names against the single sign-on guide for your Wazuh version on the 4.14 line, because vendor-specific settings differ and the guide is the source to follow.

The second decision is who keeps local break-glass access. Retiring shared accounts does not mean deleting every local account, because an administrator path has to survive an identity provider outage, a certificate expiry or a bad mapping change. Decide how many break-glass accounts exist, who owns their credentials, where those credentials are stored, what conditions justify using them, and how each use is recorded and reviewed. Rotate the password after every use and test the account on a schedule, so the team knows it works when the identity provider is unavailable.

The third task is proving that removing a user at the identity provider removes dashboard access. Test this with a pilot account in each role: disable the account, remove it from the admin group and remove it from the read-only group, then confirm what happens to an active session and to a new login attempt. Session and token lifetimes are set by configuration on both sides, so ask the identity team and the Wazuh administrators to agree on acceptable maximums. Include users who belong to several groups, and keep the test results as evidence for access reviews.

Which Wazuh components and identity pieces the SAML login touches

A SAML login with Wazuh involves three sides: the Wazuh dashboard, the Wazuh server and indexer behind it, and the identity provider that holds users and groups. Each side must supply specific information to the others before a user can sign in and receive the right role.

Wazuh dashboard as service provider

The Wazuh dashboard is the web interface that acts as the SAML service provider. It receives the signed assertion from the identity provider after the user authenticates there. Before go-live, confirm which service provider details the dashboard expects, such as its entity identifier and assertion consumer address, and register exactly those values in the identity provider. A mismatch here is the most common reason a login fails before any role is checked.

Wazuh server as the role-aware back end

The Wazuh server analyzes agent data with decoders and rules and also manages users and roles used by the dashboard. When a SAML login completes, the role decision is applied against what the server knows about that user. Plan how group membership from the identity provider maps to the administrator and read-only roles on the server, and test each mapping with a sample account before granting access to real staff.

Wazuh indexer as the alert data store

The Wazuh indexer stores alerts and is the full-text search and analytics engine behind the dashboard views. SSO does not move alert data, but the dashboard reads from the indexer on every session, so a user who signs in successfully still sees nothing if the indexer is unavailable. Include the indexer in login testing and confirm that access controls on alert data follow the roles you assign.

Identity provider as the source of users

The identity provider, such as Okta, Microsoft Entra ID or Keycloak, is the authoritative source for who may sign in and whether an account is active. Disabling a user there should stop new Wazuh sessions, but confirm how existing dashboard sessions expire. Document which identity provider tenant or realm serves the Wazuh application so that account lifecycle changes have a clear owner.

Signing metadata and certificate from the IdP

The identity provider supplies its metadata and signing certificate, which the Wazuh dashboard uses to verify that assertions are genuine and unmodified. Certificates expire, so record the expiry date, the owner who renews it, and the steps to load a new certificate into Wazuh. A certificate rollover that is not planned is a common cause of sudden login outages.

Group and attribute claims for role membership

Role membership reaches Wazuh as group or attribute claims inside the SAML assertion. The identity provider must release the claim your mapping expects, with values that match the group names configured on the Wazuh side. Verify the exact claim name and format in a test assertion, because a claim that is present but named differently will silently fall back to a default role or no role.

Which SSO path and role model fit your environment

This table compares three sign-in paths for the Wazuh dashboard and two ways to assign roles, then sets out when each fits and what it costs to run. Read each row against your emergency access rules and how your identity provider already groups people. The main takeaway is that mapping roles from identity provider groups usually gives the clearest audit trail, but only if the groups themselves are governed.

Option	When it fits	Operational cost	Audit clarity and admin effort
SAML only with local break-glass admin accounts	Regulated teams that must keep a documented emergency account for use when the identity provider or SAML login is unavailable	A second credential set to create, store, rotate and review, plus a tested procedure for when it is used	Clear for daily access through the identity provider, but every break-glass login needs its own review trail
SAML with a small set of mapped roles	Teams with a few administrator and read-only needs that map cleanly to existing identity provider groups	Group names and claim mappings to maintain whenever the identity provider changes, and a test login after each change	Strong audit clarity when group membership is reviewed in the identity provider; moderate effort to keep mappings aligned
Fully federated model with no local users	Organizations that require every human login to pass through the identity provider and accept the risk of depending on it for access	No local fallback, so identity provider outages or misconfigured SAML settings can lock out all administrators until recovery	Simplest single source of truth, with the lowest ongoing administration effort, but the highest recovery dependency
Map roles from identity provider groups	Organizations that already manage access through groups and run periodic access reviews in the identity provider	Upfront agreement on group names, plus governance so that group owners request changes through the same process as other applications	Strongest audit trail, because role assignment and removal are recorded where access reviews already happen
Assign roles manually in Wazuh after first login	Small teams with few users, or environments where the identity provider cannot yet provide suitable group claims	Each new user needs an administrator action in the dashboard, and departures must be removed in Wazuh as well	Easy to start, but role history lives in Wazuh and is easy to miss during reviews, so evidence needs a separate record
Confirm the group claim and attribute names before build	All paths that map roles from groups	Requires the identity provider administrator and the Wazuh owner to agree on claim format and test users early	Prevents silent mismatches where users sign in with the wrong or no role
Test break-glass login on a schedule	Any option that keeps local accounts	Recurring effort to rehearse emergency access and record the result	Provides evidence that the emergency path works, which assessors commonly ask to see

How to wire a SAML identity provider to the Wazuh dashboard

This sequence connects the Wazuh dashboard to your SAML identity provider so that users sign in with corporate credentials and receive administrator or read-only access based on their group membership. Each step ends with a check, so you know the integration works before you retire shared or local accounts.

Agree the identity provider application and claims
Work with the identity team to create or select a SAML application for the Wazuh dashboard. Agree the entity identifier, the assertion consumer URL for your dashboard hostname, the name identifier format, and the attribute or claim name that carries group membership. Record each value in a shared worksheet, because the same strings must match on both sides. The step is done when the identity team confirms the application exists in a test tenant and the claim names are written down. Confirm the exact field names against the Wazuh single sign-on documentation for your release, since names can differ between versions and between identity providers.
Collect the identity provider metadata and certificate
Export the SAML metadata document or the individual values from the identity provider, including the single sign-on URL, the entity identifier of the identity provider, and the public signing certificate. Store the certificate as a file on the Wazuh dashboard host with restrictive file permissions. Check the certificate's expiry date and record who receives renewal notices, because an expired signing certificate will stop all logins. The step is done when you can open the metadata and confirm each value matches what the identity team sent.
Configure the SAML settings on the Wazuh side
Following the Wazuh single sign-on guide for your chosen identity provider, add the SAML settings to the dashboard and security configuration, including the identity provider entity identifier, the single sign-on URL, the certificate reference, and the service provider values for the dashboard. Apply the change through the documented procedure for your installation method and restart or reload the components the guide names. The step is done when the dashboard shows a single sign-on option on its login page and the configuration validates without errors in the logs.
Map identity provider groups to dashboard roles
Create the mapping from the group values in the SAML assertion to the Wazuh administrator and read-only roles. Use the group identifiers the identity provider actually emits, not display names, which are often different. Keep the mapping in version-controlled configuration where possible so that changes are reviewed. The step is done when you have a written table showing each group, the role it grants and the owner who approves membership. Test the mapping only after the next step, when real assertions are available to compare against.
Configure a break-glass local administrator
Before enabling SAML for all users, create at least one local administrator account in the Wazuh internal user database that is not used for daily work. Store its credentials in your privileged credential vault, set a documented procedure for when it may be used, and make sure its use generates an alert or an audit record. Confirm that this account still signs in with the local login form, so that an identity provider outage or misconfiguration does not lock every administrator out. The step is done when the account logs in successfully and the vault entry is recorded.
Run the first login and verify role assignment
Sign in with a test user who belongs to the administrator group and confirm the dashboard shows the administrator role. Repeat with a read-only group member and confirm the restricted view. Inspect the SAML assertion the identity provider sends during the test to verify the expected groups arrive under the claim name you configured. Finally, sign in with a user who is in neither group and confirm access is refused. The step is done when all three outcomes match the mapping table, and the results are recorded for your change review.

How identity provider groups map to administrator and read-only roles

The mapping decides who can administer Wazuh and who can only look at alerts, so it is the access control decision that matters most after the SAML connection itself works. The model is simple. The identity provider (IdP) sends the user's group membership as attribute values inside the SAML assertion. The Wazuh dashboard compares those values with the role mappings configured on its side, and the user receives the permissions of every role that matches at login. Nothing else in the assertion grants access, so the group values are the whole basis for privilege. Before you configure anything, confirm in your release's single sign-on documentation how the group attribute is named, how role mappings are entered, and which roles exist. Do not assume a role list from another version or from a sibling deployment.

Naming discipline in the IdP is where most mapping problems start. Create dedicated groups for Wazuh access, with names that state the role and the platform, and assign only the people who need that role. Avoid reusing broad corporate groups such as all engineers or all staff, because a group that exists for another purpose will eventually grant Wazuh access to people who were never meant to have it. Keep administrator and read-only groups separate, and keep the group names stable, since renaming a group in the IdP silently breaks the match and can lock out the team that depends on it. Record the group object identifiers as well as the display names, so a rename in one system does not become an unnoticed change in the other.

A user who belongs to more than one mapped group receives the combined permissions of all matched roles, so a read-only user who is also placed in an administrator group becomes an administrator. Decide in advance whether any roles are mutually exclusive, and enforce that in the IdP rather than trusting users to behave. Review nested group membership too, because a group that contains another group can carry memberships you did not intend. The access review for Wazuh should list every mapped group and every user who holds more than one of them, and it should be repeated on a schedule your own policy sets. Ask the implementer to show you how the chosen IdP exposes nested membership in the assertion, since some configurations flatten it and others do not.

A user with no mapped group should be denied access, not placed in a default role. Confirm how your release behaves when the assertion contains no matching value, because the safe outcome depends on the configuration, and test it explicitly with an account that has no Wazuh group. Also test an account that holds only an unrelated group, since that is the common real-world case after a reorganization. Before widening access, run a pilot with a small group of named users who represent each intended role. Check that administrators can perform administrative actions, that read-only users cannot change configuration, and that removing a user from a group takes effect at their next login. Record the results, including any failed case and its fix, before adding more users.

Record the final mapping as an access control artifact that an auditor can read without help. A useful record lists each IdP group, its object identifier, the Wazuh role it maps to, the approver, the date it was approved, the pilot evidence, and the review owner. Keep the IdP configuration export, the Wazuh role mapping settings, and the test results together under change control, so a later change shows up as a new version with an approval. Auditors will ask who can administer the SIEM and how that is controlled, and a current, versioned mapping with its review history answers those questions directly. Confirm with your assessor which evidence format and retention period they expect, because those requirements come from your framework and your own policy, not from this guide.

How SSO setup differs by deployment model

In a single node or all-in-one installation, the Wazuh dashboard usually runs on the same host as the indexer and server, so the dashboard URL is one hostname that users reach directly. The SAML assertion consumer URL and the entity ID must match that hostname exactly, including scheme and port. Certificate trust is simpler because there is one dashboard certificate to present to the browser and to the identity provider's metadata validation, but that certificate still has to chain to a authority the identity provider and user devices trust.

What to check:

The exact external dashboard URL, including port, as users will type it
Whether the dashboard certificate's subject name matches that URL
Which DNS record resolves the hostname and whether internal resolvers answer it
Whether the identity provider can reach the dashboard callback path over the network
Who owns the identity provider application and can register the new redirect URI

Confirm these with the platform owner before changing the SAML settings, because a single mismatch in the callback URL is the most common cause of failed sign-in on this model.

Securing the SAML trust, certificates and break-glass access

Single sign-on moves the authentication decision to the identity provider, so the SAML trust, the signing certificates and the people who can change them become the controls that matter most. The cards below cover what to check at go-live and what must be reviewed on a schedule after it. Each one addresses a point where a misconfiguration could grant access that the Wazuh dashboard cannot detect on its own.

Certificate ownership and rotation

Name a single owner for the SAML signing certificate that Wazuh trusts and record its expiry date and the rotation procedure in your change system. An expired or unplanned certificate change can lock out every administrator at once. Confirm with your identity provider how it notifies you before expiry and whether it supports overlapping certificates so Wazuh can be updated without a login outage.

Assertion signature and audience checks

Confirm that Wazuh accepts only assertions signed by the expected identity provider certificate and that the audience restriction matches the Wazuh service provider entity ID exactly. Assertions that are unsigned, signed with another key or addressed to a different audience should fail. Test these cases with deliberately altered sample assertions in a non-production environment before go-live, and record the results.

Restricting who edits SAML and roles

Limit the ability to change SAML settings, role mappings and the local administrator account to a small named group, separate from people who only use the dashboard. Changes to the trust or to group-to-role mappings effectively change who is an administrator, so they deserve the same approval as a privileged access grant. Review the list of editors whenever staff change roles.

Break-glass local administrator

Keep at least one local administrator account in the Wazuh internal user database for use when the identity provider, the network path or the SAML configuration fails. Store its credential under dual control, for example split between two officers or in a sealed vault with two-person access, and test that the login works before you rely on it. Disable it for routine use and log every login to it.

Logging administrator changes to SSO settings

Make sure changes to SAML configuration, role mappings and local accounts are captured in audit logs that leave the Wazuh host, such as the Wazuh indexer or a central log store you control. Test that a change to a mapping produces an event with the actor and the time. Without this record, a silent change to who holds administrator rights may not surface until an incident review.

Recertifying identity provider groups

Groups in the identity provider decide who receives Wazuh roles, so a group that still exists after an offboarding or a team change can keep granting administrator access. Map each group to a Wazuh role on purpose, record the owner of each mapping and recertify the mappings on a fixed schedule set by your policy. Check the Wazuh documentation for the identity provider you chose for any hardening steps that apply to its current release.

How to test SSO logins, failure paths and handover

The SSO work is not finished when the first administrator signs in through the identity provider. It is finished when every login path has been exercised on purpose, the expected refusals have been observed, and the people who will run the integration later can find everything they need. Build the test plan from the mapping you agreed with the identity provider team, then run each case against the Wazuh dashboard in your own environment and record the result with the date, the tester and the account used.

Start with the successful path. For each SAML group that maps to a Wazuh role, sign in with a test user who belongs only to that group and confirm the dashboard grants the expected role. Then check the reverse: a user who belongs to no mapped group should be refused, not silently placed in a default role. Run this with at least one user from each identity provider group you intend to use. Keep the test users in the identity provider, named clearly as test accounts, so the cases can be repeated after upgrades or certificate changes.

Next, test the failure paths that matter for offboarding and outages. Disable a test user in the identity provider and confirm that an existing browser session and a fresh login attempt both fail within the session behavior you documented. Repeat with a removed user. Then make the identity provider unreachable, for example by pointing a test copy of the configuration at a wrong metadata endpoint in a non-production node, and confirm that the break-glass local account still signs in. Verify that role permissions match the mapping by opening the role-restricted views and actions with each test user, since a correct login can still carry the wrong privileges.

Rehearse certificate expiry before it happens for real. Use a non-production instance to install a signing certificate with a short validity, let it expire or swap it deliberately, and confirm the failure symptoms your operators will see and the steps needed to restore access. Confirm with the identity provider contacts which certificate is in use, how far ahead they send renewal notices, and who approves a metadata change. Ask your vendor or integration guide to confirm how Wazuh expects the certificate and metadata to be updated in the version you run.

Handover closes the work. Give the operations team a configuration record that lists the identity provider type, entity identifiers, metadata source, attribute and group claims, role mapping table, and the location of the stored configuration files. Add named contacts on the identity provider side, certificate renewal dates taken from the certificate itself, the break-glass procedure with its custody and review steps, and the test scripts or checklists used in this section. Ask the operations team to run the checklist once themselves before sign-off, so the handover is verified rather than assumed.

What drives SSO effort and how to keep it down

This table lists the main factors that raise the work of connecting the Wazuh dashboard to a SAML identity provider, with a practical way to reduce each one. Read each row as a driver you can measure in your own estate before asking for a quote. The main takeaway is that agreeing scope and naming early usually does more to control effort than any single technical choice.

Driver	Why it raises effort	How to keep it down
Number of identity providers and tenants	Each IdP or tenant needs its own SAML application, metadata exchange, attribute mapping and test sign-in. Multiple tenants multiply that work across the same Wazuh instance.	Confirm early which IdPs and tenants must sign in to Wazuh. Start with one, and add others only after the first is stable.
Number of groups and roles to map	Every IdP group that should grant access must map to a Wazuh role such as administrator or read-only. Many nested or overlapping groups make the mapping hard to verify.	Limit the mapping to the roles people actually need. Build a short written matrix of group, role and owner before configuring anything.
Group naming and ownership	Groups with unclear names or no owner lead to repeated rework, with access questions reopened during testing and after go-live.	Agree group naming conventions with the IdP team up front, and record who approves changes to group membership.
Availability and responsiveness of the IdP team	SAML setup needs IdP administrators to create applications, release claims and confirm sign-in behavior. Delays on their side stall testing on the Wazuh side.	Book named IdP administrators for the setup window, agree a response path for questions, and prepare test accounts in advance.
Number of Wazuh environments	Production, staging and lab each need their own redirect addresses, certificates and role checks. Separate IdP applications per environment double the configuration and testing.	Reuse a single IdP application pattern across environments, changing only the redirect and entity identifiers. Pilot in staging first.
Federation broker in front of several IdPs	A broker such as Keycloak can unify several upstream IdPs, but it adds another component to configure, secure, patch and monitor, and its own group mapping layer.	Decide whether a broker is needed before starting. Use one only when several upstream IdPs must reach the same Wazuh instance, and document the mapping once.
Network path and certificates in restricted zones	Offline or restricted segments may block the IdP metadata exchange, sign-in redirects or certificate validation. Certificates issued by an internal authority need trust set up on each relevant host.	Map the required network paths and certificate chains with the network and security teams before the pilot. Confirm whether metadata can be exchanged by file where live connectivity is blocked.
Compliance evidence requirements	Assessors often ask for proof of who can sign in, how roles were approved and how access was reviewed. Collecting this after the fact takes extra effort.	Define the evidence list at the start, such as configuration exports, role approvals and sign-in logs, and capture it during testing. DeployOpen prepares evidence for assessors but does not issue audit reports.

Questions buyers ask before bringing in SSO help

What does Wazuh SAML single sign-on work typically cost?

The cost depends on the scope agreed in writing, and DeployOpen does not publish a price list, so a quote follows from that scope. The main drivers are how many identity providers and environments are involved (for example, a test and a production Wazuh stack), whether the identity provider already has application registrations and group claims configured, how many group-to-role mappings are needed for administrator and read-only access, and whether the work includes testing of failed sign-in paths and documentation. Ask the quote to separate one-time work (configuration, testing, handover) from any recurring support or upgrade retainer, and to state which party is responsible for identity provider changes. Ask for the effort and schedule assumptions in writing so you can compare them with your own team's estimate.

How long does Wazuh SSO setup take in general?

Duration depends on how ready your identity provider and Wazuh environment are, and the written scope should state the expected schedule. Work usually moves faster when the identity team can register the Wazuh dashboard as a SAML application quickly, when group membership is already maintained for the people who need admin or read-only access, and when a non-production Wazuh dashboard is available for testing. Delays tend to come from approval cycles for identity changes, unclear role ownership, and certificate or metadata exchanges that need several rounds. Request the schedule, the dependencies on your teams, and the review points in the quote rather than relying on a general estimate.

Can our internal team set up Wazuh SAML login without outside help?

Yes, many teams can do this with their own engineers, provided they have someone who understands the identity provider's SAML configuration and someone who administers the Wazuh dashboard and its security configuration. The skills that matter most are attribute and claim mapping, group handling, certificate and metadata management, and safe testing that does not lock out the only administrator. Outside help is most useful when the team has no SAML experience, when several identity providers or environments must be aligned, or when the work must be documented for an audit. Wazuh publishes single sign-on guides for several providers, and your team can compare its own plan against the written scope of a fixed-scope engagement.

What do we need from the identity team and the Wazuh owner?

The identity team usually needs to create or approve the SAML application, supply or confirm the metadata and signing certificate handling, define which groups or claims carry Wazuh roles, and approve test users. The Wazuh owner needs to provide dashboard access for configuration, confirm the external URLs and certificates in use, decide which group maps to administrator and which to read-only, and agree on a rollback path. Both teams should name a single decision-maker for changes during the work, and should agree on who reviews sign-in logs after go-live. Put these responsibilities in the scope so that delays are visible early and each team knows what it signs off.

Can SAML login and local Wazuh accounts work together?

Wazuh supports SAML single sign-on in addition to its internal user database, so a design that keeps some local accounts is possible, and the exact behavior should be confirmed against the Wazuh version you run. Keeping a local administrator is a common safeguard for recovery when the identity provider is unavailable, but it must be protected with a strong credential, restricted access and monitoring, because it is an alternative path into the dashboard. Decide in advance which accounts remain local, who holds their credentials, and how their use is logged and reviewed. The scope should record this decision so auditors and the identity team can see that the break-glass path is intentional and controlled.

What happens if the identity provider fails during sign-in?

If the identity provider is unavailable, SAML users cannot sign in to the Wazuh dashboard, so the design must include a recovery path before go-live. Common approaches include a tested local break-glass administrator, a documented procedure for restoring the identity provider or its certificates, and a way for the Wazuh owner to reach the server directly for diagnosis. Test the failure cases in a non-production environment: an expired signing certificate, a changed metadata URL, a missing group claim and a removed user. Write down who can invoke the recovery path and how access is restored afterward. A well-scoped engagement includes these failure tests and the runbook that results from them.

Can DeployOpen take over Wazuh SSO support after go-live?

Yes, ongoing support, upgrades and continuous testing are available as retainers, and the terms are set out in a written agreement. Taking over later depends on what has been documented and handed over: configuration records, role mappings, certificate renewal dates, the break-glass procedure and the upgrade impact on SAML settings. Ask for a handover that covers the Wazuh version in use, the identity provider configuration, and the owners on each side. Support scope should state which changes are covered, how requests are prioritized, and what happens when the identity provider or Wazuh is upgraded. Confirm the details in the written scope before relying on them for production access.

How DeployOpen works on this

DeployOpen plans and implements Wazuh SSO with SAML identity providers inside your own infrastructure, so the dashboard login, the identity provider and the role mapping are set up in your environment. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.

How we scope

Confirm which SAML identity provider you run, such as Okta, Microsoft Entra ID or Keycloak, and its version and administrators
Map which identity provider groups should receive administrator and read-only roles in the Wazuh dashboard
Record the written scope, deliverables and timeline for the SSO integration before work starts

How we build

Configure SAML settings in the Wazuh dashboard against your identity provider's metadata and certificates
Set up group-to-role mapping and test sign-in with administrator, read-only and denied test accounts
Confirm the internal user database stays available as a documented fallback for break-glass access

How we hand over

Document the identity provider configuration, certificate locations and role mapping rules for your team
Provide a test record showing each group's expected access level and the results of each check
Walk your administrators through adding users, changing group membership and rotating certificates

How we support

Review SSO settings after Wazuh upgrades within the 4.14 line, since dashboard configuration can change between patches
Re-test role mapping when identity provider groups are renamed, added or removed
Ongoing support is available as a retainer, with scope agreed in writing

Wazuh SSO with SAML identity providers