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

# LDAP / Active Directory Integration

> Connect Open WebUI to Active Directory or LDAP servers for centralized authentication

Open WebUI supports LDAP and Active Directory integration for enterprise user authentication. Users can sign in with their existing directory credentials without creating separate accounts.

## Prerequisites

* LDAP or Active Directory server accessible from Open WebUI
* Service account with read access to user directory (optional but recommended)
* LDAP search base DN and user attributes

## Configuration

### Basic LDAP Setup

Set these environment variables to enable LDAP authentication:

```bash theme={null}
# Enable LDAP authentication
ENABLE_LDAP=true

# LDAP server connection
LDAP_SERVER_LABEL="Active Directory"  # Display name in UI
LDAP_SERVER_HOST=ldap.company.com
LDAP_SERVER_PORT=389

# User attributes
LDAP_ATTRIBUTE_FOR_USERNAME=sAMAccountName  # Or 'uid' for OpenLDAP
LDAP_ATTRIBUTE_FOR_MAIL=mail

# Search configuration
LDAP_SEARCH_BASE="ou=users,dc=company,dc=com"
LDAP_SEARCH_FILTERS="(objectClass=person)"  # Optional additional filters

# Service account (optional but recommended)
LDAP_APP_DN="cn=openwebui-service,ou=service-accounts,dc=company,dc=com"
LDAP_APP_PASSWORD="service-account-password"
```

### TLS/SSL Configuration

<Warning>
  For production deployments, always use LDAPS (LDAP over TLS) to encrypt credentials in transit.
</Warning>

```bash theme={null}
# Enable TLS
LDAP_USE_TLS=true
LDAP_SERVER_PORT=636  # Standard LDAPS port

# Certificate validation
LDAP_VALIDATE_CERT=true
LDAP_CA_CERT_FILE="/path/to/ca-certificate.pem"  # Optional CA cert

# Cipher configuration (optional)
LDAP_CIPHERS="HIGH:!aNULL:!MD5"
```

## Active Directory Configuration

For Microsoft Active Directory, use these recommended settings:

```bash theme={null}
ENABLE_LDAP=true
LDAP_SERVER_LABEL="Company Active Directory"
LDAP_SERVER_HOST=ad.company.com
LDAP_SERVER_PORT=636
LDAP_USE_TLS=true

# AD-specific attributes
LDAP_ATTRIBUTE_FOR_USERNAME=sAMAccountName
LDAP_ATTRIBUTE_FOR_MAIL=mail
LDAP_ATTRIBUTE_FOR_GROUPS=memberOf  # For group sync

# Search base - typically your domain
LDAP_SEARCH_BASE="dc=company,dc=com"
LDAP_SEARCH_FILTERS="(&(objectClass=user)(objectCategory=person))"

# Service account with domain\\username format
LDAP_APP_DN="cn=svc-openwebui,ou=Service Accounts,dc=company,dc=com"
LDAP_APP_PASSWORD="your-service-password"
```

## OpenLDAP Configuration

For OpenLDAP servers:

```bash theme={null}
ENABLE_LDAP=true
LDAP_SERVER_LABEL="Corporate LDAP"
LDAP_SERVER_HOST=ldap.company.com
LDAP_SERVER_PORT=636
LDAP_USE_TLS=true

# OpenLDAP attributes
LDAP_ATTRIBUTE_FOR_USERNAME=uid
LDAP_ATTRIBUTE_FOR_MAIL=mail
LDAP_ATTRIBUTE_FOR_GROUPS=memberOf

# Search configuration
LDAP_SEARCH_BASE="ou=people,dc=company,dc=com"
LDAP_SEARCH_FILTERS="(objectClass=inetOrgPerson)"

# Bind DN
LDAP_APP_DN="cn=admin,dc=company,dc=com"
LDAP_APP_PASSWORD="admin-password"
```

## Group Synchronization

Enable automatic group synchronization from LDAP to Open WebUI:

```bash theme={null}
# Enable group management
ENABLE_LDAP_GROUP_MANAGEMENT=true
ENABLE_LDAP_GROUP_CREATION=true

# Group attribute (usually 'memberOf')
LDAP_ATTRIBUTE_FOR_GROUPS=memberOf
```

### How Group Sync Works

