📘

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 https://retool.foocorp.com

1. Obtain your Client ID and Client Secret

2. Find your authorization and token url.

3. Add Retool to your callback url

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

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

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnaXZlbl9uYW1lIjoiRm9vIiwiZmFtaWx5X25hbWUiOiJCYXIiLCJuaWNrbmFtZSI6ImZvb2JhciIsIm5hbWUiOiJGb28gQmFyIiwicGljdHVyZSI6Imh0dHBzOi8vZm9vLmJhciIsImxvY2FsZSI6ImVuIiwidXBkYXRlZF9hdCI6IjIwMjAtMDktMjVUMDY6NTk6MzAuMjA4WiIsImVtYWlsIjoiZm9vYmFyQGZvb2NvcnAuY29tIiwiZW1haWxfdmVyaWZpZWQiOnRydWUsImlzcyI6Imh0dHBzOi8vcmV0b29sLmF1dGgwLmNvbS8iLCJzdWIiOiJnb29nbGUtb2F1dGgyfDExMTExMTExMTExMTExIiwiYXVkIjoiWW91ckNsaWVudElEIiwiaWF0IjoxNjAxMDE3MTcwLCJleHAiOjE2MDEzNTMxNzB9.15ZdZH2R06JuCcI_rDoz55h8QIh4xCQlQWAnWcf72hg

Which when decoded, look like this:

{
  "given_name": "Foo",
  "family_name": "Bar",
  "nickname": "foobar",
  "name": "Foo Bar",
  "picture": "https://foo.bar",
  "locale": "en",
  "updated_at": "2020-09-25T06:59:30.208Z",
  "email": "[email protected]",
  "email_verified": true,
  "iss": "https://retool.auth0.com/",
  "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.

5. 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_ID = yypLZ44LxEz0XlQZBu5k2Nq9XsdOv4f5 
CUSTOM_OAUTH2_SSO_CLIENT_SECRET = xxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
CUSTOM_OAUTH2_SSO_SCOPES = openid email profile offline_access 
CUSTOM_OAUTH2_SSO_AUTH_URL = https://retool.auth0.com/authorize 
CUSTOM_OAUTH2_SSO_TOKEN_URL = https://retool.auth0.com/oauth/token 
CUSTOM_OAUTH2_SSO_JWT_EMAIL_KEY = idToken.email 
CUSTOM_OAUTH2_SSO_JWT_FIRST_NAME_KEY = idToken.given_name 
CUSTOM_OAUTH2_SSO_JWT_LAST_NAME_KEY = idToken.family_name

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

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

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

8. (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_JWT_ROLES_KEY=roles_key_in_your_JWT
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.