Configure LDAP (Lightweight Directory Access Protocol) authentication for your Devana.ai whitemark instance. This allows integration with existing directory services like Active Directory, OpenLDAP, or other LDAP-compliant systems.
Required Environment Variables
Variable
Description
Required
Example
LDAP_URL
LDAP server URL
Yes
ldap://ldap.yourcompany.com:389 or ldaps://ldap.yourcompany.com:636
LDAP_BIND_DN
Distinguished name for binding
Yes
cn=admin,dc=yourcompany,dc=com
LDAP_BIND_CREDENTIALS
Password for bind DN
Yes
your-admin-password
LDAP_SEARCH_BASE
Base DN for user searches
Yes
ou=users,dc=yourcompany,dc=com
LDAP_SEARCH_FILTER
Filter for finding users
Yes
(uid={{username}}) or (sAMAccountName={{username}})
Setup Instructions
1. LDAP Server Configuration
Ensure your LDAP server is properly configured and accessible:
Network Access:
LDAP server must be accessible from your Devana.ai server
Standard ports: 389 (LDAP), 636 (LDAPS)
Ensure firewall rules allow connections
Service Account:
Create a service account for binding to LDAP
Grant read permissions for user directory
Use least-privilege principle
2. Environment Configuration
For Active Directory:
# LDAP Configuration for Active Directory
LDAP_URL=ldap://dc.yourcompany.com:389
LDAP_BIND_DN=cn=service-account,cn=Users,dc=yourcompany,dc=com
LDAP_BIND_CREDENTIALS=your-service-account-password
LDAP_SEARCH_BASE=cn=Users,dc=yourcompany,dc=com
LDAP_SEARCH_FILTER=(sAMAccountName={{username}})
For OpenLDAP:
# LDAP Configuration for OpenLDAP
LDAP_URL=ldap://ldap.yourcompany.com:389
LDAP_BIND_DN=cn=admin,dc=yourcompany,dc=com
LDAP_BIND_CREDENTIALS=your-admin-password
LDAP_SEARCH_BASE=ou=people,dc=yourcompany,dc=com
LDAP_SEARCH_FILTER=(uid={{username}})
For Secure LDAP (LDAPS):
# LDAP Configuration with SSL/TLS
LDAP_URL=ldaps://ldap.yourcompany.com:636
LDAP_BIND_DN=cn=admin,dc=yourcompany,dc=com
LDAP_BIND_CREDENTIALS=your-admin-password
LDAP_SEARCH_BASE=ou=users,dc=yourcompany,dc=com
LDAP_SEARCH_FILTER=(uid={{username}})
3. Whitemark Configuration
Configure your whitemark to include LDAP as an allowed provider:
Application binds to LDAP server using service account credentials
Application searches for user using the provided username
If user found, application attempts to bind with user's credentials
If bind successful, user profile is extracted from LDAP attributes
User is created/updated in Devana.ai and logged in
User Data Mapping
LDAP attributes are mapped to Devana.ai user fields:
LDAP Attribute
Devana.ai Field
Notes
mail or userPrincipalName
email
Primary identifier
givenName
firstName
First name
sn
lastName
Last name
cn
displayName
Common name (fallback for names)
uid
providerId
Unique user identifier
dn
-
Distinguished name (available but not mapped)
LDAP Attributes Retrieved
The system retrieves the following attributes from LDAP:
searchAttributes: [
"dn", // Distinguished Name"uid", // User ID"cn", // Common Name"sn", // Surname"givenName", // Given Name"mail", // Email Address"userPrincipalName", // User Principal Name (AD)
]
Search Filter Examples
Active Directory Filters
# By username
(sAMAccountName={{username}})
# By email
(userPrincipalName={{username}})
# By multiple attributes
(|(sAMAccountName={{username}})(userPrincipalName={{username}}))
OpenLDAP Filters
# By user ID
(uid={{username}})
# By email
(mail={{username}})
# By multiple attributes
(|(uid={{username}})(mail={{username}}))
Security Considerations
Connection Security
Use LDAPS when possible:
LDAP_URL=ldaps://ldap.yourcompany.com:636
StartTLS for non-encrypted connections:
LDAP over TLS on standard port 389
Requires server support for StartTLS
Service Account Security
Least Privilege:
Grant only read permissions for user directory
Avoid using administrative accounts
Credential Management:
Store credentials securely
Rotate service account passwords regularly
Monitor service account usage
Network Security
Firewall Rules:
Restrict LDAP access to authorized servers only
Use VPN or private networks when possible
Monitoring:
Log authentication attempts
Monitor for suspicious activity
Advanced Configuration
Custom Attributes
To retrieve additional LDAP attributes, modify the search attributes:
LDAP can provide group information for authorization:
Add group attributes to search:
searchAttributes: [..., "memberOf"]
Implement group checking in authentication callback:
// Check if user is member of required groupsconst requiredGroups = ["cn=devana-users,ou=groups,dc=company,dc=com"];
const userGroups = Array.isArray(user.memberOf) ? user.memberOf : [user.memberOf];
Troubleshooting
Common Issues
Connection refused / timeout:
Verify LDAP server is running and accessible
Check firewall rules and network connectivity
Confirm correct port (389 for LDAP, 636 for LDAPS)
Bind failed / Invalid credentials:
Verify LDAP_BIND_DN and LDAP_BIND_CREDENTIALS are correct
Check service account exists and has proper permissions
Ensure DN format matches your LDAP schema
User not found:
Verify LDAP_SEARCH_BASE contains the user accounts
Check LDAP_SEARCH_FILTER matches your LDAP schema
Confirm username format matches expected attribute
No email found in profile:
User may not have mail or userPrincipalName attributes
Check LDAP user attributes with LDAP browser tool
Verify email attribute is populated in directory
SSL/TLS certificate errors:
For LDAPS, ensure valid SSL certificate on LDAP server
Consider certificate validation settings for self-signed certificates
Check certificate chain and CA trust
Testing LDAP Connection
Use command-line tools to test LDAP connectivity:
# Test basic connection
ldapsearch -x -H ldap://ldap.yourcompany.com:389 -D "cn=admin,dc=yourcompany,dc=com" -W -b "dc=yourcompany,dc=com""(objectClass=person)"# Test user search
ldapsearch -x -H ldap://ldap.yourcompany.com:389 -D "cn=admin,dc=yourcompany,dc=com" -W -b "ou=users,dc=yourcompany,dc=com""(uid=testuser)"
Debug Logging
Enable LDAP debug logging:
DEBUG=ldap*
This will show:
Connection attempts
Bind operations
Search queries and results
Authentication flow details
Best Practices
Use LDAPS or StartTLS for encrypted connections
Create dedicated service account with minimal permissions
Implement proper error handling for connection failures
Monitor authentication logs for security issues
Test failover scenarios if using multiple LDAP servers
Document your LDAP schema and attribute mappings
Regularly audit service account permissions
Consider connection pooling for high-volume deployments
High Availability
For production deployments, consider:
Multiple LDAP Servers:
Configure failover to secondary servers
Use load balancers for LDAP traffic
Connection Pooling:
Maintain persistent connections
Handle connection timeouts gracefully
Monitoring:
Monitor LDAP server health
Alert on authentication failures
Track response times
Migration Notes
When migrating from other authentication systems:
User Mapping:
Ensure LDAP users can be matched to existing accounts