1. User authenticates via LDAP
2. Open WebUI reads the `LDAP_ATTRIBUTE_FOR_GROUPS` attribute
3. For each group DN, Open WebUI:
   * Creates the group if it doesn't exist (when `ENABLE_LDAP_GROUP_CREATION=true`)
   * Adds the user as a member
4. Groups are synchronized on each login

<Note>
  Group names are extracted from the CN (Common Name) component of the group DN.
  For example: `CN=Engineering,OU=Groups,DC=company,DC=com` becomes "Engineering"
</Note>

## Docker Compose Example

```yaml theme={null}
version: '3'

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    environment:
      # LDAP Configuration
      - ENABLE_LDAP=true
      - LDAP_SERVER_LABEL=Active Directory
      - LDAP_SERVER_HOST=ad.company.com
      - LDAP_SERVER_PORT=636
      - LDAP_USE_TLS=true
      - LDAP_ATTRIBUTE_FOR_USERNAME=sAMAccountName
      - LDAP_ATTRIBUTE_FOR_MAIL=mail
      - LDAP_SEARCH_BASE=dc=company,dc=com
      - LDAP_APP_DN=cn=svc-openwebui,ou=Service Accounts,dc=company,dc=com
      - LDAP_APP_PASSWORD=${LDAP_PASSWORD}  # From .env file
      
      # Group sync
      - ENABLE_LDAP_GROUP_MANAGEMENT=true
      - ENABLE_LDAP_GROUP_CREATION=true
      - LDAP_ATTRIBUTE_FOR_GROUPS=memberOf
    volumes:
      - open-webui:/app/backend/data
    restart: always

volumes:
  open-webui:
```

## Troubleshooting

### Connection Issues

**Problem**: Cannot connect to LDAP server

```bash theme={null}
# Test LDAP connectivity
ldapsearch -x -H ldaps://ad.company.com:636 -b "dc=company,dc=com" -D "cn=svc-openwebui,dc=company,dc=com" -W
```

**Check**:

* Network connectivity to LDAP server
* Firewall rules allow port 389 (LDAP) or 636 (LDAPS)
* Certificate validation if using TLS

### Authentication Failures

**Problem**: Users cannot log in

**Check**:

* `LDAP_SEARCH_BASE` includes the user's organizational unit
* `LDAP_ATTRIBUTE_FOR_USERNAME` matches the login username format
* Service account has read permissions
* `LDAP_SEARCH_FILTERS` don't exclude the user

### Group Sync Not Working

**Problem**: Groups not appearing or syncing

**Check**:

* `ENABLE_LDAP_GROUP_MANAGEMENT=true` is set
* `LDAP_ATTRIBUTE_FOR_GROUPS` matches your directory schema (usually `memberOf`)
* User's LDAP entry contains group memberships
* Group DNs can be parsed (contain `CN=` component)

### Certificate Validation Errors

```bash theme={null}
# Temporarily disable cert validation for testing (NOT for production)
LDAP_VALIDATE_CERT=false

# Or provide CA certificate
LDAP_CA_CERT_FILE=/path/to/ca-cert.pem
```

## Security Best Practices

<Warning>
  **Important Security Considerations:**

  1. **Always use TLS** - Set `LDAP_USE_TLS=true` and `LDAP_SERVER_PORT=636`
  2. **Service Account** - Use dedicated service account with minimal read-only permissions
  3. **Strong Passwords** - Store `LDAP_APP_PASSWORD` securely (use secrets management)
  4. **Certificate Validation** - Set `LDAP_VALIDATE_CERT=true` in production
  5. **Firewall Rules** - Restrict LDAP server access to Open WebUI instances only
  6. **Regular Audits** - Monitor LDAP authentication logs for suspicious activity
</Warning>

## Implementation Details

The LDAP integration is implemented in:

* Configuration: `backend/open_webui/config.py:4109-4200`
* Authentication logic: `backend/open_webui/routers/auths.py:315-573`
* Uses `ldap3==2.9.1` Python library

## Next Steps

* [SCIM Provisioning](/enterprise/scim-provisioning) - For automated user lifecycle management
* [RBAC](/enterprise/rbac) - Configure role-based access control
* [OAuth SSO](/features/sso) - Additional SSO options