> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wazuh/wazuh-dashboard-plugins/llms.txt
> Use this file to discover all available pages before exploring further.

# Single Sign-On (SSO)

> Configure SAML-based SSO for Wazuh Dashboard with administrator and read-only access

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):**

```yml theme={null}
idp.metadata_url: https://idp.example.com/metadata
```

**Example (File):**

```yml theme={null}
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:**

```yml theme={null}
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:**

```yml theme={null}
sp.entity_id: wazuh-dashboard
```

**`kibana_url`**

The fully qualified URL where users access the Wazuh Dashboard.

**Example:**

```yml theme={null}
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:**

```yml theme={null}
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:**

```yml theme={null}
exchange_key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
```

**Generate a secure exchange key:**

```bash theme={null}
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):

```yml theme={null}
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`):

```yml theme={null}
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:

```bash theme={null}
/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:

```bash theme={null}
# 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:**

```bash theme={null}
/var/log/wazuh-indexer/wazuh-indexer.log
```

**Dashboard Logs:**

```bash theme={null}
/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:

* **SSO Overview:** [Wazuh SSO Documentation](https://documentation.wazuh.com/current/user-manual/user-administration/single-sign-on/index.html)
* **Administrator Role Setup:** [Administrator Configuration](https://documentation.wazuh.com/current/user-manual/user-administration/single-sign-on/administrator/index.html)
* **Read-Only Role Setup:** [Read-Only Configuration](https://documentation.wazuh.com/current/user-manual/user-administration/single-sign-on/read-only/index.html)

## Related Topics

* [Authentication Setup](/configuration/authentication)
* [Plugin Settings](/configuration/settings)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.