Mapping users/groups from an OpenLDAP or Generic LDAP server

This article describes how to setup basic OpenLDAP integration with Kerio Connect server.

What should you know before you start reading this article

Before you start read the following article for information on:

• How to edit files under linux, for example using vi.
• Basic knowledge about linux systems, for example how to install files.
• Idea about the directory structure you want to implement.
• This solution describes mapping of users and groups to Kerio Connect server.
• This example use non-secured LDAPLightweight Directory Access Protocol - A protocol that enables users to access centrally managed contacts. binding.
• Authentication mechanism used in this scenario sends plain text passwords over the network, so it is recommended to have both - OpenLDAP server and Kerio Connect server on the same machine.
• Example is for SuSe Linux 10.0 or Debian, but it would work for other distributions as well.

LDAP browser might be helpful for editing and for further analysis, such as JExplorer. Following login can be used throughout this example to log into the OpenLDAP server:

• Host: IP Address of the LDAP server
• Protocol: LDAP v3
• Base DN: dc=example, dc=com
• Level: User+Password
• User DN: cn=Manager, dc=example, dc=com
• Passoword: passoword

System requirements

• Supported Linux distribution.
• Following packages are required in addition:

• openldap2 - OpenLDAP server package
• nss-ldap - optional module for user search in OpenLDAP required by some authentication mechanisms
• pam_ldap - optional module required by PAM module for the user authentication against LDAP

• Kerio Connect installation, it is recomended to install it on the same machine as the OpenLDAP server is due to security reasons.
• Files in attachment section may be useful during the setup and getting the solution to work.

Overview

Following image is a basic connection map between the OpenLDAP server and Kerio Connect server described in this article.

OpenLDAP server installation and configuration

In case you haven't installed the OpenLDAP server yet, install it. You can do it easilly using the Yast configuration interface on Suse linux or using following command on Debian linux:

apt-get install ldap-utils slapd

Install the Kerio Connect server to some local machine or to the same machine as the OpenLDAP server is installed on.

After the installation of OpenLDAP server, default configuration is created. It will be used in this example. But you can modify default configuration according to your needs. The configuration is stored in a file /etc/openldap/slapd.conf. There are few fields you will need to configure. In this example let's assume our domain is "my-domain.com", the slapd.conf file will looks like following:

database dbm

suffix "dc=my-domain,dc=com"

rootdn "cn=Manager,dc=my-domain,dc=com"

rootpw secret

directory /var/lib/ldap

index objectClass,uid,uidNumber,gidNumber,memberUid eq

index cn,mail,surname,givenname eq,subinitial

It contains more information but only these are important in this part of the configuration. Following table describes meaning of each configuration option:

slapd.conf

Database	Database type
suffix	The base distinguished name of the LDAP directory schema
rootdn	Built-in directory manager's name, it is not displayed in the directory structure
rootpw	Built-in directory manager's password, it is not displayed in the directory structure
directory	The directory where is stored the LDAP database
index	Which attributes will be used for indexing

The managers password is stored unencrypted by default. It can be replaced with encrypted password if needed. The hash of the password can be obtained using the following command:

/root/ldapconf # slappasswd -h {SHA}

New password:

Re-enter new password:

{SHA}e4YJDouLxNrSgL/D3m7ZG49EriuICmP8

or, using different hash if required:

/root/ldapconf # slappasswd -h {MD5}

New password:

Re-enter new password:

{MD5}c4gYerDyeue6NSgL/D3m7ghGsh9rhtu==

Before we will continue, start the OpenLDAP server to double check everything is configured properly:

/etc/init.d/ldap start (Suse linux)

It is also possible to adjust access lists (ACL) in the slapd.conf file. It is not necessary by default and we will not do it in this example. Currently we have OpenLDAP server running. We can double check the server is running properly by performing a simple query:

linux:/etc/openldap # ldapsearch -x -b '' -s base '(objectClass=*)' namingContexts

# extended LDIF

#

# LDAPv3

# base <> with scope base

# filter: (objectClass=*)

# requesting: namingContexts

#

#

dn:

namingContexts: dc=my-domain,dc=com

# search result

search: 2

result: 0 Success

# numResponses: 2

# numEntries: 1

linux:/etc/openldap #

