Running Kerberos with Zimbra Collaboration Suite: Difference between revisions

m (Add some detailed steps needing attention)
Line 37: Line 37:
  Entry for principal imap/macpro.local@MACPRO.LOCAL with kvno 3, encryption type DES cbc mode with CRC-32 added to 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.
   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=
=Preparing Zimbra for Kerberos Authentication=

Revision as of 07:22, 3 November 2010

Admin Article

Article Information

This article applies to the following ZCS versions.

ZCS 5.0 Article ZCS 5.0

This guide contains instructions for installing, configuring, running, and troubleshooting 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. And make sure each KDC server is turned on.

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.

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.

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

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.


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: 2010-11-03



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