SCIM provisioning
This feature is only available to organization owners and administrators.
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 supports SCIM
integration, both in Zulip Cloud and for self-hosted
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.
- While Zulip's SCIM integration is generic, it has only been
fully tested and documented with Okta's SCIM provider, and it is
possible minor adjustments may be required. Zulip
support is happy to help customers configure
this integration with SCIM providers that do not yet have detailed
self-service documentation on this page.
Zulip Cloud customers who wish to use this feature must upgrade to
the Zulip Cloud Plus plan.
-
Make sure your Zulip Cloud organization is on the Zulip Cloud
Plus plan.
-
Contact support@zulip.com to request the
Bearer token that Okta will use to authenticate to your SCIM API.
-
In your Okta Dashboard, go to Applications, and select
Browse App Catalog.
-
Search for SCIM and select SCIM 2.0 Test App (Header Auth).
-
Click Add and choose your Application label. For example, you can
name it "Zulip SCIM".
-
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.
-
In Credentials Details, specify the following fields:
- Application username format:
Email
- Update application username on:
Create and update
-
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)
When you proceed to the next step, Okta will verify that these details are
correct by making a SCIM request to the Zulip server.
-
Enable the following Provisioning to App settings:
- Create Users
- Update User Attributes
- Deactivate Users
-
Remove all attributes in Attribute Mappings, except for the following:
- userName
- givenName
- familyName
-
Optional: If you'd like to also sync user role,
you can do it by adding a custom attribute in Okta. Go to the Profile Editor,
click into the entry of the SCIM app you've just set up and Add Attribute.
Configure the following:
- Data type:
string
- Variable name:
role
- External name:
role
- External namespace:
urn:ietf:params:scim:schemas:core:2.0:User
With the attribute added, you will now be able to set it for your users directly
or configure an appropriate Attribute mapping in the app's Provisioning
section.
The valid values are: owner, administrator, moderator, member, guest.
-
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.
Related articles