If there is similar output displayed, the OpenLDAP server is running properly. If you want to start OpenLDAP server automatically during the system startup execute following command:

linux:/etc/openldap # chkconfig ldap on (Suse linux)

Adding new user/group to OpenLDAP server

This step describes how to add a new users or create a new groups in OpenLDAP server. This is still only OpenLDAP configuration and should be known before we will continue in further configuration steps. The example uses simple objectClass'es which may vary accross LDAP implementations. In case you already use some users/group definition proceed to next step.

Objects can be easily imported to the OpenLDAP directory using LDIF file. The LDIF file is a text file in a format containing data to import/modify/remove objects. This article will not describe the structure of this file, but you can use example files provided in this article. To import a test user account download the user.ldif file and execute following command or use your LDAP browser to import the LDIF file:

linux:/etc/openldap #linux:/etc/openldap # ldapadd -f user.ldif -h 127.0.0.1 -D "cn=Manager,

dc=my-domain,dc=com" -x -W

Enter LDAP Password:

adding new entry "uid=test_user,dc=my-domain,dc=com"

linux:/etc/openldap #

The password is requested interactivelly (-W option), but you can provide it by -w [password] parameter. This password is LDAP administrators password provided in the slapd.conf file. The -f [filename] parameter specifies the LDIF file to import and the -h [IPaddress/hostname] specifies the IP addressAn identifier assigned to devices connected to a TCP/IP network. or a hostname of the LDAP server (in our example both Kerio Connect and OpenLDAP are installed on the same computer, so localhost address is used).

user.ldif file example:

dn: uid=test_user,dc=my-domain,dc=com

uid: test_user

sn: User

cn: Test User

objectClass: person

objectClass: organizationalPerson

objectClass: posixAccount

objectClass: top

loginShell: /bin/bash

homeDirectory: /home/testuser

uidNumber: 1001

gidNumber: 1001

Almost the same applies to groups, but the format is slightly different. See example LDIF file named group.ldif for more information. To add a group to your OpenLDAP server download the group.ldif file and execute following command:

linux:/etc/openldap #linux:/etc/openldap # ldapadd -f group.ldif -h 127.0.0.1 -D "cn=Manager

,dc=my-domain,dc=com" -x -W

Enter LDAP Password:

adding new entry "uid=Group1,dc=my-domain,dc=com"

linux:/etc/openldap #

group.ldif file example:

dn: cn=Group1,dc=my-domain,dc=com

cn: Group1

objectClass: top

objectClass: groupOfNames

objectClass: posixGroup

member: uid=test_user,dc=my-domain,dc=com

gidNumber: 100

memberUid: test_user

There are two independent group definitions - objecClasses - in the group.ldif file. The groupOfNames class and posixGroup class. It is not necessary to use both of them, even both are used in this example. Choose one which fits your needs. According to choosed group specify users using the member attribute - in case of groupOfNames objectClass definition. Or using the memberUID attribute - in case of posixGroup objectClass definition.

Kerio Connect configuration - directory mapping

Once the OpenLDAP server is configured and new user/group is created, it is possible to bind the OpenLDAP with Kerio Connect server.

• Create a new email domain in Kerio Connect. In Directory Services tab choose the Open Directory service. This service is closest to the OpenLDAP definition and can be used as a reference. Fill in all necessary information in all dialogs according to the example below. Finally test the connection if everything is correct and if it is possible to do LDAP bind against the OpenLDAP server.
• Extend the OpenLDAP schema for the Kerio Connect's properties. It will not affect any existing user, but it will be possible to add some additional attributes to each user/group definition. These attributes are used only by Kerio Connect to store its own attributes. In case you already have your custom attributes you want to match against the Kerio Connect server, it is possible to use them instead of Kerio ones and adjust the map file which will be described later in this article.

• " To extend the OpenLDAP schema download schema extension file kerio-mailserver.schema from Attachments section. Copy schema extension file to /etc/openldap/schema/ directory.
• Edit the /etc/openldap/slapd.conf file (using the vi editor for example) and add new line to appropriate section of the config file (the section with other includes): include /etc/openldap/schema/kerio-mailserver.schema

