📘

Only available for Enterprise 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.

❗️

Necessary Environment Variables

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

CUSTOM_OAUTH2_SSO_CLIENT_ID
CUSTOM_OAUTH2_SSO_CLIENT_SECRET
CUSTOM_OAUTH2_SSO_SCOPES
CUSTOM_OAUTH2_SSO_AUTH_URL
CUSTOM_OAUTH2_SSO_TOKEN_URL
CUSTOM_OAUTH2_SSO_JWT_EMAIL_KEY

Example walk through: Google

Suppose we want to set up SSO with Auth0 for an instance of Retool running on https://retool.foocorp.com

1. Create a new Google OAuth Client ID

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

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

4. Obtain your Client ID and Client Secret

5. 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_CLIENT_ID=22222222222-dq62o6pidgmgrem34fb07klc8qa1308t.apps.googleusercontent.com
CUSTOM_OAUTH2_SSO_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxx
CUSTOM_OAUTH2_SSO_SCOPES=openid email profile https://www.googleapis.com/auth/userinfo.profile
CUSTOM_OAUTH2_SSO_AUTH_URL=https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&prompt=consent
CUSTOM_OAUTH2_SSO_TOKEN_URL=https://oauth2.googleapis.com/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
CUSTOM_OAUTH2_SSO_ACCESS_TOKEN_LIFESPAN_MINUTES=45

📘

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

1. Obtain your Client ID and Client Secret

2. Find your OAuth Authorization URL and OAuth 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.

Example walk though: Okta

1. Create a new app integration

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

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

3. Copy Client ID & Client Secret from Okta and set environment variables on your Retool instance.

CUSTOM_OAUTH2_SSO_CLIENT_ID=XXXXXXXXXX
CUSTOM_OAUTH2_SSO_CLIENT_SECRET=XXXXXXXXXX
CUSTOM_OAUTH2_SSO_SCOPES=openid email
CUSTOM_OAUTH2_SSO_AUTH_URL=https://XXXXXXXXXX.oktapreview.com/oauth2/v1/authorize
CUSTOM_OAUTH2_SSO_TOKEN_URL=https://XXXXXXXXXX.oktapreview.com/oauth2/v1/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
CUSTOM_OAUTH2_SSO_ACCESS_TOKEN_LIFESPAN_MINUTES=720
#CUSTOM_OAUTH2_SSO_JWT_ROLES_KEY=
#CUSTOM_OAUTH2_SSO_ROLE_MAPPING = devops -> admin, support -> viewer

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_JWT_ROLES_KEY=roles_key_in_your_JWT
CUSTOM_OAUTH2_SSO_ROLE_MAPPING=devops -> admin, support -> viewer

Examples of how this might work

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

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

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

5. Fill out the form for the new scope

6. Navigate to the Claims tab and press Add Claim

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

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

CUSTOM_OAUTH2_SSO_JWT_ROLES_KEY=idToken.groups

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

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

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:

CUSTOM_OAUTH2_SSO_USERINFO_URL=https://your-company.okta.com/oauth2/v1/userinfo

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