📘

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.

📘

Some SSO providers don't return both an ID token and access token by default. You might need to provide additional metadata during the OpenIDConnect process to obtain both tokens. These requirements are noted in the provider-specific guides below, and in the generic process to obtain a fat token.

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

6. (Optional) If you want to provide authorization to access resources when a user logs in with SSO, you need to specify the API audience that corresponds to the resource as configured in Auth0. Find the API audience in the Auth0 UI under Applications > APIs, and set it as the value of the CUSTOM_OAUTH2_SSO_AUDIENCE environment variable in your Retool deployment. For example, CUSTOM_OAUTH2_SSO_AUDIENCE = https://retool.auth0.com/api/v2

🚧

If you don't configure the CUSTOM_OAUTH2_SSO_AUDIENCE environment variable, Retool receives an opaque token, and you won't be able to use the accessToken to control access to components and resources.

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

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

9. (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 offline_access profile
CUSTOM_OAUTH2_SSO_USERINFO_URL=https://yourcompany.okta.com/oauth2/v1/userinfo
CUSTOM_OAUTH2_SSO_AUTH_URL=https://yourcompany.okta.com/oauth2/v1/authorize
CUSTOM_OAUTH2_SSO_TOKEN_URL=https://yourcompany.okta.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

Replace https://yourcompany.okta.com with your Okta domain in these three environment variables:

• CUSTOM_OAUTH2_SSO_USERINFO_URL
• CUSTOM_OAUTH2_SSO_AUTH_URL
• CUSTOM_OAUTH2_SSO_TOKEN_URL

Example walk through: Azure Active Directory

1. Create an Azure Active Directory Enterprise application

• In the Azure Active Directory admin center, add a new Enterprise application.

• Retool is not listed in the Azure AD Gallery, so you must select “Create your own application”.

  • Name the application.

  • Select Register an application to integrate with Azure AD (App you're developing).

  • Specify which tenants are allowed to use the application. For this guide, select Accounts in this organizational directory only (Default Directory Only - Single tenant).

  • Add a Web Redirect URI, specifying the path where Azure AD should redirect users after completing authentication:

    • The path in your Retool instance is /oauth2sso/callback.
    • Enter the full path for your instance, like https://retool.yourcompany.com/oauth2sso/callback.

2. Configure secrets

• In the settings for the new Retool enterprise application, access the Single sign-on menu. Click the link to go to the App registrations experience.
• Access the Certifications & secrets menu. Add a new client secret, setting an expiration period. You'll need to update your Retool deployment when the secret expires, so we recommend setting the maximum allowable period of 24 months.
• You'll provide this secret as a Retool environment variable in step six.

3. Configure optional claims

• In the Azure app registration experience, access the Token configuration menu. Add optional claims for the ID token. At a minimum, include the following claims:

  • acct
  • email
  • family_name
  • given_name

• When saving claims, turn on the Microsoft Graph email, profile permissions.

• You can optionally specify additional claims to be included in the Access token.

4. (Optional) Configure group claims

You can optionally map Azure AD groups to Retool groups to automatically assign users to groups when they authenticate using SSO. This requires adding group claims to the ID token.

In the Azure app registration experience, access the Token configuration menu. Add optional claims for the ID token:

• Choose which groups to include in the claim.
• Include the Group ID for ID, Access, and SAML.

You specify the mapping between Azure AD groups and Retool groups in a subsequent step.

5. Retrieve connection details

• In the Azure app registration experience, access the Overview menu and select Endpoints.

• Note the following information:

  • Application (client) ID
  • OAuth 2.0 authorization endpoint (v2)
  • OAuth 2.0 token endpoint (v2)

6. Configure required Retool environment variables

Add the following environment variables to your docker.env file:

• CUSTOM_OAUTH2_SSO_CLIENT_ID = Application (client) ID collected in step five
• CUSTOM_OAUTH2_SSO_AUTH_URL = OAuth 2.0 authorization endpoint (v2) collected in step five
• CUSTOM_OAUTH2_SSO_TOKEN_URL = OAuth 2.0 token endpoint (v2) collected in step five
• CUSTOM_OAUTH2_SSO_CLIENT_SECRET = Client secret generated in step two
• CUSTOM_OAUTH2_SSO_SCOPES=openid profile email offline_access
• CUSTOM_OAUTH2_SSO_JWT_EMAIL_KEY=idToken.email

7. Configure optional Retool environment variables

If you want to transmit the user's first name and last name to Retool, set the following environment variables:

• CUSTOM_OAUTH2_SSO_JWT_FIRST_NAME_KEY=family_name
• CUSTOM_OAUTH2_SSO_JWT_LAST_NAME_KEY=given_name

If you configured group claims in step four, construct a role mapping string to map Azure AD group object IDs to Retool group names. Find Azure AD group object IDs in the Azure Groups application.

For example, let's say you have an Azure AD group called "Retool Editors" with an object ID of fd951-f454-4b7a. All members of this group should be assigned to the "Editor" group in Retool. Your role mapping string would be fd951-f454-4b7a -> editor.

Set the following environment variables to complete the process:

• CUSTOM_OAUTH2_SSO_ROLE_MAPPING = Role mapping string
• CUSTOM_OAUTH2_SSO_JWT_ROLES_KEY=idToken.groups

8. (Optional, but recommended) Turn on JIT User Provisioning

Just in time (JIT) user provisioning enables Retool to provision user accounts when users sign in for the first time. This means you won't have to manually invite each user to Retool first. To turn this on, toggle the switch on the Settings > Advanced page.

9. Test the integration

• Navigate to the /auth/login page for your Retool instance.
• Click the Sign in with SSO button.
• Retool redirects you to login.microsoft.com where you are prompted for credentials.
• After entering credentials for a user who is assigned to the Retool app in Azure, you are redirected back to Retool and logged into the instance.
• In the Retool app editor mode, confirm that an idToken and accessToken are available as keys on the current_user.metadata object.

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.

Referencing JWT claims in Retool applications

You can use JWT claims returned by your SSO provider to personalize Retool apps or control component permissions. Retool automatically includes these claims as the values of the current_user.metadata.idToken and current_user.metadata.accessToken keys. 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:

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.