ZCS Administrator's Guide, Network Edition 5.0 (Rev 5.0.19 September 2009)
Table of Contents Previous Next Index


Zimbra Directory Service

Zimbra Directory Service
The Zimbra LDAP service is a directory service running a version of the OpenLDAP software that has the Zimbra schema already installed. This chapter describes 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 ZCS 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.
Figure 4 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
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 class 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 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.
Figure 5 shows the Zimbra LDAP hierarchy. Each type of entry (object) has certain associated object classes.
Figure 5: Zimbra LDAP Hierarchy
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 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 Zimbra, 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:
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 methods 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 authentication 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.
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:
ldap://ldapserver:port/
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:
ldap://server1:389
ldap://exch1.acme.com
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:
user@domain.com
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.
Custom Authentication - zimbraCustomAuth
You can implement a custom authentication on your domain. Custom authentication allows external authentication to your proprietary identity database. When an AuthRequest comes in, Zimbra checks the designated auth mechanism for the domain. If the auth mechanism is set to custom auth, Zimbra invokes the registered custom auth handler to authenticate the user.
To set up custom authentication, prepare the domain for the custom auth and register the custom authentication handler.
Preparing a domain for custom auth
To enable a domain for custom auth, set the domain attribute, zimbraAuthMet to custom:{registered-custom-auth-handler-name}.
For example:
zmprov modifydomain {domain|id} zimbraAuthMech custom:sample.
In the above example, “sample” is the name under which a custom auth mechanism is registered.
Registering a custom authentication handler
To register a custom authentication handler, invoke ZimbraCustomAuth.register [handlerName, handler] in the init method of the extension.
Note: Definitions
handlername is the name under which this custom auth handler is registered to Zimbra’s authentication infrastructure. This is the name that is set in the domain’s zimbraAuthMech attribute. For example, if the registered name is “sample”, than zimbraAuthMech must be set to custom:sample.
handler is the object on which the authenticate method is invoked for this custom auth handler. The object has to be an instance of zimbraCustomAuth (or subclasses of it).
Example
 
How Custom Authentication Works
When an AuthRequest comes in, if the domain is specified to use custom auth, the authenticating framework invokes the authenticate method on the ZimbraCustomAuth instance passed as the handler parameter to ZimbraCustomAuth.register ().
The account object for the principal to be authenticated and the clear-text password entered by the user are passed to the ZimbraCustomAuth .authenticate () method. All attributes of the account can be retrieved from the account object.
Kerberos5 Authentication Mechanism
Kerberos5 Authentication Mechanism authenticates users against an external Kerberos server. To set up Kerberos5 auth set the domain attribute zimbraAuthMech to kerberos5. Then set the domain attribute zimbraAuthKerberos5Realm to the Kerberos5 realm in which users in this domain are created in the Kerberos database.
When users log in with an email password and the domain, zimbraAuthMech is set to kerberos5, the server constructs the Kerberos5 principal by {localpart-of-the-email}@{value-of-zimbraAuthKerberos5Realm} and uses that to authenticate to the kerberos5 server.
Kerberos5 can be supported for individual accounts. This is done by setting the account’s zimbraForeignPrincipal as kerberos5. Set the account's zimbraForeignPrincipal as kerberos5:{kerberos5-principal}. For example: kerberos5:user1@MYREALM.COM. If zimbraForeignPrincipal starts with kerberos5:, the server uses {kerberos5-principal} as the Kerberos5 principal instead of the algorithm of grabbing the realm from the zimbraAuthKerberos5Realm as mentioned in the previous paragraph.
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:
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 set of attributes, some of which are user-modifiable (preferences) 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 the Managing User Accounts.
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.
Domains Object
A Domains object represents an email domain such as example.com or example.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 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 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.
Zimlet Object
Zimlet Object defines Zimlets that are installed and configured in Zimbra. 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.
Identity Object
Identity object represents a persona of a user. A persona contains the user’s identity such as display name and a link to the signature entry used for outgoing emails. A user can create multiple personas. Identity entries are created under the user’s LDAP entry in the DIT. The object class name is zimbraIdentity.
Data Source Object
Data source object represents an external mail source of a user. The two types of data source are POP3 and IMAP. A data source contains the POP3/IMAP server name, port, and password for the user’s external email account. The data source also contains persona information, including the display name and a link to the signature entry for outgoing email messages sent on behalf of the external account. Data Source entries are created under the user’s ldap entry in the DIT. The object class name is zimbraDataSource.
Signature Object
Signature object represents a user’s signature. A user can create multiple signatures. Signature entries are created under the user’s LDAP entry in the DIT. The object class name is zimbraSignature.
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:
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:
 
(zimbraMailDeliveryAddress = %s*)
(zimbraMailAlias=%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.
Table 1 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.
Flushing LDAP Cache
The Zimbra LDAP server caches the following types of entries
Themes and Locales
When you add or change themes (skins) properties files and local resource files for ZCS on a server, you flush the cache to reload the new content. Until you do this, the new skins and locales are not available in the COS or Account.
To flush skins, type zmprov flushCache skin
To flush locales, type: zmprov flushCache locale
Note: Flushing the skin/locale cache only makes the server aware of the resource changes. It does not automatically modify any COS or account’s LDAP zimbraAvailableSkin and zimbraAvailableLocal settings. The LDAP attributes must be modified separately either from the administration console or with the zmprov ma command.
Accounts, COS, Domains, and Servers
When you modify Account, COS, Domain, and Server attributes, the change is effective immediately on the server to which the modification is done. On the other servers, the LDAP entries are automatically updated after a period of time if the attributes are cached. Use zmprov flushCache to make the changes available immediately on a server.
Note: The default ZCS setting for updating the server is 15 minutes.
To flush accounts, COS, domain, and server caches, type zmprov flushCache [account|cos|domain|server] [name|id]
If you do not specify a name or ID along with the type, all entries in cache for that type are flushed and the cache is reloaded.
Note: Some server attributes are not effective until after a server restart, even after the cache is flushed. For example, settings like bind port or number of processing threads.
Global Configuration
When you modify global config attributes, the changes are effective immediately on the server to which the modification is done. On other mailbox servers, you must flush the cache to make the changes available or restart the server. LDAP entries for global config attributes do not expire.
Note: Some global config attributes are computed into internal representations only once per server restart. For efficiency reasons, changes to those attributes are not effective until after a server restart, even after the cache is flushed. Also, some global configuration settings and server settings that are inherited from global config are only read once at server startup, for example port or number of processing threads. Modifying these types of attributes requires a server restart.
To make a global config change effective on all servers do the following:
1.
Modify the setting using zmprov mcf. For example, type zmprov mcf zimbraImapClearTextLoginEnabled.
Note: The change is only effective on the server zimbra_zmprov_default_soap_server, port zimbra_admin-service_port.
2.
Flush the global config cache on all other servers, zmprov flushCache must be issued on all servers, one at a time. For example:
zmprov –s server-1 flushCache config
zmprov –s server-2 flushcache config
zmprov -s server-3 flushcache config

Zimbra Directory Service

Table of Contents Previous Next Index
ZCS Administrator's Guide, Network Edition 5.0 (Rev 5.0.19 September 2009)
Copyright © 2009 Zimbra Inc.