• Restart the OpenLDAP server by executing following command: /etc/init.d/ldap restart
• We used the Apple Open Directory mapping as a reference configuration, but there are differencies in the OpenLDAP and Open Directory implementation. According to these different implementations we need to adjust Kerio Connect's configuration file mailserver.cfg.

1. Stop Kerio Connect service
2. Open mailserver.cfg file located in the installation directory of Kerio Connect.
3. Locate your domain definition in following section of the configuration file: <list name="Ldap">
4. According to the example below for test domain example.com modify the UserBaseDN and GroupBaseDN search path to appropriate search path in your OpenLDAP implementation. In this example it is "dc=my-domain,dc=com" which is default domain after the OpenLDAP installation. But it can be different in case you have some containers for user accounts (for example), or if you use different domain name of course. Also create a copy of the apple.map file and save it as openldap.map file which we will use for our OpenLDAP mapping. The configuration of openldap.map file will be described later in this article.

<listitem>

<variable name="Domain">example.com</variable>

<variable name="ServerName">127.0.0.1</variable>

<variable name="ServerPort">389</variable>

<variable name="BindDn">cn=Manager,dc=my-domain,dc=com</variable>

<variable name="BindPassword">DE3:716f95b639c...15</variable>

<variable name="MapFile">openldap.map</variable>

<variable name="Filter"></variable>

<variable name="UserBaseDn">dc=my-domain,dc=com</variable>

<variable name="GroupBaseDn">dc=my-domain,dc=com</variable>

<variable name="Description"></variable>

<variable name="Enabled">1</variable>

<variable name="PrimaryRefreshInt">30</variable>

<variable name="LdapNetworkTimeout">10</variable>

<variable name="SecureConnection">0</variable>

</listitem>

• Start Kerio Connect engine.
• You should not see any error message when you try to access Users or Groups in Domain Settings tree. You will not see any user yet, because users don't have any Kerio Connect properties yet. However this test may prove the LDAP connection is working properly and Kerio Connect extensions were installed properly. In case you receive error message saying the Directory Extensions were not installed properly, check steps above if you specified correct search patch and the include was accepted by the OpenLDAP server.

Extending user definitions in OpenLDAP for the Kerio Connect properties

At this point the OpenLDAP server is configured and Kerio Connect server is configured to connect to the OpenLDAP directory.

But there is still no user mapped from the OpenLDAP directory to kerio Connect. It is because there is no Kerio Connect user enabled in your actual OpenLDAP directory. Each user which should have Kerio Connect account have to be extended for Kerio Connect properties. Follow these steps to extend user's attributes and configure correct user mapping to create a Kerio Connect account for such user:

1. The OpenLDAP user have to be extended for Kerio Connect attributes. We can divide it to two groups. First group contains necessary attributes (objectClass definition), second one contains optional attributes. You can modify existing user.ldif file according to your needs or you can use an example kerio-user.ldif file as a reference one. These modifications can be easily applied by executing following command on your OpenLDAP server:

linux:/etc/openldap # ldapmodify -f kerio_user.ldif -h 127.0.0.1 -x -D "cn=Manager,dc=

my-domain,dc=com" -W

Enter LDAP Password:

modifying entry "uid=test_user,dc=my-domain,dc=com"

linux:/etc/openldap #

The kerio_user.ldif file example...

dn: uid=test_user,dc=my-domain,dc=com

uid: test_user

sn: User

cn: Test User

objectClass: person

objectClass: organizationalPerson

objectClass: posixAccount

objectClass: top

objectClass: kerio-Mail-User

loginShell: /bin/bash

homeDirectory: /home/testuser

uidNumber: 1001

gidNumber: 1001

Necessary attributes/objectClasses	Description
objectClass: kerio-Mail-User	This option will extend the user attributes set for the Kerio Connect ones. It allows to add optional attributes like the Message Quota, ... It does not activate the account, account needs to be activated using the optional kerio-Mail-Active attribute.

