SSO with OpenID providers
Configure SSO for providers like Google, Auth0, Okta, and Azure AD.
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 walkthrough: Google
Suppose we want to set up SSO with Google for an instance of Retool running on https://retool.foocorp.com
- Create a new Google OAuth Client ID
-
You might be asked to configure an OAuth consent screen. If that is required, you should simply select "Internal"
-
Configure the app as a Web Application and with the correct redirect URI
- Obtain your Client ID and Client Secret
- 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
andprompt=consent
in order to obtain refresh tokens. This is why theCUSTOM_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 theCUSTOM_OAUTH2_SSO_ACCESS_TOKEN_LIFESPAN_MINUTES
variable to 45 in order to refresh the tokens more frequently.
Example walkthrough: Auth0
Suppose we want to set up SSO with Auth0 for an instance of Retool running on https://retool.foocorp.com
- Obtain your Client ID and Client Secret
- Find your OAuth Authorization URL and OAuth Token URL
- Add Retool to your callback url
- 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.
- 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
- (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 theaccessToken
to control access to components and resources.
-
Restart your Retool container with the environment variables, and you should now have SSO set up.
-
(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.
-
(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 walkthough: Okta
- Create a new app integration
Set Sign-on method to OIDC and Application type to Web Application.
- Set Sign-in redirect URIs to your Retool instance
- 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 walkthrough: 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
.
- The path in your Retool instance is
-
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 fiveCUSTOM_OAUTH2_SSO_AUTH_URL
= OAuth 2.0 authorization endpoint (v2) collected in step fiveCUSTOM_OAUTH2_SSO_TOKEN_URL
= OAuth 2.0 token endpoint (v2) collected in step fiveCUSTOM_OAUTH2_SSO_CLIENT_SECRET
= Client secret generated in step twoCUSTOM_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=idToken.family_name
CUSTOM_OAUTH2_SSO_JWT_LAST_NAME_KEY=idToken.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 stringCUSTOM_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
andaccessToken
are available as keys on thecurrent_user.metadata
object.
Role mapping
You can use environment variables to map the roles returned from the OpenID response to your Retool permission groups.
The following example maps the devops
and support
roles to specific Retool permission groups.
CUSTOM_OAUTH2_SSO_JWT_ROLES_KEY=idToken.groups
CUSTOM_OAUTH2_SSO_ROLE_MAPPING=devops -> admin, support -> viewer
After setting these environment variables, a user's groups will sync the next time they log in to Retool over SSO.
Examples of how this might work
List of roles | Role mapping variable | Result |
---|---|---|
["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
-
Switch to using the Classic Okta Admin UI
-
From the Security navigation dropdown, select API to go to the API Dashboard
- Edit the Authorization Server that Retool is integrating with by clicking the pencil icon
- Select the Scopes tab and press "Add Scopes"
- Fill out the form for the new scope
- Navigate to the Claims tab and press Add Claim
- 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.
- 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
- 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 theCUSTOM_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.
Updated 4 days ago