HowTos/Kerberos

Scalix Wiki -> How-Tos -> Kerberos

Introduction

Kerberos can be used as an authentication and network security system for Scalix in a number of areas:

• Single-Server Installations (including Scalix Community Edition and CE Raw)
  • External Authentication source for username/password authentication of Scalix users
  • Single Sign On for domain member PCs running Microsoft Windows and Outlook
  • IMAP authentication for Kerberos-capable clients
• Multi-Server Installations (in addition to the above)
  • Additional network communications security for distributed SAC configurations
  • Cross-Server trust relationships for SWA resource booking and delegate functionality

The Kerberos Key Distribution Center (KDC)

For all applications of Kerberos security described above, a Kerberos KDC must be setup. This will act as a central repository for authentication data or - in Kerberos-speak - as a "trusted 3rd party". In a multi-server environment, only one KDC needs to be set up.

In Scalix environments, two types of KDCs are commonly used:

• Linux-based KDC based on the MIT or Heimdal OpenSource Kerberos implementation. Note: If you have the choice, it is recommended to use the MIT implementation; MIT is the inventor of the Kerberos protocol, therefore MIT is the official "reference" implementation of the service. Heimdal was created as a European project, because MIT's software could previously not be used outside the US because of export restrictions around encryption technology involved. Most of these restrictions have been lifted, however.
• Windows-based KDC based on a Windows 2000 or 2003 Server domain controller. This is setup automatically when you configure Active Directory on your Windows server.

Each entity in Kerberos that has a identity on the network is referred to as a principal. Principals can represent users and services; each entity involved in authentication must have it's associated principal, for example if Mr. User wants to use a Scalix IMAP server, two principals are involved - one for Mr. User (a user principal) and one representing the Scalix IMAP server (a server principal).

Setting up a KDC

Setting up a Linux-based KDC

Scalix provides a script that automatically sets up a KDC on Scalix-supported Linux platforms. In a multi-server environment, you only need to set up a KDC on one server.

Prerequisites

• On Debian, the following DEBs must be installed as a prerequisite: krb5-kdc, krb5-config, krb5-user and libkrb53.
• On RedHat Enterprise Linux 4 (RHEL4) and RedHat Enterprise Linux 5 (RHEL5), the following RPMs must be installed as a prerequisite: krb5-libs, krb5-workstation and krb5-server.

Running the Scalix KDC creation script

You create the KDC using omkrbinstall. It can only be run on a system where no database currently exists. It creates default admin principals and adds them to the system "keytab" file /var/kerberos/krb5kdc/kadm5.keytab. It adds the admin principal to the system ACL file /var/kerberos/krb5kdc/kadm5.acl. It also adds realm and admin-host (KDC) information to the system configuration file /etc/krb5.conf and the KDC configuration file /var/kerberos/krb5kdc/kdc.conf.

omkrbinstall -r <realm> -s <admin server> -a <admin principal> -p <admin password>

where

• <realm> is the Kerberos Realm. This is a domain-type name that groups all Kerberos objects. In environments with multiple independent KDCs that might require trust relationships for cross-Realm authentication, the name must be unique within the whole environment. The name must be in all-uppercase and can contain dots ("."). Often, a DNS-domain style name is being used to guarantee uniqueness, e.g. KERBEROS.SCALIX.COM.
• <admin server> is your Kerberos KDC's fully-qualified domain name.
• <admin principal> is a user name for your initial Kerberos KDC admin account. By convention, this is usually of the form <name>/admin, where <name> is a personal identifier for the admin. Kerberos standards recommend against using shared or generic admin accounts. You can create further admin accounts later.
• <admin password> is the initial password for the admin principal.

For example, the following could be used to create a typical KDC on a Scalix server; the master key name (in bold) is what you should enter when prompted for the KDC database master key.

omkrbinstall -r TRAINING.SCALIX.DEMO -s server1.scalix.demo -a john/admin -p secret
Checking MIT Kerberos installation...done.
Loading random data
Initializing database '/var/kerberos/krb5kdc/principal' for realm 'TRAINING.SCALIX.DEMO',
master key name 'K/M@TRAINING.SCALIX.DEMO'
You will be prompted for the database Master Password.
It is important that you NOT FORGET this password.
Enter KDC database master key:
Re-enter KDC database master key to verify:
Success!  Kerberos database created, configured and started.

Setting up a Linux-based Kerberos slave

Scalix provides a script that automatically configures a Kerberos slave on Scalix-supported Linux platforms.

Prerequisites

• On Debian, the following DEBs must be installed as a prerequisite: tbd.
• On RedHat Enterprise Linux 4 (RHEL4) and RedHat Enterprise Linux 5 (RHEL5), the following RPMs must be installed as a prerequisite: krb5-libs and krb5-workstation.

Running the Scalix Kerberos slave configuration script

Configure the slave (non-KDC) servers with omkrbconf

omkrbconf -r realm -s admin-host [ -d domain-name ]

• <realm> is the realm that your Kerberos database controls.
• <admin-host> is the fully qualified host name of the Kerberos KDC machine.
• <domain-name> (optional) is the domain name in which the Kerberos Realm operates. If it is not explicitly defined, it will be deduced from the current domain.

