SSO with generic OpenID providers

Configure SSO for providers like Auth0 and Okta.


Only available for Enterprise on-prem users of Retool

Retool supports SSO with most OpenID providers. On top of this, Retool also supports reusing the authentication tokens obtained through the SSO process in other API calls.

Setting up single sign on

Retool's OpenID integration utilizes the Authorization Code Flow. Retool, at minimum, expects either an id token or access token to be a JWT that will contain the email of the user being authenticated.

Before you get started, you'll need the following information:

  • The Client ID for your application
  • The Client Secret for your application
  • A list of scopes that you'll want to grant to Retool
  • The "authorization url" for your OpenID provider
  • The "token url" for your OpenID provider

Besides this, you'll also want to check how your SSO provider formats the id token or access token. Retool will attempt to decode the id token and access token as if they were JWTs. You will need to provide Retool the path in the decoded JWT that corresponds with your user's identifying information.

Finally, you'll want to add https://your.retool.instance/oauth2sso/callback as a callback URL for your application.

Necessary Environment Variables

In order for Retool to show the "Login with SSO" button, you must have all of the following environment variables set:


Example walk through: Google

Suppose we want to set up SSO with Auth0 for an instance of Retool running on

  1. Create a new Google OAuth Client ID

  1. You might be asked to configure an OAuth consent screen. If that is required, you should simply select "Internal"

  2. Configure the app as a Web Application and with the correct redirect URI

  1. Obtain your Client ID and Client Secret

  1. Take this information and translate them to environment variables for Retool:

Here's an example of how you might configure your SSO integration:
CUSTOM_OAUTH2_SSO_SCOPES=openid email profile


A few non-standard options

Google requires the URL parameters access_type=offline and prompt=consent in order to obtain refresh tokens. This is why the CUSTOM_OAUTH2_SSO_AUTH_URL variable includes both of those in the URL. Google's tokens also expire after 1 hour. By default, our integration refreshes tokens if they are older than 2 hours. For this reason, we've also set the CUSTOM_OAUTH2_SSO_ACCESS_TOKEN_LIFESPAN_MINUTES variable to 45 in order to refresh the tokens more frequently.

Example walk through: Auth0

Suppose we want to set up SSO with Auth0 for an instance of Retool running on

  1. Obtain your Client ID and Client Secret

In Auth0, this is found in the Settings section of your application.In Auth0, this is found in the Settings section of your application.

  1. Find your OAuth Authorization URL and OAuth Token URL

In Auth0, this is found in Settings -> Advanced Settings -> EndpointsIn Auth0, this is found in Settings -> Advanced Settings -> Endpoints

  1. Add Retool to your callback url

In Auth0, this is found in Settings -> Application URIsIn Auth0, this is found in Settings -> Application URIs

  1. Get an example ID Token and see what it looks like:

For example, with Auth0, ID Tokens look like this:


Which when decoded, look like this:

  "given_name": "Foo",
  "family_name": "Bar",
  "nickname": "foobar",
  "name": "Foo Bar",
  "picture": "",
  "locale": "en",
  "updated_at": "2020-09-25T06:59:30.208Z",
  "email": "[email protected]",
  "email_verified": true,
  "iss": "",
  "sub": "google-oauth2|11111111111111",
  "aud": "YourClientID",
  "iat": 1601017170,
  "exp": 1601353170

We see here that the email field is what we'll want to use to identify the user, and that the given_name and family_name correspond to the user's first and last name.

  1. Take this information and translate them to environment variables for Retool:

Here's an example of how you might configure the Auth0 app:

CUSTOM_OAUTH2_SSO_CLIENT_SECRET = xxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
CUSTOM_OAUTH2_SSO_SCOPES = openid email profile offline_access 

If desired you can also provide a custom audience using the CUSTOM_OAUTH2_SSO_AUDIENCE environment variable.

  1. Restart your Retool container with the environment variables, and you should now have SSO set up.

  2. (Optional) As an Admin, you can enable just-in-time (JIT) user provisioning under Organization settings -> Advanced if you do not wish to provision users manually.

  3. (Optional) Set the environment variable TRIGGER_OAUTH_2_SSO_LOGIN_AUTOMATICALLY=true if you would like users to automatically be prompted with the Oauth 2.0 authorization screen.

