Discussion

Both Active Directory and Open Directory offer directory services which can be configured to work with Kerio MailServer running on Linux. This article describes how to perform this configuration.

Assumptions

Before you begin this article, the following must be true:

1. A properly configured and working Active Directory or Open Directory domain.
2. Valid DNS records for your AD or OD domain.
3. A properly configured and working Kerio MailServer installation on a supported version of Linux

Choose the appropriate setup for your network from the options below and follow the steps in numerical order:

Open Directory

Steps

1. Preparing Open Directory for Kerberos
   
2. Obtaining the Kerberos Realm and DNS Names in Open Directory
3. Configure the /etc/krb5.conf file
4. Calibrate the time
5. Edit the apple.map file (Open Directory)
6. Join KMS to the Open Directory Service
7. Troubleshooting
8. Linux Packages

Active Directory

Steps

1. Obtaining the Kerberos Realm and DNS Names in Active Directory
2. Configure the /etc/krb5.conf file
3. Calibrate the time
4. Join KMS to the Active Directory Service
5. Troubleshooting
6. Linux Packages

Individual Steps

Linux uses a technology called Kerberos for directory services security. Support for Kerberos in Open depends on your version of OS X.

Mac OS X 10.3.9 and Mac OS X 10.4.x

On these versions, Open Directory is configured for Kerberos by default. To verifiy that Kerberos is working, follow these steps:

1. On the Open Directory server run Server Admin
2. Under "Computers & Services" choose the Open Directory server
3. The "Overview" page should show "Kerberos is: Running"

If you do not see "Kerberos is: Running", it must be configured and started.

The following Apple documents explains how to configure and start Kerberos on a Mac OS X Server 10.4.x. Steps are similar for Mac OS X 10.3.9.

Starting Kerberos After Setting Up an Open Directory Master

Hint: See section, "Starting Kerberos After Setting Up an Open Directory Master"
Open Directory Manual for Mac OS X 10.4

Hint: See section, "Setting Up an Open Directory Master"
Open Directory Manual for Mac OS X 10.3

Mac OS X 10.2.x

Older versions of Mac OS X (versions 10.2 and older) can run Kerberos, but the configuration is more complicated. See the following Apple document:

Mac OS X 10.2: About Using Kerberos

Make sure Kerberos is running before proceeding with the steps in this article.

On the Active Directory master perform the following steps:

1. Open Programs-->Administrative Tools-->Active Directory Management
2. Choose "Active Directory Domains and Trusts."
3. The Active Directory domain names are listed.

The Active Directory domain name is also the coresponding Kerberos realm name and DNS domain name. Pick the domain you want to join the mailserver to. Always use the Kerberos realm name in upper case letters and the DNS domain name in lower case letters.

For more information about DNS, Kerberos, and domain names read Microsoft KB article Q248807:

Using Uppercase Letters for Kerberos Realm Names

The Kerberos realm name and DNS domain name will already be known if it was necessary to setup Open Directory for Kerberos as described above.

If Open Directory is already running Kerberos, then use the following process:

1. Open a terminal as an admin user
2. Enter the following command:
   sudo grep -A 2 domain_realm /Library/Preferences/edu.mit.Kerberos
   

   (Example)
   tiger:~ root# grep -A 2 domain_realm /Library/Preferences/edu.mit.Kerberos
   [domain_realm]
      .example.mac = TIGER.EXAMPLE.MAC
      example.mac = TIGER.EXAMPLE.MAC
   tiger:~ root#

   The DNS domain name is on the left of the equals symbol, and the Kerberos realm name is on the right.

Configure the /etc/krb5.conf File on Linux

The file on your Open Directory master called /Library/Preferences/edu.mit.Kerberos is a krb5.conf file. Copy that file from the Open Directory master to the Linux machine running KMS and use it as the /etc/krb5.conf file as follows:

(Example)
linux:~# cd /etc
linux:/etc# scp opendirectoryserver:/Library/Preferences/edu.mit.Kerberos ./krb5.conf

Replace "opendirectoryserver" with the hostname of your Open Directory server.

A much more detailed description of the /etc/krb5.conf file is available at the official Kerberos web site.

Kerberos: Configuration Files/krb5.conf

For Active Directory or Open Directory with a more complicated network (such as multiple Kerberos realms) it is necessary to configure the existing krb5.conf file or create one from scratch. Linux is distributed with a /etc/krb5.conf file that contains references to EXAMPLE.COM as follows:

A typical default /etc/krb5.conf file on Linux

[libdefaults]
default_realm = EXAMPLE.COM
dns_lookup_realm = false
dns_lookup_kdc = false
[realms]
EXAMPLE.COM = {
kdc = kerberos.example.com:88
admin_server = kerberos.example.com:749
default_domain = example.com
}
[domain_realm]
.example.com = EXAMPLE.COM
example.com = EXAMPLE.COM

