How to Configure External LDAP Authentication for Zimbra

What external LDAP authentication changes in Zimbra

External LDAP authentication lets Zimbra verify a user’s password against another directory instead of the password stored in Zimbra’s internal LDAP. The current Zimbra Daffodil (v10) Administrator Guide states that external LDAP authentication is configured per domain and that the external method attempts to bind to the specified directory with the supplied user credentials. If the bind succeeds, the password is considered valid.

This does not automatically turn an external LDAP directory into Zimbra’s account database. Zimbra still stores Zimbra-specific account data in its own directory. The v10 guide explicitly notes that users normally need to exist in both Zimbra and the external directory unless you separately configure auto-provisioning.

For the current product documentation, see the Zimbra Daffodil v10 Administrator Guide and the Zimbra v10 Config Guide.

Quick planning checklist

• Confirm the Zimbra domain you want to change, for example example.com.
• Confirm that the same users already exist in Zimbra, or plan auto-provisioning separately.
• Know the external LDAP hostname, port, TLS method, and certificate chain.
• Know how a Zimbra login name maps to a user DN in LDAP.
• If the DN cannot be built directly from the login name, prepare a search base, search filter, and least-privilege search account.
• Keep a Zimbra administrator session open while testing so you can roll back quickly.

Choose the right mapping method first

The current v10 Config Guide still defines the search-base, search-bind, search-filter, and per-account external-DN attributes. Older official Zimbra Tech Center material explains how these mappings are used in practice. Because that material predates Daffodil, treat it as operational background and verify details against your installed release before applying a large migration. See the official Zimbra Tech Center external LDAP notes.

Step 1: Record the current domain authentication settings

Run administrative commands as the zimbra operating-system user. Before changing anything, capture the existing domain values:

su - zimbra

zmprov gd example.com \
  zimbraAuthMech \
  zimbraAuthLdapURL \
  zimbraAuthLdapBindDn \
  zimbraAuthLdapSearchBase \
  zimbraAuthLdapSearchFilter \
  zimbraAuthFallbackToLocal

Save the output in your change record. The v10 Config Guide lists valid values for zimbraAuthMech, including zimbra, ldap, ad, and Kerberos or custom mechanisms. For this guide, the target mechanism is ldap.

Step 2: Verify network reachability and TLS before changing Zimbra

Do not troubleshoot authentication mappings until basic connectivity is known to work. From the Zimbra server, confirm DNS resolution and that the LDAP endpoint is reachable. For LDAPS, you can inspect the certificate chain with OpenSSL:

openssl s_client -connect ldap.example.net:636 \
  -servername ldap.example.net -showcerts

For a directory using standard LDAP plus StartTLS, test the StartTLS-capable endpoint with an LDAP client appropriate for your operating system. If ldapsearch is installed, a search-account check can look like this:

ldapsearch -x -H ldap://ldap.example.net:389 -ZZ \
  -D "cn=zimbra-search,ou=svc,dc=example,dc=net" -W \
  -b "ou=people,dc=example,dc=net" \
  "(uid=alice)" dn

Zimbra’s v10 Administrator Guide states that an ldaps: endpoint requires the LDAP server certificate to be trusted by Zimbra. Do not bypass certificate validation merely to make the test pass. Install the appropriate CA or certificate chain according to the trust-store procedure for your exact Zimbra build.

Step 3: Configure a direct bind-DN template when user DNs are predictable

This is the simplest pattern. Suppose the external directory stores users as uid=alice,ou=people,dc=example,dc=net and the Zimbra login is alice@example.com. Configure the domain like this:

zmprov md example.com zimbraAuthMech ldap

zmprov md example.com \
  zimbraAuthLdapURL "ldaps://ldap.example.net:636"

zmprov md example.com \
  zimbraAuthLdapBindDn "uid=%u,ou=people,dc=example,dc=net"

The Administrator Guide describes zimbraAuthLdapBindDn as a format string used to determine the DN used for the external bind. Official Zimbra Tech Center documentation describes common substitution values such as %u for the local part of the login name and %n for the complete login name.

Use a DN template only when it deterministically identifies the right directory object. If users are located under different organizational units or their DN is not derived from the login name, use the search-filter pattern instead.

Step 4: Use search-filter mapping when the DN cannot be constructed directly

Search-filter mapping lets Zimbra first locate the user entry, then authenticate against the returned DN. The v10 Config Guide defines the required search-related domain attributes.

A typical OpenLDAP-style configuration is:

zmprov md example.com \
  zimbraAuthLdapSearchBase "ou=people,dc=example,dc=net"

zmprov md example.com \
  zimbraAuthLdapSearchFilter "(uid=%u)"