Optional Kerio Connect attributes	Description
kerio-Mail-Active	It activates the Kerio Connect account. 0 - not active 1 - active
kerio-Mail-AccountEnabled	It can enable/disable the account.
kerio-Mail-AdminRights	Admin rights.
kerio-Mail-Authorization	The authorization properties.
kerio-Mail-Address	User's email address.
kerio-Mail-ForwardMode	Forward mode.
kerio-Mail-ForwardAddress	Address to which email should be forwarded in case forward mode is enabled.
kerio-Mail-QuotaStorage	The user's storage quota.
kerio-Mail-QuotaMessage	The max. number of emails user's quota.
kerio-Mail-MaxOutgoingMessageSize	Maximal outgoing message size.
kerio-Mail-WebReplyToAddress	Reply-to address used in webmail interface.

Example minimal attribute set:

Example attribute sets	Description
objectClass: kerio-Mail-User kerio-Mail-Active: 1	The user can have Kerio Connect account. The account is activated (can receive emails).

2. Now it should be possible to activate (Add) new user from the Administration console of Kerio Connect. Activated user can not be used because there is no user-group mapping and there is no authentication method specified. To create Kerio Connect group in OpenLDAP and to create user-group mapping read next chapter.

Extending group definitions in OpenLDAP for the Kerio Connect properties

OpenLDAP uses different mapping for users and groups than OpenDirectory or ActiveDirectory. Usually other directory services use two directional mapping when each group definition contains users which belongs to the group, and vise versa the user contains the information to which group belongs. This scenario is used in Active Directory or Open Directory.

OpenLDAP uses only one way mapping when group contains its members. But the information in user definition to which group the user belongs is missing. Because of this limitation it is required to create such mapping manually. We can split group integration into two parts. Extending the schema for custom groupMemberShip attribute and to mapping the OpenLDAP group to Kerio Connect. Follow next steps to extend the schema for custom groupMemberShip attribute. In addition we are adding apple-generateduid attribute which is required since Kerio MailServer 6.7. for web based administration. This attribute is used to uniquely identify user or a group. So it is required to add it to group definition as well (use the same approach as for the user definition in this example). The apple-generatedid is automatically updated by Kerio Connect so it is not necessary to define it manually.

1. Open the OpenLDAP schema file defining the user definition - /etc/openldap/schema/rfc2307bis.schema in this example. You can modify any schema used for user definition in case you use different OpenLDAP implementation. If you already have such mapping, skip extending the schema for the groupMemberShip attribute and proceed to part describing the group mapping to Kerio Connect.
2. Locate last attribute definition in this file.

attributetype ( 1.3.6.1.1.1.1.33 NAME 'automountInformation'

DESC 'Automount information'

EQUALITY caseExactIA5Match

SUBSTR caseExactIA5SubstringsMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 SINGLE-VALUE )

objectclass ( 1.3.6.1.1.1.2.0 NAME 'posixAccount' SUP top AUXILIARY

DESC 'Abstraction of an account with POSIX attributes'

MUST ( cn $ uid $ uidNumber $ gidNumber $ homeDirectory )

MAY ( userPassword $ loginShell $ gecos $ groupMemberShip $

description ) )

3. Once you find last attribute definition change it according to following example.

attributetype ( 1.3.6.1.1.1.1.33 NAME 'automountInformation'

DESC 'Automount information'

EQUALITY caseExactIA5Match

SUBSTR caseExactIA5SubstringsMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 SINGLE-VALUE )

attributetype ( 1.3.6.1.1.1.1.34 NAME 'groupMemberShip'

EQUALITY caseExactIA5Match

SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )

attributetype (1.3.6.1.1.1.1.35

NAME ( 'apple-generateduid' )

DESC 'generated unique ID'

EQUALITY caseExactMatch

SUBSTR caseExactSubstringsMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE )

objectclass ( 1.3.6.1.1.1.2.0 NAME 'posixAccount' SUP top AUXILIARY

DESC 'Abstraction of an account with POSIX attributes'

MUST ( cn $ uid $ uidNumber $ gidNumber $ homeDirectory )

MAY ( userPassword $ loginShell $ gecos $ groupMemberShip $ apple-generateduid $

description ) )

4. Restart the OpenLDAP server to apply changes.

The user definition is now extended for new attributes describing the group to which the user belongs, what is native for OpenLDAP implementations. However we use apple-kerberos.map file. OpenDirectory use different user to group mapping as well as Active Directory. We need to extend also user definition in the map file to properly search Open LDAP for new groupMemebrShip attribute mapping:

