Skip to main content
This guide explains how to configure SAML-based Single Sign-On (SSO) for the Wazuh Dashboard, enabling centralized authentication through an Identity Provider (IdP) with role-based access control.

​
Overview

Single Sign-On allows users to authenticate to the Wazuh Dashboard using their organization’s identity management system. The Dashboard integrates with OpenSearch Security’s SAML authentication to provide seamless access control.

​
Prerequisites

Before configuring SSO, ensure the following requirements are met:
  • Wazuh indexer and Wazuh Dashboard are installed and operational
  • An Identity Provider (IdP) that supports SAML 2.0:
    • Okta
    • Microsoft Entra ID (formerly Azure AD)
    • Keycloak
    • OneLogin
    • Other SAML 2.0 compatible IdPs
  • Administrator access to the Dashboard and indexer security configuration
  • Access to configure the IdP application settings

​
Required Parameters

The following parameters are required for SAML SSO configuration:

​
IdP Configuration

idp.metadata_url or idp.metadata_file The URL or file path to the IdP metadata document. This document contains the IdP’s configuration, including endpoints, certificates, and entity ID. Example (URL): 
idp.metadata_url: https://idp.example.com/metadata
Example (File): 
idp.metadata_file: /etc/opensearch/idp-metadata.xml
idp.entity_id The unique identifier for your Identity Provider. This is provided by the IdP. Example: 
idp.entity_id: https://idp.example.com/saml

​
Service Provider Configuration

sp.entity_id The unique identifier for the Wazuh Dashboard (Service Provider). This value must match what is configured in the IdP application. Example: 
sp.entity_id: wazuh-dashboard
kibana_url The fully qualified URL where users access the Wazuh Dashboard. Example: 
kibana_url: https://dashboard.example.com

​
SAML Attributes

roles_key The SAML attribute name that contains the user’s role or group membership information. The IdP sends this attribute in the SAML assertion. Common values:
  • roles (generic)
  • groups (Active Directory/Entra ID)
  • memberOf (LDAP-based)
Example: 
roles_key: groups

​
Security

exchange_key A secure random string used for encrypting the SAML authentication exchange. This must be at least 64 characters long. Example: 
exchange_key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
Generate a secure exchange key: 
openssl rand -hex 32

​
Configuration Workflow

​
High-Level Setup Steps

  1. Create groups in the IdP
    • Create two groups for different access levels (e.g., wazuh-admin and wazuh-readonly)
    • Assign users to appropriate groups
  2. Configure SAML application in the IdP
    • Use the SP metadata from the Wazuh indexer security plugin
    • Configure attribute mappings
    • Set up group/role claims
  3. Configure SAML in Wazuh indexer and Dashboard
    • Update the OpenSearch Security configuration
    • Define SAML settings with required parameters
    • Configure authentication domains
  4. Map IdP groups to OpenSearch security roles
    • Create or modify role mappings
    • Map wazuh-admin group to administrator role
    • Map wazuh-readonly group to read-only role
  5. Apply configuration and restart services
    • Run the securityadmin script to apply changes
    • Restart the Wazuh indexer and Dashboard services if required
  6. Validate and test
    • Test authentication with users from both groups
    • Verify role-based access is working correctly
    • Confirm read-only users have restricted permissions

​
Role Mapping

​
Administrator Access

Create a role mapping for users who should have full access to the Wazuh Dashboard: IdP Group: wazuh-admin OpenSearch Role: all_access or a custom administrative role Permissions:
  • Full read/write access to all indices
  • Dashboard management capabilities
  • Wazuh Server API access with appropriate privileges
  • Ability to modify settings and configurations

​
Read-Only Access

Create a role mapping for users who should have read-only access: IdP Group: wazuh-readonly OpenSearch Role: kibana_read_only or a custom read-only role Permissions:
  • Read access to Wazuh indices
  • View-only access to dashboards and visualizations
  • Limited Wazuh Server API access (read-only operations)
  • Cannot modify settings or configurations

​
Example Configuration

​
OpenSearch Security Configuration

