MonoSign preparation

Single sign-on between MonoSign and Zimbra: preparing the application in MonoSign, the wizard preset in Zimbra, test, publish and troubleshooting.

Organisation users sign in to webmail with their MonoSign account and are never asked for a Zimbra password. For the wizard steps on the Zimbra side see Single sign-on (SAML); for installation see Single sign-on (SAML) setup.

Preparation and example values

Replace the example values below with your own. In the text, <zimbra-address>, <tenant> and <GUID> stand for these values.

What	Example	Note
Zimbra public address	https://posta.zpe.profelis.net	The address users open in the browser
Domain to put under SSO	zpe.profelis.net	A domain can belong to one connection only
MonoSign management console	https://ornek-mng.monofor.com	Administrator screen
MonoSign user portal	https://ornek.monofor.com	The address users sign in at
Application key (GUID)	00000000-0000-0000-0000-000000000000	MonoSign generates it when the application is created

Prerequisites:

• The Profelis SAML extension installed on Zimbra PFE 10; Tools and Migration › Single Sign-On (SAML) appears in the admin console.
• Time synchronisation (NTP) on Zimbra and MonoSign. A difference of more than 2 minutes makes sign-ins fail.
• Each user's Email field in MonoSign must equal their Zimbra mail address; if it differs, add a domain rewrite in the wizard.
• A test user with an account in both MonoSign and Zimbra. MonoSign administrator accounts without an email, such as root, cannot be tested.

No SSH needed for configuration

The connection, certificate, domain login and logout addresses, virtual host, CSRF allowed hosts and the logout address list are written by the wizard and the Publish button. The server console is needed only for the first installation of the extension, a mailboxd restart in rare cases, and emergency rollback if the admin console is unavailable.

Network Edition steps are not needed

MonoSign's own documentation is written for Network Edition. The addresses work the same in Profelis; the wizard does everything that saml-config.properties, zimbraMyoneloginSamlSigningCert and the manual zmprov steps do. Do not apply the zimbra_same_site_cookie="" step: it weakens CSRF protection for no reason.

MonoSign side

In the MonoSign management console under Applications, register Zimbra as a service provider.

Application and SAML key

1. Applications › new application: the Zimbra template from the catalogue, or an application of type Web.
2. Keys › Add New Key: Type SAML, lifetime Lifetime.
3. Copy the Metadata address from the SAML 2 card: https://<tenant>.monofor.com/saml/<GUID>/metadata. This is the only address the Zimbra side needs.

Keys tab: the SAML 2 card and the Metadata address

Common mistake: entering the card's \"Entity Id\" in Zimbra

The value https://<tenant>.monofor.com/saml/<GUID> on the card is MonoSign's own identity (the IdP). If it is entered in the SP Entity ID field in Zimbra, the extension rejects the connection. Zimbra's Entity ID is derived from the Zimbra address.

SAML settings

On the SAML 2 card, Configure › SAML Settings › Configuration:

MonoSign field	Value
Assertion Consumer Url	https://<zimbra-address>/service/extension/samlreceiver
ACS Validation Mode	Enforce
Entity Id	https://<zimbra-address>/service/extension/samlreceiver (same as the ACS; identical to the Zimbra SP entity ID)
NameId Format	urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
Name Id	Email
Logout Url (single logout, at the bottom of the page)	https://<zimbra-address>/service/extension/samlslo
Audience, Relay State	Empty

The Values to enter on the MonoSign side box in step 3 of the Zimbra wizard shows these values with your own address, ready to copy.

Configure › SAML Settings › Configuration (upper part)

Lower part: Logout Url `.../samlslo`

Logout Url: /samlslo, not /samllogout

MonoSign sends the logout response (LogoutResponse) and its own logout request to this address. /samllogout only starts the user's logout from Zimbra and does not accept MonoSign's messages.

NotBefore

MonoSign adds a non-standard NotBefore to the confirmation data. The extension release of 15.10.2026 and later tolerates it, so the Exclude NotBefore switches can stay off. If an older release fails the test with Subject confirmation validation failed, update the extension or temporarily turn on Exclude NotBefore › From Confirmation.

Assignments

1. Edit › Source, Provider and Profile: User Access Type = Only Assigned Users (you may select All Users temporarily while testing).
2. Assignments › Assign a User: assign the users who will use Zimbra (or groups from the Groups tab).
3. The Email field of every assigned user under Directory › Users must equal their Zimbra address.

Edit › Source, Provider and Profile

Assignments: users assigned to the application

MonoSign preset in the Zimbra wizard

In the admin console go to Single Sign-On (SAML), press New connection and choose MonoSign (Monofor). Legacy-compatible ACS URL (/samlreceiver) and IdP-initiated sign-in are on, and the NameID is set to email. The steps are described on the Single sign-on (SAML) page. Recommended security values for MonoSign:

Setting	Value
Signature policy	Signed assertion (MonoSign signs the assertion)
Sign the AuthnRequest	On
Allow IdP-initiated sign-in	On: needed to sign in from the tile in the MonoSign portal. Turn it off if the portal is not used (login CSRF risk)
Require re-authentication at every sign-in	Off
Allowed clock skew	120 s
Maximum IdP session age	28800 s (8 hours)
Skip the audience check	Off
Single logout (SLO)	On: when off, the system signs the user back in without a password after logout

In the IdP details step, paste the Metadata address from MonoSign and press Read metadata. If the server cannot reach MonoSign, upload the file you downloaded with Download IdP Metadata in MonoSign to the XML file tab. In the Zimbra side step, leave SP entity ID empty or enter https://<zimbra-address>/service/extension/samlreceiver.

Test and publish

1. In step 6 press Start test: the MonoSign sign-in screen opens in a new window. Sign in as a user who is assigned to the application and has an email. If another MonoSign session is open, sign out first or use a private window.
2. When all eight checks are green, the Publish button becomes available.
3. Publish: the login page of the selected domains redirects to MonoSign. Unpublish reverts everything.

Publishing takes effect in about a minute

The web client caches domain information. On stock Zimbra this lasts 60 minutes; the Profelis installation lowers it to 1 minute with the SAML module. If the publish result says "The sign-in page updates in about a minute", wait a minute; no restart is needed. 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 on a single server run zmmailboxdctl restart as the zimbra user, in an Always On cluster run profelis-alwayson-companion rolling-restart as root (no downtime, see Always On). (The install links the command under /usr/local/sbin; full path /opt/profelis-alwayson/bin/profelis-alwayson-companion.)

Verifying user sign-in

Try in a private window with the test user.

• The surest way: give the test user a MonoSign password that differs from the Zimbra password. If the sign-in works with the MonoSign password, SSO is working.
• Redirect: opening https://<zimbra-address> moves the address bar to the MonoSign sign-in page.
• Single logout: sign out of webmail; the MonoSign session closes too and a new sign-in is required.
• IdP-initiated sign-in: click the Zimbra tile in the MonoSign user portal; the mailbox opens directly.
• Sign-in events: admin console › Single Sign-On (SAML) › Sign-in events: every sign-in, sign-out and test with result, user, IP and browser.

Troubleshooting by symptom

Symptom	Cause	Fix
Timeout: "No response arrived from the IdP within 5 minutes"	MonoSign did not send a response (usually one of the two MonoSign errors below)	Look at the MonoSign error in the test window
"Cannot find entity … SPSSODescriptor"	MonoSign's Entity Id was entered in the SP Entity ID field	Leave SP Entity ID empty or enter .../samlreceiver
"Subject confirmation validation failed"	MonoSign's NotBefore value (older extension release)	Update the extension, or in MonoSign set Exclude NotBefore › From Confirmation
Audience is red in the test result	MonoSign Entity Id differs from the Zimbra SP entity ID	Make both identical
Zimbra account is red	The account does not exist, is inactive, or the email is in another domain	Create the account or add a domain rewrite
Signature is red	Old or wrong certificate; signature policy mismatch	Refresh IdP metadata; try Signed assertion / Signed response
Time validity is red	Clock difference of more than 2 minutes	NTP on both sides
Zimbra's own login form appears after publishing	The domain has no virtual host, or the web client cache is stale (60 min on stock, 1 min with the Profelis install)	Wait a minute; read the warning in the publish result; zmprov gd <domain> zimbraVirtualHostname must include the public address
Signs in again after logout without asking for a password	SLO is off; the MonoSign session stays open	Turn on Single logout in the security step; MonoSign Logout Url = .../samlslo
403 on return from the IdP	The CSRF referer list was not refreshed (zm-mailbox patch 122 missing)	On a single server zmmailboxdctl restart; in an Always On cluster profelis-alwayson-companion rolling-restart

Errors seen on the MonoSign screen:

"You need permission": the user is not assigned to the application. Fix: assign the user on the Assignments tab.

"Your Email seems empty": the user's Email field is empty (for example `root`). Try a user whose Email is filled, or fill it in.

Rejection caused by NotBefore on an older release; the reason shows under Technical details

For a detailed trace: zmprov aal <user> zimbra.extensions debug (run zmprov ral when finished).

Emergency and rollback

Password sign-in is never switched off.

• Emergency sign-in: https://<zimbra-address>/?ignoreLoginURL=1. If MonoSign is unreachable, users sign in here with their Zimbra password.
• Turning SSO off: Unpublish on the connection card. Domain settings return to their previous state; if publishing added a virtual host, only that is removed.
• If the admin console is unavailable:

su - zimbra -c "zmprov md <domain> zimbraWebClientLoginURL '' zimbraWebClientLogoutURL ''"

If the MonoSign signing certificate changes, use Refresh IdP metadata on the connection card (if the metadata address is saved) or upload the new metadata. The dashboard shows a certificate yellow when 30 days remain.