SAML authentication

Zulip supports using SAML authentication for single sign-on, both when self-hosting or on the Zulip Cloud Plus plan.

This page documents details on how to set up SAML authentication with Zulip with various common SAML identity providers. Once you have set up SAML, you may also want to consider configuring SCIM.

If you are self-hosting, this documentation is likely still useful for how to configure these SAML providers to work with Zulip.

Configure SAML with Okta

1. Make sure you have created your organization.

2. Set up SAML authentication by following Okta's documentation. Specify:

   • https://auth.zulipchat.com/complete/saml/ for the "Single sign on URL"`.
   • https://zulipchat.com for the "Audience URI (SP Entity ID)".
   • Skip "Default RelayState".
   • Skip "Name ID format".
   • Set 'Email` for "Application username format".
   • Provide "Attribute statements" of email to user.email, first_name to user.firstName, and last_name to user.lastName.

3. Assign the appropriate accounts in the "Assignments" tab. These are the users that will be able to log in to your Zulip organization.

4. Send the following information to us at support@zulip.com:

   • The URL of your zulipchat-hosted organization.
   • The "Identity Provider metadata" provided by Okta for the application.
   • The name "X" that will be displayed on the "Log in with X" button in Zulip.
   • Optionally you can also send us an icon that should be shown on the button.

5. We will take care of the server-side setup and let you know as soon as it's ready.

Configure SAML with OneLogin

1. Make sure you have created your organization.

2. Navigate to the OneLogin Applications page, and click "Add App".

3. Search for the "SAML Custom Connector (Advanced)" app and select it.

4. Set a name and logo according to your preferences and click "Save". This doesn't affect anything in Zulip, but will be shown on your OneLogin Applications page.

5. Go to the "Configuration" section:

   • Leave the RelayState field empty.
   • Set https://zulipchat.com as the Audience.
   • Set https://auth.zulipchat.com/complete/saml/ as the Recipient, ACS URL and ACS URL Validator.
   • Leave the remaining fields as they are.

6. Go to the "Parameters" section. Ignore the pre-configured parameters that are already there and add custom ones to match the following screenshot:

   

   Make sure to set the "Include in SAML assertion" flag on them.

7. The OneLogin side of configuration should be ready! Send the following information to us at support@zulip.com:

   • The URL of your zulipchat-hosted organization.
   • The issuer URL from the "SSO" section. It contains Identity Provider metadata that we will need.
   • The name "X" that will be displayed on the "Log in with X" button in Zulip.
   • Optionally you can also send us an icon that should be shown on the button.

8. We will take care of the server-side setup and let you know as soon as it's ready.

Configure SAML with AzureAD

1. Make sure you have created your organization.

2. From your AzureAD Dashboard, navigate to "Enterprise applications", click "New application", followed by "Create your own application".

3. Enter a name (E.g. "Zulip Cloud") for the new AzureAD application, choose "Integrate any other application you don't find in the gallery (Non-gallery)" and click "Create".

4. From your new AzureAD application's Overview page that opens, go to "Single sign-on" and select "SAML".

5. In the "Basic SAML Configuration" section:

   • Set "Identifier (Entity ID)" to be https://zulipchat.com.
   • Check the "Default" box - this is necessary for IdP-initiated sign on to work.
   • Set https://auth.zulipchat.com/complete/saml/ as the "Reply URL (Assertion Consumer Service URL)".
   • Optional: If you want to set up IdP-initiated sign on, enter {"subdomain": "{your organization's subdomain}"} in the RelayState field. E.g. if your organization's address is mytestorganization.zulipchat.com, set this field to {"subdomain": "mytestorganization"}.

6. The default "User Attributes & Claims" are correct. If you need to make changes to them, mention it in your email to support@zulip.com in a later step. The screenshot below illustrates the expected configuration - which is the default the new app comes with at the time of writing this:

   

7. The AzureAD side of configuration should be ready! Send the following information to us at support@zulip.com:

   • The URL of your zulipchat-hosted organization.
   • The App Federation Metadata Url and the certificate downloaded from Certificate (Base64) in the "SAML Signing Certificate" section.
   • The Login URL and Azure AD Identifier from the "Set up" section.
   • The name "X" that will be displayed on the "Log in with X" button on the Zulip login page.
   • Optionally, you can also send us an icon that should be shown on the button.

8. We will take care of the server-side setup and let you know as soon as it's ready.

Configure SAML with Keycloak

1. Make sure you have created your organization.

2. Make sure your Keycloak server is up and running. We assume the URL is https://keycloak.example.com and your Keycloak realm is yourrealm.

3. In Keycloak, register a new Client for your Zulip organization:

   • Client-ID: https://zulipchat.com
   • Client Protocol: saml
   • Client SAML Endpoint: leave this field empty

4. In the Settings tab for your new Keycloak client, set the following properties:

   • Valid Redirect URIs: https://auth.zulipchat.com/*
   • Base URL: https://auth.zulipchat.com/complete/saml/
   • Client Signature Required: Disable

5. In the Mappers tab for your new Keycloak client:

   • Create a Mapper for first name:
     • Property: firstName
     • Friendly Name: first_name
     • SAML Attribute Name: first_name
     • SAML Attribute Name Format: Basic
   • Create a Mapper for last name:
     • Property: lastName
     • Friendly Name: last_name
     • SAML Attribute Name: last_name
     • SAML Attribute Name Format: Basic
   • Create a Mapper for email address:
     • Property: email
     • Friendly Name: email
     • SAML Attribute Name: email
     • SAML Attribute Name Format: Basic

6. The Keycloak side of configuration should be ready! Send the following information to Zulip Support at support@zulip.com:

   • The URL of your Zulip Cloud organization, i.e. https://example.zulipchat.com.
   • The URL of your Keycloak realm. If master is your Keycloak realm name, then the Keycloak realm URL should resemble https://keycloak.example.com/auth/realms/yourrealm.

Related articles

• SAML configuration for self-hosting
• SCIM provisioning