Documentation

Welcome to Retool! We're a fast way to build custom internal software.

You'll find the 5 minute demo, quickstart guide, and documentation for each of our connectors and components here. If you've got any questions -- chat with us on the bottom right!

Get Started    Guides

SCIM User Provisioning

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 Active Directory to manage employee authentication because user accounts can automatically be created / updated / deactivated in other applications like Retool!

To be able to use this feature, Retool needs to be at least at version 2.32.1.

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 that you need to define a secret that only Retool and your SSO provider knows. To do that, just add new environment variable in your Retool's 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 and you should see a special error that looks like this:

{"detail":"Not Found","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.

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.

Known Issues / Troubleshooting

n/a

This integration with Okta is currently under development and is not available to customers yet.
Contact to learn more.