snapshot of https://github.com/zulip/zulip.git @ 48c69911c7dd4e03b20552eb3bd77ad8151c1357 (2026-09-15)

docs/production/scim.md

@@ -0,0 +1,111 @@
+# 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](https://zulip.com/help/scim) for
+documentation on SCIM in [Zulip Cloud](https://zulip.com) 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](docker.md), 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.
+
+1. Configure the Zulip server by adding a `SCIM_CONFIG` block to your
+   `/etc/zulip/settings.py`:
+
+   ```python
+   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.
+
+1. Now you can proceed to [configuring your SCIM IdP](https://zulip.com/help/scim).
+   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:
+
+  ```python
+  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:
+
+  ```python
+  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.