Running Kerberos with Zimbra Collaboration Suite

Revision as of 02:12, 23 June 2008 by Cfremon (talk | contribs) (Removing WIP template from article, adding brief Introduction)

This guide includes instructions for running Kerberos with Zimbra Collaboration Suite.

Kerberos Installation and Configuration

Begin your integration of Zimbra and Kerberos by installing and configuring 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. You will need to follow the additional instructions in this Wiki article in order to run Kerberos with Zimbra Collaboration Suite.

Kerberos Configuration Files

Install the /etc/krb5.conf file on any client machines using Kerberos, including all of the Zimbra Mailbox servers.

IMAP Service Principal

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.

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.

Prepare a Domain for Kerberos5 Authentication

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

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.


Verified Against: ZCS 5.0.x Date Created: 5/12/2008
Article ID: https://wiki.zimbra.com/index.php?title=Running_Kerberos_with_Zimbra_Collaboration_Suite Date Modified: 2008-06-23



Try Zimbra

Try Zimbra Collaboration with a 60-day free trial.
Get it now »

Want to get involved?

You can contribute in the Community, Wiki, Code, or development of Zimlets.
Find out more. »

Looking for a Video?

Visit our YouTube channel to get the latest webinars, technology news, product overviews, and so much more.
Go to the YouTube channel »

Jump to: navigation, search