zmprov md example.com \
  zimbraAuthLdapSearchBindDn \
  "cn=zimbra-search,ou=svc,dc=example,dc=net"

To avoid putting a directory password directly into shell history, read it into a temporary shell variable first:

read -s LDAP_BIND_PASSWORD
zmprov md example.com \
  zimbraAuthLdapSearchBindPassword "$LDAP_BIND_PASSWORD"
unset LDAP_BIND_PASSWORD

The search account should have only the read access needed to find users under the configured base. It does not need broad directory-administration privileges.

For Active Directory, a filter might use sAMAccountName or userPrincipalName, depending on your login convention. Zimbra also provides an external Active Directory authentication mechanism, so use the AD-specific mechanism when it better matches your deployment rather than forcing every AD environment through generic LDAP settings.

Step 5: Verify what Zimbra actually stored

Read the domain attributes back after the change:

zmprov gd example.com \
  zimbraAuthMech \
  zimbraAuthLdapURL \
  zimbraAuthLdapBindDn \
  zimbraAuthLdapSearchBase \
  zimbraAuthLdapSearchFilter \
  zimbraAuthLdapSearchBindDn \
  zimbraAuthFallbackToLocal

Check for quoting mistakes, an incorrect base DN, an unexpected hostname, or an old mapping left in place from a previous attempt. Do not print the search-bind password into documentation, screenshots, tickets, or shell transcripts.

Step 6: Test with one controlled user before broad rollout

Choose a non-administrator test account that exists in both Zimbra and the external directory. Test these cases deliberately:

• The correct external LDAP password allows Zimbra login.
• An incorrect external LDAP password is rejected.
• A disabled or locked directory account behaves according to your directory policy.
• A Zimbra account that does not exist cannot log in unless auto-provisioning has been configured.
• LDAP server or network failure produces the expected failure behavior.

The last test matters because zimbraAuthFallbackToLocal is a separate domain option. The v10 documentation says its default is FALSE. Enabling fallback may be useful for a carefully designed migration, but it can also defeat the expectation that disabling or changing a password in the external directory immediately blocks access if an old local Zimbra password remains valid. Treat fallback as a security-policy decision, not a generic troubleshooting switch.

Step 7: Decide whether you also need auto-provisioning

External authentication and account provisioning are different functions. If new directory users should automatically receive Zimbra accounts, configure Zimbra auto-provisioning separately. The current v10 Administrator Guide documents EAGER, LAZY, and MANUAL modes and their own zimbraAutoProv* attributes.

Do not reuse authentication settings blindly for auto-provisioning. Auto-provisioning has separate URL, bind, search-base, filter, account-name mapping, and attribute-mapping options. First make external authentication reliable for an existing user; then design provisioning as a second change.

Common failure patterns and what to check

Rollback plan

If the external directory configuration prevents normal user authentication, switch the domain back to internal Zimbra authentication using an administrator session that is already open:

zmprov md example.com zimbraAuthMech zimbra

Then verify the value:

zmprov gd example.com zimbraAuthMech

Do not delete the external LDAP attributes during an emergency rollback unless you have a reason to. Keeping them in place makes it easier to inspect what failed and retry after correcting the mapping or TLS issue.

Practical reference summary

• zimbraAuthMech: selects the authentication mechanism for the domain.
• zimbraAuthLdapURL: external LDAP endpoint; use ldaps: for LDAP over SSL.
• zimbraAuthLdapBindDn: format used to construct the user DN for direct binding.
• zimbraAuthLdapSearchBase: subtree in which Zimbra searches for the external user.
• zimbraAuthLdapSearchFilter: LDAP filter used to locate the user.
• zimbraAuthLdapSearchBindDn and zimbraAuthLdapSearchBindPassword: credentials used for the lookup when anonymous search is not appropriate.
• zimbraAuthLdapExternalDn: explicit external DN mapping for a single Zimbra account.
• zimbraAuthFallbackToLocal: controls whether Zimbra falls back to local authentication if external authentication fails.

Final validation checklist

• External LDAP endpoint is reachable from the Zimbra mailbox server.
• TLS certificate validation succeeds without insecure workarounds.
• The chosen bind-DN template or search filter maps one login to exactly one directory entry.
• The test user exists in Zimbra or auto-provisioning is intentionally configured.
• Correct and incorrect password tests behave as expected.
• Fallback behavior matches your security policy.
• The original domain settings and rollback command are documented.

For production changes, prefer a staged rollout with one test domain or a small user group. External LDAP authentication is straightforward when identity mapping is predictable; most difficult failures come from DN mapping, certificate trust, or confusing authentication with account provisioning.