Example walk though: Okta

  1. Create a new app integration

Set Sign-on method to OIDC and Application type to Web Application.

Creating a new app integrationCreating a new app integration

  1. Set Sign-in redirect URIs to your Retool instance

  1. Copy Client ID & Client Secret from Okta and set environment variables on your Retool instance.
CUSTOM_OAUTH2_SSO_SCOPES=openid email offline_access profile
#CUSTOM_OAUTH2_SSO_ROLE_MAPPING = devops -> admin, support -> viewer

Replace with your Okta domain in these three environment variables:


Role Mapping

You can map the roles returned from the OpenID response to your Retool permission groups using environment variables.

Here's an example that maps the DevOps & support roles to particular Retool permission groups:

CUSTOM_OAUTH2_SSO_ROLE_MAPPING=devops -> admin, support -> viewer

Examples of how this might work

List of roles

Role mapping variable


["admin", "editor"]


The user is placed in the admin, editor, and "All Users" groups



The user is placed in the "All Users" group

["admin", "support"]


A new custom group called "support" is created.

The user is placed in the "admin", "support", and "All Users" group

["support", "devops"]

"devops -> editor"

A new custom group called "support" is created.

The user is placed in the "editor", "support", and "All Users" group.

Guide on how to use this with Okta Group Claims

  1. Switch to using the Classic Okta Admin UI

  2. From the Security navigation dropdown, select API to go to the API Dashboard

  1. Edit the Authorization Server that Retool is integrating with by clicking the pencil icon

  1. Select the Scopes tab and press "Add Scopes"

  1. Fill out the form for the new scope

  1. Navigate to the Claims tab and press Add Claim

  1. Fill out the Add Claim form.

You can customize the "Filter" option to whatever you like. In this screenshot, we are including any group that starts with "Retool." Note that in Okta, the "Starts with" filter is case insensitive.

  1. Modify your SSO configuration

Add the groups scope to the CUSTOM_OAUTH2_SSO_SCOPES environment variable

CUSTOM_OAUTH2_SSO_SCOPES=openid email profile offline_access groups

Specify that the groups can be read in the idToken


Specify any additional remapping you'd like to do. For example, if you'd like any member of the "Retool devops" group to also be an admin in Retool:

CUSTOM_OAUTH2_SSO_ROLE_MAPPING=Retool devops -> admin

You can refer to these tokens using the following syntax in resources:

%USER_OAUTH2_ACCESS_TOKEN% will be replaced with the access token obtained in the auth flow
%USER_OAUTH2_ID_TOKEN% will be replaced with the id token obtained in the auth flow
  1. Test it!

Try logging in as another user and checking if the permissions were correctly updated automatically.

Using the JWTs obtained from the auth flow in resources

One benefit of using this integration is that this makes it possible for you to re-use the tokens obtained throughout the SSO process in API calls you make from Retool to your backend services.

Here's an example of how you can set headers using these variables


Refreshing the tokens

If your OpenID Provider returned a refresh token in the initial login flow, Retool will automatically use it to refresh the access and id tokens every two hours by default. You can set a custom refresh time using the CUSTOM_OAUTH2_SSO_ACCESS_TOKEN_LIFESPAN_MINUTES environment variable.

Referencing ID token claims in Retool applications

You can use ID token claims returned by your SSO provider to personalize Retool apps or control component permissions. Retool automatically includes these claims as the value of the current_user.metadata.idToken key. Access them using curly braces anywhere in your Retool app: {{current_user.metadata.idToken.picture}}

Thin tokens and fat tokens

Some OIDC Identity Providers don't send all the claims associated with a user during the authentication flow. This is called a "thin token" and is used in place of a "fat token" for performance reasons. If you find that the id token returned is lacking certain claims, you need to tell Retool to make an additional request to the /userinfo endpoint to grab the fat token.

You do this by setting an additional environment variable:


During the authentication flow, Retool will replace the thin token with the fat token returned from this endpoint.

Did this page help you?