mirror of https://github.com/zulip/zulip.git
help center: Update "SCIM provisioning" page.
Updates page to match help center documentation patterns, and to use the newly added macros. Fixes: #22890.
This commit is contained in:
David Rosa
Tim Abbott
parent
e747fa893d
commit
0bd3f1dce2
|
|
@ -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)
|
||||
|
|
|
|||
Loading…
Reference in New Issue