HOWTO CASify Zimbra 4.5 and 5.0

Zimbra is web suite for email, calendaring, and document collaboration. This guide makes it possible to use both the built-in authentication of Zimbra, and also provide a custom URL that allows access to Zimbra using your site's CAS implementation.

1. Configure SSL

The first requirement is that your Zimbra server's java keystore contain the appropriate SSL certificates for you CAS server. If you are using an SSL certificate on your CAS server that requires a "chaining certificate," such as ipsCA, you'll need to import the CA, the chain cert, and finally the cert for you CAS server.

Import your CAS certificate into the Zimbra cacerts

/opt/zimbra/java/bin/keytool -import -file yourfile.cer -alias cas -trustcacerts -keystore /opt/zimbra/java/jre/lib/security/cacerts

When using ipsCA, I used ipsCA's guide for Tomcat to get the certs root_der.cer, chain_der.cer, mycasserver.example.com.cer on my CAS server, which I then copied to my Zimbra server securely, and installed with the following command:

/opt/zimbra/java/bin/keytool -import -trustcacerts -keystore /opt/zimbra/java/jre/lib/security/cacerts -alias root -file root_der.cer
/opt/zimbra/java/bin/keytool -import -trustcacerts -keystore /opt/zimbra/java/jre/lib/security/cacerts -alias chain -file chain_der.cer
/opt/zimbra/java/bin/keytool -import -trustcacerts -keystore /opt/zimbra/java/jre/lib/security/cacerts -alias cas -file mycasserver.example.com.cer

2. Add jar files

You need to provide the necessary java libraries to your Zimbra server so it can use CAS. These can be downloaded from http://www.ibiblio.org/maven/cas/jars/. A version known to work with CAS 3.0 and Zimbra 4.5 is casclient-2.1.1.jar.

Copy the casclient.jar into /opt/zimbra/tomcat/common/lib

3. Modify web.xml

Add the following lines to /opt/zimbra/tomcat/conf/zimbra.web.xml.in (or /opt/zimbra/jetty/etc/zimbra.web.xml.in for Zimbra 5.0), substituting the appropriate server names, ports and URLs as necessary for your setup. For Zimbra 4.5 this is about line 108 (or line 158 for Zimbra 5.0), just after all the other <filter> and <filter-mapping> sections but before the first <servlet> section:

<filter>
   <filter-name>CAS Filter</filter-name>
   <filter-class>edu.yale.its.tp.cas.client.filter.CASFilter</filter-class>

   <init-param>
      <param-name>edu.yale.its.tp.cas.client.filter.loginUrl</param-name>
      <param-value>https://casserver.example.com:8443/cas/login</param-value>
   </init-param>
   <init-param>
      <param-name>edu.yale.its.tp.cas.client.filter.validateUrl</param-name>
      <param-value>https://casserver.example.com:8443/cas/proxyValidate</param-value>
   </init-param>
   <init-param>
      <param-name>edu.yale.its.tp.cas.client.filter.serverName</param-name>
      <param-value>zimbraserver.example.com:80</param-value>
   </init-param>
</filter>

<filter-mapping>
   <filter-name>CAS Filter</filter-name>
   <url-pattern>/*</url-pattern>
</filter-mapping>

4. Run zmprov

zmprov gdpak yourmail.domain

This will create a preAuthKey: 359d722926fc3daebd0fee5d8b9dad9bbe1646e68041afa8ab662c6a9152e6b9

5. Configure preauth.jsp

Now you need to provide a new JSP page to Zimbra that authenticates your users using CAS instead of the built-in Zimbra auth.

Copy preauth.jsp (an attachment to this wiki page) to: /opt/zimbra/tomcat/webapps/zimbra for Zimbra 4.5, or /opt/zimbra/jetty/webapps/zimbra for Zimbra 5.0

Replace the DOMAIN_KEY with the key you generated with zmprov in step 4.

public static final String DOMAIN_KEY = "359d722926fc3daebd0fee5d8b9dad9bbe1646e68041afa8ab662c6a9152e6b9";

Add/Modify the following lines in the JSP page (around line 111), substituting in your zimbra server hostname for "yourdomain":

<%
            String user = (String)request.getSession().getAttribute("edu.yale.its.tp.cas.client.filter.user");
            String redirect = generateRedirect(request, user + "@yourdomain");
            response.sendRedirect(redirect);
%>

6. Restart Zimbra

Zimbra needs to be restarted to recognize the new jars and config files:

zmcontrol stop
zmcontrol start

I've found that it is necessary to restart the zimbra service as the root user to be sure everything comes up and uses the right ports.

/etc/init.d/zimbra restart

7. Test

Now, you should be able to point customers at the JSP preauth page you installed on the server and this will redirect to your CAS server for authentication, after which you will gain access to the Zimbra web software. An example URL would be (again, insert the hostname of your zimbra server):

http://zimbraserver.example.com/zimbra/preauth.jsp

Central Authentication Service

CASifying Zimbra 4.5 and 5.0