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. LaboChat supports SCIM integration, both in LaboChat Cloud and for self-hosted LaboChat servers. This page describes how to configure SCIM provisioning for LaboChat.

LaboChat Cloud customers who wish to use this feature must upgrade to the LaboChat Cloud Plus plan.

Tip: While LaboChat’s SCIM integration is generic, we’ve only fully documented the setup process with the Okta and Microsoft EntraID SCIM providers. LaboChat support is happy to help customers configure this integration with SCIM providers that do not yet have detailed self-service documentation on this page.

Configure SCIM

Okta

1. Make sure your LaboChat Cloud organization is on the LaboChat Cloud Plus plan.
2. Contact support@zulip.com to request the Bearer token that Okta will use to authenticate to your SCIM API.
3. In your Okta Dashboard, go to Applications, and select Browse App Catalog.
4. Search for SCIM and select SCIM 2.0 Test App (Header Auth).
5. Click Add and choose your Application label. For example, you can name it “LaboChat SCIM”.
6. 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 LaboChat organization.
7. In Credentials Details, specify the following fields:
   • Application username format: Email
   • Update application username on: Create and update
8. In the Provisioning tab, click Configure API Integration, check the Enable API integration checkbox, and specify the following fields:
   • Base URL for LaboChat Cloud: https://your-org.zulipchat.com/scim/v2
   • Base URL for self-hosting: https://zulip.example.com/scim/v2
   • API token: Bearer <token> (given to you by LaboChat support) When you proceed to the next step, Okta will verify that these details are correct by making a SCIM request to the LaboChat server.
9. Enable the following Provisioning to App settings:
   • Create Users
   • Update User Attributes
   • Deactivate Users
10. Remove all attributes in Attribute Mappings, except for the following:
    • userName
    • givenName
    • familyName
11. 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.
12. Now that the integration is ready to manage LaboChat user accounts, assign users to the SCIM app.
    • When you assign a user, Okta will check if the account exists in your LaboChat organization. If it doesn’t, the account will be created.
    • Changes to the user’s email or name in Okta will automatically cause the LaboChat account to be updated accordingly.
    • Unassigning a user from the app will deactivate their LaboChat account.

Microsoft Entra ID

1. Make sure your LaboChat Cloud organization is on the LaboChat Cloud Plus plan.
2. Contact support@zulip.com to request the Secret Token that Entra will use to authenticate to your SCIM API.
3. Sign in to the Microsoft Entra admin center.
4. Go to Identity -> Applications -> Enterprise applications.
5. Select New application -> Create your own application.
6. Complete the form:
   • Enter a name for your application.
   • Select the option Integrate any other application you don’t find in the gallery.
   • Click Add to create the new app. It will be added to your Enterprise applications.
7. Continue to the app’s management screen and click Provisioning in the left panel.
8. In the Provisioning Mode menu, select Automatic and specify the following fields:
   • Tenant URL for LaboChat Cloud: https://your-org.zulipchat.com/scim/v2/?aadOptscim062020.
   • Tenant URL for self-hosting: https://zulip.example.com/scim/v2/?aadOptscim062020. The ?aadOptscim062020 part of it is a feature flag that needs to be added to ensure SCIM compliance by Entra ID.
   • Secret Token: <token> (given to you by LaboChat support)
9. Click Test Connection.
10. In the Mappings section, there are two sets of attribute mappings: one for Users and one for Groups. Make sure to set Provision Microsoft Entra ID Groups to be disabled. Provisioning of Groups is currently not supported in LaboChat.
11. In Provision Microsoft Entra ID Users, configure the necessary mappings:
    • Change userName to map to mail. Important: You need mail to be set for all your users or trying to assign them to the app will fail.
    • Delete the other default entries leaving only the active and name.formatted mappings, until your list looks like the image below.
12. Once your configuration is complete, set the Provisioning Status to On and then click Save to start the Microsoft Entra provisioning service.
13. Now you can proceed to the Users and groups tab, where you can assign users to be provisioned via this integration.
14. Wait for the initial provisioning cycle to be started by Entra. This might take up to 40 minutes. This delay is entirely inside Entra, and not under LaboChat’s control. You can also use Provision on demand in Entra to cause immediate SCIM provisioning for specific users, which is handy when testing the integration.

Tip: Once SCIM has been configured, consider also configuring SAML.

Synchronizing group membership with SCIM

You can enable group sync for any of your SCIM provider’s groups. When you do, the SCIM integration will create a user group in LaboChat with the matching name and user memberships. When you add or remove users from the group in your SCIM provider, these changes will immediately be reflected in group memberships in LaboChat.

In order to ensure consistent state, do not modify the name or user memberships of SCIM-managed groups inside of LaboChat. Such groups are meant to be managed in your SCIM provider. Changes made on the LaboChat side will not be reflected in your SCIM provider, and instead will cause the state of the LaboChat group to become inconsistent with the state of the SCIM provider’s group.

LaboChat supports adding user groups to other groups, but some SCIM providers (including Okta) do not. As a result, this concept is also not supported in LaboChat’s SCIM integration. If you want to use nested groups, you can add groups to other groups in LaboChat and manage the individual members of each subgroup in your SCIM provider.

Okta

1. Follow the instructions above to configure SCIM.
2. Rename any LaboChat groups that have the same names as groups that you want to sync. If you push a group whose name matches an existing LaboChat group, the request will fail.
3. Open the Application you set up above for the LaboChat SCIM integration, and go to the Push groups tab. This menu allows you to choose the Okta groups which should be synchronized with LaboChat’s user groups.

SCIM DELETE requests are not supported for groups. To Unlink a group in Okta from the LaboChat SCIM integration, select Leave the group in the target app. The Delete the group in the target app option is not supported.

Related articles

• SAML authentication
• Moving to LaboChat