Zimbra Single Sign On (Zm SSO)

Zm SSO is the Zimbra Collaboration Open Source Edition extension for single sign-on authentication to the Zimbra Web Client.
Copyright (C) 2020-present iWay Vietnam and/or its affiliates. All rights reserved.

• Using framework: pac4j is an easy and powerful security engine for Java to authenticate users, get their profiles and manage authorizations in order to secure web applications and web services.
• Supported authentication mechanisms: SAML - CAS - OpenID Connect

Building Java extension

Requirement

• JDK 11 or newer.
• Apache Maven 3.5 or newer for Maven build.
• Apache Ant 1.x for Ant build.
• rpm-build for rpm package build.

Setting up your build system

• On Fedora or CentOS 8.x or Red Hat EL 7.x

dnf -y install java-11-openjdk java-11-openjdk-devel maven ant git make rpmdevtools rpm-build

• On CentOS 7.x or Red Hat EL 7.x

yum -y install java-11-openjdk java-11-openjdk-devel maven ant git make rpmdevtools rpm-build

• On Debian or Ubuntu

apt install -y openjdk-11-jdk maven ant git make

Clone code from git repository

mkdir -p ~/projects/zimbra
cd ~/projects/zimbra
git clone https://github.com/iwayvietnam/zm-sso.git

Build jar file by using Maven

cd ~/projects/zimbra/zm-sso
mvn clean package

The output should be like this:

--- maven-jar-plugin:3.0.2:jar (default-jar) @ zm-hab ---
Building jar: ~/projects/zimbra/zm-sso/target/zm-sso-1.0.0-1.jar

Build jar file by using Ant

cd ~/projects/zimbra/zm-sso
ant jar

The output should be like this:

[jar] Building jar: ~/projects/zimbra/zm-sso/dist/zm-sso-1.0.0-1.jar

Build rpm package

cd ~/projects/zimbra/zm-sso
make rpmbuild

The output should be like this:

Wrote: ~/rpmbuild/RPMS/noarch/zm-sso-1.0.0-1.el7.noarch.rpm

Installation

Install jar extension

• Copy jar extension to zimbra server