Edit the file using the following guidelines:

• [libdefaults]
  1. Set default_realm to the Kerberos realm name for your network

  Example: for realm name KERIO.COM

  [libdefaults]
  default_realm = KERIO.COM
  dns_lookup_realm = false
  dns_lookup_kdc = false


• [realms] Each "realm" is listed as a realm name in upper case letters equals symbol and then a small section enclosed in curly braces as shown in the example above.
  1. Change the EXAMPLE.COM realm name to correct Kerberos realm name or if no example realm exists, copy the one from the example krb5.conf file shown above.
  2. Each realm contains "kdc" and "admin_server" values. Set those to the fully qualified DNS hostname of the Open Directory or Active Directory server.
  3. Set the default_domain to the DNS domain name bound to the realm.
  4. There can be multiple realms so Kerio MailServer can have multiple mail domains joined to different Kerberos realms.

  Example: for realm KERIO.COM, Open Directory master master.kerio.com, and DNS domain kerio.com

  [realms]
  KERIO.COM = {
  kdc = master.kerio.com:88
  admin_server = master.kerio.com:749
  default_domain = kerio.com
  }


• [default_realm] This section simply contains DNS domain name, equals symbol, then Kerberos realm name then another line identical except with a preceding dot as shown in the example above.
  1. Change each instance of EXAMPLE.COM to your Kerberos realm name in upper case letters.
  2. Change each instance of example.com to your DNS domain name that is bound to the coresponding Kerberos realm.
  3. There can be similar entries in this section for other domains and their respective realms so Kerio MailServer can have different mail domains joined to different Kerberos realms.

  Example: realm is KERIO.COM and DNS domain is kerio.com

  [default_realm]
  .kerio.com = KERIO.COM
  kerio.com = KERIO.COM

Calibrate the time

The clock on the Linux server and the clock on the AD or OD directory master server ('domain controller') must not be different by more than 5 minutes (300 seconds).

Note: There can be problems if the [libdefaults] section of the krb5.conf file contains an entry called "clockskew" and it is set to a very low value. The default for this value is 300. Calibrating the clocks without a working NTP network can be difficult if this value is set too low. If the domain controller and Kerio MailServer computers are not calibrated by NTP, then remove this value if it exists. If they are calibrated by NTP but you still cannot authenticate, try increasing this value.

For Open Directory, it is necessary to tell KMS not to use Apple Password Service for authentication.

1. On the KMS machine, open the file called /opt/kerio/mailserver/ldapmap/apple.map in a text editor.
2. Find an XML value called Auth_Type that is most likely set to "4" ("4" stands for Apple Password Service).
3. Change this value to "3" ("3" stands for Kerberos) but be careful to honor the XML formatting in this file. It should look exactly the same as before except the 4 has been changed to a 3.
4. Save the file and quit out of the text editor.

Example Auth_Type setting in apple.map

<variable>
<name>Auth_type</name>
<value>3</value>
</variable>

The following link to the Kerio MailServer manual describes how to join Kerio MailServer to a directory service in detail with illustrations:

Setting of Directory Services

Note: Be sure to check the domain search suffix. For a domain such as ad.example.com, the search suffix should be "dc=ad,dc=example,dc=com" but sometimes it will only show "dc=example,dc=com". This will prevent Active Directory authentication from working. Insure that it is correct for your domain name.

Be sure the DNS on the Linux mailserver is pointed to the DNS server provided by the Active Directory or Open Directory server. Many Kerberos issues are actually problems in DNS. The best policy is to always use the DNS provided by the directory service. Using 3rd party DNS is possible, but is not recommended and involves some configuration that is beyond the scope of this document. If it is not possible to use the correct DNS server, then be sure the correct DNS forwarding is configured so queries are still answered by the directory server machine.

For Kerberos problems in Open Directory that might be caused by DNS, visit the following article from Apple:

Kerberos is Stopped on an Open Directory Master or Replica

Essentially, the same steps provided in the Apple document apply to DNS on Active Directory as well.

If users still cannot authenticate to Kerio MailServer, yet there are no errors except password failures, then it is possible the keytab file is damaged. The keytab file is a special file used by Kerberos. The keytab file is more likely to get messed up in Open Directory than with Active Directory because Open Directory does not always depend on Kerberos whereas Active Directory depends on it for everything. The following document from Apple describes how to build a new keytab file.

Mac OS X Server 10.3 or later: Kerberos authentication may not work after changing to LDAP master or replica, or Kerberizing a particular service

The correct packages for using Kerberos are distributed with most modern linuxes. However, if for some reason they are somehow missing, try installing the following packages: pam_krb5-1.31-1, krb5-libs-1.2.2-4, krb5-workstation-1.2.2-4 (note, these versions will change over time).