CommuniGate Pro
Version 5.1
Directory
 
 
 
Directory

Directory

The CommuniGate Pro Server includes the Directory Manager implementing high-performance standards-based Directory storage.

The Directory can contain records about the CommuniGate Pro Accounts, Domains, and other objects. It can also contain any other type of records, and it can be used as a stand-alone Directory Server serving any LDAP-based applications.

The Directory Manager is not the same as an LDAP server. The CommuniGate Pro LDAP module provides access to the Directory for LDAP clients, but various CommuniGate Pro components (Account and Domain Managers, WebUser Interface, etc.) access the Directory data directly, bypassing LDAP communications.

The Directory Manager implements Meta-Directory: it can store directory data in one or several sets of the server files (Local Units), and it can also use external LDAP servers as Directory Remote Units. Many different configurations are possible. The following simplest configurations are used most often:
  • All Directory data is stored in a single Local Unit. In this case Meta-Directory is the same as a Directory implemented with a regular LDAP server.
  • All Directory data is stored in a single Remote Unit. In this case Meta-Directory is used just as a method to access records stored on an external LDAP server.

What is Directory?

attribute
a name (attribute name) and one or several attribute values.
Usually an attribute is presented in the name=value form.
Attribute names are case-insensitive.
Samples:
userName=john
eyeColor=blue
object class
an attribute with the objectClass name; this attribute is used to specify a nature of the object it belongs to.
Samples:
objectClass=person
objectClass=organization
distinguished name (DN).
a sequence of attributes presented in the name=value form and separated with the comma (,) symbol.
DNs are used as unqiue names for objects (records).
Sample:
userName=john,server=BigIron,realm=Internet

DNs are used to build object name trees, with the rightmost attribute specifying the most generic name, and the leftmost attribute specifying the unique object name itself.
The leftmost attribute is called Relative Distinguished Name (RDN) - it provides a unique name for the object among all objects with DNs having the same parent DN.
Sample:
userName=jim,server=BigIron,realm=Internet
this is a different DN, but it has the same "parent DN" (server=BigIron,realm=Internet)

Sample:
userName=john,server=SmallCopper,realm=Internet
this is a different DN, with a different "parent DN" (server=SmallCopper,realm=Internet)
directory record or object
set of attributes with a distinguished name
Usually a record is presented as several lines starting with the name presenting the record DN, followed by the lines presenting the record attributes. Several records are usually separated with an empty line.
Sample:
DN: userName=jim,server=BigIron,realm=Internet
objectClass=person
eyeColor=blue
mailboxLimit=1024000

DN: userName=john,server=BigIron,realm=Internet
objectClass=person
eyeColor=green
mailboxLimit=2048000
Note: the LDAP standard recommends to include the RDN attribute into the set of attributes making up a directory record. CommuniGate Pro Directory Manager enforces this rule.
directory
a set of directory records; this can be a very large set (millions of records). The set is organized as a tree using DNs. Records are removed automatically when the record with the parent DN is removed. Record DNs are updated automatically when the parent DN is changed (renamed).
directory schema
a set of directory restrictions, including:
  • a set of attribute names that can be used in the Directory (userName, mail, city, eyeColor, ...);
  • a set of objectClass attribute values that can be used in the Directory (person, organization, device, printer ...);
  • for each objectClass - names of the attributes that must be present in the object record; for records with objectClass=person a schema may require attributes with cn (canonical name) and sn (surname) names;
  • for each objectClass - names of the attributes that may be present in the object record; for records with objectClass=person a schema may allow attributes with driverLicense and eyeColor names.

Directory Storage Units

While the entire CommuniGate Pro Directory is presented to its clients as one large tree of directory records, its subtrees can be stored in separate storage units. This type of "virtual" directories is often called Meta-Directory.

CommuniGate Pro Directory supports two types of storage units:

As a result, the CommuniGate Pro Directory may include subtrees located on remote servers. If an LDAP server ldap.server.dom provides access to some directory tree, you can create a remote unit in the CommuniGate Pro Directory that points to the ldap.server.dom server and the entire ldap.server.dom directory tree or one of its subtrees will be seen in the CommuniGate Pro Directory as some subtree.

Initially, the CommuniGate Pro server creates one Local Storage Unit Main that contains the entire directory. You may add additional storage units using the WebAdmin Interface.

The diagram below shows a directory stored in one Local Unit Main:
Tree1