1. We used Apple Open Directory server mapping as a reference configuration and we created openldap.map file based on apple.map file. Hence we need to adjust the openldap.map file which is used for this mapping. This file is located in ../installation_directory/ldapmap folder. Locate this file and open it via some text editor.
2. Locate User definition section at the beginning of this file. See this example from original apple.map file.

<map table="User">

...

<variable>

<name>Groups</name>

<value><attribute>cn</attribute></value>

</variable>

...

</map>

3. Change the directory map file according to following example to alter the user to group mapping in Kerio Connect.
4. Example of user to group mapping using the GroupMemebrShip attribute from our example...

<map table="Users">

...

<variable>

<name>Groups</name>

<value><GroupMemberShip></value>

</variable>

...

</map>

5. Restart the Kerio Connect engine to apply changes.
6. You can download complete map file from Attachment section - openldap.map.

Following steps maps our OpenLDAP group to Kerio Connect and we will add the test_user into this new group.

The OpenLDAP group has to be extended for Kerio Connect attributes as well as the OpenLDAP user. We can divide attributes to two groups. First group contains necessary attributes (objectClass definition), second one contains optional attributes. You can modify existing group.ldif file according to your needs or you can use an example kerio-group.ldif file as a reference one (it contains all required attributes). These modifications can be easily applied by executing following command on your OpenLDAP server:

linux:/etc/openldap # ldapmodify -f kerio_group.ldif -h 127.0.0.1 -x -D "cn=Manager,dc=my-do

main,dc=com" -W

Enter LDAP Password:

modifying entry "cn=Group1,dc=my-domain,dc=com"

linux:/etc/openldap #

The kerio_group.ldif file example:

dn: cn=Group1,dc=my-domain,dc=com

cn: Group1

objectClass: top

objectClass: groupOfNames

objectClass: posixGroup

objectClass: kerio-Mail-Group

member: uid=test_user,dc=my-domain,dc=com

gidNumber: 100

memberUid: test_user

Necessary attributes/objectClasses	Description
objectClass: kerio-Mail-Group	This option will extend the user attributes set for the Kerio Connect ones. It allows to add optional attributes like the Message Quota, ... It does not activate the account, account needs to be activated using the optional kerio-Mail-Active attribute.

Optional Kerio Connect attributes	Description
kerio-Mail-Active	It activates the Kerio Connect group account. 0 - not active 1 - active
kerio-Mail-AdminRights	Admin rights.
kerio-Mail-Authorization	The authorization properties.
kerio-Mail-Address	User's email address.

Examples minimal definition:

Example attribute sets	Description
objectClass: kerio-Mail-Group kerio-Mail-Active: 1	The user can have Kerio Connect account. The account is activated (can receive emails).

In this point we have created Kerio Connect group in OpenLDAP server. So we can adjust the map file to map the OpenLDAP group definition with Kerio Connect.

To create appropriate mapping follow these steps:

1. We used Apple Open Directory server mapping as a reference configuration. Hence we need to adjust the apple.map file which is used for this mapping. This file is located in ../installation_directory/ldapmap folder. Locate this file and open it via some text editor.
2. Locate Group definition section at the bottom of this file. See this example from original apple.map file.

<map table="Group">

<filter>objectclass=apple-group</filter>

<active-attribute>kerio-Mail-Active</active-attribute>

<variable>

<name>Name</name>

<value><attribute>cn</attribute></value>

</variable>

<variable>

<name>MailAddress</name>

<value><attribute>kerio-Mail-Address</attribute></value>

</variable>

<variable>

<name>Rights</name>

<value><attribute>kerio-Mail-AdminRights</attribute></value>

</variable>

<variable>

<name>Authorization</name>

<value><attribute>kerio-Mail-Authorization</attribute></value>

</variable>

<variable>

<name>Description</name>

<value><attribute>apple-group-realname</attribute></value>

</variable>

</map>

</mapfile>

3. Change the group map file according to your group definition in OpenLDAP. We used three group objectClass definitions in our OpenLDAP group - groupOfNames, posixGroup, kerio-MailGroup. Choose one from this list and use it as a filter. So only OpenLDAP items with the specified objectClass will be searched as Kerio Connect groups. All other attributes are optional and may stay unchanged (instead of last one which use apple attribute, change it to some attribute describing your OpenLDAP group - in this example it is description attribute).
4. Example of group definitions...

