SSO: Generic OpenID providers (Auth0, Azure, etc.)


Only available for on-prem users of Retool

Retool supports setting SSO with most OpenID providers (e.g. Auth0, Azure AD, etc.). 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.

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.

  1. Find your authorization and token url.

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

  1. Add Retool to your callback url

In 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.

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 admin & support roles to particular Retool permission groups:

CUSTOM_OAUTH2_SSO_ROLE_MAPPING=admin=>retool_admin_group_name, support=>retool_support_group_name

Using the auth tokens elsewhere in Retool

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.

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

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.

Updated about a month ago

SSO: Generic OpenID providers (Auth0, Azure, etc.)

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.