upstream-zulip/docs/production/scim.md

SCIM provisioning

Zulip has beta support for user provisioning and deprovisioning via the SCIM protocol. In SCIM, a third-party SCIM Identity Provider (IdP) acts as the SCIM client, connecting to the service provider (your Zulip server).

See the SCIM help center page for documentation on SCIM in Zulip Cloud as well as detailed documentation for how to configure some SCIM IdP providers.

Synchronizing groups via SCIM is currently not supported.

Server configuration

:::{important}

If you are using Docker, set SCIM_CONFIG via the SETTING_SCIM_CONFIG environment variable; see {doc}docker:how-to/compose-settings.

:::

The Zulip server-side configuration is straightforward:

1. Pick a client name for your SCIM client. This name is internal to your Zulip configuration, so the name of your IdP provider is a good choice. We'll use okta in the examples below.

2. Configure the Zulip server by adding a SCIM_CONFIG block to your /etc/zulip/settings.py:

   SCIM_CONFIG = {
       "subdomain": {
           "bearer_token": "<secret token>",
           "scim_client_name": "okta",
           "name_formatted_included": False,
       }
   }
   

   The bearer_token should contain a secure, secret token that you generate. You can use any secure password generation tools for this, such as the apg command included by default in some Linux distributions. For example, apg -m20 will generate some passwords of minimum length 20 for you.

   Make sure to restart the server after editing your settings, by running /home/zulip/deployments/current/scripts/restart-server.

   The SCIM IdP will authenticate its requests to your Zulip server by sending an Authorization header like this: Authorization: Bearer <secret token>. name_formatted_included needs to be set to False for Okta. It tells Zulip whether the IdP includes name.formatted in its User representation.

3. Now you can proceed to configuring your SCIM IdP. Use the value Bearer <secret token> using the bearer_token you've generated earlier as the API token that the SCIM IdP will ask for when configuring authentication details.

Additional options

• To enable the creation of guest accounts without automatically subscribing them to any initial channels, add "create_guests_without_streams": True to your client's config dict in SCIM_CONFIG. This option is particularly useful for organizations that prefer to manually invite new guest users to the appropriate channels.

  Example configuration with the additional option:

  SCIM_CONFIG = {
     "subdomain": {
        "bearer_token": "<secret token>",
        "scim_client_name": "okta",
        "name_formatted_included": False,
        "create_guests_without_streams": True,
     }
  }
  

• To sync custom profile fields from the SCIM IdP, add "custom_profile_field_map" to your client's config dict. This is a dictionary mapping Zulip custom profile field names to SCIM attribute names. A custom profile field is represented for this feature by its user-facing name in lowercase with spaces replaced by underscores (e.g., "Phone number" is represented by phone_number).

  Example configuration with custom profile field syncing:

  SCIM_CONFIG = {
     "subdomain": {
        "bearer_token": "<secret token>",
        "scim_client_name": "okta",
        "name_formatted_included": False,
        "custom_profile_field_map": {
            # Phone number
            "phone_number": "phoneNumber",
            # Birthday
            "birthday": "birthday",
        },
     }
  }
  

  With this configuration, when the SCIM IdP sends a phoneNumber attribute in a User request, its value will be synced to the "Phone number" custom profile field in Zulip. The custom profile fields referenced must already exist in the Zulip organization settings.