<map table="Group">

<filter>objectclass=groupOfNames</filter>

<active-attribute>kerio-Mail-Active</active-attribute>

<variable>

<name>Name</name>

<value><attribute>cn</attribute></value>

</variable>

<variable>

<name>MailAddress</name>

<value><attribute>kerio-Mail-Address</attribute></value>

</variable>

<variable>

<name>Rights</name>

<value><attribute>kerio-Mail-AdminRights</attribute></value>

</variable>

<variable>

<name>Authorization</name>

<value><attribute>kerio-Mail-Authorization</attribute></value>

</variable>

<variable>

<name>Description</name>

<value><attribute>description</attribute></value>

</variable>

</map>

5. Restart the Kerio Connect engine to apply changes.

It would be possible to see OpenLDAP group in Kerio Connect's Administration console. Next chapter describes how you can add users into groups.

Adding users to groups

If all previous configuration steps were successfully passed, it should be possible to see users from the OpenLDAP database in Kerio Connect Administration console and it should be possible to see also groups defined in your OpenLDAP server in it. Following text describes how to add a user into a group using the OpenLDAP directory definitions.

As was described in Group mapping section OpenLDAP uses one direction of mapping of users. Because of this we have created new special attribute named groupMemeberShip which can be used by Kerio Connect to locate group to which user belongs. So adding a user to some group means adding this attribute to user definition in OpenLDAP server.

See following example how to add our test_user to a Group1. Exactly it means extending the user definition for groupMemeberShip attribute.

1. Edit the kerio_user.ldif file, or your custom user definition file.
2. Add attribute groupMemeberShip to definition file as is shown on following example or use the LDAP browser to extend the user definition for a new attribute groupMemberShip:

dn: uid=test_user,dc=my-domain,dc=com

uid: test_user

sn: User

cn: Test User

objectClass: person

objectClass: organizationalPerson

objectClass: posixAccount

objectClass: top

objectClass: kerio-Mail-User

loginShell: /bin/bash

homeDirectory: /home/testuser

uidNumber: 1001

gidNumber: 1001

groupMemberShip: Group1

3. Now the user belongs to a group named Group1.

Authentication

We set up the OpenLDAP account and the OpenLDAP group and we performed correct mapping. But the user still can't authenticate. This is because of the incorrect authentication type used for a user. The authentication type is set in the apple.map file. Default value is KerberosAn authentication protocol for client/server applications. authentication in Apple OpenDirectory.

1. The authentication type is set in the map file (openldap.map) and is set to 3 by default. See possible authentication methods:

• 0 - Internal database authentication
• 1 - NT domain authentication.
• 2 - LinuxPAM authentication method.
• 3 - Kerberos authentication. Requires Kerberos server.
• 4 - Apple Password Server authentication method.
• 5 - Authentication against LDAP server. It is used in this example.

2. This method send passwords in plain text format to the LDAP server so it is not secure to send it over the network. Hence it is highly recommended to have Kerio Connect on the same machine as your OpenLDAP server or in the same isolated network. The second disadvantage of this solution is that the user cannot change his password. We recommend to use different authentication method if it is possible hence it is more secure, and it may also supports password updates. If it is necessary to use this authentication type follow these instructions to enable it.
3. Stop Kerio Connect engine.
4. Modify the openldap.map file according to following example:

<variable>

<name>Auth_type</name>

<value>5</value>

</variable>

5. Modify or add additional map attribute (in openldap.map file in user definition section) according to the following example:

<variable>

<name>LdapDN</name>

<value><dn /></value>

</variable>

6. Start Kerio Connect engine. Now you should be able to authenticate against the OpenLDAP server.

linux:/etc/openldap # ldappasswd -S -D "cn=Manager,dc=my-domain,dc=com" -h 127.0.0.1 -x -W "

uid=test_user,dc=my-domain,dc=com"

New password:

Re-enter new password:

Enter LDAP Password:

Result: Success (0)

linux:/etc/openldap #

Attachments:

• mailserver.cfg
• kerio-mailserver.schema
• openldap.map
• slapd.conf
• user.ldif
• group.ldif
• schema2.png
• kerio_user.ldif
• kerio_group.ldif