Running Kerberos with Zimbra Collaboration Suite
Article Information |
---|
This article applies to the following ZCS versions. |
This guide contains instructions for installing, configuring, running, and troubleshooting Kerberos with Zimbra Collaboration Suite. The concepts and descriptions might be not precise, just for general understanding of the mechanisms, steps and usages. For a more detailed reference of Kerberos, consult MIT's Kerberos V5 Admin Guide.
Introduction
General Knowledge of Kerberos Authentication
You may try to authenticate yourself into some service server via simply username/password login or other similar manner such as PLAIN or CRAM-MD5. In these cases you prove to the service server your identity. The server confirms this and authorize you with the requested services. However, in Kerberos protocol, a trusted third party is introduced, which generates "tickets", which hold credentials to both the user and service server. After gaining the credentials, both the user and service server can prove he is who he claims to be. Then they exchange some messages and finish the mutual authentication. This is the general steps of Kerberos authentication protocol.
In implementation, the trusted third party is the KDC (Kerberos Distribution Center) server. It holds a database (comprised of several regular files) of principals and keys.In the Kerberos world, everyone, including users, services, hosts, etc, has a principle associated with it. Principals should be global unique. Each principal has several components, which can be a username, service name, host name or realm. For example, imap/example.com@EXAMPLE.COM is a valid principal, in which "imap" is the service name, "exmaple.com" is the host name who provides this service, and "EXAMPLE.COM" is the realm. Principal is case sensitive. Traditionally, realm is a capitalized domain name like string. Meanwhile, each principal is associated with a key.
A key is a string generated by the password. You can get a ticket contain a principal by giving that password. Also, you can write the keys into the keytabfiles and authenticate with them. A keytab file can contain multiple principals' keys with various encryption types. For example, if you have M principals and N encryption types, you may have M*N entries in a keytab file. Therefore you can consider keytab files and password equivalent. However, it's rather noteworthy that if a key is written into keytabfile, the password is no longer effective.
After authenticating to KDC, the corresponding credential is retrieved and cached locally. In MIT Kerberos implementation, it's cached in a regular file called /tmp/krb5cc_<uid>.Other implementations may cache it in the memory. Each credential has an expired time, commonly several hours or 1 day. Before that you can get it from cache without sending request to KDC. Note the UNIX user you used to get and use the credential. If you get it by root (e.g. sudo), and then use it with a normal user with uid 1000, it will fail because the credential you want to use is in krb5cc_0 rather than krb5cc_1000.
KDC reads the configure file "kdc.conf" to setup itself. This config tells which ports to listen, where the database files located, what encryption types should be supported and so on. KDC also reads "krb5.conf" to decide what the default realm is, how to write logs, ... The client and service server are all clients of KDC. They need to read krb5.conf to decide what the default realm is and where KDC is (address and port). Here you can set KDC for each realm. krb5.conf used by Kerberos server and client are often same.So you can config a valid krb5.conf and copy it to everywhere.
Kerberos Executives
Here are the executives of Kerberos implementation.
Name | Description |
---|---|
krb5kdc | KDC server. Default listen on 88, 750 ports |
kadmin.local | Manage principal database by directly manipulate database files. Only work in the machine where those files locate. |
kadmin | Remotely manage principal database, require kadmind. |
kadmind | Kerberos managment server. Default listen on 749 port. |
kdb5_util | Kerberos database maintainance utility. Can create, destroy, load a database. |
kinit | Authenticate to KDC, get the credential. |
klist | Show the entries in the credential cache or keytab files |
There are some other executives for advanced functions, not necessary to introduce here.
Configuration Overview
The picture in the right shows the overview of ZCS with Kerberos authentication support. There are 3 hosts in logic. "kerberos.example.com" holds KDC server, principal database and configs; "client.example.com" holds the client applications which initiates the authentication; "zcs.example.com" runs ZCS servers. Although they are in logic 3 separated hosts, you can choose to install all of them in the same host like what most developers do.In the rest of this article, I'll use these host names to illustrate the examples.
Install Kerberos
MIT Kerberos
Download Kerberos from Massachusetts Institute of Technology (MIT) at http://web.mit.edu/Kerberos/. Install Kerberos, following the instructions provided in MIT's Kerberos V5 Installation Guide. Normally you just run the command "./configure && make && make install". The build process might report some missing dependency such as "bison (yacc)". The Kerberos executive will be generated in /usr/local/bin and /usr/local/sbin. The most important one is /usr/local/sbin/krb5kdc. It's the KDC server.
After that, you need to copy sample krb5.conf and kdc.conf from <krb-source-root>/src/config-files by yourself. Copy krb5.conf to /etc/krb5.conf; then copy kdc.conf to /usr/local/var/krb5kdc/kdc.conf. /usr/local/var/krb5kdc is also the default location of principal database files.
MIT Kerberos Packages from Ubuntu
If using Ubuntu, you can choose to apt-get install the following packages: krb5-admin-server, krb5-kdc, krb5-config, krb5-user, krb5-clients. For Kerberos clients, no need to install admin server and KDC. In this way, the default location of kdc.conf is /etc/krb5kdc; the default location of principal database files is /var/lib/krb5kdc. Meanwhile, the KDC executive name is /etc/init.d/krb5-kdc.
Heimdal
TODO
Other Related Packages
If KDC and Kerberos clients are planed to run in different hosts, it's necessary to install NTP (Network Time Protocol) packages to make time synchronized. Kerberos protocol requires that time synchronization to improve security and convenience. But if all are going to be installed in the same host, no need to do this.
If want to do some test, you can install gsasl (GNU SASL). It contains APIs and sample client/server to use Kerberos authentication.
Configuration
Prepare Valid Host Name
Configure Kerberos
Install the /etc/krb5.conf file on any client machines using Kerberos, including all of the Zimbra Mailbox servers. And make sure each KDC server is turned on.
Add Principals
Creating a Service Principal for Zimbra IMAP Services
For each server, create a service principal for the Zimbra IMAP service. This should be of the form imap/<host>@<realm> where <host> is the fully qualified host name of the Zimbra server and <realm> is the Kerberos realm name. The server host name must match the value of the zimbra_server_hostname local configuration property.
For example:
macpro:/usr/local_schemers$ /usr/local/sbin/kadmin.local Authenticating as principal schemers/admin@MACPRO.LOCAL kadmin.local: addprinc -randkey imap/macpro.local@MACPRO.LOCAL WARNING: no policy specified for imap/macpro.local@MACPRO.LOCAL; defaulting to no policy Principal "imap/macpro.local@MACPRO.LOCAL" created.
Creating a Local Keytab for the Service Principal
For each server, a keytab file must be created with the service principal key. This file should be located in $ZIMBRA_ROOT/conf/krb5.keytab where ZIMBRA_ROOT is the Zimbra installation directory (i.e. /opt/zimbra).
For example:
macpro:/usr/local schemers$ /usr/local/sbin/kadmin.local Authenticating as principal schemers/admin@MACPRO.LOCAL with password. kadmin: ktadd -keytab /opt/zimbra/conf/krb5.keytab imap/macpro.local@MACPRO.LOCAL Entry for principal imap/macpro.local@MACPRO.LOCAL with kvno 3, encryption type Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/opt/zimbra/conf/krb5.keytab. Entry for principal imap/macpro.local@MACPRO.LOCAL with kvno 3, encryption type DES cbc mode with CRC-32 added to keytab WRFILE:/opt/zimbra/conf/krb5.
Now you can test this by:
macpro:/usr/local schemers$ /usr/local/sbin/kinit -k -t /opt/zimbra/conf/krb5.keytab imap/macpro.local@MACPRO.LOCAL
No results indicate a successful login to KDC. Otherwise, see the reported error message and judge what's wrong.
Preparing Zimbra for Kerberos Authentication
When you have installed and configured Kerberos, you must prepare a domain for Kerberos5 Authentication and then provision Zimbra accounts.
Configure ZCS
1. Set domain authentication mechanism to kerberos5
zmprov md example.com zimbraAuthMech kerberos5
2. Set domain zimbraAuthKerberos5Realm to the kerberos5 realm in which users in this Zimbra domain are created in the Kerberos database.
zmprov md example.com zimbraAuthKerberos5Realm EXAMPLE.COM
Provision Zimbra Accounts
When a user attempts to login to Zimbra as user/password, and when the domain's zimbraAuthMech is kerberos5, the system will authenticate to a Kerberos Key Distribution Center (KDC) instead of LDAP.
The Kerberos credential for the user is:
- Password. This is the user's password.
- Principal. The Kerberos principal for a user can be resolved by either of the following methods.
Principal Resolution Method 1
One method of resolving a user's Kerberos principal is to enter the user's address in the form of <local part of Zimbra email address>@<zimbraAuthKerberos5Realm>.
For example, for user1@example.com, the Kerberos principal will be user1@EXAMPLE.COM.
Principal Resolution Method 2
Kerberos principal can also be resolved on a per account basis, instead of using the realm defined in zimbraAuthKerberos5Realm. This allows accounts in the same Zimbra domain to be mapped to different Kerberos Realms.
To use this method, set the account's zimbraForiegnPrincipal as kerberos5:<kerberos5-principal>. If the zimbraForeignPrincipal of the account starts with kerberos5:, the system will authenticate to Kerberos using as the principal the text appearing after the kerberos5: in the zimbraForeignPrincipal.
For example:
zmprov ma user2@example.com +zimbraForeignPrincipal kerberos5:example@KERBEROSREALM.COM
In the above example, for user2@example.com, the Kerberos principal will be example@KERBEROSREALM.COM.
Note: Method 2 will overwrite Method 1. If the account has a zimbraForeignPrincipal in the form of kerberos5:<kerberos5-principal>, the system will resolve the Kerberos principal using Method 2.
Troubleshooting
KDC has no support for encryption type (14) - BAD_ENCRYPTION_TYPE
This note applies to versions of ZCS at least up to and including 5.0.18.
In some environments Kerberos-authenticated users may be unable to log in, or only some users may be able to log in. This is due to a bug in the version of Java included with ZCS. ZCS uses the Sun Java Runtime Environment version 5, which is unable to process credential caches with encryption types it doesn't understand. This will result in errors in /opt/zimbra/log/audit.log like:
Security - cmd=Auth; account=account name; protocol=soap; error=authentication failed for name(kerberos5 principal: principal), KDC has no support for encryption type (14) - BAD_ENCRYPTION_TYPE;
Recent (roughly post-2005) MIT Kerberos principals include enctypes not understood by the Java 5 runtime. To successfully authenticate, uncomment the following lines at the top of your /etc/krb5.conf:
default_tgs_enctypes = des3-hmac-sha1 default_tkt_enctypes = des3-hmac-sha1 permitted_enctypes = des3-hmac-sha1
Encryption type not in permitted_enctypes list
If the keytabs generated by KDCs are built with enctype AES256-CTS, which is not supported in the Java 6 shipped by Zimbra, you will see an error in /opt/zimbra/log/mailbox.log that looks like the following:
javax.security.sasl.SaslException: GSS initiate failed [Caused by GSSException:Failure unspecified at GSS-API level (Mechanism level: AES256 CTS mode with HMAC SHA1- 96 encryption type not in permitted_enctypes list)]
In order to use keytabs that are built with enctype AES256-CTS, you must download Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 6 from Sun Microsystems' Java SE Downloads page, and install JCE on your Zimbra servers.