LDAP Module

The CommuniGate Pro LDAP module provides access to the CommuniGate Pro Directory tree and its records.

It is important to understand that the CommuniGate Pro LDAP module itself does not provide any Directory services. It just implements an access protocol, and the functionality it provides depends on the CommuniGate Pro Directory Manager and its units.

Very often LDAP services are used to look for names and E-mail addresses of Server users. But since the LDAP module provides access to the entire Directory tree, it can be used to work with any type of data placed into the CommuniGate Pro Directory. While the CommuniGate Pro Directory can be stored in several Storage Units - both local and remote, the LDAP clients see the entire Directory as one large tree.

To browse and modify the Directory, system administrators can use either LDAP clients and utilities, or the Directory Browser interface built into the CommuniGate Pro WebAdmin Interface.

Note: while the LDAP module implements an LDAP server functionality, the CommuniGate Pro Server can also work as an LDAP client, using the LDAP protocol to access external LDAP servers and their databases. Those external Directories are presented as subtrees of the CommuniGate Pro Directory tree. See the Remote Units Directory section for more details.

Use the WebAdmin Interface to configure the LDAP module. Open the Services pages in the Settings realm, and open the LDAP page.

Processing
Log Level:	Crashes OnlyFailuresMajor & FailuresProblemsLow LevelAll Info	Channels:	off13510255010025050010005000other	Listener

Log

Use this setting to specify what kind of information the LDAP module should put in the Server Log. Usually you should use the Major or Problems (non-fatal errors) levels. But when you experience problems with the LDAP module, you may want to set the Log Level setting to Low-Level or All Info: in this case protocol-level or link-level details will be recorded in the System Log as well.

The LDAP module records in the System Log are marked with the LDAP tag. Please note that LDAP is a binary protocol, so all low-level data is presented in the hexadecimal form.

Channels

When you specify a non-zero value for the TCP/IP Channels setting, the LDAP module creates a so-called "listener" on the specified port. The module starts to accept all LDAP connections that mail clients establish in order to update password data. This setting is used to limit the number of simultaneous connections the LDAP module can accept. If there are too many incoming connections open, the module will reject new connections, and the user should retry later.
If the number of channels is set to zero, the LDAP module closes the listener and releases (unbinds from) the TCP port(s).

listener

By default, the LDAP module Listener accepts clear text connections on the TCP port 389, and secure connections - on the TCP port 636. Follow the listener link to tune the LDAP Listener.

Note:The pre-4.7 Netscape ® LDAP clients crash if they communicate with a very fast server returning more than 90 records. Ask your users to update to the 4.7 or later version of Netscape browser/mailer product.

Note:The Netscape® LDAP client (version 4.7) does not correctly process the "properties" command - it always tries to connect to the port 389, even if the search was successfully made on a different (for example, secure) port.

Sometimes you need to specify the Directory Tree Root element (an empty string) as the "search base DN". Some LDAP clients do not process this situation correctly (for example, Microsoft LDAP client silently replaces an empty Search Base string with the c=your_country string).
In these cases you should specify the string  top  as your Search Base string. The LDAP module interpretes this string as an empty string (Directory Root DN).

The Directory Access Rights are based on the so-called Bind DNs rather than on CommuniGate Pro Account names and Account rights. See the Directory Manager Access Rights section for more details.

The Directory Access Rights set by default do not require Directory (LDAP) clients to authenticate in order to retrieve any information from the Directory tree.

When an LDAP client tries to authenticate as a certain DN, the LDAP server retrieves the Directory record with the specified DN and compares that record userPassword attribute with the password supplied by the LDAP client. If the record exists, and it contains the userPassword attribute, and the attribute value matches the supplied password, the LDAP client authentication succeeds.

The LDAP module provides an alternative authentication method, when the client specifies a CommuniGate Pro Account name instead of some record DN. In this case, the CommuniGate Pro Server opens the specified Account and compares the Account password with the supplied password. If the passwords match, the Server builds a DN for the Account record using the Directory Integration settings, and uses it as the Bind DN.

Sample:

If the Directory Integration settings are:

Base DN:		o=myCompany
Domain RDN attribute:		cn

and the client has submitted the [email protected] name and the correct password for the [email protected] account, then the LDAP client is authenticated with the following Bind DN:
uid=user,cn=domain.dom,o=myCompany
and this client can access the Directory information available for that Bind DN.

The LDAP module uses the alternative authentication method if the specified string does not contain any equals (=) symbol, or if it starts with the mail= symbols and does not contain any other equals (=) symbols.

This authentication service can be disabled by disabling the LDAP Service for a Domain and/or an Account.

The LDAP Provisioning option can modify the authentication process. If this option is enabled and the supplied Bind DN represents the DN for some CommuniGate Pro Account, the supplied Bind DN is converted into that Account name, and the alternative method is used.

Bind DN string specified	Data used to verify the password
uid=user,cn=domain.dom,o=myCompany (LDAP Provisioning is off)	the userPassword record attribute of the uid=user,cn=domain.dom,o=myCompany Directory record
ou=human_resources,o=myCompany	the userPassword record attribute of theou=human_resources,o=myCompany Directory record
[email protected]	the [email protected] Account password
[email protected]	the [email protected] Account password
uid=user,cn=domain.dom,o=myCompany (LDAP Provisioning is on)	the [email protected] Account password

The LDAP module allows users to employ all authentication methods supported with the CommuniGate Pro Server. It supports Simple, SASL, and NTLM BIND methods.

