Use address book stored in LDAP server like Active Directory or OpenLDAP

Introduction

This article explains how you can edit xml configuration files of WebMail Pro to make it use LDAP Address Book, either instead of the default address book (which is stored in SQL database), or alongside with it. The approach can be used with virtually any LDAP storage: OpenLDAP, Active Directory etc.

NB: This integration feature currently has test status (non-production), you are using this at your own risk. If you'd like to engage our experts in enabling the LDAP integration for your particular environment, please let us know.

Configuration files

Information on LDAP server access, fields and attributes used are stored in App_Data\SETTINGS\ldap_book_private.xml or ldap_book_global.xml file. Existing App_Data\SETTINGS\settings.xml file is used to determine when address book is retrieved over LDAP and when it's taken from SQL.

The section holds the option for global and personal address book (GlobalAddressBook ? PersonalAddressBook). The mode parameter can have one of the following values:

• Off - address book is disabled;
• Sql - address book is stored in SQL server (default option);
• Ldap - address book is retrieved from LDAP server.

<?xml version="1.0" encoding="utf-8"?>
<Settings>
...
<Contacts>
	<PersonalAddressBook>
		<!-- See ldap_book_private.xml file for naming scheme and LDAP settings-->
		<Mode>Off|Sql|Ldap</Mode>
	</PersonalAddressBook>
	<GlobalAddressBook>
	<!-- See ldap_book_global.xml file for naming scheme and LDAP settings-->
		<Mode>Off|Sql|Ldap</Mode>
		<Sql>
			<Visibility>Off|SystemWide|DomainWide</Visibility>
		</Sql>
	</GlobalAddressBook>
</Contacts>
</Settings>

Connecting to LDAP server

There are several approaches for connecting to LDAP server.

1. Password-less. In this case, server is protected with a firewall to ensure that LDAP server is only accessible locally and not from outside.

2. Single username/password pair (e.g. root / password) for connecting to LDAP address book and fetching data from it. This approach is usually used for accessing global address book.

3. With username/password the user has entereed on WebMail login screen. This way, scope of data accessible over LDAP is restricted based on login ID. This approach is usually used for accessing personal address book.

Thus, with personal address book, user's credentials are used. For global address book, it's either password-less access, or single username/password pair defined via Bind DN and BindPassword configuration options.

Configuring Private Address Book access

Configuration file used here is App_Data\SETTINGS\ldap_book_private.xml. Its section is responsible for connecting to LDAP server for accessing personal address book.

<AddressBook>
   <Ldap>
      <Host>webmail.mailstone.net</Host>
      <Port>389</Port>
      <UseTls>false</UseTls>
      <BindDn>cn=%e,ou=people,o=root</BindDn>
      <BindPassword></BindPassword>
      <AuthType>Anonymous|Simple|Sasl</AuthType>
      <BaseDn>cn=%e,ou=people,o=root</BaseDn>
      <Writable>1</Writable>
   </Ldap>
   ...
</AddressBook>

<Host>webmail.mailstone.net</Host>

LDAP server host

<Port>389</Port>

LDAP server port

<UseTls>0</UseTls>

Defines whether SSL is used

<BindDn>cn=%e,ou=people,o=root</BindDn>

Here, %e stands for email address. %u is username, %d is domain name.

<BindPassword></BindPassword>

In case if password is not specified explicitly, user account password is used

<AuthType></AuthType>

Authentication type used. Some servers support particular auth type only

<BaseDn>cn=root,ou=people,o=root</BaseDn>

base dn is either the same as bind dn or for superuser access

Configuring Global Address Book access

Configuration file used here is App_Data\SETTINGS\ldap_book_global.xml. Its section is responsible for connecting to LDAP server for accessing global address book.

<AddressBook>
   <Ldap>
      <Host>webmail.mailstone.net</Host>
      <Port>389</Port>
      <UseTls>0</UseTls>
      <BindDn>cn=root,dc=afterlogic,dc=com</BindDn>
      <BindPassword>mypassword</BindPassword>
      <BaseDn>ou=AddressBook,dc=afterlogic,dc=com</BaseDn>
      <Writable>0</Writable>
   </Ldap>
   ...
</AddressBook>

<Host>webmail.mailstone.net</Host>

LDAP server host

<Port>389</Port>

LDAP server port

<UseTls>0</UseTls>

Defines whether SSL is used

<BindDn>cn=root,dc=afterlogic,dc=com</BindDn>

bind dn

<BindPassword>mypassword</BindPassword>

bind password

<BaseDn>ou=AddressBook,dc=afterlogic,dc=com</BaseDn>

base dn

Read-only address book access

The Writable tag defines whether insert/edit is allowed for LDAP address book or not. By default, Private Address Book is writable (true) while Global Address Book is read-only (false).

<AddressBook>
   <Ldap>
      ...
      <Writable>true|false</Writable>
   </Ldap>
   ...
</AddressBook>

NB: if the option is set to false, insert/edit is disabled, so CSV file import is not available as well.

Address book fields

Address book can contain any number of fields which are displayed line by line as name/value pairs.

Files hold the information on records retrieved from address book and the way they are matched against address book in WebMail Pro:

	<Contact searchClass="posixAccount" createClass="top,posixAccount">
		<Email>mail</Email>
		<FullName>displayName</FullName>
		...
		<OtherProperties>
			<Property name="CommonName" defValue="%u" >cn</Property>
			<Property name="Cellphone">mobile</Property>
			...
		</OtherProperties>
	</Contact>
	<Group searchClass="posixGroup" createClass="top,posixGroup">
		<GroupName>cn</GroupName>
		<Email />
		<Contacts searchBy="uid">memberUid</Contacts>
		...
		<OtherProperties>
			<Property name="Description">description</Property>
			...
		</OtherProperties>
	</Group>

Contact and Group tags describe respective entities. searchClass attribute defines which class denotes particular entity on LDAP server and is used to select groups/contacts. createClass attribute describes all the classes of entity which should be supplied when creating the entity.

Sub-tag names match properties of AddressBookContact and AddressBookGroup in WebMail Pro, while the values should match object attributes on LDAP server - except for OtherProperties tag, which contains object attributes which don't have matching properties in WebMail Pro but still should be retrieved or must be supplied when creating an object. name attribute of Property tag defines how the property is shown in WebMail Pro interface while its value is an attribute on LDAP server. Same approach applies to creating an object on LDAP server, properties from OtherProperties container will have empty values assigned.

For Contacts tag nested into Group tag, the searchBy attribute is added, it points to attribute of the contact which belongs to the group. For instance, group may have multiple memberUid attributes:

memberUid=user1; memberUid=user2

and each of them points to uid value of the contact (contacts with uid attribute containing user1 and user2 respectively).

defValue attribute contains the default value for the property, it will be used in case if the value is not specified explicitly.

If searchInContact is set to true, that means the information on the group(s) the contact belongs to is available in contact record, i.e. contact entry has a field which stores groups' identifiers. If searchInContact is set to false, contacts information is stored in the group, i.e. group record has a field where contacts' ids are listed.

The SearchFields tag contains the information on fields which are used for search.

<AddressBook>
   ...
   <SearchFields wildcardsearch=”true”>
      <Field>cn</Field>
      <Field>displayName</Field>
      <Field>mail</Field>
   </SearchFields>
</AddressBook>

The wildcardsearch attribute defines whether wildcard search is supported or not. If it's set to true (the default value), the address book is also used for autocompleting addresses in To/Cc/Bcc fields. Otherwise, "*" characters are removed from search pattern.