Skip to main content

Zimbra configuration

Prerequisites

This document describes how to configure Active Directory (AD) authentication for the Zimbra mail domain addomain.example.com, using the AD domain addomain.local, and integrate it with the Intalio ZI-ADPassword extension.

Required information:

  • Zimbra mail domain: addomain.example.com (example).
  • AD DNS domain and user UPN suffix: addomain.local (example; verify the actual UPN suffix).
  • AD domain controller FQDN: ad.addomain.local (example).
  • AD search base: DC=addomain,DC=local (adjust to your directory structure).
  • Dedicated AD service account DN and credentials, with the permissions required for directory searches and the password operations implemented by the extension.
  • Trusted CA certificate for the AD server, or the AD server certificate itself if it is genuinely self-signed, in PEM format.
  • A Zimbra test account that maps unambiguously to an AD test user.

Security: Do not use a Domain Administrator account for routine directory searches. Delegate only the permissions required by the extension. 

References: Zimbra external AD authentication

Domain configuration

Run the following Zimbra administration commands as the zimbra system user:

su - zimbra

Check whether the mail domain already exists:

zmprov gd addomain.example.com

If it does not exist, create it once:

zmprov cd addomain.example.com

LDAPS certificate and connectivity

On every Zimbra mailbox server, obtain the AD CA certificate from a trusted administrator. If the domain controller uses a genuinely self-signed server certificate, use that server certificate instead. In the commands below the certificate is saved as /tmp/ad_ca_or_dc.pem; make sure it is readable by the zimbra user.

Inspect the certificate and verify its SHA-256 fingerprint against a trusted value:

/opt/zimbra/common/bin/openssl x509 \
  -in /tmp/ad_ca_or_dc.pem -noout \
  -subject -issuer -dates -fingerprint -sha256

Import the certificate using the Zimbra certificate-management utility (run as zimbra):

/opt/zimbra/bin/zmcertmgr addcacert /tmp/ad_ca_or_dc.pem

Verify the AD server's TLS certificate, including its hostname, using the certificate or CA file selected above:

/opt/zimbra/common/bin/openssl s_client \
  -connect ad.addomain.local:636 \
  -servername ad.addomain.local \
  -verify_hostname ad.addomain.local \
  -CAfile /tmp/ad_ca_or_dc.pem \
  -verify_return_error < /dev/null

Expect a successful TLS verification (for example, Verify return code: 0 (ok)). The DNS name configured in zimbraAuthLdapURL must match a DNS name in the AD server certificate's Subject Alternative Name (SAN). 

Note: A successful zmcertmgr addcacert import makes the certificate trusted; it does not configure AD authentication or grant password-change permissions.

Active Directory authentication settings

The following example maps the local part of a Zimbra address, %u, to an AD user. It assumes the user's AD sAMAccountName matches the local part of their Zimbra email address. Verify this mapping for your users before applying the configuration.

zmprov md addomain.example.com zimbraAuthLdapSearchBase 'DC=addomain,DC=local'
zmprov md addomain.example.com zimbraAuthLdapSearchBindDn 'CN=svc_zimbra,CN=Users,DC=addomain,DC=local'
zmprov md addomain.example.com zimbraAuthLdapSearchBindPassword 'REPLACE_WITH_SERVICE_ACCOUNT_PASSWORD'
zmprov md addomain.example.com zimbraAuthLdapSearchFilter '(sAMAccountName=%u)'
zmprov md addomain.example.com zimbraAuthLdapURL 'ldaps://ad.addomain.local:636'

Configuration details:

  • zimbraAuthLdapSearchBase – LDAP subtree used for locating AD accounts. The domain root includes accounts in organizational units as well as the default CN=Users container.
  • zimbraAuthLdapSearchBindDn – dedicated service account used for LDAP searches; replace the example DN with the real DN.
  • zimbraAuthLdapSearchBindPassword – service-account password; insert securely, never in a published document.
  • zimbraAuthLdapSearchFilter – lookup filter; adjust if Zimbra usernames do not match AD sAMAccountName.
  • zimbraAuthLdapURL – LDAPS URL, using the FQDN covered by the domain controller's TLS certificate.

Important: Standard Zimbra authentication can use either a bind-name template or a directory search to identify a user. When both are configured, search-based resolution may take precedence.

Test standard AD authentication

On a new/test mail domain, first test standard Zimbra AD authentication before enabling the custom extension:

zmprov md addomain.example.com zimbraAuthMech ldap
zmprov gd addomain.example.com | grep -E '^zimbraAuth'

Restart mailboxd on each affected mailbox server after the certificate import, then test logging in with a non-privileged AD test account:

zmmailboxdctl restart

Check that a valid AD password works and that an incorrect password is rejected. A matching Zimbra mailbox account must exist (or an independently configured auto-provisioning mechanism must create it); external authentication alone does not provision mailboxes.

Production caution: If the mail domain already has working authentication, changing zimbraAuthMech affects its users. Perform this validation in a test environment or a maintenance window and record the previous authentication setting.

ZI-ADPassword extension configuration

Only after the Intalio ZI-ADPassword server extension has been installed, licensed, and confirmed compatible with the Zimbra version, configure the password-change listener and custom authentication:

zmprov md addomain.example.com zimbraPasswordChangeListener ZIADChangePassword
zmprov md addomain.example.com zimbraAuthMech 'custom:ZIADPassword'

Restart mailboxd on every mailbox server after activating the extension:

zmmailboxdctl restart

Verification and troubleshooting

Test with a dedicated, non-privileged AD account:

  1. Confirm that the user can log in to Zimbra using their current AD password.
  2. Confirm that the password-change option is visible in the relevant Zimbra web client and COS configuration.
  3. Change the password from Zimbra and verify directly in AD that the operation succeeded.
  4. Confirm that the new password works.
  5. Test an AD account whose password has expired or is marked for password change at next logon.
  6. Check unsuccessful authentication attempts and account lockouts in both AD and Zimbra.

If the change-password option is missing, check the account/COS attribute zimbraFeatureChangePasswordEnabled and whether the extension supports the selected web client. Do not blindly change COS settings for all users.

Inspect mailbox logs during a controlled test:

tail -f /opt/zimbra/log/mailbox.log
tail -f /opt/zimbra/log/zmmailboxd.out

In a multi-server deployment, examine the mailbox server that processed the user's request.

Rollback: Before enabling custom:ZIADPassword, record the prior values of zimbraAuthMech and zimbraPasswordChangeListener. If authentication fails after the change, restore the previous, working configuration and restart mailboxd. Do not assume that ad was the previous production setting.