Edit the OpenSearch Security configuration file (typically config.yml in the OpenSearch security plugin directory): 
config:
  dynamic:
    authc:
      saml_auth_domain:
        http_enabled: true
        transport_enabled: false
        order: 1
        http_authenticator:
          type: saml
          challenge: true
          config:
            idp:
              metadata_url: https://idp.example.com/metadata
              entity_id: https://idp.example.com/saml
            sp:
              entity_id: wazuh-dashboard
            kibana_url: https://dashboard.example.com
            roles_key: groups
            exchange_key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
        authentication_backend:
          type: noop

​
Role Mapping Configuration

Edit the role mapping configuration (typically roles_mapping.yml): 
all_access:
  reserved: false
  backend_roles:
    - "wazuh-admin"
  description: "Maps wazuh-admin group to all_access role"

kibana_read_only:
  reserved: false
  backend_roles:
    - "wazuh-readonly"
  description: "Maps wazuh-readonly group to read-only role"

​
Applying Configuration Changes

After modifying the security configuration files, apply the changes using the securityadmin script: 
/usr/share/opensearch/plugins/opensearch-security/tools/securityadmin.sh \
  -cd /etc/opensearch/opensearch-security/ \
  -icl \
  -nhnv \
  -cacert /etc/opensearch/certs/root-ca.pem \
  -cert /etc/opensearch/certs/admin.pem \
  -key /etc/opensearch/certs/admin-key.pem
Parameters:
  • -cd: Configuration directory containing security files
  • -icl: Ignore cluster name
  • -nhnv: No hostname verification
  • -cacert: Path to CA certificate
  • -cert: Path to admin certificate
  • -key: Path to admin key

​
Restart Services

Restart the services to apply the configuration: 
# Restart OpenSearch/Wazuh indexer
systemctl restart wazuh-indexer

# Restart Wazuh Dashboard
systemctl restart wazuh-dashboard

​
Testing SSO Configuration

​
Administrator Access Test

  1. Log out of any existing Dashboard session
  2. Navigate to the Dashboard URL
  3. You should be redirected to the IdP login page
  4. Authenticate with a user assigned to the wazuh-admin group
  5. Verify you are redirected back to the Dashboard
  6. Confirm full access to all features and settings

​
Read-Only Access Test

  1. Log out of the current session
  2. Navigate to the Dashboard URL
  3. Authenticate with a user assigned to the wazuh-readonly group
  4. Verify you can view data but cannot modify settings
  5. Test that write operations are blocked

​
Troubleshooting

​
Common Issues

Redirect Loop Cause: Misconfigured kibana_url or sp.entity_id Solution: Verify the URLs match exactly between IdP and SP configuration Authentication Fails Cause: Invalid SAML response or attribute mapping Solution:
  1. Check IdP logs for error messages
  2. Verify roles_key matches the attribute name sent by the IdP
  3. Ensure users are assigned to the correct groups
  4. Validate SAML response using browser developer tools
Role Mapping Not Working Cause: Backend role names don’t match IdP group names Solution:
  1. Verify group names in the IdP match backend_roles in role mapping
  2. Check for case sensitivity differences
  3. Review OpenSearch Security logs for mapping errors
Certificate Errors Cause: Invalid or expired SAML signing certificates Solution:
  1. Verify the IdP metadata contains valid certificates
  2. Update metadata if certificates have been rotated
  3. Check system time synchronization (important for SAML)

​
Log Files

Check the following logs for troubleshooting: OpenSearch/Indexer Logs: 
/var/log/wazuh-indexer/wazuh-indexer.log
Dashboard Logs: 
/var/log/wazuh-dashboard/wazuh-dashboard.log

​
Security Considerations

  1. Use HTTPS: Always configure the Dashboard and IdP with HTTPS
  2. Secure Exchange Key: Generate a strong, random exchange key
  3. Certificate Validation: Ensure proper certificate validation is enabled
  4. Session Timeout: Configure appropriate session timeout values
  5. Audit Logging: Enable audit logging to track authentication events
  6. Regular Updates: Keep IdP metadata updated when certificates rotate

​
Official Documentation References

For IdP-specific configuration steps and additional details, refer to the official Wazuh documentation:

Build docs developers (and LLMs) love

Get started for freeTalk to us