Provision users with SCIM

SCIM, or System for Cross-domain Identity Management, is the industry standard for automatically provisioning user accounts. It's useful when companies use a third party SSO provider like Okta or Azure Active Directory to manage employee authentication because user accounts can automatically be created / updated / deactivated in other applications like Retool.

Requirements

To use SCIM provisioning, Retool needs to be at least at version 2.32.1.

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

SCIM works like this: let's say you've added Retool as an application in your SSO provider. Once you assign the application to a user then an account in Retool is automatically created. That happens because the SSO provider makes an API request to Retool and tells Retool to create a new account for John.

To make sure that accounts can't be created by anybody, Retool uses a Bearer Token authentication scheme. All that means is you need to define a secret that only Retool and your SSO provider knows. To do that, add this new environment variable in your Retool environment.

SCIM_AUTH_TOKEN=A_SECRET_TOKEN

🚧

The secret must be at least 10 characters long

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

Once you've defined that environment variable, you can test it out by opening up https://yourRetoolAppDomain/api/scim/v2/Schemas. There, you should see a special 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.

Okta Specific Guide

Supported Features

• Create Users: New or existing users in Okta will be pushed to Retool as new users.
• Update User Attributes: Updates to user profiles in Okta will be pushed to Retool.
• Deactivate Users:Users deactivated in Okta will be automatically disabled in the Retool. They are immediately logged out and will also not count towards the billable user count. If a user is reactivated, they will 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.

Requirements

To enable this feature you must be able to configure the environment variables of the Retool application. Create a new environment variable like below:

SCIM_AUTH_TOKEN=A_SECRET_TOKEN

The secret token must be at least 10 characters long. After modifying the environment variables, restart the Retool container.

Configuration Steps

• Add the Retool application to your Okta account
• Please 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

The Okta integration will automatically prefix the URL with https

• Once added, go to the Provisioning tab and click “Configure API Integration”
• Tick the “Enable API integration” box, and enter in "{your scim auth token}" as the API token
• Click “Test API credentials” to ensure the connection is working

📘

Do not include a Bearer prefix in the Auth Token

The Okta integration will automatically prefix the token with Bearer

• Click “Save” to enable provisioning for the Retool app
• You will now activate the desired provisioning features. In the provisioning settings for the app, under “To App”, click “Edit” and enable the “Create Users”, “Update User Attributes” and “Deactivate Users”. Click “Save” to save your settings.

That's it! You can now start assigning users to the Retool app and they will be automatically created in Retool.

Enabling 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. Login 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 on Integration
6. Click on Edit and then Test API Credentials and then click Save
   Note, 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.