Configure Auth0 OIDC SSO
Learn how to set up Auth0 SSO with OpenID Connect (OIDC).
Use this guide to configure Auth0 SSO with OpenID Connect (OIDC) on Retool. Once configured, users can log in to Retool with their Auth0 credentials.
Requirements
To configure Auth0 SSO, you must:
- Have admin permissions on Retool Cloud or permissions to add environment variables on self-hosted Retool instances.
- Have permissions to create an OIDC application in Auth0.
1. Create a new Auth0 application
In Auth0, create a new application for Retool. Go to your application Settings and save the Client ID and Client secret.
Next, save the OAuth Authorization URL and OAuth Token URL. In Auth0, this is found in Settings > Advanced Settings > Endpoints.
Add https://<subdomain>.retool.com/oauth2sso/callback as the callback URL, replacing <subdomain> with your subdomain. In Auth0, the callback URL is set in Settings > Application URIs.
2. Configure settings in Retool
Configure your SSO settings in Retool.
When possible, use the Settings UI to configure SSO for a more streamlined setup. Existing environment variables pre-populate in the Settings UI, which you can override or preserve. Some settings are only available as environment variables.
- SSO settings page
- Environment variables
On Retool Cloud and self-hosted Retool versions 3.16 and later, enter settings on Settings > Single Sign-On (SSO).
| Setting | Example |
|---|---|
| Client ID | yypLZ44LxEz0XlQZBu5k2Nq9XsdOv4f5 |
| Client secret | xxxxxxxxxxxxxxxxxxxxxxxxxxxxx |
| Scopes | openid email profile offline_access |
| Auth URL | https://retool.auth0.com/authorize |
| Token URL | https://retool.auth0.com/oauth/token |
| Email key | idToken.email |
| First name key | idToken.given_name |
| Last name key | idToken.family_name |
On self-hosted Retool versions earlier than 3.16, configure the following environment variables on your Retool instance.
| Environment variable | Example |
|---|---|
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 settings
To provide authorization to access resources when a user logs in with SSO, specify the API audience that corresponds to the resource as configured in Auth0. Find the API audience in the Auth0 UI under Applications > APIs. Set this value as the CUSTOM_OAUTH2_SSO_AUDIENCE environment variable in your Retool deployment, or in the SSO Audience field in the Retool UI.
If you don't configure the CUSTOM_OAUTH2_SSO_AUDIENCE setting, Retool receives an opaque token, and you won't be able to use the accessToken to control access to components and resources.
3. Test the connection
Once you've configured your settings, click Save Changes. To test the integration and its settings, click the Test Connection button.
This triggers a simulation of the SSO flow that ensures that the proper groups are mapped, the right user metadata is sent from your identity provider, and the integration works seamlessly. Clicking the Test Connection button does not change the current user's permission groups, and you won't be locked out if SSO is misconfigured.
After Retool tests the connection, a new tab opens and displays the Connection Status, Issues Detected, and Connection Details. If there are any issues, this page displays warnings and recommendations to resolve them. You can see the full response from the SSO provider in the Connection Details section.
Once you are satisfied with your configuration, log out of Retool and log back in using SSO to test the flow yourself.
If you use a self-hosted deployment and updated your environment variables, restart your Retool instance.
If you added environment variables, restart your Retool instance.