Skip to main content

LDAP Configuration

LDAP authentication setup for Chatty AI.

Overview​

Chatty AI supports LDAP authentication, allowing users to log in with their existing corporate credentials. This integrates with:

  • Active Directory
  • OpenLDAP
  • FreeIPA
  • Other LDAP-compatible directories

LDAP Variables​

LDAP_SERVER_URL​

  • Type: String (URL)
  • Required: No (only if using LDAP)
  • Default: None
  • Example:
    • ldap://ldap.company.com
    • ldaps://ldap.company.com:636 (secure)
  • Description: LDAP server URL
  • Format: ldap://host:port or ldaps://host:port
  • Port:
    • LDAP: 389 (default)
    • LDAPS: 636 (secure)
  • Used in: chattyai service

LDAP_BIND_DN​

  • Type: String (Distinguished Name)
  • Required: No (only if using LDAP)
  • Default: None
  • Example: cn=admin,dc=company,dc=com
  • Description: DN of service account for LDAP bind
  • Purpose: Used to search for users
  • Permissions: Read access to user directory
  • Used in: chattyai service

LDAP_BIND_PASSWORD​

  • Type: String (password)
  • Required: No (only if using LDAP)
  • Default: None
  • Security: 🔴 HIGH - Keep secret
  • Example: ldap-service-password
  • Description: Password for LDAP bind DN
  • Used in: chattyai service

LDAP_USER_BASE​

  • Type: String (Distinguished Name)
  • Required: No (only if using LDAP)
  • Default: None
  • Example: ou=users,dc=company,dc=com
  • Description: Base DN where users are located
  • Purpose: Starting point for user searches
  • Used in: chattyai service

LDAP_SEARCH_FILTER​

  • Type: String (LDAP filter)
  • Required: No (only if using LDAP)
  • Default: (uid={0})
  • Example:
    • (uid={0}) - OpenLDAP
    • (sAMAccountName={0}) - Active Directory
    • (mail={0}) - Email-based
  • Description: LDAP search filter for finding users
  • Placeholder: {0} is replaced with username entered at login
  • Used in: chattyai service

Configuration Examples​

Active Directory​

LDAP_SERVER_URL=ldaps://ad.company.com:636
LDAP_BIND_DN=cn=chatty-service,ou=service-accounts,dc=company,dc=com
LDAP_BIND_PASSWORD=service-account-password
LDAP_USER_BASE=ou=employees,dc=company,dc=com
LDAP_SEARCH_FILTER=(sAMAccountName={0})

OpenLDAP​

LDAP_SERVER_URL=ldap://ldap.company.com:389
LDAP_BIND_DN=cn=admin,dc=company,dc=com
LDAP_BIND_PASSWORD=admin-password
LDAP_USER_BASE=ou=people,dc=company,dc=com
LDAP_SEARCH_FILTER=(uid={0})

FreeIPA​

LDAP_SERVER_URL=ldaps://ipa.company.com:636
LDAP_BIND_DN=uid=chatty-service,cn=users,cn=accounts,dc=company,dc=com
LDAP_BIND_PASSWORD=service-password
LDAP_USER_BASE=cn=users,cn=accounts,dc=company,dc=com
LDAP_SEARCH_FILTER=(uid={0})

Email-Based Login​

LDAP_SERVER_URL=ldap://ldap.company.com
LDAP_BIND_DN=cn=admin,dc=company,dc=com
LDAP_BIND_PASSWORD=admin-password
LDAP_USER_BASE=ou=users,dc=company,dc=com
LDAP_SEARCH_FILTER=(mail={0})

Setup Steps​

1. Create Service Account​

Create a dedicated LDAP service account for Chatty AI:

Active Directory:

