Updated SAML for Zimbra – Now Supports Single Log Out (updated January 2023)

Hello Zimbra Partners, Customers & Friends,

Did you know that Zimbra support SAML single sign on? SAML is an open standard that allows you to have a single login page for all applications in your organization. SAML is a Zimbra Network Edition feature. Once you have set-up your SAML portal, you can easily add Multi Factor Authentication.

This isn’t brand-new news, but we’ve updated our SAML implementation to support Single Log Out. This was a request from Zimbra Partners to enhance account security.

Set up Zimbra SP in SimpleSAMLphp

In SAML, applications are called Service Providers or SPs. The service that provides your user database and takes care of your authentication in SAML is called an Identity Provider or IDP. Usually you only have one IDP and as many SPs as you have applications.

In this example, we’ll set up Zimbra as a SAML SP and use SimpleSAMLphp as the IDP.

SAML is an open standard for Single Sign-On. When using SAML an Identity Provider (IdP) will take care of user authentication after which users can use their applications without having to log-on to each of them separately. In SAML these applications are called Service Providers (SP). In this guide we will set-up SimpleSAMLphp to act as SAML IdP. And we configure the IdP to use Zimbra’s LDAP to validate the users. This way we add full SAML capabilities to Zimbra.

Setting up SimpleSAMLphp

SimpleSAMLphp needs to be installed on a server with Apache and PHP. You can follow the install guide to set it up.

These settings have become mandatory since 2020 as of Google Chrome version 80.

'session.cookie.secure' => true,
'session.cookie.samesite' => 'None',

Setting up Zimbra as the authentication source for SimpleSAMLphp

You have to make sure SimpleSAMLphp can access port 389 on the Zimbra server. Also it is highly recommended to use valid SSL certificates. To set up Zimbra as the authentication source you have to append it to /var/simplesamlphp/config/authsources.php like this:

<?php
// Default location: /var/simplesamlphp/config/authsources.php
$config = [
...
'zimbra9' => array(
    'ldap:LDAP',
    'hostname' => 'zimbra9.example.com',
    'enable_tls' => TRUE,
    'dnpattern' => 'uid=%username%,ou=people,dc=zimbra9,dc=example,dc=com',
),
...

Then you have to enable the zimbra9 authentication source in the IdP by adding 'auth' ⇒ 'zimbra9', to /var/simplesamlphp/metadata/saml20-idp-hosted.php like this:

<?php
// Default location: /var/simplesamlphp/metadata/saml20-idp-hosted.php
$metadata['__DYNAMIC:1__'] = [
...
'auth' => 'zimbra9',
...

Once that is set-up you can test the authentication via the SimpleSAMLphp WebUI replace saml.example.com with your installation domain https://saml.example.com/simplesaml/module.php/core/authenticate.php?as=zimbra9 and enter a valid username and password from your Zimbra server LDAP.

If it succeeds it will show some LDAP meta data, and all is well. If it says authentication failed, perhaps your LDAP cannot be reached or you may need a different DN. Check the logs to find clues by using tail -f /var/log/messages on your SAML server.

Set up Zimbra SP in SimpleSAMLphp

In SAML terms applications are called Service Providers or SP’s. The service that provides your user database and takes care of your authentication is in SAML terms called Identity Provider or IDP. Usually you only have one IDP and as many SP’s as you have applications. In this example we will set-up Zimbra as a SAML SP and use SimpleSAMLphp as IDP. This is the configuration needed on SimpleSAMLphp (in /etc/simplesamlphp/metadata/saml20-sp-remote.php):

     $metadata['https://zimbra9.example.com/service/extension/samlreceiver'] = array(
         'simplesaml.attributes'     => true,
            'debug' => TRUE,
             'AssertionConsumerService' => 'https://zimbra9.example.com/service/extension/samlreceiver',
             'SingleLogoutService' => 'https://zimbra9.example.com/service/extension/samlslo',
             'NameIDFormat' => 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress',
             'authproc' => array (
                     10 => array(
             'class' => 'saml:AttributeNameID',
             'attribute' => 'emailAddress',
             'Format' => 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress',
              ),
          )
     );

You will also need to get the X.509 public certificate that is used for signing the SAML request from th IDP to Zimbra. You will need to download it and save it on
your Zimbra server. This guide will assume you store your cert in /tmp/idpcert.pem, don’t forget to chown zimbra:zimbra /tmp/idpcert.pem. If you followed the SimpleSAMLphp setup guide you can find the certificate at /etc/simplesamlphp/cert/server.crt.

Set up Zimbra

Add the file /opt/zimbra/conf/saml/saml-config.properties to configure SAML in Zimbra add the contents:

     # Issuer
     saml_sp_entity_id=https://zimbra9.example.com/service/extension/samlreceiver
     # Login receiver for the service provider
     saml_acs=https://zimbra9.example.com/service/extension/samlreceiver
     # Name ID format for the IDP to use in the SAMLResponse
     saml_name_id_format=urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
     # Date format for issue instant
     saml_date_format_instant=yyyy-MM-dd'T'HH:mm:ss'Z'
     # Identity provider login endpoint for redirect method
     saml_redirect_login_destination=https://saml.example.com/simplesaml/saml2/idp/SSOService.php?spentityid=https://zimbra9.example.com/service/extension/samlreceiver
     # Identity provider login endpoint for POST method
     saml_post_login_destination=
     # Identity provider logout endpoint for redirect method
     saml_redirect_logout_destination=https://saml.example.com/simplesaml/saml2/idp/SingleLogoutService.php
     # Identity provider logout endpoint for POST method
     saml_post_logout_destination=
     # Logout redirect page if we are the landing page logout endpoint
     saml_landing_logout_redirect_url=/
     # Disable the audience path check
     saml_skip_audience_restriction=true
     # URL to send the user with error_code, error_msg query params. Default results in HTTP error code pages.
     saml_error_redirect_url=
     # The SAML logout document encoding, and SAML login receiver parameter encoding.
     saml_document_encoding=ASCII
     # Set to true to disable the audience path check.
     saml_skip_audience_restriction=false
     # The redirect location to send the user if their Zimbra account is not active.
     saml_inactive_account_redirect_url

From the command line as user root copy the samlextn.jar and set up the IDP certificate like this:

mkdir /opt/zimbra/lib/ext/saml
cp /opt/zimbra/extensions-network-extra/saml/samlextn.jar /opt/zimbra/lib/ext/saml/
su zimbra
cat /tmp/idpcert.pem |xargs -0 zmprov md barrydegraaff.tk zimbraMyoneloginSamlSigningCert
# zmprov mcf zimbraCsrfRefererCheckEnabled FALSE
zmprov mcf zimbraCsrfAllowedRefererHosts saml.barrydegraaff.tk
# new since 9.0.0 patch 25 you are required to set zimbraVirtualHostName:
zmprov md barrydegraaff.tk zimbraVirtualHostName zm-zimbra9.barrydegraaff.tk
/opt/zimbra/bin/zmlocalconfig -e zimbra_same_site_cookie=""  #read below section!
zmmailboxdctl restart

If your IDP and Zimbra are on the same domain in an on-premise deployment. For example zimbra.example.com and saml-idp.example.com you can use SameSite cookie setting Strict:

/opt/zimbra/bin/zmlocalconfig -e zimbra_same_site_cookie="Strict"
zmmailboxdctl restart

If your IDP is under a different domain in a hosted SaaS IDP deployment. For example zimbra.example.com and saml.authprovider.org you probably have to disable the SameSite cookie setting as follows:

/opt/zimbra/bin/zmlocalconfig -e zimbra_same_site_cookie=""
zmmailboxdctl restart

Single logout

If you want the IDP to log-out all applications when the user clicks logout in Zimbra you have to configure Zimbra to use this log-out url:

zmprov md barrydegraaff.tk zimbraWebClientLogoutURL https://zm-zimbra9.barrydegraaff.tk/service/extension/samllogout
#or globally
zmprov mcf zimbraWebClientLogoutURL https://zm-zimbra9.barrydegraaff.tk/service/extension/samllogout
# new since 9.0.0 patch 25 you are required to set it via a local config also:
zmlocalconfig -e zimbra_web_client_logoff_urls=https://zm-zimbra9.barrydegraaff.tk/service/extension/samllogout

It is possible to use multiple URL’s in zimbra_web_client_logoff_urls by using space as a delimiter:

zmlocalconfig -e zimbra_web_client_logoff_urls="https://zimbra.com https://synacor.com"

Create users

Your user accounts must be manually created in Zimbra and be available in your IDP user database. It is important that the E-mail attribute in your IDP is set exactly the same as the Zimbra account name. Or the user will not be able to log-in. If it does not work run a tail -f /opt/zimbra/log/* while doing the authentication request and dig through to log to find out what the issue may be. Keywords to grep for: SAML, Audience and assertion.

Configurable Properties saml-config.properties

The samlextn.jar uses a property file located at: ${zimbra_home}/conf/saml/saml-config.properties.

The following properties are supported:

Key Description Default Optional

saml_sp_entity_id

Issuer

saml_acs

Login receiver for the service provider

saml_redirect_login_destination

Identity provider login endpoint for redirect method

saml_redirect_logout_destination

Identity provider logout endpoint for redirect method

saml_post_login_destination

Identity provider login endpoint for POST method (unused)

saml_post_logout_destination

Identity provider logout endpoint for POST method (unused)

saml_name_id_format

Name ID format for the IDP to use in the SAMLResponse

urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

saml_date_format_instant

Date format for issue instant

yyyy-MM-dd’T’HH:mm:ss’Z'

saml_error_redirect_url

URL to send the user with error_code, error_msg query params. Default results in HTTP error code pages.

saml_landing_logout_redirect_url

Logout redirect landing page if we are the last logout service.

/

saml_document_encoding

The SAML logout document encoding, and SAML login receiver parameter encoding.

ASCII

saml_skip_audience_restriction

Set to true to disable the audience path check.

false

saml_inactive_account_redirect_url

The redirect location to send the user if their Zimbra account is not active.

/service/extension/samllogout

Now you are ready to log-on to Zimbra using SAML. Try a fresh browser/incognito window and go to: https://saml.example.com/simplesaml/saml2/idp/SSOService.php?spentityid=https://zimbra9.example.com/service/extension/samlreceiver

If all goes well, you should now be logged-on to Zimbra. You can change the default log-in page for Zimbra using

zmprov md example.com zimbraWebClientLoginURL https://saml.example.com/simplesaml/saml2/idp/SSOService.php?spentityid=https://zimbra9.example.com/service/extension/samlreceiver

, , , , , , ,

2 Responses to Updated SAML for Zimbra – Now Supports Single Log Out (updated January 2023)

  1. Adi Putra August 13, 2021 at 7:27 PM #

    All SSO functionalities are working except for single logout, it’s got 401,as we enable the debug log in mailbox side there’s what we got

    2021-08-14 01:20:43,245 DEBUG [qtp2076287037-4194:https://127.0.0.1:8443/service/extension/samlslo%5D [] misc – Servlet (contextPath=/service active=0),
    Jetty pool (threads=19, idle=2, busy=17, room=783)
    2021-08-14 01:20:43,246 DEBUG [qtp2076287037-4194:https://127.0.0.1:8443/service/extension/samlslo%5D [] misc – CSRF Request URI: /service/extension/sam
    lslo
    2021-08-14 01:20:43,246 DEBUG [qtp2076287037-4194:https://127.0.0.1:8443/service/extension/samlslo%5D [] misc – CSRF filter was initialized : CSRFcheck
    enabled: trueCSRF referer check enabled: false, CSRFAllowedRefHost: [], CSRFTokenValidity 0ms.
    2021-08-14 01:20:43,246 DEBUG [qtp2076287037-4194:https://127.0.0.1:8443/service/extension/samlslo%5D [] misc – ReqURL : /service/extension/samlslo does
    not need to pass through CSRF check
    2021-08-14 01:20:43,246 DEBUG [qtp2076287037-4194:https://127.0.0.1:8443/service/extension/samlslo%5D [] misc – CSRF check will not be done for URI : /s
    ervice/extension/samlslo
    2021-08-14 01:20:43,246 DEBUG [qtp2076287037-4194:https://127.0.0.1:8443/service/extension/samlslo%5D [] extensions – getting handler registered at /sam
    lslo
    2021-08-14 01:20:43,246 DEBUG [qtp2076287037-4194:https://127.0.0.1:8443/service/extension/samlslo%5D [] extensions – Beginning SAML logout receiver.
    2021-08-14 01:20:43,246 DEBUG [qtp2076287037-4194:https://127.0.0.1:8443/service/extension/samlslo%5D [] extensions – Auth logout performed with an invalid or no token.

    Any suggestion ?

    • Barry de Graaff October 18, 2021 at 8:50 AM #


      zmprov mcf zimbraCsrfAllowedRefererHosts your-idp-here.example.com
      zmmailboxdctl restart

Copyright © 2022 Zimbra, Inc. All rights reserved.

All information contained in this blog is intended for informational purposes only. Synacor, Inc. is not responsible or liable in any manner for the use or misuse of any technical content provided herein. No specific or implied warranty is provided in association with the information or application of the information provided herein, including, but not limited to, use, misuse or distribution of such information by any user. The user assumes any and all risk pertaining to the use or distribution in any form of any subject matter contained in this blog.

Legal Information | Privacy Policy | Do Not Sell My Personal Information | CCPA Disclosures