zulip/templates/zerver/help/saml-authentication.md

# SAML authentication

{!admin-only.md!}

Zulip supports using SAML authentication for single sign-on, both for Zulip
Cloud and self-hosted Zulip servers.

This page describes how to configure SAML authentication with several common providers:

* Okta
* OneLogin
* AzureAD
* Keycloak

Other SAML providers are supported as well.

If you are [self-hosting](/self-hosting/) Zulip, please follow the detailed setup instructions in
the [SAML configuration for self-hosting][saml-readthedocs]. The documentation
on this page may be a useful reference for how to set up specific SAML
providers.

!!! warn ""
    Zulip Cloud customers who wish to use SAML authentication must upgrade to
    the Zulip Cloud Plus plan. Contact
    [support@zulip.com](mailto:support@zulip.com) for plan benefits and pricing.

## Configure SAML

{start_tabs}

{tab|okta}

{!upgrade-to-plus-if-needed.md!}

1. Set up SAML authentication by following
   [Okta's documentation](https://developer.okta.com/docs/guides/saml-application-setup/overview/).
   Specify the following fields, skipping **Default RelayState** and **Name ID format**:
     * **Single sign on URL**: `https://auth.zulipchat.com/complete/saml/`
     * **Audience URI (SP Entity ID)**: `https://zulipchat.com`
     * **Application username format**: `Email`
     * **Attribute statements**:
         * `email` to `user.email`
         * `first_name` to `user.firstName`
         * `last_name` to `user.lastName`

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

1. {!send-us-info.md!}

     1. Your organization's URL
     1. The **Identity Provider metadata** provided by Okta for the application.
        To get the data, click the **View SAML setup instructions button** in
        the right sidebar in the **Sign on** tab.
        Copy the IdP metadata shown at the bottom of the page.
     {!saml-login-button.md!}

{tab|onelogin}

{!upgrade-to-plus-if-needed.md!}

1. Navigate to the OneLogin **Applications** page, and click **Add App**.

1. Search for the **SAML Custom Connector (Advanced)** app and select it.

1. Set a name and logo and click **Save**. This doesn't affect anything in Zulip,
   but will be shown on your OneLogin **Applications** page.

1. In the **Configuration** section, specify the following fields. Leave the
   remaining fields as they are, including blank fields.

    * **Audience**: `https://zulipchat.com`
    * **Recipient**: `https://auth.zulipchat.com/complete/saml/`
    * **ACS URL**: `https://auth.zulipchat.com/complete/saml/`
    * **ACS URL Validator**: `https://auth.zulipchat.com/complete/saml/`

1. In the **Parameters** section, add the following custom parameters. Set the
   **Include in SAML assertion** flag on each parameter.

      | Field name | Value
      |---         |---
      | email      | Email
      | first_name | First Name
      | last_name  | Last Name
      | username   | Email

1. {!send-us-info.md!}

     1. Your organization's URL
     2. The **issuer URL** from the **SSO** section. It contains required **Identity Provider** metadata.
     {!saml-login-button.md!}

{tab|azuread}

{!upgrade-to-plus-if-needed.md!}

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

1. 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**.

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

1.  In the **Basic SAML Configuration** section, specify the following fields:

    * **Identifier (Entity ID)**: `https://zulipchat.com`
    * **Default**: *checked* (This is required for enabling IdP-initiated sign on.)
    * **Reply URL (Assertion Consumer Service URL)**: `https://auth.zulipchat.com/complete/saml/`

1. If you want to set up IdP-initiated sign on, in the **Basic SAML
   Configuration** section, also specify:

     * **RelayState**: `{"subdomain": "<your organization's zulipchat.com subdomain>"}`

1. Check the **User Attributes & Claims** configuration, which should already be
   set to the following. If the configuration is different, please
   indicate this when contacting [support@zulip.com](mailto:support@zulip.com)
   (see next step).

      * **givenname**: `user.givenname`
      * **surname**: `user.surname`
      * **emailaddress**: `user.mail`
      * **name**: `user.principalname`
      * **Unique User Identifier**: `user.principalname`

1. {!send-us-info.md!}

     1. Your organization's URL
     1. From the **SAML Signing Certificate** section:
        * **App Federation Metadata Url**
        * Certificate downloaded from **Certificate (Base64)**
     1. From the **Set up** section
        * **Login URL**
        * **Azure AD Identifier**
     {!saml-login-button.md!}

{tab|keycloak}

{!upgrade-to-plus-if-needed.md!}

1. Make sure your Keycloak server is up and running.

1. In Keycloak, register a new Client for your Zulip organization:
    * **Client-ID**: `https://zulipchat.com`
    * **Client Protocol**: `saml`
    * **Client SAML Endpoint**: *(empty)*

1. 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`

1. In the **Mappers** tab for your new Keycloak client:
    * Create a Mapper for the first name:
        * **Property**: `firstName`
        * **Friendly Name**: `first_name`
        * **SAML Attribute Name**: `first_name`
        * **SAML Attribute Name Format**: `Basic`
    * Create a Mapper for the last name:
        * **Property**: `lastName`
        * **Friendly Name**: `last_name`
        * **SAML Attribute Name**: `last_name`
        * **SAML Attribute Name Format**: `Basic`
    * Create a Mapper for the email address:
        * **Property**: `email`
        * **Friendly Name**: `email`
        * **SAML Attribute Name**: `email`
        * **SAML Attribute Name Format**: `Basic`

1. {!send-us-info.md!}

     1. Your organization's URL
     2. The URL of your Keycloak realm.
     {!saml-login-button.md!}

!!! tip ""

    Your Keycloak realm URL will look something like this: `https://keycloak.example.com/auth/realms/yourrealm`.

{end_tabs}

!!! tip ""

    Once SAML has been configured, consider also [configuring SCIM](/help/scim).

## Related articles

* [SAML configuration for self-hosting][saml-readthedocs]
* [SCIM provisioning](/help/scim)
* [Getting your organization started with Zulip](/help/getting-your-organization-started-with-zulip)

[saml-readthedocs]: https://zulip.readthedocs.io/en/stable/production/authentication-methods.html#saml