Zulip SAML Integration

This document explains how to implement Monosign with Zulip, the open-source team chat. It covers Single Sign-On using SAML 2.0, where Monosign acts as the Identity Provider (IdP) and Zulip as the Service Provider (SP). Before you continue, it is better to read the Zulip documentation (opens in a new tab) about SAML.

This configuration was tested with Zulip 12.3. If your version is different, please check the Zulip documentation.

Zulip supports SAML 2.0 and OpenID Connect natively. There is no single sign-on screen in the Zulip web interface; the authentication methods are configured in the settings of the Zulip server. The OpenID Connect integration is described in a separate document.

Monofor has no responsibility to do Zulip configurations. If you need support please contact the Zulip community or your Zulip support provider.

Zulip is free and open source (Apache 2.0). Single sign-on with SAML is not limited by a license key.

Instructions

This documentation contains 6 main steps for integration.

Creating an application on Monosign
Configuring the SAML settings on Monosign
Assign a user to the Zulip application
Configuration Single Sign-On for Zulip
Sign In Test
IdP-initiated sign-in from the Monosign portal

1- Creating an Application on Monosign

Create your application on Monosign first. Open the Applications page from the left menu and click Add New.

Zulip is not in the application catalog, so click Create from scratch.

Fill in the application details on the Application tab and click Next.

Property	Value	Description
Name	`Zulip`	Name of the application shown to users on the Monosign portal and on the Monosign sign-in page.
Type	`Web`	Zulip is accessed through a web browser. Options: Web, Mobile, Desktop, API.
Url	Optional	Leave empty or enter the address of Zulip (for example `https://<zulip-address>`). The sign-in can be started from the Zulip login page with the Log in with Monosign SAML button (step 5) or from the Monosign portal (step 6).
Logo	Optional	Browse and upload a logo; it is also shown on the Monosign sign-in page.
Users can see this application on their list	`Enabled`	Displays the application on the user portal.

On the Access tab define who can reach the application and click Create Application.

Property	Value	Description
User Access Type	`System Default`	Defines which users can access this application. Options: Only Assigned Users, All Users, System Default.
User Group Access Type	`System Default`	Defines the application’s user group access.
Source Using Type	`System Default`	Defines which user sources the application can use.
Profile Access Type	`All`	Defines which user profile attributes are available to the application (Options: Restricted, All). Zulip needs the e-mail address and the name of the user.

With auto_signup enabled (step 4), Zulip creates an account for every Monosign user who signs in for the first time. Make sure the effective User Access Type is Only Assigned Users and give access only to the users you assign in step 3.

After the application is created, click Keys and add a new Access Key for SAML access.

Select SAML as the key type and click Create. Monosign generates the Key value of the SAML application automatically; it is a part of the Monosign SAML addresses.

Property	Value	Options
Type	`SAML`	Rest API, OIDC/OpenID, SAML, RADIUS, Access Gateway, LDAP, AuthN/Z Server
Key	Generated automatically	Unique identifier of the SAML application in the Monosign addresses.
Session	`System Default`	System Default, On-demand, Permanent
State	`Enabled`	Enabled, Disabled
Never Expires	`Yes`	Turn off to define a specific expiration date for the key.

The key page shows the Monosign values that are needed in the Zulip configuration (step 4):

Monosign value	Example	Used in Zulip as
Entity Id	`https://<monosign-host>/saml/<key>`	`entity_id`
Sign On Service	`https://<monosign-host>/saml/<key>/login`	`url`
View Certificate / Download Certificate	X.509 certificate of Monosign	Saved on the Zulip server as `/etc/zulip/saml/idps/monosign.crt` (PEM format).
Metadata (View IdP Metadata / Download IdP Metadata)	`https://<monosign-host>/saml/<key>/metadata`	Contains the Entity Id, the Sign On Service and the certificate. Zulip does not read it by itself; use it to copy the values.

2- Configuring the SAML Settings on Monosign

Click the Configure button of the SAML key (or Edit of the key) and go to the SAML Settings → Configuration tab. Enter the address where Zulip receives the SAML response in Assertion Consumer Url, the Entity Id of Zulip as Audience and set the Name Id to the e-mail address of the user.

Property	Value	Description
Assertion Consumer Url	`https://<zulip-address>/complete/saml/`	The address where Zulip receives the SAML response (the SSO URL or ACS URL of Zulip). The path is fixed by Zulip and must end with a slash. Use the public (HTTPS) address of Zulip, which is the `EXTERNAL_HOST` of the server.
Audience	`https://<zulip-address>`	The SP Entity Id of Zulip (`SOCIAL_AUTH_SAML_SP_ENTITY_ID`), which is the address of Zulip without a path and without a slash at the end. Zulip publishes it in its metadata at `https://<zulip-address>/saml/metadata.xml` (`entityID`); check it there.
ACS Validation Mode	`Enforce`	Monosign accepts only the registered ACS address. Zulip sends exactly this address in its request. `Warn Only` works as well.
NameId Format	`System Default (unspecified)`	Default value.
Name Id	`Email`	NameID of the SAML response. Zulip reads the user from the attributes (see below), not from the NameID.
Other fields (Entity Id, Idp Description, Relay State, Additional ACS URLs)	Empty / default	Not needed for a single organization. A Relay State is only needed when one Zulip server hosts several organizations (see step 6).

