Centralizing Mail Credentials: A Hands‑On Guide to LDAP Authentication in Dovecot

Why LDAP for Dovecot?

When a mail server grows beyond a handful of users, keeping passwords in local /etc/dovecot/passwd becomes a maintenance nightmare. LDAP lets you store all credentials in a single directory service, making password changes, user provisioning, and group‑based ACLs a one‑stop shop. However, the jump from local to LDAP authentication introduces a handful of pitfalls that can lock out users or expose sensitive data if misconfigured.

Problem Statement

Administrators often find themselves dealing with two separate authentication mechanisms: local files for legacy accounts and LDAP for new ones. This dual setup can cause inconsistent login experiences and double the effort required to manage passwords. The goal is to replace the local file with LDAP without breaking existing mail flows.

Thesis

By configuring Dovecot’s ldap_passwd scheme, binding securely to the LDAP server, and enabling query caching, you can move all user authentication to LDAP while maintaining performance and security.

Step‑by‑Step Configuration

1. Install the LDAP support package. On Debian‑based systems this is apt install dovecot-ldap. On RHEL/CentOS use yum install dovecot-ldap. The package provides the dovecot-ldap plugin and the ldap_passwd schema.

2. Secure the credentials file. Create a file /etc/dovecot/conf.d/ldap.conf and set chmod 600 and ownership to root:dovecot to protect the bind DN and password.

3. Define the LDAP connection. In ldap.conf add:

   hosts = ldap.example.com
   port = 636
   ssl = start_tls
   binddn = cn=admin,dc=example,dc=com
   bindpw = <admin‑password>
   

   Replace placeholders with your server’s actual host, port, and bind credentials. Using TLS is mandatory in production to protect credentials in transit.

4. Specify the user lookup schema. Still in ldap.conf:

   user_filter = (&(objectClass=inetOrgPerson)(uid=%u))
   user_attrs = uid,mail,homeDirectory,mailHomeDirectory
   password_attr = userPassword
   password_scheme = ldap_passwd
   

   The user_filter tells Dovecot how to locate a user; the %u placeholder expands to the username supplied by the client. The password_scheme instructs Dovecot to compare the client’s password against the userPassword attribute stored in LDAP.

5. Enable caching. Add to /etc/dovecot/conf.d/10-auth.conf:

   auth_mechanisms = plain login
   !include_try <mail_auth>
   

   Then create /etc/dovecot/conf.d/20-lua.conf with a simple Lua script to cache LDAP queries if you have the dovecot-ldap-cache plugin installed. A minimal script:

   local cache = require('cache')
   function ldap_cache(key)
     return cache.get(key)
   end
   

   For many environments, the built‑in dovecot-ldap-cache is sufficient; no extra Lua is needed.

6. Restart Dovecot. Run systemctl restart dovecot and verify the service is active.

Concrete Worked Example

Suppose your LDAP tree looks like this:

DN	Attributes
uid=jdoe,ou=Users,dc=example,dc=com	uid=jdoe,mail=[contact removed],userPassword=…
uid=asmith,ou=Users,dc=example,dc=com	uid=asmith,mail=[contact removed],userPassword=…

With the configuration above, a client that connects to Dovecot and sends:

AUTHENTICATE LOGIN
jdoe
P@ssw0rd

will have Dovecot query LDAP for (uid=jdoe), retrieve the userPassword attribute, and compare it against the supplied password. If the hash matches, authentication succeeds and the user can open IMAP/POP3 sessions.

Verification Checklist

1. View current settings. Run dovecot -n on the server. Look for the hosts, binddn, and user_filter lines under the ldap section.

2. Test LDAP lookup. From the Dovecot host, execute:

   ldapsearch -x -H ldap://ldap.example.com -b "ou=Users,dc=example,dc=com" "(uid=jdoe)"
   

   Ensure the output contains the expected attributes.

3. Attempt a real login. Use an IMAP client (e.g., openssl s_client -connect mail.example.com:993) to issue an AUTHENTICATE command. Observe the log entry in /var/log/dovecot.log for an ldap entry that shows the query and result.

4. Check cache hits. In the log, look for ldap_cache_hit or ldap_cache_miss markers to confirm caching is active.

Trade‑Offs and Limitations

• Performance vs. Freshness. Caching reduces round‑trips to LDAP but may serve stale passwords if the user changes credentials outside of Dovecot. The cache TTL (default 10 minutes) can be tuned via cache_ttl in the LDAP config.
• Single Point of Failure. If the LDAP server goes down, authentication fails for all users. Consider a secondary LDAP host or a fallback to local files for critical accounts.
• Credential Exposure. Storing the bind DN and password in ldap.conf requires strict file permissions. Failure to secure this file can compromise the entire directory.
• Complex Filters. Overly broad search filters can inadvertently expose unrelated entries. Always include the objectClass constraint and limit the scope with base DN.

Actionable Closing

By following the configuration steps, securing credentials, and enabling caching, you can migrate all Dovecot authentication to LDAP with minimal disruption. Remember to monitor the logs for authentication failures and cache hit ratios. If you notice frequent cache misses, consider increasing the cache size or adjusting TTLs. Finally, test the setup in a staging environment before rolling out to production to catch any subtle misconfigurations.