Configuring Exchange ActiveSync with Autodiscover on Zimbra

After suffering some days to get ActiveSync working on Zimbra I decided to write this story on how to configure it.

Thanks to imanudin11 for providing the steps, I just updated them and tested Autodiscover with that.

To get ActiveSync and Autodiscovery to work on Postfix-Based servers we need to use Z-Push.

Z-Push is the open-source implementation of ActiveSync Protocol, it provides the ability to use ActiveSync on Postfix servers and thus gaining the great benefits of synchronizing email, contacts, calendars and tasks between all ActiveSync capable devices.

I’m using the current latest versions in this guide:

• Zimbra 8.8.15 GA Release Patch 5
• Z-Push 2.5.1
• Z-Push Zimbra Backend Release 68

In this guide, I’m using Ubuntu 18.04.3 LTS but it should also work on CentOs 7 and Ubuntu 16.04.

Prerequisites:

• Zimbra 8.8.6 or newer.
• Ubuntu 18.04/16.04 or CentOs 7.
• Using the included Zimbra-Proxy instead of an external proxy.

First, Installing the Dependencies:

On Ubuntu 18.04 and 16.04:

apt update
apt install git php-cli php-soap php-cgi php-mbstring php-curl php-xml -y

On CentOs 7:

yum install epel-release
yum install git php-cli php-soap php-process php-mbstring php-xml -y

Download and Configure Z-Push and Z-Push Zimbra Backend

I will be using git to clone the repo of Z-Push, this gives us more control of the currently used version of Z-Push as opposed to using the package manager.

Download the source code of Z-Push from git to /opt/z-push directory:

git clone https://stash.z-hub.io/scm/zp/z-push.git /opt/z-push

Switch to master branch to use the latest stable releases of z-push:

git checkout master

Create the needed directories for Z-Push logs and libs and grant permissions to zimbra user:

mkdir /var/lib/z-push /var/log/z-push
chmod 755 /var/lib/z-push /var/log/z-push
chown zimbra:zimbra /var/lib/z-push /var/log/z-push

Now we need to make a .gitignore file to untrack the directories and files that we will be adding to Z-Push, sadly Z-Push doesn’t provide .gitignore file in the root directory of the repo so we need to create that and exclude it from tracking:

echo "src/WEB-INF/
src/backend/zimbra/" >> /opt/z-push/.gitignore

Exclude it from tracking to ensure a clean repo for future updates (git pull)

echo -e “.gitignore\n” >> /opt/z-push/.git/info/exclude

Download Z-Push Zimbra Backend:

I’m using the current latest release 68, you can check their Sourceforge repo for newer version:

wget https://netcologne.dl.sourceforge.net/project/zimbrabackend/Release68/zimbra68.tgz
mkdir -p /opt/z-push/src/backend/zimbra && tar -xvf zimbra68.tgz — strip-components 1 -C /opt/z-push/src/backend/zimbra && rm zimbra68.tgz

Configure Z-Push:

First we need to configure Z-Push itself, edit the file /opt/z-push/src/config.php with your favorite editor.

at the line 30 we need to specify our timezone:

define(‘TIMEZONE’, ‘Europe/Berlin’);

at the line 279, specify which Backend to use, in our case BackendZimbra:

define(‘BACKEND_PROVIDER’, ‘BackendZimbra’);

Adding Z-Push PHP Conf file to PHP Confs:

On CentOs 7:

wget -O /etc/php.d/zpush.ini https://raw.githubusercontent.com/DonMcCoy/zpushOnZimbra/master/zpush.ini

On Ubuntu 16.04:

wget -O  /etc/php/7.0/cgi/conf.d/10-zpush.ini https://raw.githubusercontent.com/DonMcCoy/zpushOnZimbra/master/zpush.ini

On Ubuntu 18.04:

wget -O  /etc/php/7.2/cgi/conf.d/10-zpush.ini https://raw.githubusercontent.com/DonMcCoy/zpushOnZimbra/master/zpush.ini

Configure Z-Push Zimbra Backend:

edit the following file with your favorite editor:

/opt/z-push/src/backend/zimbra/config.php

Here we need to specify the Zimbra_URL:

define(‘ZIMBRA_URL’, ‘https://mail.domain.tld');

Note: the value of ZIMBRA_URL should be the same value of the domain Public hostname you set during domain creation in Zimbra (Zimbra Administration -> Configure -> Domains (select the domain) -> Public service host name).

in case you have domain1.com on Zimbra server mail.domain1.com the value is recommended to set to mail.domain1.com with https.

in case you have domain1.com and domain2.com, here there are multiple possible scenarios:

1. if the domains have each their own virtual host e.g. mail.domain1.com and mail.domain2.com on a single Zimbra server, you should have the Public host name of each domain to their virtual host.

The only problem here is which domain to use for ZIMBRA_URL, the good thing is you can use any of them and Z-Push Zimbra Backend will overwrite that to the correct one when a user from different virtual host try to login.

Of course the users from different virtual hosts as the ZIMBRA_URL need to authenticate with their full email address

The only drawback of this is having the Z-Push logs full with warnings, and thus I’m currenly doing mostly the second scenario.

2. if the both domains use mail.domain1.com you can then set the ZIMBRA_URL to mail.domain1.com and get rid of warnings.

Configuring Z-Push Autodiscover:

edit the following file with your favorite editor:

/opt/z-push/src/autodiscover/config.php

the same as Z-Push the only lines that we need to change are:

define(‘TIMEZONE’, ‘Europe/Berlin’);
define('BACKEND_PROVIDER', 'BackendZimbra');

Note: In case you have Z-Push running on different server than Zimbra, you will need to specify ZPUSH_HOST to point to your Zimbra server:

define(‘ZPUSH_HOST’, ‘mail.domain1.com’);

This is used by Z-Push to build the ActiveSync URL for the response XML like the following:

https://mail.domain1.com/Microsoft-Server-ActiveSync

Adding the needed DNS Records:

Autodiscover has many phases in which it searches for possible server configudations.

One of those is trying to search the autodiscover.domain1.com for configurations:

https://autodiscover.domain1.com/autodiscover/autodiscover.xml

if this fails it will then try to query the DNS for possible SRV records, this is the method I’m currenly using as it won’t require me to have a SSL Certificate for everything autodiscover.domain1.com, the needed SRV record is:

_autodiscover._tcp.domain1.com SRV 443 mail.domain1.com

If you are using Cloudflare as your nameserver, the record should look like that:

Configuring Jetty

Create a Symlink from Z-Push source to Jetty Webapps:

ln -s /opt/z-push/src /opt/zimbra/jetty_base/webapps/z-push

Create a WEB-INF Directory and web.xml descriptor:

This file is needed to describe to Jetty how to handle the PHP files.

mkdir /opt/z-push/src/WEB-INF && wget -O /opt/z-push/src/WEB-INF/web.xml https://raw.githubusercontent.com/DonMcCoy/zpushOnZimbra/master/WEB-INF/web.xml

Next we need a CGI helper file so Jetty can execute PHP files via CGI:

wget -O /usr/bin/php-cgi-fix.sh https://raw.githubusercontent.com/DonMcCoy/zpushOnZimbra/master/php-cgi-fix.sh

Grant it exec perms:

chmod +x /usr/bin/php-cgi-fix.sh

Now we need to tell Jetty to use Z-Push when https://mail.domain.com/Microsoft-Server-ActiveSync is being requested instead of its native EAS.

Backup the current jetty.xml.in and replace it with the modified one:

mv /opt/zimbra/jetty/etc/jetty.xml.in /opt/zimbra/jetty/etc/jetty.xml.in.backup

On Zimbra 8.8.15:

wget -O /opt/zimbra/jetty/etc/jetty.xml.in https://raw.githubusercontent.com/DonMcCoy/zpushOnZimbra/master/jetty.xml.in-for-zcs-8815

On Zimbra 8.8.8 and 8.8.12

wget -O /opt/zimbra/jetty/etc/jetty.xml.in https://raw.githubusercontent.com/DonMcCoy/zpushOnZimbra/master/jetty.xml.in-for-zcs-888-8812

On Zimbra 8.8.7

wget -O /opt/zimbra/jetty/etc/jetty.xml.in https://raw.githubusercontent.com/DonMcCoy/zpushOnZimbra/master/jetty.xml.in-for-zcs-887

On Zimbra 8.8.6

wget -O /opt/zimbra/jetty/etc/jetty.xml.in https://raw.githubusercontent.com/DonMcCoy/zpushOnZimbra/master/jetty.xml.in-for-zcs-886

Regrant permissions to Zimbra user:

chown zimbra.zimbra /opt/zimbra/jetty/etc/jetty.xml.in

Now we have everything installed and configured we need to restart Zimbra Mailbox Service to apply the changes:

su — zimbra -c ‘zmmailboxdctl restart’

Testing Exchange ActiveSync

By visting your ActiveSync URL on your Zimbra server like:

https://mail.domain1.com/Microsoft-Server-ActiveSync

If everything is fine you would be prompted to login, login with one of your accounts, if you get to Z-Push page, like the following:

This should indicate that Z-Push is successfully installed.

Testing Autodiscover

Using Testconnectivity tool from Microsoft we can check if Autodiscover is working as intended, choose the ActiveSync Autodiscover test:

Enter any of your accounts, like the follwing:

If Autodiscover is working and responsed with a valid XML, you should see the final test step successful like that:

Note: that you can also use Testconnectivity to better test and ensure that ActiveSync is working.