CommuniGate Pro
Version 5.2
Directory
 
 
Integration

Directory Integration

CommuniGate Pro Directory can be used to store any information. One of the Server features is integration of the CommuniGate Pro Directory and CommuniGate Pro Domains. The integration level is selected on a per-domain basis.

A Server Administrator can control how CommuniGate Pro Domains are integrated with the Directory. Open the Domains page and follow the Directory Integration link.

Directory Integration Concept

CommuniGate Pro Domains can use the following levels of Directory integration:

Finally, the CommuniGate Pro can use regular (non Directory-Based) domains, but still allow Account provisioning via LDAP, so it looks like the Directory-Based Domains are used and LDAP commands can create and update Account. This feature is called LDAP-based Provisioning.


Attribute Renaming

Some Domain and Account settings names may not match the standard attribute names used in the Directory Schema. For example, the Account setting Real Name has to be stored in the Directory as the cn (common name) attribute, and the custom settings surname and city (see below) should be stored as attributes sn and l.

When you need to add an attribute to your Directory Schema, always try to use attribute names specified in one of the LDAP Internet Standards (RFCs). If this attribute should be used for Directory Integration (i.e. it will be used to store some Domain or Account setting value), you may want to use the Attribute Renaming capability to "map" CommuniGate Pro Domain or Account setting name on some Directory Attribute name.

Use the Attributes Translation table to specify the name translation rules:

Attributes Translation
Name in CommuniGate Name in Directory

Note: The Attributes Translation feature works only for the Directory Integration component of the CommuniGate Pro Server. If you access the CommuniGate Pro Directory directly (via the LDAP module, for example), no translation takes place: LDAP clients should specify the Directory Attribute names, and the returned records have Directory Attribute names, not CommuniGate Pro Domain and Account setting names - "cn", not "RealName" and "userPassword", not "Password".


Domains Subtree

For each regular CommuniGate Pro Domain with the Directory setting set to Keep in Sync, and for each Directory-Based Domain a Directory Subtree is created. This Subtree has the Domain record as its root, and all Domain Account records as the Subtree elements ("leaves"). For Directory-based Domains, additional elements are created to store Account aliases, Domains settings, etc.

The Domain Subtree panel allows you to specify the location of Subtrees created for each CommuniGate Pro Domain:

Domain Subtree
Base DN:
Domain RDN Attribute:
Domain objectClass:
UID Subtree:
Base DN
This field specifies the "base" DN for all domains in the Central Directory. You may want to set it as:
o=your company name
so each CommuniGate Pro Domain will have the following DN:
cn=domain name,o=your company name

When a domain is placed into the Directory, a record with its DN is created. If the Base DN does not exist, the Directory Manager may return an error. Use the Create It button to create an empty record with the Base DN.

If you are an ISP you may want to give each domain you host the top-level DN:

cn=domain name
In this case, specify an empty string in the Base DN field.
Domain RDN attribute
This field specifies the attribute name to use for Domain record RDNs. In most cases, the default value (cn) is the best choice. However, you can change that to the name of any other attribute defined in the Directory schema. If you set this name to o, the CommuniGate Pro Domain records will have the following DNs:
o=domain name,base DN
Note: If you specify the string dc as the Domain RDN attribute, then the DN for a CommuniGate Pro Domain mail.domain.dom will be composed as dc=mail,dc=domain,dc=dom.
Domain objectClass
This field specifies the objectClass for CommuniGate Pro Domain records in the Directory. The CommuniGateDomain objectClass defined in the CommuniGate Pro Directory Manager schema is the default value. If you choose to select a different objectClass, make sure it exists in your Directory schema.

For regular domains, the domain Directory record is empty. As a result, you may use any objectClass that can store the cn attribute (or the attribute you have specified in the Domain RDN attribute setting).

For Directory-based Domains, the domain Directory record contains all domain settings, so the objectClass for these records should support all attributes included into the CommuniGateDomain objectClass.

UID subtree
If this field is empty, then the Domain Object (Account, Group, List, Forwarder) records are stored in the directory using the following DNs: uid=objectName,domain DN.
If the base DN is o=mycompany, and the Domain RDN attribute is cn, then the directory record for the user1 Account in the domain1.dom Domain will have the following DN:
uid=user1,cn=domain1.dom,o=mycompany
The UID subtree parameter allows you to place the objects "below" the domain tree. If the UID subtree is set to ou=People, then the record for the same Account will have the following DN:
uid=user1,ou=People,cn=domain1.dom,o=mycompany
If the Domain RDN attribute is set to dc, then the record for the same Account will have the following DN:
uid=user1,ou=People,dc=domain1,dc=dom,o=mycompany