omkrbconf -r TRAINING.SCALIX.DEMO -s server1.scalix.demo

Setting up a Windows-based KDC

This is automatically done as soon as you activate Active Directory on a Windows 2000 or 2003 server. No further steps are necessary.

Creating Kerberos Principals

From the viewpoint of the administrator, Kerberos principals are similar to user accounts. They have a principal name and a password (plus some policy attributes such as password expiration, etc.). They must be created within the KDC which acts as an account and authentication database.

Kerberos principal name conventions

In general, Kerberos principals have names of the form name@REALM. The name can be of arbitrary length and is allowed to contain some special characters, typically "/" or "-". In Linux-based KDCs, the name is treated in a case-sensitive manner; windows uses the login name as the Kerberos name - this is not case-sensitive.

The realm is the Kerberos "domain" as defined for a certain KDC; by definition, it is always all-uppercase and must be specified and written as such. In Windows, this is the AD domain name in all-uppercase, so if your Windows domain is scalix.local, your Kerberos realm as implemented by AD is SCALIX.LOCAL. In Linux Kerberos implementations, it is what you specified during the KDC creation.

Service principals typically have names in the form <service>/<fqdn>@REALM where service is a service designator, such as imap and fqdn is the fully-qualified domain name of the machine running the service. Some of these service names, such as the imap one, are defined in RFCs and are shared by many different implementations of the service. Others are defined by the application.

Scalix uses the following principal names for it's services (in alphabetical order):

service name	description
imap	The Scalix IMAP service
res	The Scalix administration agent
scalix-ual	The Scalix UAL service (used for Outlook and SSO)
ubermanager	The Scalix Admin Server

Thus, the principal name for the IMAP service on server server1.scalix.demo in the Kerberos realm TRAINING.SCALIX.DEMO would be imap/server1.scalix.demo@TRAINING.SCALIX.DEMO

Kerberos service principals and passwords

Like human users, Kerberos service principals will have a username and a password. However, they will need to have access to passwords in electronic form, because they cannot authenticate interactively. Therefore, passwords for service principals are stored in password database files known as keytabs. Password can be automatically assigned, however, normally a random password is generated during creation of the service principal and stored in both the KDC's internal password database and the keytab file. The keytab file must then be transferred to the machine on which the service is running. Then, the contents of the keytab file must either be merged into a system-wide keytab containing all the passwords for services running on this machine or the service in question offers you to specify a separate keytab file dedicated to it.

Creating Kerberos principals on Linux

On linux, the tool to create Kerberos principals is called kadmin. However, Scalix comes with a script that makes the creation of Scalix-specific easy. The tool is called omaddprincs and runs on RedHat and SuSE Linux. The syntax for the omaddprincs command is as follows:

omaddprincs -s <selector> -h <scalix-server-fqdn> -o <keytab-filename>

This command must be run on the machine hosting the KDC created with the omkrbinstall command as per above.

• <selector> is the type of principal to create. This can be one of imap, res, ual or um to select one of the Scalix-specific service principals listed above or all for all of them.
• <scalix-server-fqdn> is the fully qualified hostname of the machine running the services represented by the principals. This will be embedded in the principal name. Remeber, the principal name is of the form service/fqdn@REALM.
• <keytab-filename> is the output filename to which the randomly generated passwords for the principals created are written.

Creating Kerberos Principals in a Single-Server Environment

After creating a KDC with the omkrbinstall command, create the Scalix Kerberos service principals in the Kerberos databse with omaddprincs.

omaddprincs -s ual -h server1.scalix.demo -o /tmp/keytab.ual

Merge the new keytab into the Kerberos system keytab file.

ommergekeys /tmp/keytab.ual

Creating Kerberos Principals in a Multi-Server Environment

On the KDC server, create the principals and put them into a temporary file. Note that the -h specifies the host where the service is running; in this case it is the slave host(s).

omaddprincs -s ual -h server2.scalix.demo -o /tmp/keytab.ual

Copy the keytab file to the slave host for which it was generated, and add it to the keytab file with ommergekeys.

ommergekeys key-tab

• <key-tab> is a list of one or more keytab files whose contents you want to add to the system keytab file.

ommergekeys /tmp/keytab.ual

Creating Kerberos principals on Windows

t.b.d.

Appendix: Configuring Kerberos for SWA Cross-Server Delegate Functionality

• Configure one server to be the KDC using krbinstall as described earlier in this document.
• Configure the other servers to be slaves using omkrbconf as described earlier in this document.
• On the KDC server, create server principals for IMAP and UAL services for each of the servers in the environment. Do this with the omaddprincs command as described previously.
• Copy the keytab files created with the omaddprincs command to the appropriate slave servers and merge them into that server's keytab with the ommergekeys command.
• On each server, create a file called /var/opt/scalix/??/s/sys/trust which is world readable. In the trust file put a line for each of the other servers in the environment. For example, in a three server environment, the trust file on server2 would be:

imap/server1.scalix.demo@TRAINING.SCALIX.DEMO ASUSER
imap/server3.scalix.demo@TRAINING.SCALIX.DEMO ASUSER