New-ADUser -Name "Chatty AI Service" `
  -SamAccountName "chatty-service" `
  -UserPrincipalName "chatty-service@company.com" `
  -Path "OU=Service Accounts,DC=company,DC=com" `
  -AccountPassword (ConvertTo-SecureString "SecurePassword123!" -AsPlainText -Force) `
  -Enabled $true

OpenLDAP:

dn: cn=chatty-service,dc=company,dc=com
objectClass: simpleSecurityObject
objectClass: organizationalRole
cn: chatty-service
userPassword: {SSHA}encrypted-password
description: Chatty AI LDAP Service Account

2. Grant Read Permissions​

Service account needs read access to user directory:

Active Directory:

  • Add to "Domain Users" group
  • Grant "Read" permission on Users OU

OpenLDAP:

dn: ou=users,dc=company,dc=com
changetype: modify
add: aci
aci: (targetattr="*")(version 3.0; acl "Chatty AI Read"; allow (read,search,compare) userdn="ldap:///cn=chatty-service,dc=company,dc=com";)

3. Test LDAP Connection​

Test before configuring Chatty AI:

# Test bind
ldapsearch -x -H ldap://ldap.company.com \
  -D "cn=admin,dc=company,dc=com" \
  -w "password" \
  -b "dc=company,dc=com" \
  "(objectClass=*)"

# Test user search
ldapsearch -x -H ldap://ldap.company.com \
  -D "cn=admin,dc=company,dc=com" \
  -w "password" \
  -b "ou=users,dc=company,dc=com" \
  "(uid=testuser)"

4. Configure Chatty AI​

Add LDAP variables to .env:

# LDAP Configuration
LDAP_SERVER_URL=ldap://ldap.company.com
LDAP_BIND_DN=cn=chatty-service,dc=company,dc=com
LDAP_BIND_PASSWORD=service-password
LDAP_USER_BASE=ou=users,dc=company,dc=com
LDAP_SEARCH_FILTER=(uid={0})

5. Restart Services​

docker compose down
docker compose up -d

6. Test Login​

Try logging in with LDAP credentials:

  • Username: LDAP username (e.g., jdoe)
  • Password: LDAP password

Security Best Practices​

1. Use LDAPS (Secure LDAP)​

Always use encrypted connection in production:

# Secure
LDAP_SERVER_URL=ldaps://ldap.company.com:636

# Not secure (dev only)
LDAP_SERVER_URL=ldap://ldap.company.com:389

2. Dedicated Service Account​

  • Create dedicated service account
  • Grant minimal permissions (read-only)
  • Use strong password
  • Rotate password regularly

3. Restrict User Base​

Limit search to specific OU:

# Good - specific OU
LDAP_USER_BASE=ou=employees,dc=company,dc=com

# Bad - entire directory
LDAP_USER_BASE=dc=company,dc=com

4. Secure Bind Password​

# Never commit to git
echo "LDAP_BIND_PASSWORD=*" >> .gitignore

# Use strong password
LDAP_BIND_PASSWORD=$(openssl rand -base64 24)

Troubleshooting​

Connection Failed​

Check LDAP server is reachable:

# Test connection
telnet ldap.company.com 389

# Or with nc
nc -zv ldap.company.com 389

Check firewall allows outbound LDAP:

sudo ufw allow out 389/tcp
sudo ufw allow out 636/tcp

Authentication Failed​

Verify bind credentials:

ldapsearch -x -H ldap://ldap.company.com \
  -D "cn=chatty-service,dc=company,dc=com" \
  -w "password" \
  -b "dc=company,dc=com" \
  "(objectClass=*)"

Check Chatty AI logs:

docker compose logs chattyai | grep -i ldap

User Not Found​

Verify search filter:

# Test search
ldapsearch -x -H ldap://ldap.company.com \
  -D "cn=chatty-service,dc=company,dc=com" \
  -w "password" \
  -b "ou=users,dc=company,dc=com" \
  "(uid=testuser)"

Check user base DN is correct:

# List all users
ldapsearch -x -H ldap://ldap.company.com \
  -D "cn=chatty-service,dc=company,dc=com" \
  -w "password" \
  -b "ou=users,dc=company,dc=com" \
  "(objectClass=person)"

SSL/TLS Errors​

For self-signed certificates, may need to disable verification (dev only):

# Not recommended for production
LDAP_SERVER_URL=ldap://ldap.company.com  # Use non-SSL

Or import CA certificate into container.

LDAP + Local Users​

Chatty AI supports both LDAP and local users:

  • LDAP users: Authenticate via LDAP
  • Local users: Authenticate via database (admin, etc.)
  • First match wins: Checks LDAP first, then local database

Admin Account​

Admin account is always local (not LDAP):

CHATTYAI_ADMIN_EMAIL=admin@company.com
CHATTYAI_ADMIN_PASSWORD=admin-password

This ensures you can always log in even if LDAP is down.

Common LDAP Filters​

Active Directory​

# By username
LDAP_SEARCH_FILTER=(sAMAccountName={0})

# By email
LDAP_SEARCH_FILTER=(userPrincipalName={0})

# By employee ID
LDAP_SEARCH_FILTER=(employeeID={0})

# Multiple attributes
LDAP_SEARCH_FILTER=(|(sAMAccountName={0})(mail={0}))

OpenLDAP​

# By UID
LDAP_SEARCH_FILTER=(uid={0})

# By email
LDAP_SEARCH_FILTER=(mail={0})

# By CN
LDAP_SEARCH_FILTER=(cn={0})

Performance Tuning​

Connection Pooling​

LDAP connections are pooled automatically by Chatty AI.

Search Optimization​

Use specific user base to reduce search scope:

# Fast - specific OU
LDAP_USER_BASE=ou=employees,ou=staff,dc=company,dc=com

# Slow - entire directory
LDAP_USER_BASE=dc=company,dc=com