diff --git a/templates/zerver/help/scim.md b/templates/zerver/help/scim.md index 2395d3fe56..1aaa9a1820 100644 --- a/templates/zerver/help/scim.md +++ b/templates/zerver/help/scim.md @@ -1,62 +1,90 @@ # SCIM provisioning -SCIM (System for Cross-domain Identity Management) is an standard +{!admin-only.md!} + +SCIM (System for Cross-domain Identity Management) is a standard protocol used by Single Sign-On (SSO) services and identity providers -to provision/deprovision user accounts and groups. Zulip's SCIM -integration is currently beta and has a few limitations: +to provision/deprovision user accounts and groups. Zulip supports SCIM +integration, both in Zulip Cloud and for +[self-hosted](/help/self-hosting) Zulip servers. This page describes +how to configure SCIM provisioning for Zulip. + +Zulip's SCIM integration has the following limitations: * Provisioning Groups is not yet implemented. -* It has only been fully tested and documented with Okta. +* While Zulip's SCIM integration is generic, it has has only been + fully tested and documented with Okta's SCIM provider, and it is + possible minor adjustments may be required. [Zulip + support](/help/contact-support) is happy to help customers configure + this integration with SCIM providers that do not yet have detailed + self-service documentation on this page. -The instructions below explain how to configure SCIM in Okta for Zulip -Cloud customers. Like SAML, feature is currently only available in -Zulip Cloud with the Zulip Cloud Plus plan. +!!! warn "" + Zulip Cloud customers who wish to use SCIM integration must upgrade to + the Zulip Cloud Plus plan. Contact + [support@zulip.com](mailto:support@zulip.com) for plan benefits and pricing. -These instructions can also be used by self-hosters to set up the Okta -side of SCIM for their deployment. +## Configure SCIM -## Configure SCIM with Okta +{start_tabs} -1. Before you begin, contact [email support](mailto:support@zulip.com) to receive - the bearer token that Okta will use to authenticate to make its SCIM requests. +{tab|okta} -1. In your Okta Dashboard, go to `Applications` and choose `Browse App Catalog`. +{!upgrade-to-plus-if-needed.md!} -1. Search for `SCIM` and select `SCIM 2.0 Test App (Header Auth)`. +1. Contact [support@zulip.com](mailto:support@zulip.com) to request the + **Bearer token** that Okta will use to authenticate to your SCIM API. -1. Click `Add` and choose your `Application label`. For example, you can name it `Zulip SCIM`. +1. In your Okta Dashboard, go to **Applications**, and select + **Browse App Catalog**. -1. Continue to `Sign-On Options`. Leave the `SAML` options, as this type of Okta application - doesn't actually support `SAML` authentication, and you'll need to set up a separate Okta app - to activate `SAML` for your Zulip organization. +1. Search for **SCIM** and select **SCIM 2.0 Test App (Header Auth)**. -1. In `Credentials Details`, set `Application username format` to `Email` and - `Update application username on` to `Create and update`. +1. Click **Add** and choose your **Application label**. For example, you can + name it "Zulip SCIM". -1. The Okta app has been added. Navigate to the `Provisioning` tab. +1. Continue to **Sign-On Options**. Leave the **SAML** options as they are. + This type of Okta application doesn't actually support SAML authentication, + and you'll need to set up a separate Okta app to activate SAML for your Zulip + organization. -1. Click `Configure API Integration` and check the `Enable API integration` box. - Okta will ask you for the `Base URL` and `API token`. The `Base URL` should be - `yourorganization.zulipchat.com/scim/v2` and for `API token` you'll set the value - given to you by support. When you proceed to the next step, Okta will verify that - these details are correct by making a SCIM request to the Zulip server. +1. In **Credentials Details**, specify the following fields: + * **Application username format**: `Email` + * **Update application username on**: `Create and update` -1. In the `To App` section of the `Provisioning` tab (which should be opened by default - when you continue from the previous step), edit the `Provisioning to App` settings - to enable `Create Users`, `Update User Attributes` and `Deactivate Users`. +1. In the **Provisioning** tab, click **Configure API Integration**, check the + **Enable API integration** checkbox, and specify the following fields: + * **Base URL**: `yourorganization.zulipchat.com/scim/v2` + * **API token**: `Bearer token` (given to you by Zulip support) -1. In `Attribute Mappings`, remove all attributes except `userName`, `givenName` - and `familyName`. + When you proceed to the next step, Okta will verify that these details are + correct by making a SCIM request to the Zulip server. -1. Now the integration should be ready and you can `Assign` users to - the app to configure their Zulip accounts to be managed by - SCIM. When you assign a user, Okta will check if the account exists - in your Zulip organization and if it doesn't, the account will be - created. Changes to the user's email or name in Okta will - automatically cause the Zulip account to be updated accordingly. - Unassigning a user from the app will deactivate their Zulip - account. +1. Enable the following **Provisioning to App** settings: + * **Create Users** + * **Update User Attributes** + * **Deactivate Users** -If you want to also set up SAML authentication, head to our -[SAML configuration instructions](/help/saml-authentication). It will require -adding a separate Okta application. +1. Remove all attributes in **Attribute Mappings**, _except_ for the following: + * **userName** + * **givenName** + * **familyName** + +1. Now that the integration is ready to manage Zulip user accounts, **assign** + users to the SCIM app. + * When you assign a user, Okta will check if the account exists in your + Zulip organization. If it doesn't, the account will be created. + * Changes to the user's email or name in Okta will automatically cause the + Zulip account to be updated accordingly. + * Unassigning a user from the app will deactivate their Zulip account. + +{end_tabs} + +!!! tip "" + + Once SCIM has been configured, consider also [configuring SAML](/help/saml-authentication). + +## Related articles + +* [SAML authentication](/help/saml-authentication) +* [Getting your organization started with Zulip](/help/getting-your-organization-started-with-zulip)