Zimbra Directory Service (LDAP)

Zimbra Directory Service (LDAP)

   KB 1450        Last updated on 2015-07-13  

(0 votes)

(From Zimbra 4.0 docs)

The Zimbra LDAP service is a directory service running a version of the OpenLDAP software that has the Zimbra schema already installed. This chapter describe how the directory service is used for user authentication and account configuration and management.

Note: Zimbra also supports integration with Microsoft’s Active Directory Server. Contact Zimbra support for more detailed information on specific directory implementation scenarios.

The LDAP server is identified when the Zimbra software is installed. Each server has its own LDAP entry that includes attributes specifying operating parameters. In addition, there is a global configuration object that sets defaults for any server whose entry does not specify every attribute.

A selected subset of these attributes can be modified through the Zimbra administration console; others can be changed through the CLI utility.

Directory Services Overview

LDAP directory services provide a centralized repository for information about users and devices that are authorized to use your network. The central repository used for Zimbra’s LDAP data is the OpenLDAP directory server.

The figure below shows traffic between the Zimbra-LDAP directory server and the other servers in the Zimbra system. The Zimbra MTA and the Zimbra mailbox server read from, or write to, the LDAP database on the directory server. The edge MTA does not connect to the LDAP database; instead, it uses the DNS server’s MX entry to determine where to direct mail.

The Zimbra clients connect through the Zimbra server, which in turn connects to LDAP.

Figure 4: LDAP Directory Traffic

5 Zimbra LDAP.4.1.1.jpg

At the core of every LDAP implementation is a database organized using a schema. The schema specifies the types of objects that are stored in the database, and what types of attributes they have.

An LDAP directory entry consists of a collection of attributes and has a globally unique distinguished name (DN). The attributes allowed for an entry are determined by the object classes associated with that entry. The values of the object class attributes determine the schema rules the entry must follow.

The object classes determine what type of object the entry refers to and what type of data can be stored for that entry. An entry’s object classes that determines what kind of entry it is, is called a structural object class and cannot be changed. Other object classes are called auxiliary and may be added to or deleted from the entry.

Use of auxiliary object classes in LDAP allows for an object class to be combined with an existing object class. For example, an entry with structural object class inetOrgPerson, and auxiliary object class zimbraAccount, would be an account, either administrator or end-user. An entry with the object class zimbraServer would be a server in the Zimbra system that has one or more Zimbra software packages installed.

LDAP Hierarchy

LDAP directories are arranged in an hierarchal tree-like structure. In the Zimbra system, the structure is arranged based on Internet domain names. LDAP entries typically include items such as user accounts, organizations, or servers.

The figure below shows the Zimbra LDAP hierarchy. Each type of entry (object) has certain associated object classes.

Figure 5: Zimbra LDAP Hierarchy

5 Zimbra LDAP.4.1.2.jpg

For a complete listing of the Zimbra auxiliary object classes, see the Zimbra LDAP Schema.

Zimbra Schema

Every LDAP implementation has a schema that defines its domain structure, account attributes, and other data structures in use by the organization. Zimbra includes a custom LDAP schema that extends the generic schema included with OpenLDAP software and is designed to potentially coexist with existing directory installations. The Zimbra server, the Zimbra administration console, the command-line account provisioning, and the management utilities require the Zimbra schema.

All attributes and object classes specifically created for Zimbra are prefaced by “zimbra”, as in zimbraMailRecipient object class or the zimbraAttachmentsBlocked attribute.

The Zimbra schema assumes a baseline schema. In the OpenLDAP installer package included with the Zimbra system, the following schema files are included in the OpenLDAP implementation:


Note: You cannot modify the Zimbra schema.

Account Authentication

This section describes the account authentication mechanisms and formatting directives supported:

External LDAP
External Active Directory

The Internal authentication method assumes the Zimbra schema running on the OpenLDAP directory server.