cd ~/projects/zimbra/zm-sso
ssh [email protected] "mkdir -p /opt/zimbra/lib/ext/zm-sso"
scp target/*.jar [email protected]:/opt/zimbra/lib/ext/zm-sso
scp target/dependencies/*.jar [email protected]:/opt/zimbra/jetty_base/common/lib
scp conf/zm.sso.properties [email protected]:/opt/zimbra/conf

• Restart mailbox to load the extension.

ssh [email protected] "su - zimbra -c '/opt/zimbra/bin/zmmailboxdctl restart'"

Install rpm package

ssh [email protected] "mkdir -p /tmp/zimbra"
scp ~/rpmbuild/RPMS/noarch/zm-sso-1.0.0-1.el7.noarch.rpm [email protected]:/tmp/zimbra
ssh [email protected] "rpm -Uvh /tmp/zimbra/zm-sso-1.0.0-1.el7.noarch.rpm"

Configuration

The settings loaded from zm.sso.properties file. The location of this file is /opt/zimbra/conf/zm.sso.properties

Default client configuration

• Using a text editor to open zm.sso.properties in /opt/zimbra/conf. Ex: vi /opt/zimbra/conf/zm.sso.properties
• Specify default pac4j client by setting the value for the sso.defaultClient key. Ex: sso.defaultClient = SAML2Client

Callback endpoint configuration

To handle authentication, a callback endpoint is necessary to receive callback calls from the identity server and finish the login process.

Config:

• Using a text editor to open zm.sso.properties in /opt/zimbra/conf.
• Specify callback endpoint by setting the value for the sso.callbackUrl key. The path of endpoint can be:
  • /service/extension/sso/callback (using default client. specified in sso.defaultClient). Ex: sso.callbackUrl = https://mail.zimbra-server.com/service/extension/sso/callback
  • /service/extension/saml/callback (using SAML client). Ex: saml.callbackUrl = https://mail.zimbra-server.com/service/extension/saml/callback
  • /service/extension/cas/callback (using CAS client). Ex: cas.callbackUrl = https://mail.zimbra-server.com/service/extension/cas/callback
  • /service/extension/oidc/callback (using OpenID Connect client). Ex: oidc.callbackUrl = https://mail.zimbra-server.com/service/extension/oidc/callback
• Specify profile should be saved in session by setting the value for the sso.saveInSession key.
• Specify multi profiles are supported by setting the value for the sso.multiProfile key.
• Specify the session must be renewed by setting the value for the sso.renewSession key.

Logout endpoint configuration

To handle the logout, a logout endpoint is necessary to perform:

• The local logout by removing the pac4j profiles from the session.
• The central logout by calling the identity provider logout endpoint. This is the Single LogOut (SLO) process.

Config:

• Using a text editor to open zm.sso.properties in /opt/zimbra/conf.
• sso.localLogout: It indicates whether a local logout must be performed.
• sso.destroySession: It defines whether we must destroy the web session during the local logout.
• sso.centralLogout: It defines whether a central logout must be performed.
• sso.postLogoutURL: It defines whether logout return url from idp server back to zimbra. By default at the last step of SP initiated logout user will see a blank page.

Configuration with any SAML identity provider using the SAML v2.0 protocol.

First, if you don’t have one, you need to generate a keystore for all signature and encryption operations. Ex:

keytool -genkeypair -alias samlkey -keypass samlpasswd -keystore /opt/zimbra/conf/saml/keystore.jks -storepass samlpasswd -keyalg RSA -keysize 2048 -validity 3650

Config:

• Using a text editor to open zm.sso.properties in /opt/zimbra/conf.
• saml.keystorePath: It defines the keystore resource location. It is the value of the -keystore option for the keystore generation with prefix file:. Ex: saml.keystorePath = file:/opt/zimbra/conf/saml/keystore.jks
• saml.keystorePassword: It defines keystore password. It is the value of the -storepass option for the keystore generation.
• saml.privateKeyPassword: It defines key password. It is the value of the -keypass option for the keystore generation.
• saml.keystoreAlias: It defines keystore alias. It is the value of the -alias option for the keystore generation.
• saml.identityProviderMetadataPath: It defines the resource location should point to your IdP metadata. Ex: saml.identityProviderMetadataPath = https://samltest.id/saml/idp
• saml.serviceProviderEntityId: It defines the entity ID of your application (the Service Provider). Ex: saml.serviceProviderEntityId = https://mail.zimbra-server.com/service/extension/saml/metadata

Configuration to login with a CAS server.

• Using a text editor to open zm.sso.properties in /opt/zimbra/conf.
• cas.loginUrl: It defines the login URL of your CAS server. Ex: cas.loginUrl = https://cas.cas-server.com/cas/login
• cas.protocol: It defines the CAS protocol you want to use. Ex: cas.protocol = CAS20

Configuration to login using the OpenID Connect protocol v1.0.

• Using a text editor to open zm.sso.properties in /opt/zimbra/conf.
• oidc.discoveryUri: It defines the discovery URI for fetching OP metadata. Ex: oidc.discoveryUri = https://demo.c2id.com/.well-known/openid-configuration
• oidc.id: It defines the OpenID client identifier.
• oidc.secret: It defines the OpenID client secret.
• oidc.scope: It defines the OpenID client scope.

Replace login and logout urls

• Execute following commands with the Zimbra user for domain configuration:

# SSO login by using default client. Specified in sso.defaultClient
zmprov md yourdomain.com zimbraWebClientLoginURL https://mail.zimbra-server.com/service/extension/sso/login
# or SSO login by using SAML client
# zmprov md yourdomain.com zimbraWebClientLoginURL https://mail.zimbra-server.com/service/extension/saml/login
# or SSO login by using CAS client
# zmprov md yourdomain.com zimbraWebClientLoginURL https://mail.zimbra-server.com/service/extension/cas/login
# or SSO login by using OpenID Connect client
# zmprov md yourdomain.com zimbraWebClientLoginURL https://mail.zimbra-server.com/service/extension/oidc/login
# Specified logout URL
zmprov md yourdomain.com zimbraWebClientLogoutURL https://mail.zimbra-server.com/service/extension/sso/logout

• Execute following commands with the zimbra user for global configuration:

# SSO login by using default client. Specified in sso.defaultClient
zmprov mcf zimbraWebClientLoginURL https://mail.zimbra-server.com/service/extension/sso/login
# or SSO login by using SAML client
# zmprov mcf zimbraWebClientLoginURL https://mail.zimbra-server.com/service/extension/saml/login
# or SSO login by using CAS client
# zmprov mcf zimbraWebClientLoginURL https://mail.zimbra-server.com/service/extension/cas/login
# or SSO login by using OpenID Connect client
# zmprov mcf zimbraWebClientLoginURL https://mail.zimbra-server.com/service/extension/oidc/login
# Specified logout URL
zmprov mcf zimbraWebClientLogoutURL https://mail.zimbra-server.com/service/extension/sso/logout

• Execute the following command with the zimbra user to restart Zimbra server: zmcontrol restart

Import untrusted ssl certificate to the cacerts file

This is primarily for allowance of untrusted ssl certificates in external data sources.

• Export untrusted ssl certificate to the file:

openssl s_client -servername idp.server.net -connect idp.server.net:443 </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' >/path/to/cert.pem

• Execute following commands with the Zimbra user:

zmcertmgr addcacert /path/to/cert.pem
zmmailboxdctl restart

Add identity provider hostname to ignore CSRF referer check

zmprov -l mcf +zimbraCsrfAllowedRefererHosts idp.server.net
zmmailboxdctl restart

Tutorials

• Single sign on with WSO2 Identity Server (WSO2 IS)
• Single sign on with Keycloak
• Single sign on with Azure AD B2C
• Single sign on with Apereo Central Authentication Service (CAS)

Licensing

Zm SSO is licensed under the GNU AFFERO GENERAL PUBLIC LICENSE, Version 3. See LICENSE for the full license text.