Skip to main content

Provision users with SCIM

Learn how to implement SCIM user provisioning with Okta or Microsoft Entra ID.

SCIM, or System for Cross-domain Identity Management, is the industry standard for automatically provisioning user accounts. It's useful when using a third-party SSO provider for authentication, such as Okta, because it allows you to automatically create, update, and deactivate user accounts in applications such as Retool.

See the SCIM reference to learn how to make requests to the SCIM endpoints Retool implements.

SCIM user provisioning can modify group memberships when requests are made. During initial configuration, test SCIM user provisioning on a non-admin user or verify that a separate admin can log in with an alternate authentication method to avoid losing admin access.

Requirements​

You can use SCIM provisioning on Retool Cloud or self-hosted Retool versions 2.32.1 and later.

If you use Okta, follow the configuration steps to create an application. If you use another provider, see the documentation for your SSO provider to learn how to add Retool as an application.

If your Retool instance is behind a firewall and you use Okta, add Okta's IP addresses to your allowlist so it can connect to Retool. Optionally, you can add a rule to your load balancer to only expose the needed paths: /api/scim/v2/*.

SCIM server authentication​

To use SCIM, you first add Retool as an application in your SSO provider. After you assign the application to a user, an account in Retool is automatically created. That happens because your SSO provider makes an API request to Retool and instructs Retool to create an account for your user.

To ensure accounts are only created by authorized users, Retool uses a Bearer Token authentication scheme. You define a secret that only Retool and your SSO provider know.

Generate tokens in Retool​

You can create API tokens with the SCIM API scope in the API settings for your organization.

  1. Go to Settings > API and click Create new to generate an access token.
  2. Enter a name and description, then select the required scopes.
  3. Copy and save your token, as you can only access it once.
Create a SCIM access token

Create tokens outside of Retool​

On self-hosted Retool versions earlier than 3.4.0, generate your own token and set it as the SCIM_AUTH_TOKEN token environment variable.

SCIM_AUTH_TOKEN=A_SECRET_TOKEN

The SCIM API endpoints that Retool makes available are highly sensitive and should be protected. Use a long and secure secret token that nobody can guess.

After creating your token, restart your Retool instance.

Test your token​

After creating your token, test it by opening https://yourRetoolAppDomain/api/scim/v2/Schemas. There, you should see an error that looks like this:

{"detail":"SCIM request not authorized","schemas":["urn:ietf:params:scim:api:messages:2.0:Error"]}

After that's been set, only requests to Retool's SCIM API with the header Authorization: Bearer YOUR_SECRET_TOKEN will be accepted.

Microsoft Entra ID requirements​

In Microsoft Entra ID, you must add aadOptscim062020 to your Tenant URL for your requests to be SCIM 2.0 compliant and work in Retool. See the Microsoft Entra ID documentation for more.

Okta-specific requirements​

When using Okta as an SSO provider, the SCIM API offers the following features:

  • Create Users: New or existing users in Okta are pushed to Retool as new users.
  • Update User Attributes: Updates to user profiles in Okta are pushed to Retool.
  • Deactivate Users: Users deactivated in Okta are automatically disabled in Retool. They are immediately logged out and do not count towards the billable user count. If a user is reactivated, they regain access to Retool and keep all previously specified access controls.
  • Importing Users: Users that are created manually in Retool can be imported into Okta as Okta users.
  • Group Push: Group Push lets you take existing Okta groups and their memberships and push them to Retool.

Configuration steps​

Before you begin, create an access token.

  1. In Okta, add the Retool application to your Okta account.

  2. Enter your Retool domain in the following format: YOUR.RETOOL.INSTANCE.COM. For example, if you log into https://YOUR.RETOOL.INSTANCE.COM/, enter: YOUR.RETOOL.INSTANCE.COM”.

Do not include the https:// prefix in the Retool domain—it is automatically included.

  1. Go to the Provisioning tab and click Configure API Integration.

  2. Enable the Enable API integration setting, and enter your Retool SCIM API access token.

  3. Click Test API credentials to ensure the connection is working.

Do not include a Bearer prefix in the Auth Token as this is automatically included.

  1. Click Save to enable provisioning for the Retool app.

  2. Activate the desired provisioning features. In the provisioning settings for the app, under To App, click Edit and enable Create Users, Update User Attributes, and Deactivate Users. Save your settings.

  3. If you use Retool user attributes and want to connect Okta custom attributes to the metadata user attribute, set External namespace to metadata on the Okta custom attribute.

You can now start assigning users to the Retool app and they will be automatically created in Retool.

Enable group push​

If you're setting up Okta for the first time, you will get access to Group Push with the rest of the Okta SCIM features, and you can ignore the rest of this guide. If you've already set up Retool with Okta, you will have to re-authenticate your account to enable Group Push. To do this, follow these steps.

  1. Log in to your Okta org as an Admin.
  2. Open the Admin UI.
  3. Open your Retool application instance.
  4. Go to the Provisioning tab.
  5. On the Settings sidebar, click Integration.
  6. Click Edit and then Test API Credentials, and then click Save. If you've followed the Configuration Steps of this guide, your credentials should already be in the Integration section.

SCIM should now be enabled for your Retool instance.

Push to default Retool groups​

This feature is available on self-hosted Retool versions 2.94 and later.

You cannot rename Retool's default groups using SCIM group mapping, but you can map your custom groups to the four default Retool groups (admin, editor, viewer, All Users). Okta is used as an example, but a similar process also works for other identity providers.

  1. Follow instructions in Okta to import groups using the Import Now button. After importing, the four Retool default groups show in Okta as Retool production - [group name]. These groups are read-only in Okta.

  2. To push custom Okta groups to Retool default groups, follow the Okta instructions. Check Push group members immediately if you want to immediately sync group memberships.

  3. If you disabled the automatic push in step 2, you can manually push your groups. Confirm your group has a Push Status of Active in the Push Groups tab.

  4. Log in to Retool and go to the Users page to verify your group members are synced.