CommuniGate Pro: Directory

Intro
Installation
SysAdmin
Objects
Transfer
Access
Directory
Schema 
Integration 
Data Files
Clusters
WebMail
Miscellaneous
Licensing
HowTo

The CommuniGate Pro Server includes the Directory Manager implementing a 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 can work with both Local Directory Storage Units and with Remote Storage Units, such as external LDAP Directories.


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 (,) sign.
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 atributes. 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 always include the RDN attribute into the set of attributes making up the 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 (cannonical 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.

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 entire ldap.server.dom directory 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:

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:

Click the Directory link in the left frame of the CommuniGate Pro Server WebAdmin Interface. The Directory Storage Units page opens. You need to have the Directory access right to open this page.

Filter:
  2 of 2 Storage Units selected
Subtree Unit Name
<root>Main
o=node6node6

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
Log:

Log
Use this setting to specify what kind of information the Local Storage Unit Manager should put in the Server Log.

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


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:
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.

BIND DN, BIND Password
Thes fields specify the Distinguished Name and Password to use for "binding" (loging 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 unauthorised access. When users want to access protected Directory data, they should authenticate themselves first. This process is called binding and successfull 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 Web User Interface 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

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:

 NameTargetBind DNTypeRights 
specifications
specifications
specifications

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.

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:

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:

Entry-Level
delete entry create entry
These options specify if clients with the given Bind DN can create or delete records with the given Target DN.

Readable Attributes
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 ("*") sign.

Searchable Attributes
This field lists the attributes that clients with the given Bind DN can use in filters when searching Target DN subtrees.

Modifiable Attributes
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.comusers read the objectClass, cn, uid, officeEmail, and roomNumber attributes from Directory records of other 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.comusers search the domain Directory subtree by cn (cannonical name) and uid, but not by other readable attributes.


Directory Browser

The CommuniGate Pro WebAdmin Interface includes a Directory Browser. Open the Directory page 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"\"subsidiary for Stalker Software, Inc.\""
o"Stalker Labs"
objectclassorganization
seealso"o=Stalker Software, 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.comCommuniGateDomain
cn=bbb.comCommuniGateDomain

Use the poup menu to limit the number of records displayed on in 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.


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