Example:

BaseDN is an empty string, Domain RDN Attribute is cn, and three CommuniGate Pro domains (domain1.dom, domain2.dom, and domain3.dom) have been created:
Pic1
To search for Accounts in these Domain subtrees, LDAP clients should have the string
cn=domainN.dom
specified in their "Base Object" or "Search Base" settings.

Example:

BaseDN is o=acme, Domain RDN Attribute is cn, and three CommuniGate Pro domains (domain1.dom, domain2.dom, and domain3.dom) have been created:
Pic2
To search for Accounts in these Domain subtrees, LDAP clients should have the string
cn=domainN.dom,o=acme
specified in their "Base Object" or "Search Base" settings.

Example:

BaseDN is o=acme, Domain RDN Attribute is dc, and three CommuniGate Pro domains (domain1.dom, domain2.dom, and domain3.dom) have been created:
Pic3
To search for Accounts in these Domain subtrees, LDAP clients should have the string
dc=domainN,dc=dom,o=acme
specified in their "Base Object" or "Search Base" settings.

After you have decided how to organize your Domains Subtree, you can create additional Directory Storage Units to store your Domain and Account data in several units (if necessary). For example, if you want to use your CommuniGate Pro Directory Manager to store information not related to CommuniGate Pro Accounts, and you want all Domain and Account information to be stored either on a remote LDAP server or in a dedicated Local Storage Unit, you can create a Storage Unit MyDomains for the Directory Integration Base DN subtree (o=acme in the examples listed above). In this case, all Domains and Account records will be stored in that MyDomains Storage Unit (in a separate local unit or on a remote LDAP server), while all records that do not have the o=acme suffix will be stored in other Storage Units:

Pic4

Note:If you change any Domain Subtree setting, the existing Subtree is not modified. Carefully select the proper values for the Domain Subtree settings before you start any Directory Integration activity. If you need to change these settings later, it is your responsibility to move the existing Domain Subtree to the new location (specified with the new BaseDN) and/or to change RDNs of the existing domain records (if you have changed the Domain RDN Attribute setting).


Custom Account Settings

The CommuniGate Pro Server has a predefined set of Account Settings (see the Accounts section for more details). The Directory Integration settings include a panel that allows you to specify additional, Custom settings for CommuniGate Pro Accounts:

Custom Account Settings
System
Public Info

You can use these Custom Account Settings to store additional information about your users: locations, phone numbers, demographic data, etc.

The System custom settings can be modified by Server administrators and Domain adminitrators with the Basic Domain Access Right.

The Public Info custom settings can be modified by the users themselves.

To add a Custom Setting, type its name into the last (empty) field and click the Update button.

Additional (custom) Account Settings are stored in Account Directory records (these records have the CommuniGateAccount objectClass).


When you select a name for a new Custom Account Setting, either use a name of an attribute already specified for CommuniGateAccount object class in the Directory Schema, or use the Directory Integration Attribute Renaming feature and map the new Custom Account Setting name onto a name of any already specified attribute.

Example:

To add the telephoneNumber setting to all CommuniGate Pro Accounts, add the name telephoneNumber to the Custom Account Settings table.
If a Local Storage Unit is used to store CommuniGate Pro Domains and Accounts subtree, no additional action is needed: the telephoneNumber attribute is already included into the CommuniGateAccount object class description in all Local Unit Schemas.

Example:

To add the surname setting to all CommuniGate Pro Accounts, add the name surname to the Custom Account Settings table, and add the pair (surname, sn) to the Attribute Renaming table, so the surname Account Settings will be stored in Directory records as sn attributes.
If a Local Storage Unit is used to store CommuniGate Pro Domains and Accounts subtree, no additional action is needed: the sn attribute is already included into the CommuniGateAccount object class description in all Local Unit Schemas.

Example:

To add the BirthDay setting to all CommuniGate Pro Accounts, add the name BirthDay to the Custom Account Settings table.
If a Local Storage Unit is used to store CommuniGate Pro Domains and Accounts subtree, add the BirthDay attribute to the Local Unit Schema, and add the newly created BirthDay attribute name to the list of Optional Attributes of the CommuniGateAccount object class.
If a Remote Storage Unit is used to store CommuniGate Pro Domains and Accounts subtree, update the Directory Schema on the remote LDAP server to allow directory records of the CommuniGateAccount object class to include the BirthDay attribute.

