LDAP Authentication

Revision as of 21:10, 24 July 2007 by Kevin kluge (talk | contribs)

Zimbra permits the use of external LDAP servers per domain for end user authentication. Zimbra user accounts are mapped to LDAP accounts on an external host using an LDAP query filter. Though it is always a good idea to use an LDAP search base, it may not be required by your LDAP server.

LDAP filter

Zimbra will use an LDAP query filter to map user accounts to entries on the external LDAP server. For example, Zimbra user usera@domain.com might be mapped to an entry in the external LDAP server having a uid attribute value of 'usera', mail attribute of 'usera@domain.com' and an objectClass of 'OrganizationalPerson'. Only a single unique attribute is required to successfully map Zimbra accounts.

To set the LDAP query filter, you will need a substitution variable and an attribute on the external LDAP server to search. The substitution variable is obtained from the 'Username' box on the user login page. Possible substitution variables are (e.g., usera@domain.com):

%n = username with @ symbol - returns 'usera@domain.com'
%u = username without the @ - returns 'usera'
%d = domain - returns 'domain.com'
%D = domain as dc=domain,dc=com - this is a common format for directories such as Active Directory and OpenLDAP


Possible filters for OpenLDAP

(uid=%u) - The user has a uid attribute value in the external directory equal to the user portion of the Zimbra user account.
(uid=%n) - Entire Zimbra user account is used to identify user in the external directory.
(&(cn=%u)(objectClass=OrganizationalPerson)) - The user has a cn attribute value in the directory equal to the user portion of the Zimbra account and has an objectClass value of 'OrganizationalPerson'.

Possible filters for Active Directory

(samAccountName=%u) - The user has a samAccountName attribute value in AD equal to the user portion of the Zimbra user account.
(userPrincipalName=%n) - The user has a userPrincipal attribute value in AD equal to the entire Zimbra user account.

LDAP search base

The search bases tells the Zimbra server which part of the external directory tree to search. Think of the search base as the "top" of the directory for your LDAP users although it may not always the top of the directory itself. The search base may be something equivalent to the organization, group, or domain name (AD) of external directory.

Common examples

o=corp - Exchange 5.5
o=corp,c=us - Lotus Domino
dc=domain,dc=com - Active Directory, OpenLDAP
ou=Mail Users,dc=domain,dc=com - Active Directory restricting to "Mail Users" organizational unit

LDAP bind DN

The bind DN is the user on the external LDAP server permitted to search the LDAP directory within the defined search base. Most of the time, the bind DN will be permitted to search the entire directory. The role of the bind DN is to query the directory using the LDAP query filter and search base for the DN (distinguished name) for authenticating Zimbra users. When the DN is returned, the DN and password are used to authenticate the Zimbra user.


Possible Active Directory bind DNs

cn=administrator,cn=Users,dc=domain,dc=com - DN format
administrator@domain.com - User principal name format



Configuring external LDAP authentication

In in the "Configuration" section of the administration console.

  1. Expand "Domains" and select the domain for which to configure authentication.
  2. Click "Configure Authentication" to initiate the Authentication Configuration Wizard.
  3. Select "External LDAP" for "Authentication Mechanism". Click "Next".
  4. In the LDAP URL box, type the fully qualified hostname (FQDN) or IP address of the external LDAP server. Specify the LDAP port if required (default 389). Check "Use SSL" if the external LDAP server is configured for LDAP over SSL (LDAPS).
  5. Specify the query filter in the "LDAP filter" box.
  6. Specify the search base in the "LDAP search base" box. Click "Next".
  7. If the external LDAP server allows anonymous queries to the directory, click "Next" and skip to step 10. Otherwise, check the box for "Use DN/Password to bind to external server".
  8. In the "Bind DN" box, specify the distinguished name of a user with search permissions on the directory.
  9. Enter the bind password in the "Bind password" and "Confirm bind password" boxes. Click "Next".
  10. Review and confirm the authentication settings, then test the configuration by supplying a username and password in the boxes provided.


Sanity check

As a basic test you can try running ldapsearch from the shell on the ZCS server, binding as a (failing) user to your external directory. You should be able to get this to work as a first step in verifying connectivity, DN, password, and appropriate access controls on the external LDAP server.


To enable logging on the mailbox server to help diagnose problems, set log4j.logger.zimbra.account=DEBUG in log4j.properties and restart the mailbox server.

In general the ZCS mailbox server will authenticate based on the zimbraAuthLdapSearch attributes on the ZCS domain of the user. For those instances you should see something like:

   "auth with search filter of {computed-search-filter}"

And if the search finds a match in the external directory it will log:

   "search filter matched {DN-of-the-acct-in-external-directory}" 

and then authenticate to {DN-of-the-acct-in-external-directory}

ZCS does provide for setting the specific DN to bind to on a particular account. Most of the time this is not done, but if done it can cause problems (or fix them) for specific accounts. To see if this is set on a failing account do "zmprov ga <account> | grep zimbraAuthLdapExternalDn". If that returns nothing, this attribute is not set and the domain settings are in effect.

If this is set the log entry will show something like

   "auth with explicit dn of {the-DN-in-zimbraAuthLdapExternalDn}"

If some users succeed and others fail

Authentication will attempt to auth against the native ZCS OpenLDAP server as well as the external LDAP server. If some users are succeeding in a domain and others are failing, it is possible that the external configuration is completely broken, and only those users with local passwords are successfully authenticating.

If some domains succeed and others fail

Authentication is configured on a per-domain basis. If your ZCS supports multiple domains you'll need to configure each one, even if they all point to the same external LDAP server.

More Information

Jump to: navigation, search