This document explains how to implement Monosign with Zulip, the open-source team chat. It covers Single Sign-On with OpenID Connect (OIDC), which is built into Zulip as the Generic OpenID Connect authentication backend. Zulip reads the Monosign addresses from the OIDC discovery document and uses the Authorization Code flow, so the OIDC/OpenID access key of Monosign is used. Before you continue, it is better to read the Zulip documentation (opens in a new tab) about OpenID Connect.
This configuration was tested with Zulip 12.3. If your version is different, please check the Zulip documentation.
Zulip supports OpenID Connect and SAML 2.0 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 SAML 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 OpenID Connect is not limited by a license key.
Instructions
This documentation contains 6 main steps for integration.
Creating an application on Monosign
Configuring the OIDC/OpenID settings on Monosign
Assign a user to the Zulip application
Configuration Single Sign-On for Zulip
Sign In Test
Starting the sign-in from the Monosign portal (IdP-initiated workaround)
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 |
| Name of the application shown to users on the Monosign portal and on the Monosign sign-in page. |
Type |
| Zulip is accessed through a web browser. Options: Web, Mobile, Desktop, API. |
Url | Optional | Leave empty or enter the address of Zulip (for example |
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 |
| 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 |
| Defines which users can access this application. Options: Only Assigned Users, All Users, System Default. |
User Group Access Type |
| Defines the application’s user group access. |
Source Using Type |
| Defines which user sources the application can use. |
Profile Access Type |
| 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 OIDC/OpenID access.
Select OIDC/OpenID as the key type and click Create. Monosign generates the Client Id and Client Secret automatically.
Property | Value | Options |
|---|---|---|
Type |
| Rest API, OAuth 2.0, JWT, OIDC/OpenID, SAML, RADIUS, Access Gateway, LDAP, AuthN/Z Server |
Client Id / Client Secret | Generated automatically | Use the eye icon next to the secret to reveal it. Both values are required in step 4. |
Session |
| System Default, On-demand, Permanent |
State |
| Enabled, Disabled |
Never Expires |
| Turn off to define a specific expiration date for the key. |
Configuration details for the Zulip application are provided as follows:
Monosign value | Example | Used in Zulip as |
|---|---|---|
Client Id |
|
|
Client Secret |
|
|
Configuration Url |
|
|
2- Configuring the OIDC/OpenID Settings on Monosign
Open the Keys tab of the application and click the Configure button of the OpenID Connect (OIDC) key to open the OIDC/OpenID settings.
Add the return address of Zulip to Allowed Redirect URIs, then press Update.
Property | Value | Description |
|---|---|---|
Allowed Redirect URIs |
| The address where Monosign sends the user back after sign-in (the Return URL of Zulip). The path |
Scope | Optional | Zulip requests the scopes it needs by itself, so the field can stay empty. |
Other fields | Empty / default | The other fields (Signing Key, Issuer, Audience, Resource, token lifetimes, CORS, Initiate Login URI) are not needed. Do not enter the return address in the Resource field. Starting the sign-in from the Monosign portal is configured on the Login tab of the application (step 6). |
Zulip identifies the user by the e-mail address in the ID token and takes the full name from the name claim. Monosign returns email and name by default, so a claim mapping is not required. 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. The OpenID Connect provider is added to the settings file /etc/zulip/settings.py of the Zulip server. Replace the placeholder values, enable the backend zproject.backends.GenericOpenIdConnectBackend in AUTHENTICATION_BACKENDS and restart Zulip.
AUTHENTICATION_BACKENDS = (
"zproject.backends.EmailAuthBackend",
"zproject.backends.GenericOpenIdConnectBackend",
)
SOCIAL_AUTH_OIDC_ENABLED_IDPS = {
"monosign": {
"oidc_url": "https://<monosign-host>",
"display_name": "Monosign",
"client_id": "<client-id>",
"secret": get_secret("social_auth_oidc_secret"),
"auto_signup": True,
},
}
SOCIAL_AUTH_OIDC_FULL_NAME_VALIDATED = True
Save the client secret of Monosign in the secrets file /etc/zulip/zulip-secrets.conf of the server:
social_auth_oidc_secret = <client-secret>
Setting | Value | Description |
|---|---|---|
AUTHENTICATION_BACKENDS |
| Enables OpenID Connect. Keep |
idp name (key of the dictionary) |
| Identifier of the provider. It appears in the addresses of the sign-in flow (also in the Login Url of step 6), but it is not shown to users. |
oidc_url |
| Address of Monosign without a slash at the end. Zulip reads the configuration from |
display_name |
| Text of the sign-in button (Log in with Monosign). |
client_id / secret | Client Id / Client Secret | Copied from the Monosign OIDC/OpenID Access Key Details created in the first step. The secret is read from the secrets file with |
auto_signup |
| 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. |
SOCIAL_AUTH_OIDC_FULL_NAME_VALIDATED |
| Optional. Zulip trusts the name from Monosign and does not show the registration form to new users. |
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'). With the official Docker image the same values are given with the environment variables ZULIP_AUTH_BACKENDS and ZULIP_CUSTOM_SETTINGS, and the secret as the Docker secret zulip__social_auth_oidc_secret. The authentication methods that are enabled on the server are listed and can be switched on or off in Organization settings → Authentication methods.
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 button below the e-mail and password form.
Click the Log in with Monosign button.
On the Monosign sign-in page 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 redirects the browser back to Zulip (
/complete/oidc/). 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- Starting the Sign-In from the Monosign Portal (IdP-Initiated Workaround)
In OpenID Connect the application must start every sign-in, because it creates the state and nonce values that it checks in the answer. Zulip therefore does not accept an unsolicited answer from Monosign, and a real IdP-initiated sign-in is not possible with OIDC (for a real IdP-initiated sign-in use the SAML integration). As a workaround, Monosign can open the sign-in start address of Zulip when the user clicks the application on the Monosign portal. This is the same address that the Log in with Monosign button uses, so for the user it works as if the button was pressed. If the user already has a Monosign session, the Zulip login page and the Monosign sign-in form are skipped.
Open the application in Monosign, click Edit, go to the Login tab, set the Login Method and the Login Url and click Save.
Property | Value | Description |
|---|---|---|
Login Method |
| The application is opened with the OpenID Connect key of step 1. |
Login Url |
| Sign-in start address of Zulip. The part |
Login Callback Url | Empty | Not needed. |
Login Form Type / Login Policy Type |
| Default values. |
Zulip ignores the extra parameters that an OpenID Connect third-party initiated login can add to the address (iss, login_hint, target_link_uri), so they do no harm. The same approach works for other applications that have a sign-in start address.
Troubleshooting
Symptom | Cause | Solution |
|---|---|---|
The Log in with Monosign button is not shown | The backend | Enable the backend and the provider (step 4), restart Zulip and check Organization settings → Authentication methods. |
Monosign shows a redirect URI error | The redirect address that Zulip sends does not exactly match the Allowed Redirect URIs, for example because the slash at the end is missing, | Add |
An error page appears after returning from Monosign | The Client Id or Client Secret is wrong, | Copy the values again from the Monosign access key (step 1), check that |
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 | Set |
The application on the Monosign portal opens the Zulip login page, or a page that is not found | The Login Url of step 6 is empty or wrong, for example | Use exactly |
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 OIDC SSO doesn’t work, because old session cookies may cause errors.