The External LDAP and External Active Directory authentication methods attempt to bind to the specified LDAP server, using the supplied user name and password. These method can be used if the email environment uses Microsoft Active Directory directory services for authentication and the Zimbra-LDAP directory services for all other Zimbra-related transactions. This requires that users exist in both OpenLDAP and in the Active Directory servers.

The method type is set on a per-domain basis, using the zimbraAuthMech attribute, with other information also coming from the domain. If this attribute is not set, the default is to use the internal method as the authentication.

The Internal Authentication Mechanism

For accounts stored in the OpenLDAP server, the userPassword attribute stores a salted-SHA1 (SSHA) digest of the user’s password. This information is not used to connect to the directory server; it is only used to compare with the information on the OpenLDAP server, using a pool of re-usable administrator LDAP connections.

External LDAP and External Active Directory Authentication Mechanism

Unlike the internal authentication mechanism, the external authentication mechanism attempts to bind to the directory server using the supplied user name and password. If this bind succeeds, the connection is closed and the password is considered valid.

Two additional domain attributes are required for the external mechanism:zimbraAuthLdapURL and zimbraAuthLdapBindDn.

zimbraAuthLdapURL Attribute and SSL

The zimbraAuthLdapURL attribute contains the URL of the Active Directory server to bind to. This should be in the form:


where ldapserver is the IP address or host name of the Active Directory server, and port is the port number. You can also use the fully qualified host name instead of the port number.

Examples include:


For SSL connection, use ldaps: instead of ldap:. If the SSL version is used, the SSL certificate used by the server must be configured as a trusted certificate.

zimbraAuthLdapBindDn Attribute

The zimbraAuthLdapBindDn attribute is a format string used to determine which user name to use when binding to the Active Directory server.

During the authentication process, the user name starts out in the format:


The user name may need to be transformed into a valid LDAP bind dn (distinguished name). In the case of Active Directory, that bind dn might be in a different domain

Zimbra Objects

Zimbra uses auxiliary object classes to add Zimbra-specific attributes to existing objects such as an account. The LDAP objects used in Zimbra include the following:

Class of Service (COS)
Distribution Lists
Global Configurations

Accounts Object

An account object represents an account on the Zimbra mailbox server that can be logged into. Account entrees are either administrators or user accounts that can be logged into. The object class name is zimbraAccount. This object class extends the zimbraMailRecipient object class.

The object class zimbraMailRecipient is a directory entry that represents an entity that can receives mail. This is a visible external mail address that is expanded through aliases or forwarding into one or more internal/external addresses.

All accounts have the following properties:

A name in the format of user@some.domain
A unique ID that never changes and is never reused
A set of attributes, some of which are user-modifiable (options) and others that are only configurable by the system administrator

All user accounts are associated with a domain, so a domain must be created before creating any accounts.

For more about account provisioning, see Managing ZCS Configuration.

Class of Service (COS) Object

Class of Service is a Zimbra-specific object that defines the default attributes an email account has and what features are added or denied. The COS controls features, default preference settings, mailbox quotas, message lifetime, password restrictions, attachment blocking and server pools for creation of new accounts. The object class name is zimbraCOS.

Each account is assigned a class of service. COS is used to group accounts and define the feature levels for those accounts. For example, executives can be assigned to a COS that allows the Calendar application. By grouping accounts into specific type of COS, account features can be updated in block.

If the COS is not explicitly set, or if the COS assigned to the user no longer exists, values come from a pre-defined COS called “default”.

A COS is not restricted to a particular domain or set of domains.

Domains Object

A Domains object represents an email domain such as ace.''com or zink.''org''. A domain must exist before email addressed to users in that domain can be delivered. The object class name is zimbraDomain.

Distribution Lists Object

Distribution Lists, also known as mailing lists, are used to send mail to all members of a list by sending a single email to the list address. The object class name is zimbraDistributionList.

Recipient Object

