Authentication/SAML: Difference between revisions

No edit summary
(4 intermediate revisions by the same user not shown)
Line 2: Line 2:
__FORCETOC__
__FORCETOC__
<div class="col-md-12 ibox-content">
<div class="col-md-12 ibox-content">
= SAML Readme =
= Zimbra Single Sign-On using SAML with SimpleSAMLphp =
{{KB|{{Unsupported}}|{{ZCS 8.0}}|{{ZCS 7.0}}|}}
{{KB|{{ZCS 9.0}}|}}
{{WIP}}
 
[[Category:Authentication]]
[[Category:Authentication]]
[[Category:Administration]]
[[Category:Administration]]
[[Category:Configuration]]
[[Category:Configuration]]


Included in Network Edition at the following location:
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%20factor%20authentication|Multi Factor Authentication]].
 
/opt/zimbra/extensions-network-extra/saml/README.txt
 
<pre>
 
The Zimbra SAML extension provides support for the "Browser/POST Profile of SAML" - Section 4.1.2 of
http://www.oasis-open.org/committees/download.php/3405/oasis-sstc-saml-bindings-1.1.pdf. Zimbra is the "Destination
Site" in the context of this section of the spec.


The flow for a user on a browser would be:
== Set up Zimbra SP in SimpleSAMLphp ==


1. User authenticates with an IdP which can act as a SAML Provider.
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 <code>/etc/simplesamlphp/metadata/saml20-sp-remote.php</code>):
2. The IdP redirects the browser to Zimbra SAML extension URL (<zimbra_base_url>/service/extension/samlreceiver) and
  passes along a SAML Response (containing a SAML Assertion).
3. The SAML extension checks the validity of the SAML Response, and then looks up the Subject inside the SAML assertion
  which should be the email address corresponding to user's Zimbra account.
4. Finally, a Zimbra cookie corresponding to that Zimbra account is returned to the browser and is redirected to the
  default Zimbra mail URL.


<pre>    $metadata['https://zm-zimbra9.barrydegraaff.tk/service/extension/samlreceiver'] = array(
        'simplesaml.attributes'    =&gt; true,
            'debug' =&gt; TRUE,
            'AssertionConsumerService' =&gt; 'https://zm-zimbra9.barrydegraaff.tk/service/extension/samlreceiver',
            'SingleLogoutService' =&gt; 'https://zm-zimbra9.barrydegraaff.tk/service/extension/samlslo',
            'NameIDFormat' =&gt; 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress',
            'authproc' =&gt; array (
                    10 =&gt; array(
            'class' =&gt; 'saml:AttributeNameID',
            'attribute' =&gt; 'emailAddress',
            'Format' =&gt; 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress',
              ),
          )
    );</pre>
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 <code>/tmp/idpcert.pem</code>, don’t forget to <code>chown zimbra:zimbra /tmp/idpcert.pem</code>. If you followed the SimpleSAMLphp setup guide you can find the certificate at <code>/etc/simplesamlphp/cert/server.crt</code>.


Zimbra Setup
=== Set up Zimbra ===
------------


- Create "saml" directory under /opt/zimbra/lib/ext; Copy samlextn.jar under it.
Add the file <code>/opt/zimbra/conf/saml/saml-config.properties</code> to configure SAML in Zimbra add the contents:


- Add the SAML signing certificate to the domain:
<pre>    # Issuer
    saml_sp_entity_id=https://zm-zimbra9.barrydegraaff.tk/service/extension/samlreceiver
    # Login receiver for the service provider
    saml_acs=https://zm-zimbra9.barrydegraaff.tk/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.barrydegraaff.tk/simplesaml/saml2/idp/SSOService.php?spentityid=https://zm-zimbra9.barrydegraaff.tk/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.barrydegraaff.tk/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</pre>
From the command line as user root copy the samlextn.jar and set up the IDP certificate like this:


    zmprov md <domain> zimbraMyoneloginSamlSigningCert <saml-signing-cert-base64-data>
<pre>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 exampledomain.com zimbraMyoneloginSamlSigningCert
zmprov mcf zimbraCsrfRefererCheckEnabled FALSE
zmmailboxdctl restart</pre>
=== Single logout ===