Note: Account records in the Directory always contain the sn attribute to make them compatible with the standard LDAP Directory Schema. If you do not include this attribute into the Custom Account Settings set, CommuniGate Pro stores account records with the sn attribute containing the none string.

After you have specified some Custom Account Settings, their names appear on the Account Settings pages. You can use those pages or CLI to add and update the Custom Setting values for all CommuniGate Pro Accounts:

Real Name: 
surname: 
city: 
CommuniGate  
Password: 
telephoneNumber: 

Note: if you rename a custom attribute name or remove it, the attribute values are not modified in the Directory - you are effectively changing the Directory Integration parameters, not the Directory data itself. To update the actual Directory data (for example, to remove all telephoneNumber attribute values from the Directory), use LDAP utilities and/or applications.


Integrating Regular Domains

Regular CommuniGate Pro Domains do not rely on Directory data. All Domain and Account settings are stored in files inside the CommuniGate Pro file directories and CommuniGate Pro Server reads those files when it needs to retrieve Domain and Account settings. Regular Domains can store copies of some Account Settings in Directory records.

The directory record for a Regular Domain is created when the Server needs to store a directory record for any object in that Domain. For example, when the Server needs to create a directory record for the Account john in the dom1.dom Domain, it creates the cn=dom1.dom record first (if it does not exist), and then the Server creates the uid=john,cn=dom1.dom record for the Account john.

When the Directory Integration Domain Setting is set to Keep In Sync:

None of these actions takes place when the Domain Directory Integration settings is set to Disabled.

The following diagram illustrates what happens when the dom1.dom Domain has the Directory Integration option set to Keep In Sync, and an account is created in that domain:

Pic:Create

In this example:

Now Directory search operations (initiated with an LDAP client or the WebUser Interface) can display the record for the newly created account.

Directory records for Regular Domain Accounts contain the following attributes:

The Regular Domains panel located on the Directory Integration page of the WebAdmin Interface allows you to specify these options:

Regular Domains
Copy into Account records: Passwords
Standard Settings
 
Copy Password
If this option is selected, the Directory records for Regular Domain Accounts will contain the Account Password attribute (usually it is renamed into the userPassword attribute).
Copy Standard Settings
If this option is selected, the Directory records for Regular Domain Accounts will contain all CommuniGate Pro standard Settings for those Accounts (excluding the RealName and userCertificate settings that are always being stored and the Password setting that it controlled using a separate option).

The following diagram illustrates what happens when the dom1.dom Domain has the Directory Integration option set to Keep In Sync, and Domain Account settings are updated:

Pic:Update
In this example:

Note: It is important to understand that Directory Integration for Regular Domains is a one-way relationship: if you change attributes of Account records in the Directory (using any LDAP utility), the actual Account Settings will not be modified - CommuniGate Pro always uses data in the settings files, and never reads data from the Directory when it needs to retrieve settings for Regular Domains or settings for Accounts in those Domains. The CommuniGate Pro Manager for regular Domains and Accounts only updates the Directory, but it never reads the Account record data back from the Directory.

The following diagram illustrates what happens when the dom1.dom Domain has the Directory Integration option set to Keep In Sync, and a Domain Account is renamed:

Pic:Rename
In this example:

The following diagram illustrates what happens when the dom1.dom Domain has the Directory Integration option set to Keep In Sync, and a Domain Account is removed:

Pic:Delete
In this example:

The Directory Integration panel on the Domain Settings page has the Delete All button. Use this button to delete the Domain record and all Domain Object records from the Directory. The operation deletes only those records that contain the hostServer attribute and that attribute value is the same as the Main Domain name of this CommuniGate Pro Server.

The Directory Integration panel on the Domain Settings page has the Insert All button. Use this button to create a directory record for this Domain and to create directory records for all Domain Objects.

Note: If you have created several Accounts in the regular Domain when its Directory Integration setting was set to Disabled, the Directory does not contain records for those Accounts. If later you switch that setting to Keep In Sync, you will see error reports when you try to rename, remove, or update those Accounts: the Server tries to update the Directory records for those Accounts, but the Directory records do not exist.

Before you switch the Directory Integration setting from Disabled to Keep In Sync, click the Delete All button, and then click Insert All button to synchronize the Directory and the current Domain Objects set.


LDAP-based Provisioning

CommuniGate Pro allows you to use the LDAP protocol to create, update, rename, and remove Accounts:

LDAP direct Provisioning