Recipient object represents an entity that can receive mail. An external email address exists, and the recipient can be expanded through aliases or forwarding into one or more internal/external addresses. The object class name is zimbraMailRecipient. This object class name is only used in conjunction with zimbraAccount and zimbraDistributionlist classes.

Servers Object

The servers object represents a particular server in the Zimbra system that has one or more of the Zimbra software packages installed. During the installation, the software is automatically registered on the OpenLDAP server. The object class name is zimbraServer. Attributes describe server configuration information, such as which services are running on the server.

The server name is used by the Zimbra system to make a request for the server object in the directory. The server requested gets its configuration information and picks up any changes that might have been made by the administrator through the Zimbra Administrator Console.

Global Configuration Object

The Global Configuration object specifies default values for the following objects: server, account, COS, and domain. If the attributes are not set for other objects, the values are inherited from the global settings. The object class name is zimbraGlobalConfig.

Global configuration values are required and are set during installation as part of the Zimbra core package. These become the default values for the system.

Alias Object

Alias object is a placeholders in the directory to reserve a name. The object class name is zimbraAlias. The attribute points to another entry.

TimeZone Object

TimeZone object is a list of well-known time zones used by the web client. The object class name is zimbraTimeZone.

Zimlet Object

Zimlet Object defines Zimlets that are installed and configured in ZCS. The object class name is zimbraZimletEntry. See the Working with Zimlets chapter for more information about Zimlets.

CalendarResource Object

CalendarResource object defines a calendar resource such as conference rooms or equipment that can be selected for a meeting. The object class name is zimbraCalendarResource.

Company Directory/GAL

A company directory is a company-wide listing of users, usually within the organization itself, that is available to all users of the email system. Sometimes called “white pages” or global address list (GAL), Zimbra uses the company directory to look up user addresses from within the company.

For each domain used in Zimbra, you can choose from the following GAL search options:

Use an external LDAP server for the GAL
Use the Zimbra implementation in OpenLDAP
Include both external LDAP server and OpenLDAP in GAL searches

GAL Searches in Zimbra Client

The Zimbra client can search the GAL. The GAL search returns a list of directory entries that match the user’s search.

When the user supplies a name to search for, that name is turned into an LDAP search filter similar to the following example:

(|(cn = %s*)(sn=%s*)(gn=%s*)(mail=%s*))

(zimbraMailDeliveryAddress = %s*)


(zimbraMailAddress = %s*)

The string “%s” is replaced with the name the user is searching for.

GAL Attributes in Zimbra

Two possible sources for GAL information are the Zimbra server and the Active Directory server. The relevant LDAP/Active Directory fields are referenced in the Zimbra schema under the same names as listed in the Active Directory schema.

LDAP Mapped Attributes table maps generic GAL search attributes to their Zimbra contact fields.

Zimbra GAL Search Parameters

Like authentication, GAL is configured on a per-domain basis. From the administration console, you can run the GAL Configuration Wizard to configure the domain’s attributes.

Modifying Attributes

The OpenLDAP directory should not be modified directly. Any additions, changes and deletions are made through the Zimbra administration console or from the CLI utility for provisioning, zmprov.

Users modify attributes for their entry (accounts) in the OpenLDAP directory when they change their options from the Zimbra Web Client.

Administrators can also modify LDAP attributes using the command-line tools described in Appendix A: Command-Line Utilities.

Important: Do not use any LDAP browsers to change the Zimbra LDAP content.

Verified Against: Zimbra Collaboration 7.0, 6.0 Date Created: 04/16/2014
Article ID: https://wiki.zimbra.com/index.php?title=Zimbra_Directory_Service_(LDAP) Date Modified: 2015-07-13

Try Zimbra

Try Zimbra Collaboration with a 60-day free trial.
Get it now »

Want to get involved?

You can contribute in the Community, Wiki, Code, or development of Zimlets.
Find out more. »

Looking for a Video?

Visit our YouTube channel to get the latest webinars, technology news, product overviews, and so much more.
Go to the YouTube channel »

Jump to: navigation, search