authentik and Wazuh SAML integration: how SOC logins move from authentik to the dashboard
A team that runs Wazuh for SOC work and wants one identity source for analysts and administrators can put the Wazuh dashboard behind authentik with SAML. The authentik integrations catalog includes a Wazuh guide that configures SAML single sign-on for the Wazuh dashboard. The work covers three parts: an authentik SAML provider and application, the Wazuh dashboard security configuration in the OpenSearch security plugin, and a mapping from authentik groups to Wazuh roles so that SOC analysts and administrators receive the access they need on first login.
For users, the change is in the sign-in path. Analysts open the dashboard, are redirected to authentik, complete the MFA and policy checks configured there, and return to the dashboard with a session whose roles come from their group memberships. Access reviews move to authentik: removing someone from a SOC group or disabling their account there should end dashboard access without a separate change in the dashboard. Local dashboard accounts may still be needed as a break-glass path, so decide early whether they stay enabled, who holds their credentials and where they are recorded.
The integration does not change trust between the other Wazuh components. The Wazuh indexer, Wazuh server and Wazuh agents keep their own certificates and trust settings, and agents continue to report to the server through their existing enrollment. Before the change, confirm the exact SAML provider fields, the role and group mapping file names and the certificate handling against the authentik Wazuh guide and the Wazuh single sign-on documentation for the Wazuh version you run, and test the flow in a non-production stack first.
What must be in place before the SAML configuration starts
The SAML configuration touches three systems: the authentik provider, the Wazuh dashboard and the OpenSearch security configuration in the Wazuh indexer. Confirm each prerequisite below before changing anything, because a mismatch in versions, names or group structure is harder to diagnose once SSO is switched on.
authentik version line
Run a version on the supported line. The authentik security policy lists 2026.5.x and 2026.8.x as the versions receiving security fixes, and the project announces security releases at least 24 hours in advance. The GitHub releases page showed 2026.8.4 as the latest release at the time of the sources. Confirm your running version, and plan any upgrade to the sequential path before you start the SAML work so the provider settings are not changed twice.
Wazuh 4.14 patch level
Wazuh's current release line is 4.14. The latest patch cited in the sources is 4.14.9, released on 14 October 2026, and patch releases arrive roughly every one to two months. Record the exact version of the Wazuh dashboard and indexer you run, then read the release notes for changes to the security plugin or dashboard authentication before you plan the window.
Confirm your Wazuh deployment option
Identify how Wazuh was installed: all-in-one, step-by-step, OVA, Amazon Machine Image, Docker, Kubernetes, offline, from sources, Ansible or Puppet. File paths for the dashboard and indexer configuration, the commands that apply security changes and the restart steps differ between these options. Write down the option and the host or container names you will edit before you open the runbook, so every later step targets the right files.
Working HTTPS dashboard
The Wazuh dashboard must already load over HTTPS, with agents reporting and alerts visible, before SAML is added. A failing dashboard login is hard to separate from a failing SAML exchange. Verify that a local administrator can sign in, and keep that account and its password stored offline, since it is your recovery path if the authentik provider or the certificate chain breaks.
DNS names and TLS certificates
Give the Wazuh dashboard and the authentik instance stable DNS names with certificates that clients trust. SAML relies on the browser reaching both endpoints over HTTPS and on the signing certificate being exchanged correctly between them. Confirm the exact URL the dashboard will present as its base address, because the assertion consumer and redirect URLs in both systems must match it character for character. Confirm the certificate expiry dates and who renews them.
Groups that match SOC roles
Create authentik groups that correspond to the Wazuh roles your SOC uses, for example administrators, analysts and read-only reviewers. The SAML assertion carries these group names, and the OpenSearch security plugin maps them to backend roles. Agree the mapping with the SOC lead before configuration, and decide who owns membership changes, since every group added or removed in authentik changes Wazuh access on the next login.
Access to the indexer security configuration
Someone on your team needs administrative access to the Wazuh indexer security configuration, which governs roles, role mappings and the authentication backends the dashboard uses. Confirm that person can run the security admin tooling on the indexer nodes and that the change is logged. Without this access, the role mapping cannot be applied, and a partial change can leave the dashboard unreachable for analysts.
Configuration sequence for authentik SAML and the Wazuh dashboard
This sequence connects the authentik SAML provider to the Wazuh dashboard and indexer security plugin, maps authentik groups to dashboard roles, and confirms that SOC staff reach the right access level before the integration goes into use.
Create the SAML provider and application in authentik
The engineer responsible for authentik creates a SAML provider and a matching application, using the entity ID, ACS URL and signing settings that the authentik Wazuh integration guide specifies for the dashboard. Set the audience and name ID mapping exactly as the guide describes, because a single mismatched character in the entity ID causes SAML login to fail without a clear error. Bind the application to a group that holds only the SOC users who should reach the dashboard. Closing check: the authentik application appears in the user library for a test account in the bound group, and the same account is absent for a user outside the group.
Export the signing certificate and metadata
From the new SAML provider in authentik, download the signing certificate and the metadata or the IdP certificate values the Wazuh guide requires. Store the certificate in a location the Wazuh server can read, with file permissions restricted to the service account that runs the indexer and dashboard. Confirm the certificate expiry date and record it in your renewal calendar, since rotating it later means repeating steps three and four. Closing check: you can open the certificate file on the Wazuh host, and its subject and expiry match what authentik shows on the provider page.
Configure SAML in the OpenSearch security plugin
On the Wazuh indexer, edit the security configuration to add a SAML authentication domain that points to the authentik metadata, the IdP entity ID and the SP entity ID of the dashboard. Follow the single sign-on documentation for the file locations and the apply-configuration step, and keep the basic internal authentication path enabled until the SAML login is verified. Use the security admin tooling that Wazuh documents rather than editing live cluster state by hand. Closing check: the security plugin reports the SAML domain as loaded, and the indexer logs show no configuration parse errors.
Configure the Wazuh dashboard for SAML
On the Wazuh dashboard host, enable the SAML option in the dashboard configuration file, set the IdP metadata reference, the exit and logout URLs, and the SAML header or JWT settings the Wazuh single sign-on page describes. Confirm the dashboard can reach the authentik host over HTTPS and that the certificate chain is trusted by the dashboard host. Keep the local admin account available for recovery. Closing check: the dashboard login page offers the SSO option, and the configuration validates without errors in the dashboard log.
Map authentik groups to backend roles
Decide which authentik groups correspond to which Wazuh roles, such as a read-only analyst role and an administrator role for the SOC lead, and set the group attribute in the SAML assertion so the indexer receives those values. Create matching backend role mappings in the security plugin, and keep the mapping in version-controlled files so changes are reviewed. Assign roles to the smallest group that does the job. Closing check: a test account in the analyst group receives only the analyst role in the security plugin's user view, and an account in the administrator group receives the admin role.
Restart or reload the dashboard and indexer services
Restart the Wazuh dashboard service, and reload or restart the indexer if the security configuration requires it, following the order in the Wazuh documentation for your installed 4.14 patch release. Check service status and the logs of each component before testing login. Schedule the restart in a maintenance window that your SOC accepts, since alert viewing is interrupted while the dashboard is down. Closing check: all Wazuh services report healthy status, and the dashboard loads over the expected URL.
Test each role and a rejected user
Sign in through authentik with one test account per role, plus one account outside every bound group. For each role account, confirm the dashboard opens, the expected index patterns and views are visible, and the actions the role should not have are blocked. For the outside account, confirm that authentik or the dashboard rejects the login and that the attempt appears in the logs. Record results in the change record and retire any test accounts afterwards. Closing check: every role account matches its expected access, and the outside account is refused.
Mapping authentik groups to Wazuh dashboard roles
This table compares five SOC and platform roles across the authentik source, the SAML attribute the assertion carries, the Wazuh backend role it should map to, and the access it grants. Group names, attribute names and role names are your choices, so treat the rows as a starting pattern and confirm every mapping against your Wazuh indexer security configuration before go-live. Any user who belongs to no mapped group should receive no dashboard role.
| Persona | authentik source (group or attribute) | SAML assertion carries | Wazuh backend role and access |
|---|---|---|---|
| SOC analyst | Group such as soc-analysts (illustrative) | Group membership in the group attribute | Backend role mapped to read and triage alerts, no configuration changes |
| SOC lead | Group such as soc-leads (illustrative) | Group membership in the group attribute | Backend role with alert triage plus case and report review, limited administrative actions |
| Detection engineer | Group such as detection-eng (illustrative) | Group membership in the group attribute | Backend role for rule and decoder work, scoped to test or staging policies where possible |
| Read-only auditor | Group such as audit-readonly (illustrative) | Group membership in the group attribute | Backend role with read-only dashboard and compliance views, no access to agent management |
| Platform administrator | Group such as wazuh-admins (illustrative) | Group membership, kept to a short, reviewed list | Administrative backend role, granted only to a named small set, with MFA enforced in authentik |
| Users in no mapped group | No matching group | No matching group value | No dashboard role. Confirm that login is denied or lands without access |
Keeping admin access for the SOC team when SAML is down
A SAML-only dashboard can lock out the very people who need to fix it. If the authentik server is down, a signing certificate expires, or the Wazuh side holds stale IdP metadata, every SAML login fails at once, and the SOC team loses the console precisely when an incident or a broken integration needs attention. Plan a break-glass path that does not depend on authentik before the SAML configuration goes live. The design has three parts: a local administrator account, controlled custody of its credentials, and a tested procedure for using it.
The local account lives in the Wazuh indexer security configuration, where the OpenSearch security plugin keeps its internal users and role mappings. Create a single named break-glass administrator, map it only to the admin role, and keep it out of the group-to-role mapping used for SAML so that no authentik group can grant or remove it. Store its password in the customer's own secret handling, such as a vault or sealed credential store, with access limited to two or three named people on the SOC leadership or platform side and an audit trail for every retrieval. Confirm the exact procedure for adding and hashing internal users, and where the security configuration files are applied, in the Wazuh documentation for your installed version before you rely on it.
Test the path before go-live, not during the first outage. Log in with the local account while authentik is reachable and while it is deliberately stopped in a non-production copy, confirm the admin views and the agent management functions work, and record the steps in the runbook. Repeat the test after each Wazuh or authentik upgrade and after any change to signing certificates or metadata. A break-glass account that has never been used is a common cause of a second lockout, so schedule the test and assign an owner.
Hardening the SAML path to the SOC console
A SAML sign-in to the Wazuh dashboard is only as strong as the certificates, network paths, MFA rules, logs and roles around it. The cards below cover the controls a SOC team should settle before go-live and keep running afterward, across authentik and the Wazuh indexer and dashboard.
Certificate handling and rotation
The SAML signing and any encryption keys need a named owner, a storage location and a rotation date written into the change calendar. Confirm with the Wazuh SSO documentation how the dashboard and indexer security configuration load the IdP certificate, and test a rotation in a staging copy first. Record which authentik provider certificate is current so a rotation does not lock out the whole SOC.
Restricting dashboard access to SOC networks
The dashboard should accept connections only from the networks where analysts work, such as a management VLAN or a jump host. Put the restriction at the reverse proxy or firewall in front of the dashboard, and keep the authentik login path reachable for those networks. Ask your network team to test access from an unlisted network and confirm that the denial is logged.
MFA enforced for SOC roles
Require a second factor in authentik for every user who can reach an analyst or administrator role in Wazuh, and bind the policy to the group that carries those roles. Confirm which second factors your chosen authentik edition supports before writing the policy, because the pricing page lists some features only in the Enterprise tiers. Test the enrollment and recovery path so a lost device does not force an emergency change to the indexer.
Audit logging in both systems
Log successful and failed SAML logins, group changes and role assignments in authentik, and keep the Wazuh indexer audit output for security configuration changes. Forward both to a store the SOC cannot silently edit. Ask your vendor which events the edition you run can export, and test one login failure and one role change end to end to confirm both appear.
Least-privilege role design
Map authentik groups to Wazuh roles so that analysts can search alerts and view dashboards but cannot change the indexer security configuration. Keep the administrator group small and separate from the analyst group, and review membership on a set schedule. Test each role with a sample account and record the result, since a mapping that grants too much is easy to miss in a working deployment.
Standing patch review window
Wazuh shipped 4.14 patch releases on 17 March, 23 April, 1 July, 29 July, 23 September and 14 October 2026, so expect updates every one to two months. authentik announces security releases at least 24 hours in advance, which is a short window. Set a standing review each month, confirm which authentik versions receive security fixes, and stage both upgrades in a test environment before production.
How to test role mapping before SOC cutover
Before the SOC team moves onto the SAML path, test each role end to end in a pilot that mirrors production. Create one named test account per role you intend to map from authentik groups into the Wazuh dashboard, and record the expected view for each account before the first login. For each role, write down which dashboard areas it should open, which compliance views it should see, and which actions it should be blocked from, such as changing security configuration. The prebuilt views for PCI DSS, GDPR, HIPAA and NIST 800-53 are a useful check here: each role should see only the compliance views it needs, not every framework the dashboard ships with. Confirm the expected list with your SOC lead and your compliance owner, since the right split depends on which frameworks your organization is actually accountable for.
Then run the negative tests, which are where role mapping most often fails quietly. Sign in with a user who belongs to no mapped group and confirm that access is denied or that the account lands with no privileges, not with a default admin role. Next, remove a test user from a mapped group while they hold an active session, then check whether their dashboard privileges change at the next sign-in or stay in place until the session expires. Your session lifetime settings in authentik and on the Wazuh side determine what you will observe, so record both values and confirm them with the people who own each system. Also verify that the SAML response carries the group attribute your mapping expects, by inspecting a test assertion in your environment rather than assuming the claim name from documentation.
Finish with a rehearsal of the break-glass login. Confirm that a local administrator account on the Wazuh dashboard still works when authentik or the SAML path is unavailable, that its credentials are stored where the on-call team can reach them, and that the procedure has been performed by someone other than its author. Log each test result against the expected view, and treat any unexpected privilege as a blocker for cutover. Ask your implementation partner or internal team to document the exact steps, so the SOC can repeat the checks after future Wazuh or authentik upgrades.
Why SAML logins to Wazuh fail and how to fix them
This table pairs common symptoms of a failed authentik to Wazuh SAML sign-in with their likely causes and the first check to make in the authentik provider, the SAML response or the Wazuh security configuration. Work down the rows in order, since several symptoms share one root cause. Confirm every setting name and value against the authentik Wazuh guide before changing anything.
| Symptom | Likely cause | Fix and where to check |
|---|---|---|
| Login loops or returns to the Wazuh login page | ACS URL or SAML entity ID in the authentik provider does not match what the Wazuh dashboard sends | Compare the ACS URL and entity ID in the authentik SAML provider with the values in the Wazuh security configuration. Confirm the exact fields in the authentik Wazuh guide, then re-test in a private browser window. |
| Signature validation errors on sign-in | The signing certificate was rotated in authentik, or the metadata or certificate loaded into the Wazuh dashboard is out of date | Re-export the current IdP metadata or certificate from the authentik provider and reload it into the Wazuh SAML settings. Check that the certificate in the SAML response matches the one the dashboard trusts. |
| Users sign in but see no roles or only a default view | The group attribute is missing from the assertion, or its name does not match the role mapping string in Wazuh | Inspect a captured SAML response for the group attribute and its exact name. Make sure the attribute mapping in the authentik provider emits it, and that the Wazuh role mapping uses the same name and group value. |
| Users see more dashboards, indices or admin functions than intended | A group mapping is broader than the SOC role it was meant for, or a shared group was mapped to an admin role | Review each Wazuh role mapping and remove wildcard or shared groups from admin roles. Check which authentik groups the affected user belongs to, and test with a standard analyst account before and after the change. |
| Assertions rejected with timing or validity errors | Clock skew between the authentik server, the Wazuh indexer and dashboard hosts, or the browser | Synchronize time on all hosts with NTP and confirm that the assertion validity window in the SAML response is current. Check the Wazuh and authentik logs for not-before or not-on-or-after messages. |
| Configuration change not visible in the dashboard | The dashboard or security configuration was not reloaded, or a cached session still holds old role data | Apply the security configuration update as the guide describes, restart the dashboard service if the guide requires it, then sign out all sessions and sign in again to refresh the attributes. |
| All SAML users are locked out | The SAML provider was changed or disabled before a local administrator path was confirmed, or the only mapped admin group was removed | Keep at least one local administrator account that does not depend on SAML, and confirm how to use it in the Wazuh security settings. Restore the previous provider configuration from a saved export, then correct the mapping step by step. |
Questions SOC and platform leads ask before the Wazuh SAML work
What drives the cost and effort of a Wazuh SAML integration?
The main drivers are the number of roles you need to map, the shape of your existing Wazuh deployment, how much custom role design you want, how deeply you test, and whether your team already runs authentik. A single dashboard with a handful of groups is a small change. A multi-node Wazuh cluster with several SOC tiers, custom OpenSearch security roles and a formal test plan takes more planning and more review time. If your team already operates authentik, the identity side is familiar and the work concentrates on the Wazuh configuration. Ask any quote to itemize role count, environments covered (lab, staging, production), test scope and change-control steps, since these are the items that move the total.
Can our team set up Wazuh SAML without outside help?
A team with authentik and Wazuh experience can do it alone, and the authentik Wazuh guide is a sound starting point for a single-node lab. A multi-node Wazuh cluster, a production dashboard that the SOC uses every shift, and strict change control are harder to do without help, because a wrong SAML or role setting can lock administrators out of the console during an incident. The usual gap is not the configuration itself but the rollback plan, the break-glass admin path and the test evidence your change board expects. Decide early which parts your staff own and which parts you want a partner to review or run.
How long does a Wazuh SAML integration take to complete?
No duration has been established for this integration, so treat any timeline as something to confirm for your environment. The elapsed time depends on the scope you agree, the number of roles and environments, and the change windows your team can use. A lab can be finished in one working session. Production work usually adds time for the maintenance window, validation with SOC analysts who hold different roles, and any approval cycle your organization requires. Ask for a written schedule that lists the change windows and the review points, not a single end date.
What does our organization need to provide for the integration?
The work depends on access and decisions from your side. You need named owners in the SOC and in the identity team, along with test accounts that represent each SOC role. Your team must control the certificates used for SAML signing and the DNS records for the dashboard and the authentik endpoint, because the SAML trust breaks if either changes unexpectedly. Reserve a maintenance window for the cutover, and keep a local administrator path so the console remains reachable if SSO fails. Confirm these items in writing before the scope is final.
Is SAML included in the open-source edition of authentik?
Confirm this against the authentik pricing page before you plan the work, because editions and feature lists change. The page lists the Open Source edition as free with community support, and it lists enterprise-only features such as Google Workspace and Microsoft Entra ID integrations, mTLS client certificate authentication, privileged access management, password history, enhanced audit logging and ticket-based support. SAML is not among the enterprise-only features named there, and authentik documents SAML as a provider type. Verify the provider and the edition you run in your own instance, and check the Wazuh-specific guide for any version requirements before you commit to the design.
How do the licenses of authentik and Wazuh affect our stack?
authentik publishes most of its code under the MIT license, while code in the authentik/enterprise/ directory is under a separate enterprise license defined in that directory. Your legal team should read both files to confirm which parts you use and which terms apply. Wazuh is distributed under the GNU General Public License version 2, with an exception that permits linking with the OpenSSL library. Using both products as separate services in your infrastructure is the common pattern, but any modification or redistribution has obligations that your counsel should review. Record the license of each component in your software inventory before the change is approved.
Which parts of the Wazuh SAML setup should engineers check first?
Start with the trust settings, because most SAML failures come from mismatched entity IDs, assertion consumer URLs, certificates or clock skew between the two systems. Next, verify that group claims arrive in the assertion with the names your role mapping expects, since a renamed group in authentik silently removes access. Test each SOC role with a non-admin account, then test the administrator path, and confirm that a local recovery account still works with SSO disabled. Keep the configuration in version control where your process allows it, and record the authentik and Wazuh versions you tested so that upgrades start from a known state.
How DeployOpen scopes and delivers the Wazuh SAML integration
DeployOpen plans and builds the authentik and Wazuh SAML integration inside infrastructure you control, starting from a written scope that names the Wazuh dashboard, the authentik provider and the role mapping your SOC team needs. Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts, and ongoing support is available as a retainer.
How we scope
- Confirm which Wazuh deployment, version line and dashboard hostnames the SAML integration will cover.
- Document the authentik groups, the Wazuh roles they map to, and who approves changes to that mapping.
- Agree in writing whether the scope includes the break-glass local admin path and MFA enforcement on the authentik side.
How we build
- Configure the authentik SAML provider and application, then the OpenSearch security plugin SAML settings on the Wazuh indexer.
- Test sign-in, group-to-role mapping and denied access with separate test accounts before any SOC user is switched over.
- Keep certificates, metadata and configuration files under version control with changes reviewed before they reach production.
How we hand over
- Deliver a runbook covering the authentik provider settings, the Wazuh security configuration and each role mapping.
- Walk the SOC and platform teams through the sign-in path, the local admin recovery procedure and the escalation contacts.
- Document certificate expiry dates, metadata update steps and the checks to run after each Wazuh or authentik upgrade.
How we support
- Offer retainer support for upgrades, certificate rotation and role mapping changes after the handover is complete.
- Review the integration when Wazuh patch releases or authentik security releases affect the SAML path or its dependencies.
- Confirm with your own team how sign-in logs and identity events will be retained and reviewed during operations.