When this option is enabled, the LDAP module checks the names (DNs) specified in update operations. If the DN looks like a DN of a CommuniGate Pro Account, the LDAP module does not perform the requested operation with the Directory. Instead, it executes the CreateAccount, UpdateAccount, RenameAccount, or RemoveAccount operations for the specified Account and Domain.

The diagram below illustrates how the LDAP AddRecord operation works in this case:

Pic:LDAPCreate
In this example:

Note: the Directory Integration settings are used to convert LDAP record attribute names into the CommuniGate Pro attribute names. For example, the LDAP AddRecord request can contain the cn attribute. This attribute is stored in the Account settings as the Account RealName setting. When the Account Manager adds a record to the Directory, it converts the RealName Account setting back into the cn record attribute.

Note: all LDAP AddRecord request attributes will be stored as the Account Settings if the LDAP client has authenticated itself as an Account with All Domain and Account Settings access right. But only the attributes specified with the Directory Integration parameters will be copied into the new Directory record. The Directory record will also contain the attributes not included into the original LDAP AddRecord request, but specified in the Account Template.

Note: the LDAP Provisioning feature detects the unixPassword attributes and converts them into Password settings after adding a leading 0x02 byte. See the Account Import section for the details.

The following diagram illustrates how the LDAP ModifyRecord operation can be used to modify Account Settings:

Pic:LDAPUpdate

In this example:

The following diagram illustrates how the LDAP ModifyDN operation can be used to rename Accounts:

Pic:LDAPRename
In this example:

The following diagram illustrates how the LDAP DeleteRecord operation can be used to remove Accounts:

Pic:LDAPDelete
In this example:

When LDAP Provisioning is enabled, the LDAP module uses special processing for some search requests, too. If

the LDAP module calls the Account Manager directly and retrieves the effective settings for the specified Account (i.e. the Account settings as well as all its Default Settings). The module converts these settings into Directory attributes, and sends them back to the LDAP client as a search result record.
If the authenticated LDAP user does not have the Domain Administrator access right for the target Account Domain, only the Real Name, User Certificate, Custom, Public Info, and mail attributes are retrieved.

Directory-Based Domains

The CommuniGate Pro Server software implements Directory-based Domains. Directory-based Domains and all their Accounts keep all their settings in the Directory - there is no .settings files for those Domains and Accounts.

For each Directory-based Domain a Directory record of the CommuniGateDirectoryDomain objectClass is created. This record stores all Domain Settings.
DNs for Directory-based Domains are built in the same way they are built for Regular Domain records.

For each account in a Directory-based Domain a Directory record of the CommuniGateAccount objectClass is created. This record stores all Account Settings (including the Custom Settings).
DNs for accounts in the Directory-based Domains are built in the same way they are built for Regular Domain Account records.

Directory records for Directory-based Domain Accounts must contain the storageLocation attribute. This attribute specifies the location of the Account file directory (for the Multi-mailbox accounts) or the location of the account INBOX file (for single-mailbox accounts). The location is specified as a file path relative to the base directory of the CommuniGate Pro Server hosting this Account.

If a CommuniGate Pro server has to open an Account in a Directory-based domain, and the account storageLocation attribute starts with the asterisk (*) symbol, the CommuniGate Pro Server creates the account file directory (for multi-mailbox accounts) and other required account files and file directories.

Directory records are created for aliases of Directory-based Domain Accounts.
Alias records have the same DNs as Accounts (uid=aliasname,domain DN).
Alias records have the standard alias objectClass, and their aliasedObjectName attribute specifies the DN of the original account record.

The following diagram illustrates how the LDAP AddRecord operation can be used to create an Account in the Directory-based Domain:

Pic:DirCreate
In this example:

Since the Account in the Directory-based Domains do not store their settings in the CommuniGate Pro data files, the settings are retrieved from the account Directory record every time an account has to be opened. The following diagram illustrates this procedure

Pic:DirAccess

Since the Directory records are the only source of the Account settings, modifying Directory record attributes effectively modifies the Account Settings:

Pic:DirUpdate
In this example:

Shared (Multi-Server) Directory

Several CommuniGate Pro Servers can use the same physical Directory (Directory Unit) to keep all their Domain Integration Records.

The shared Directory Unit can be implemented as a Local Storage Unit on one of the CommuniGate Pro Servers, or it can be hosted on some third-party Directory Server.

To simplify the setup, especially if you have many CommuniGate Pro Servers, it is recommended to create the Remote Storage Units for the <root> Subtrees. To create such a Unit, remove the default Main Local Unit first:

