Skip to content

Single sign-on (SAML)

Users sign in to webmail with ADFS, MonoSign or another SAML 2.0 identity provider; no Zimbra password is asked. Setup, testing and publishing are done in the admin console; no SSH is needed.

Global administrator; delegated administrator for their own domainAdmin console › Tools and Migration › Single Sign-On (SAML)

Signing in with single sign-on (SAML) Signing in with single sign-on (SAML) 1 Webmail The user opens zpe.profelis.net 2 Identity provider Sign in with the company account (ADFS, MonoSign...) 3 Verification Zimbra checks the signed SAML response 4 Session Webmail opens without asking for a password

The connections screen

Open Tools and Migration › Single Sign-On (SAML). The top shows the number of published connections and the successful / failed sign-ins of the last 24 hours; connection cards are below. A card shows the identity provider type, domains, the expiry of the IdP signing certificate and the last sign-in status.

Single Sign-On (SAML): connection card and summary

Single Sign-On (SAML): connection card and summary
  1. New connection adds an identity provider.
  2. Edit on a card changes it; Test tests it.
  3. The Sign-in events tab lists sign-in records.

Setting up a connection (wizard, 6 steps)

1. IdP type

Press New connection and choose your identity provider: Microsoft ADFS, MonoSign or Generic SAML 2.0. Matching presets are filled in.

Step 1: identity provider type

Step 1: identity provider type

2. IdP details

  1. On the Metadata URL tab enter the identity provider's metadata address (in MonoSign, the application's SAML Metadata link).
  2. Press Read metadata. Instead of an address you can upload an XML file or type the values with Manual entry.
  3. The Verified box shows the Entity ID, the sign-in (SSO) and sign-out (SLO) addresses and the signing certificate.

Step 2: IdP details after reading the metadata

Step 2: IdP details after reading the metadata

3. Zimbra side

  1. Connection name: the name shown in the list (e.g. MonoSign).
  2. Public URL: the mail address users open in the browser (e.g. https://mail.zpe.profelis.net).
  3. Domains: tick the domains that will use SSO.
  4. From the box on the right, copy the ACS, Entity ID, SP metadata and SLO addresses with Copy and enter them in the identity provider.
  5. With MonoSign, follow MonoSign preparation for the application, SAML key, setting values and assignments.

Step 3: Zimbra side and the addresses to give to the identity provider

Step 3: Zimbra side and the addresses to give to the identity provider

4. Account mapping

Choose which Zimbra account the identity sent by the identity provider maps to. For ADFS and MonoSign, NameID in Email address format is recommended. If your user names carry a different domain, add a Domain rewrite rule. Type a sample identity in Live preview on the right to see the result.

Step 4: account mapping and live preview

Step 4: account mapping and live preview

5. Security

Signature, audience check, single logout and clock skew come with safe defaults. Press Show settings to change them. Recommended values (verified with MonoSign):

Setting Recommended
Signature policy Require a signed assertion or response
Sign the AuthnRequest On
IdP-initiated sign-in Off unless a portal launches sign-in (login CSRF risk); the MonoSign preset turns it on
Re-authentication Off
Allowed clock skew 120 seconds
Maximum IdP session age 28800 seconds
Audience check On
Single logout On if the identity provider supports it

Step 5: security settings

Step 5: security settings

6. Test and publish

  1. In Summary, Change next to each setting returns to that step.
  2. Start test: you sign in at the identity provider in a new window; Zimbra does not sign you in, it only shows the response and the mapped account. It works while the connection is not published, too.
  3. If the test succeeds, press Publish. The sign-in page of the selected domains redirects to the identity provider. Unpublish takes it back.
  4. Close the wizard with Done.

Step 6: test and publish

Step 6: test and publish

When does the sign-in page change?

The sign-in page caches domain information for a short time. The Profelis installer lowers this to 1 minute with the SAML module: publishing and unpublishing show up within about a minute, no restart is needed. The publish result says "The login page updates within about a minute".

If the result shows a restart command instead, the cache is still 60 minutes (for example after a Zimbra package update). Run the installer again or apply the command shown: on a single server zmmailboxdctl restart as the zimbra user, in an Always On cluster profelis-alwayson-companion rolling-restart as root (the install links profelis-alwayson-companion under /usr/local/sbin; on older installs use the full path /opt/profelis-alwayson/bin/profelis-alwayson-companion) (no downtime, see Always On).

What the user sees

When the mail address of a published domain is opened, the user goes straight to the identity provider's sign-in page (below: MonoSign, QR code or password). After signing in, webmail opens; no Zimbra password is asked.

MonoSign sign-in page

MonoSign sign-in page

Sign-in events

The Sign-in events tab records every sign-in, test and sign-out: time, result, account, connection, failure reason, IP and browser. Filter by Connection, Result and Account. To close a user's open sessions, press End sessions on the row.

Sign-in events: filters and ending sessions

Sign-in events: filters and ending sessions

ADFS side

  1. Copy the SP metadata address from the wizard's Zimbra side step.
  2. Create the relying party trust in ADFS: Add-AdfsRelyingPartyTrust -Name "Zimbra Mail" -MetadataUrl <address> -AccessControlPolicyName "Permit everyone"
  3. Claim rules: AD mail → E-Mail Address; E-Mail Address → Name ID (e-mail format).
  4. Set-AdfsRelyingPartyTrust -SignedSamlRequestsRequired $true -NotBeforeSkew 2
  5. In Zimbra: Test › Publish.

ADFS's encrypted assertions (AES-256 + RSA-OAEP) are decrypted automatically.

MonoSign side

  • In the application, enter https://zpe.profelis.net/service/extension/samlreceiver as ACS and Entity Id, and .../service/extension/samlslo as Logout Url; NameId format emailAddress.
  • Leave the SP Entity ID field empty in the Zimbra wizard; MonoSign's "Entity Id" does not go there.

Single logout

Signing out of Zimbra sends a signed logout request to the identity provider; a logout started at the identity provider ends the Zimbra session. Logout messages must be signed.

Moving from Network Edition

Import from NE › Preview: the old settings are mapped to a Profelis connection. The connection is created disabled and the wizard opens at the test step.

Troubleshooting

  1. Get the support code from the user's error page (signature, audience, time, address, no account…).
  2. Search for the user under Events: result, reason, IP, browser.
  3. Test the connection; the red stage comes with a suggested fix.
  4. On the server: grep profelis-saml /opt/zimbra/log/mailbox.log.

Password sign-in in an emergency

Password sign-in is always available at https://<mail address>/?ignoreLoginURL=1. To switch SSO off, use Unpublish on the connection card.

Scope

IMAP, POP, SMTP, ActiveSync and CalDAV clients do not use SAML. Accounts must already exist in Zimbra. Admin console sign-in is not tied to SAML.