Open the Attribute Mapping tab, add the attributes that Zulip reads and click Update to save.

Attribute	Value	Description
email	`{{Email}}`	Required. E-mail address of the user. Zulip identifies the user by it (`attr_user_permanent_id` and `attr_email`).
username	`{{UserName}}`	User name (`attr_username`).
fullname	`{{FormattedUserName}}`	Full name of the user (`attr_full_name`), used for the name of the Zulip account.

The attribute names are case sensitive and must be the same as the attr_ values in the Zulip settings (step 4). If a Zulip account with the same e-mail address already exists, the user signs in to that account.

3- Assign a User to the Zulip Application

Open the application in Monosign, click the Assignments tab and click Assign a User.

Search and select the users who can sign in to Zulip, check the Expiration Date and save. You can select more than one user.

Property	Value	Description
User(s)	Selected users	Users who can sign in to Zulip with Monosign.
Expiration Date	Default one year	The assignment expires on this date.

4- Configuration Single Sign-On for Zulip

As we mentioned at the start, please check out the Zulip documentation first. SAML is configured in the settings file /etc/zulip/settings.py of the Zulip server. Replace the placeholder values, enable the backend zproject.backends.SAMLAuthBackend in AUTHENTICATION_BACKENDS and restart Zulip.

AUTHENTICATION_BACKENDS = (
    "zproject.backends.EmailAuthBackend",
    "zproject.backends.SAMLAuthBackend",
)

SOCIAL_AUTH_SAML_ORG_INFO = {
    "en-US": {
        "displayname": "Zulip",
        "name": "zulip",
        "url": "https://<zulip-address>",
    },
}

SOCIAL_AUTH_SAML_ENABLED_IDPS = {
    "monosign": {
        "entity_id": "https://<monosign-host>/saml/<key>",
        "url": "https://<monosign-host>/saml/<key>/login",
        "attr_user_permanent_id": "email",
        "attr_email": "email",
        "attr_username": "username",
        "attr_full_name": "fullname",
        "display_name": "Monosign SAML",
        "auto_signup": True,
    },
}

Save the certificate of Monosign (PEM format, from Download Certificate in step 1) on the Zulip server. The file name must be the name of the provider, monosign:

mkdir -p /etc/zulip/saml/idps
cp monosign.crt /etc/zulip/saml/idps/monosign.crt
chown -R zulip.zulip /etc/zulip/saml/
find /etc/zulip/saml/ -type f -exec chmod 644 -- {} +

Setting	Value	Description
AUTHENTICATION_BACKENDS	`SAMLAuthBackend`	Enables SAML. Keep `EmailAuthBackend` in the list to be able to sign in with a password as well.
idp name (key of the dictionary)	`monosign`	Identifier of the provider. It appears in the addresses of the sign-in flow and is the name of the certificate file.
entity_id	`https://<monosign-host>/saml/<key>`	Entity Id of Monosign from the key details (step 1).
url	`https://<monosign-host>/saml/<key>/login`	Sign On Service of Monosign from the key details (step 1).
attr_user_permanent_id / attr_email	`email`	Name of the SAML attribute with the e-mail address (step 2). The permanent id should be a stable and unique value; the e-mail address is the default.
attr_username	`username`	Name of the SAML attribute with the user name.
attr_full_name	`fullname`	Name of the SAML attribute with the full name. Use it instead of `attr_first_name` and `attr_last_name`, because Monosign sends the name as one attribute.
display_name	`Monosign SAML`	Text of the sign-in button (Log in with Monosign SAML). If the OpenID Connect integration is also enabled, use a different name for each so that users can tell the buttons apart.
auto_signup	`True`	Optional. Creates the Zulip account at the first sign-in. By default Zulip asks the user whether to create an account or to use another sign-in method.

Invitation-only organizations. A new Zulip organization accepts new users only by invitation. In that case a new Monosign user cannot create an account, even with auto_signup enabled, and Zulip shows the message You need an invitation to join this organization. Either invite the user with the same e-mail address, or open Organization settings → Organization permissions in Zulip and change Joining the organization so that an invitation is not required. Then access is controlled by the assignments in Monosign (step 3).