The diagram below shows the same directory stored in 2 Storage Units, with the entire o=MyCompany subtree stored in a separate Storage Unit LDAP1:

Tree2
Example 1:
An external LDAP server ldap1.com has a subtree o=MyCompany, and you want to store all CommuniGate Pro Domain and Account records in that subtree. You can use the following settings:
  • In the Integration settings, specify Base DN as o=MyCompany,o=ldap1
  • Create a Remote Unit MYLDAP for the o=ldap1 subtree.
  • Enter ldap1.com as the server name, and an empty string as the Server Subtree in the MYLDAP Unit Settings.
Now, when the CommuniGate Pro Server tries to access a directory record for the account john in the domain1.com domain:
  • The uid=john,cn=domain1.com,o=MyCompany,o=ldap1 DN is formed.
  • The Directory Manager detects that this record should reside on the MYLDAP Unit, and it asks that Unit to perform the requested operation on the record with the uid=john,cn=domain1.com,o=MyCompany DN (the Unit "mount point", o=ldap1 is removed from the DN).
  • The MYLDAP Unit sends the request for the uid=john,cn=domain1.com,o=MyCompany DN to the remote server ldap1.com.
Example 2:
An external LDAP server ldap1.com has a subtree o=MyCompany, and you want to store all CommuniGate Pro Domain and Account records in that subtree (the same situation as in the Example 1). You can use the following settings:
  • In the Integration settings, specify Base DN as o=ldap1
  • Create a Remote Unit MYLDAP for the o=ldap1 subtree.
  • Enter ldap1.com as the server name, and o=MyCompany as the Server Subtree in the MYLDAP Unit Settings.
Now, when the CommuniGate Pro Server tries to access a directory record for the account john in the domain1.com domain:
  • The uid=john,cn=domain1.com,o=ldap1 DN is formed.
  • The Directory Manager detects that this record should reside on the MYLDAP Unit, and it asks that Unit to perform the requested operation on the record with the uid=john,cn=domain1.com DN (the Unit "mount point", o=ldap1 is removed from the DN).
  • The MYLDAP Unit adds the Server Subtree suffix (o=MyCompany) to the DN, and then it sends the request for the uid=john,cn=domain1.com,o=MyCompany DN to the remote server ldap1.com .

Click the Directory link in the CommuniGate Pro Server WebAdmin Interface. The Directory Storage Units pages (realm) opens. You need to have the Directory access right to open these pages.

Filter:  2 of 2 selected
SubtreeUnit Name
<root> Main
o=node6 node6

The <root> string is used to specify the name of the default Storage Unit (i.e. the Storage Unit that stores the root of the Directory Tree).

To create a new Storage Unit, type a name for the new unit (this name will be used for administrating only), the Distinguished Name (DN) for the subtree that should be stored in that unit, and click the Add Remote Unit or Add Local Unit button.


Local Units

Local Directory unit is a set of files containing unit data (records/entries), unit schema, unit settings, and unit modification journal.

Open the Directory WebAdmin page and click the name of a Local Storage Unit. The unit Settings page opens.

Settings
Subtree:
Log Level:
Enforce Schema Search Results Limit:
Compose 'displayName' attribute  
Log
Use this setting to specify what kind of information the Local Storage Unit Manager should put in the Server Log.
Enforce Schema
When this option is selected, the Local Storage Unit Manager compares the structure of all new and updated records with the Unit Schema. If this option is disabled, then the Manager checks only the names of the record attributes and ensures that those attributes are included into the Unit Schema, but it does not enforce the objectClass-related restrictions.
Search Results Limit
This setting limits the maximum number of records a Directory Search operation can return.
Compose 'displayName' attribute
If this option is selected, the Local Storage Unit Manager checks if the displayName attribute is explicitly requested in a search operation, but this attribute is absent in a retrieved Directory record. In this case, the Manager composes the displayName attribute on-the-fly, using the cn attribute, or, if it is absent, the uid attribute.

Each Local Unit has its own Schema. See the Schema section for more details on Unit Schemas.

You can browse and modify the Local Unit Schema by retrieving and modifying the virtual record with the cn=schema DN. If the Local Unit is mounted on some Directory subtree, the DN for the Unit Schema record is cn=schema,subtree.


Remote Storage Unit

Click a Remote Storage Unit name on the Directory WebAdmin page to open the unit Settings page:

Settings
Log:
LDAP Server Name:
Security:
Server Subtree:
BIND DN:
Bind Password:
Protocol Version:
Channel Cache:
Log
Use this setting to specify what kind of information the Remote Unit Manager should put in the Server Log.
LDAP Server Name
This field specifies the name or the IP address of the remote LDAP server that hosts the Storage Unit subtree. If the remote LDAP server uses non-standard TCP port, you can specify the Server Name as servername:port.
Security
If the TLSPort option is set, connections to the remote server will be established in the secure mode. The default port for secure connections is 636.
If the STARTTLS option is set, connections are established to the regular LDAP port, and then the STARTTLS LDAP command is sent to initiate secure (encrypted) communication.
Server Subtree
This field specifies the remote LDAP server subtree to be "mounted". When this setting is left empty, the entire remote directory becomes visible as a CommuniGate Pro Directory subtree.
BIND DN, BIND Password
These fields specify the Distinguished Name and Password to use for "binding" (logging into) the remote LDAP server. If these fields are left blank, the CommuniGate Pro will use anonymous access to the remote LDAP server.
Protocol Version
Use this field to specify the LDAP protocol version supported with the remote LDAP server.
Channel Cache
Use this field to specify the number of "cached" TCP connections used to connect to the remote LDAP server.

Remote Directory Root

In certain situations a CommuniGate Pro server should not keep any Directory data in its Local Storage units. Instead, all Directory records should be stored on a remote LDAP server (some other CommuniGate Pro server or a third-party Directory server). In this case, the CommuniGate Pro "root" should be stored in a Remote Storage Unit pointing to that external server. By default, the Directory "root" is stored in the Main Local Storage Unit.

To tell the CommuniGate Pro Server that the Directory "root" and the entire Directory tree is stored on a remote server, follow these steps:

Binding to the Directory

Directory records can be (and usually are) protected from unauthorized access. When users want to access protected Directory data, they should authenticate themselves first. This process is called binding and successful authentication "binds" the user to a certain DN (distinguished name) in the Directory.

When a user tries to read or modify the Directory data, the binding DN is used to check the Directory Access Rights.

When a user accesses the Directory from a CommuniGate Pro WebUser Interface or a XIMSS session, the binding DN is the DN of the user Account record:
uid=accountname,cn=domainname,o=MyCompany.
See the Directory Integration chapter for the details.

When the Directory is accessed using the LDAP module, the client can authenticate itself using the CommuniGate Pro Account name and the Account password. In this case, the binding DN is the DN of the Account record.

Before converting the user account name into the account Directory record DN, the user account Server Access Rights are checked. If the account has the Directory access right, the special "master" bind DN is used instead of the user account record DN. Clients with the "master" bind DN have unlimited Directory access rights.

Any Directory DN can be used for LDAP binding. The directory record with the specified DN must exist, the record should contain the userPassword attribute, and the attribute value must match the supplied password string.

If a client has not authenticated itself, the special anyone bind DN is used.


Access Right Records

The CommuniGate Pro Directory restricts client rights to read, search, and modify Directory records. The Directory contains a set of the Access Right records that allow and prohibit directory operations depending on the target directory subtree and on the client binding DN.

Open the Directory Access Rights page to set the Access Right records:

 NameTarget Bind DN Type  
Edit
Edit
Edit  
     
Each Access Right record has:

The Up and Down buttons allow you to move the records in the table, increasing and decreasing record priorities.

When a client requests to perform a search, read, modify, or any other operation on a record or a subtree with a certain DN, the Access Right records are checked from top to the bottom. The server looks for an Access Right record that:

When such an Access Right record is found, the record type specifies if the operation is allowed or prohibited. If no Access Right record is found, the operation is prohibited.

If the client binding DN is "master" (see above), all operations are allowed.

When a client requests a "read"-type operation, the procedure is repeated for all attributes the client wants to retrieve. If the operation is prohibited for all specified attributes, the read operation fails. Othwerwise, the operation is peformed, and the attributes the client has a right to retrieve are returned to the client.

If a client requests a "search"-type operation, the procedure is repeated for all attributes used in the search filter. If the search operation is prohibited for at least one of those attributes, the search operation fails. The RDNs of found records is checked. If the RDN attribute is not allowed to be read, the record is not returned to the client.

