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:

# 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

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

# 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:

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:

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:

# 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

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”

Docker Compose Example

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

# 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

# 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

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

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 - For automated user lifecycle management
• RBAC - Configure role-based access control
• OAuth SSO - Additional SSO options