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.
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.
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.
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 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.
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:
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.
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.
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.
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.
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.
The zimbraAuthLdapBindDn attribute is a format string used to determine which user name to use when binding to the Active Directory server.
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.
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 enable a domain for custom auth, set the domain attribute, zimbraAuthMet to custom:{registered-custom-auth-handler-name}.
To register a custom authentication handler, invoke ZimbraCustomAuth.register [handlerName, handler] in the init method of the extension.
|
•
|
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).
|
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 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 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:
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.
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.
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, 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 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.
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.
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.
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 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 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 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.
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.
(zimbraMailDeliveryAddress = %s*)
(zimbraMailAddress = %s*)
|
The string “%s” is replaced with the name the user is searching for.
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.
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.
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.
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.
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.
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.
Copyright © 2009 Zimbra Inc.