After changing the settings, restart the Zulip server (su zulip -c '/home/zulip/deployments/current/scripts/restart-server'). When SAML is enabled, the metadata of Zulip is available at https://<zulip-address>/saml/metadata.xml. The authentication methods that are enabled on the server are listed and can be switched on or off in Organization settings → Authentication methods.

Official Docker image. The settings are given with the environment variables ZULIP_AUTH_BACKENDS (for example EmailAuthBackend,SAMLAuthBackend) and ZULIP_CUSTOM_SETTINGS of the container. Two points matter: the custom settings are read before EXTERNAL_HOST is set, so write the host name in SOCIAL_AUTH_SAML_SP_ENTITY_ID and in the url of SOCIAL_AUTH_SAML_ORG_INFO yourself (otherwise the Entity Id of Zulip becomes https://zulip.example.com and the Audience does not match); and the folder /etc/zulip/saml is lost when the container is recreated, so mount it from the host.

5- Sign In Test

Now try to log in to Zulip using Monosign SSO. Open a new browser window (or a private window) and type the address of Zulip. The login page of Zulip shows the Log in with Monosign SAML button below the e-mail and password form.

Click the Log in with Monosign SAML button.
On the Monosign sign-in page of the application log in passwordless with your QR code (Monofor Identity), with a Passkey or with your user name and password (Sign in with Password). If you are already signed in to Monosign, the page is skipped.
After the sign-in Monosign sends the SAML response to the ACS address of Zulip (/complete/saml/). At the first sign-in Zulip creates the account with the name and the e-mail address from Monosign (the user becomes a Member) and opens the organization.

6- IdP-Initiated Sign-In from the Monosign Portal

SAML supports a sign-in that is started by Monosign. When the user clicks the application on the Monosign portal, Monosign sends the SAML response directly to the ACS address of Zulip (/complete/saml/) without a request from Zulip. Zulip accepts such a response when it hosts a single organization, so no extra setting is needed on the Zulip side and the user does not see the Zulip login page.

Open the application in Monosign, click Edit, go to the Login tab, set the Login Method to SAML 2.0 and click Save.

Property	Value	Description
Login Method	`SAML 2.0`	The application is opened with the SAML key of step 1.
Login Url / Login Callback Url	Empty	Not needed. Monosign already knows the Assertion Consumer Url of step 2.
Login Form Type / Login Policy Type	`System Default`	Default values.

If one Zulip server hosts several organizations, Zulip must know which organization the user wants to enter. Enter a Relay State in the SAML settings of the key (step 2) in the form {"subdomain": "<organization>"}, or {"subdomain": ""} for the organization on the root domain.

Troubleshooting

Symptom	Cause	Solution
The Log in with Monosign SAML button is not shown	The backend `SAMLAuthBackend` is not in `AUTHENTICATION_BACKENDS`, the provider is not in `SOCIAL_AUTH_SAML_ENABLED_IDPS`, the server was not restarted after the change, or the method is switched off in the organization settings.	Enable the backend and the provider (step 4), restart Zulip and check Organization settings → Authentication methods.
Monosign shows an error about the ACS address	The Assertion Consumer Url of Monosign is different from the ACS address of Zulip, for example because the slash at the end is missing or `EXTERNAL_HOST` is wrong.	Use exactly `https://<zulip-address>/complete/saml/` in Monosign (step 2).
Zulip shows a SAML error after the sign-in	The Audience is different from the SP Entity Id of Zulip (with the Docker image it is `https://zulip.example.com` unless set explicitly), the certificate file is missing or has the wrong name, or the attribute names do not match.	Check the Audience (step 2) against `https://<zulip-address>/saml/metadata.xml`, the file `/etc/zulip/saml/idps/monosign.crt`, the `attr_` names and the Zulip log `/var/log/zulip/errors.log`.
The sign-in fails with an error about the signature	The certificate on the Zulip server is not the current certificate of the Monosign SAML key.	Download the certificate again (step 1), replace the file and restart Zulip.
The sign-in fails with an error about the time of the response	The clocks of Zulip and Monosign are different.	Synchronize the clocks of both servers.
Zulip shows You need an invitation to join this organization	The organization accepts new users only by invitation.	Invite the user or change Joining the organization (step 4).
Zulip asks whether to create an account	There is no Zulip account with the e-mail address of the Monosign user and `auto_signup` is not enabled.	Set `"auto_signup": True` or invite the user with the same e-mail address.
The sign-in from the Monosign portal (step 6) does not work	The Login Method is not SAML 2.0, or the server hosts several organizations and no Relay State is set.	Set the Login Method (step 6) and the Relay State for several organizations.
A user cannot sign in	The user is not assigned to the application.	Assign the user in step 3.

After completing the configuration on Zulip and Monosign, it is better to test in a new private browser window if the SAML SSO doesn’t work, because old session cookies may cause errors.