If a client requests a "rename"-type operation, the procedure is used twice: to learn if the client has a right to delete the original Directory record, then to learn if the client has a right to create a Directory record in the new location.

Special strings can be used in the Bind DN field:

anyone
the Access Right record is applied for any BindDN, including the anyone (absent) BindDN.
brother
the Access Right record is applied if the Bind DN and the Target DN has the same parent DN. For example, the uid=someuser,cn=domain1.com and uid=otheruser,cn=domain1.com DNs are "brothers". This type of bind DN specifications is useful to grant CommuniGate Pro users access to the Directory records of other users in the same CommuniGate Pro domain.
parent
the Access Right record is applied if the Bind DN is a parent of the Target DN. For example, the cn=domain1.com DN is a parent of uid=user1,cn=domain1.com and id=book1,uid=user1,cn=domain1.com DNs.
child
the Access Right record is applied if the Target DN is a parent of the Bind DN.
self
the Access Right record is applied if the Target DN is the same as the Bind DN. This type of bind DN specification is useful to grant CommuniGate Pro Account users a right to modify their own directory record attributes.

To create an Access Right record, enter the record name, target DN, and bind DN into the last empty element of the Access Rights table and click the Update button. Use the Up buttons to set the record priority.

To remove an Access Right record, delete the record name and click the Update button.


Access Right Specifications

To specify Directory Access Rights, open the Access Rights page and click the "specifications" link to open the Access Right record:

Record-Level Rights
prohibit Record Deletion prohibit Record Creation
These options specify if clients with the given Bind DN can create or delete records with the given Target DN.
Attribute Reading
prohibit:
This field lists the data attributes that clients with the given Bind DN can read from the records with the given Target DN. The attribute names should be comma-separated. To allow clients read all record attributes, use the asterisk (*) symbol.
Attribute Searching
prohibit:
This field lists the attributes that clients with the given Bind DN can use in filters when searching Target DN subtrees.
Attribute Modifying
prohibit:

This field lists the data attributes that clients with the given Bind DN can modify in the Target DN records.

Sample Access Right record:

Target DN
uid=*,cn=domain1.com
Bind DN
brother
Type
allow
Readable Attrbutes
objectClass,officeEmail,roomNumber,cn,uid
This record allows all domain1.com users to read the objectClass, cn, uid, officeEmail, and roomNumber attributes from Directory records of other domain1.com Domain users.

Sample Access Right record:

Target DN
cn=domain1.com
Bind DN
child
Type
allow
Readable Attrbutes
objectClass,officeEmail,roomNumber
Searchable Attrbutes
cn,uid
This record allows all domain1.com users to search the Domain Directory subtree by cn (canonical name) and uid, but not by other readable attributes.

Directory Browser

The CommuniGate Pro WebAdmin Interface includes a Directory Browser. Open the Directory realm and click the Browser link to open the Directory Browser page.

The Browser page includes the DN field:
Distinguished Name

Use this field to type the DN of the Directory record/subtree you want to view and click the Go button. Click the Up button to remove the leftmost DN element and open the parent Directory record.

The next panel displays the Directory record with the specified DN:

AttributeValue
businesscategory"Software development/technical support"
description"\"Stalker Software, Inc. subsidiary\""
o"CommuniGate Systems"
objectclassorganization
seealso"o=CommuniGate Systems, c=US"
telephonenumber676-555-1212

If the record with the specified DN could not be retrieved, this panel will contain the error message.

The next panel displays all record children.

Subtree
Filter:
RDNobjectClass
cn=aaa.dom (top,organization,CommuniGateDomain)
cn=bbb.dom (top,organization,CommuniGateDomain)

Use the pop-up menu to limit the number of records displayed on the subtree panel.

To search for specific records, enter an LDAP filter string (in the RFC 2254 format) into the Filter field and click the Display button.

The table elements display children RDNs and object classes.

Click the child element RDN link to open the child record in the Directory Browser.


Importing Directory Data

The CommuniGate Pro WebAdmin Interface allows the Server Administrator to import directory modifications from text files in the LDIF and "replog" formats:

To import data into the CommuniGate Pro Directory, click the Browse button and select an LDIF file on your workstation. Click the LDIF Import button to insert all records from the selected LDIF file.

To apply a set of record modifications to the CommuniGate Pro Directory, click the Browse button and select a "replog" file on your workstation. Click the LMOD Import button to apply all modifications from the selected file.


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