If the Account password authentication method is used, and the specified Account has the Directory Administrator access right, the LDAP client can access and modify all Directory data ("master"-type access).

The LDAP services can be used to retrieve information about the CommuniGate Pro Accounts and other Domain Objects.

To search the Directory for CommuniGate Pro Domain Objects (Accounts, Groups, Mailing Lists), the LDAP clients should be tuned to point to the proper Subtree (this parameter is called "Search Base" in many LDAP clients). The Directory Subtree for the company.com Domain is cn=company.com,o=MyCompany, where cn is the Domain RDN attribute, and o=MyCompany is the Base DN for CommuniGate Pro Domains. The Base DN and Domain RDN attribute are the Directory Integration settings and can be modified. If these settings are modified, the locations of Domain subtrees are changed, and the LDAP clients should be reconfigured to specify the new locations in their "Search Base" settings.

Some external application and devices (such as external E-mail filters) use the LDAP protocol to verify if the E-mail recipient should be accepted on behalf of the "main" mail server.
These applications check a object@domain E-mail address using one of the following requests:

• a 'record retrieval' (scope=base) request for the mail=object@domain,searchbase DN, or
• a 'record search' (scope=one) request for the searchbase DN, using the mail=object@domain filter

To support these application and devices, the CommuniGate Pro LDAP module implements a virtual dc=cgprouter Directory subtree. If a 'record retrieval' (scope=base) request DN is mail=object@domain,dc=cgprouter, or a 'record search' (scope=one) request DN is dc=cgprouter, and the search filter is mail=object@domain, the LDAP module does not consult the Directory. Instead, it tries to process the specified object@domain E-mail address using the Router component.

If the specified E-mail address is successfully routed to a local Account, or to the "Black Hole", or it is routed to an external host, but relaying to that host is allowed, the LDAP module returns a fictitious Directory record, informing an application that the supplied E-mail address is a valid one, and E-mail sent to that address can be accepted.

If the address can not be routed (or relaying is not allowed) and the request was the 'record search' one, the result is empty. If the request was the 'record retrieval' one, the result delivers routing error.

CommuniGate Pro supports Directory-based Domains. Account information in those Domains is stored in the Directory, and the LDAP module can be used to modify Account data in the Directory. Directory-based Domains resemble the architecture of some older Messaging Systems, and CommuniGate Pro supports it for compatibility and migration reasons. See the Directory-Based Domains section for more details.

The LDAP module can also be used to perform basic provisioning operations within regular Domains. This feature is called LDAP Provisioning. If the DN specified in the request "looks like" a DN of a Directory record that some CommuniGate Pro Account has (or could have), the LDAP module does not perform any operation on the Directory at all. Instead of passing the request to the Directory, the LDAP module sends a command directly to the Account Manager, and the Account Manager creates/removes/renames/updates/reads the specified Account. See the Directory Integration section for more details.

Many LDAP clients expect to see the mail attribute in Account and other Domain Object records. But, by default, CommuniGate Pro does not store such an attribute in those directory records.

If the LDAP module has to return such a record (a record of the CommuniGateAccount, CommuniGateMailList, or CommuniGateGroup object class), and that record does not contain the mail attribute, the LDAP module can compose that attribute on-the-fly, using the Object record DN: it takes the uid value from the DN (Account/Object name), the cn attribute value (Domain name), and merges them using the @ symbol to build the uidValue@cnValue mail attribute value. As a result, when an object is renamed (its record uid attribute is changed), or when the Domain is renamed (the cn attribute in the object DN is changed), the mail attribute is automatically updated.

Since the mail attribute is not stored in the Directory records by default, all search filters that use the mail attribute can be modified internally to use the uid attribute instead. If the search operation is "equals to", and the search string contains the @ symbol, only the part of the string before that symbol is used.

These two features can be enabled or disabled using the Domain Integration page in the Users realm of the WebAdmin Interface:

LDAP Attribute Processing

Substitute 'mail' with 'uid' in conditions

Compose 'mail' using 'uid'

Ignore 'objectCategory' conditions

Ignore objectCategory filters

Some clients (including Microsoft Outlook) always send their LDAP search requests using filters checking for certain objectCategory attribute values.
Since this attribute is not included into CommuniGate Pro Account records by default, you would have to create this attribute as a Custom one, and put a "proper" value into each Account settings.
This option tells the LDAP server to ignore all "objectCategory equals value" search operations (the Server treats these operations as the constant true-values).

The LDAP module checks if a search request explicitly specifies the displayName attribute. If a retrieved record does not contain that attribute, but the record contains the cn attribute, or the uid attribute, the value of the cn or uid attribute is included into the response as the displayName attribute value.

The LDAP module supports the Extension for Simple Paged Results Manipulation (RFC2696) which allows LDAP clients to retrieve large search results in smaller portions (pages).
However, to return one page to a client the Server has to find all records matching the search criteria, then optionally sort them; and only then it can return the requested page. In order to prevent the performance degradation caused by repetitive searches and sortings the Server may cache several such search results using its internal memory.

The caching parameters can be adjusted using the Domain Integration page in the Users realm of the WebAdmin Interface:

LDAP paged Search Results Cache
Size:01235 10203050other	Used: 1
Time-out:60 sec2 min3 min 4 min5 min10 min20 min30 min 60 minother

Size

The maximum number of cached search results.

Used

The number of currntly cached results.

Time-out

The time period since the last client retrieval of a subsequent page, after which the memory used by cached data will be released.