Pic:SharedDirectory
In this example:

Distributed Domains (Directory Routing)

When several CommuniGate Pro Servers use a Shared Directory to keep all their Domain Integration Records, these Servers can be used to serve the same Domain (or the same Domains). Such a Domain is called a Distributed Domain, and each Server hosts a subset of that Domain Accounts. The Distributed Domain should not be a Main Domain of any CommuniGate Pro Server:
Pic:Distributed Domain

In this example:

When an Account is created, renamed, removed, or updated on one of the sv*.corp.dom Servers, the Directory Unit on the Shared Directory Server is updated. As a result, the Shared Directory contains records for all Accounts created on all sv*.corp.dom Servers.

When any Server creates an Account and places a record into the Shared Directory, it stores the Server Main Domain name as the record hostServer attribute.

The Shared Directory can be used to route Distributed Domain mail to the proper location (Server). Open the General page in the WebAdmin Settings realm, then open Cluster settings page, and enable the Directory-Based Clustering. The address routing mechanism is modified:

This Distributed Domain configuration is useful for multi-location and international organizations and corporations where all employee accounts should be in the same domain, but each organizational unit is served with its own Server. The DNS MX records for the such a Distributed Domain should point to any or to all Servers hosting that domain. When a Server receives mail for a Distributed Domain, it either delivers the mail locally (if the addressed Account is hosted on that Server), or relays mail to Server specified in the hostServer attribute of the Account Directory record.

Usually, one of the Servers (the "main location") hosts most of the Distributed Domain Accounts. It is recommended to host the Shared Directory on that CommuniGate Pro Server to minimize the delays introduced with the Directory lookups. Other CommuniGate Pro Server serving this Distributed Domain can be configured to reroute all mail to non-local objects of the Distributed Domain to that "main location" Server. Open the Distributed Domain Settings, and set the Mail/Signal To Unknown options to

Reroute To: *%domain.dom@mainserver.via

This method eliminates a need for "remote location" Servers to communicate with the Directory when they have to route addresses. The "remote location" Servers communicate with the Directory only when Accounts are created in, renamed, or removed from a Distributed Domain, and when a WebMail, XIMSS, SIP, or LDAP user requests a Directory search operation. This can drastically improve the "remote location" Servers performance if the communication links between them and the Shared Directory Server are slow and/or unreliable.

In asymmetric, "main/remote location" configurations, the high-priority MX records for the Distributed Domain should point to the "main location" Server, while "remote location" Server names can be used for low-priority MX records. It is not recommended to use Directory-based Domains for Distributed Domains if connections between "remote location" Servers and the Shared Directory are slow and/or unreliable.

The Distributed Domains concept is the foundation of the CommuniGate Pro Static Clusters.

For small Distributed Domains, routing can be implemented using regular CommuniGate Pro Router records. If the Distributed Domain has the same Accounts as shown in the example above, the SV1 server should have the following records in its Router:

; SV2 accounts
<dan@corp.dom>  =  dan%corp.dom@sv2.corp.dom.via
<ed@corp.dom>   =   ed%corp.dom@sv2.corp.dom.via
<fred@corp.dom> = fred%corp.dom@sv2.corp.dom.via
;
; SV3 accounts
<gil@corp.dom>  =  gil%corp.dom@sv3.corp.dom.via
<hugh@corp.dom> = hugh%corp.dom@sv3.corp.dom.via
<judy@corp.dom> = judy%corp.dom@sv3.corp.dom.via

While this method does not require any Directory activity, it is hardly acceptable for Domains with more than few dozen Accounts, unless names of Accounts hosted on different Servers can be easily expressed using the Router wildcard symbols. For example, if all Accounts hosted on the Server SV2 end with the -uk suffix (dan-uk@corp.dom, ed-uk@corp.dom, fred-uk@corp.dom, etc.), routing for all SV2 Accounts can be specified with one Router record:

<*-uk@corp.dom> = *-uk%corp.dom@sv2.corp.dom.via

Directory Integration in a Cluster

The CommuniGate Pro Dynamic Cluster maintains cluster-wide Directory Integration settings: the cluster-wide Attribute Renaming table, Domain Subtree, and Custom Attributes settings are used with all Accounts in Shared Domains, while "regular" settings are used for all Accounts in "local" Domains.

When you open the Directory Integration WebAdmin page on a Cluster Member, the page contains a link that allows you to switch the Cluster-wide Settings.


CommuniGate® Pro Guide. Copyright © 1998-2009, Stalker Software, Inc.