In case you need to support SLO initiated from the IDP you need the SLO url: https://zimbraserver.example.com/service/extension/samlslo


Note for SAML Provider
Also if you want to trigger the IDP to log-out when the user clicks logout in Zimbra you have to configure Zimbra to use this log-out url: https://zimbraserver.example.com/service/extension/samllogout.
----------------------


SAML Provider must POST the SAML Response at the following URL for SSO:
=== Create users ===


    <zimbra_base_url>/service/extension/samlreceiver
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 <code>tail -f /opt/zimbra/log/*</code> 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.


This SAML Consumer extension requires that the Subject Name Identifier inside the SAML Assertion must be the account
=== Configurable Properties saml-config.properties ===
email address, so configure the Provider accordingly.


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


== Troubleshooting ==
The following properties are supported:
* Check /opt/zimbra/log/zmmailboxd.out for exceptions - it's more useful than mailbox.log in this case


* In 8.7.11, set zimbraCsrfRefererCheckEnabled to FALSE or add the domain to zimbraCsrfAllowedRefererHosts. Setting it to FALSE is preferred.
{|
!width="10%"| Key
!width="37%"| Description
!width="24%"| Default
!width="27%"| 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
| <code>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</code>
| √
|-
| saml_date_format_instant
| Date format for issue instant
| <code>yyyy-MM-dd'T'HH:mm:ss'Z'</code>
| √
|-
| saml_error_redirect_url
| URL to send the user with <code>error_code</code>, <code>error_msg</code> 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.
| <code>/</code>
| √
|-
| saml_document_encoding
| The SAML logout document encoding, and SAML login receiver parameter encoding.
| <code>ASCII</code>
| √
|-
| saml_skip_audience_restriction
| Set to true to disable the audience path check.
| <code>false</code>
| √
|-
| saml_inactive_account_redirect_url
| The redirect location to send the user if their Zimbra account is not active.
| <code>/service/extension/samllogout</code>
| √
|}


* Also in 8.7.11, we've seen the existing certificate stored in 'zimbraMyOneLoginSamlSigningCert' doesn't load in certain situations, especially after an upgrade. To fix this, we'll simply have to reload the certificate.
{{Article Footer|Zimbra 9|02/22/2021}}
To do this, either get a copy of the certificate, or recreate it from the output of:
zmprov gd example.com zimbraMyOneLoginSigningCert
After that, null the value:
zmprov md example.com zimbraMyOneLoginSigningCert ' '
And then set it to the new certificate.
{{Article Footer|Zimbra Collaboration 8.0, 7.0|04/16/2014}}

Revision as of 15:48, 22 February 2021

Zimbra Single Sign-On using SAML with SimpleSAMLphp

   KB 20404        Last updated on 2021-02-22  




5.00
(one vote)
ZCS 9.0 Article ZCS 9.0

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.

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://zm-zimbra9.barrydegraaff.tk/service/extension/samlreceiver'] = array(
         'simplesaml.attributes'     => true,
            'debug' => TRUE,
             'AssertionConsumerService' => 'https://zm-zimbra9.barrydegraaff.tk/service/extension/samlreceiver',
             'SingleLogoutService' => 'https://zm-zimbra9.barrydegraaff.tk/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://zm-zimbra9.barrydegraaff.tk/service/extension/samlreceiver
     # Login receiver for the service provider
     saml_acs=https://zm-zimbra9.barrydegraaff.tk/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.barrydegraaff.tk/simplesaml/saml2/idp/SSOService.php?spentityid=https://zm-zimbra9.barrydegraaff.tk/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.barrydegraaff.tk/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 exampledomain.com zimbraMyoneloginSamlSigningCert
zmprov mcf zimbraCsrfRefererCheckEnabled FALSE
zmmailboxdctl restart

Single logout

In case you need to support SLO initiated from the IDP you need the SLO url: https://zimbraserver.example.com/service/extension/samlslo

Also if you want to trigger the IDP to log-out when the user clicks logout in Zimbra you have to configure Zimbra to use this log-out url: https://zimbraserver.example.com/service/extension/samllogout.

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
Verified Against: Zimbra 9 Date Created: 02/22/2021
Article ID: https://wiki.zimbra.com/index.php?title=Authentication/SAML Date Modified: 2021-02-22



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