Skip to main content

Configure Auth0 OIDC SSO

Learn how to set up Auth0 SSO with OpenID Connect (OIDC).

Available on:Enterprise plan

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.

On Retool Cloud and self-hosted Retool versions 3.16 and later, enter settings on Settings > Single Sign-On (SSO).

SettingExample
Client IDyypLZ44LxEz0XlQZBu5k2Nq9XsdOv4f5
Client secretxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Scopesopenid email profile offline_access
Auth URLhttps://retool.auth0.com/authorize
Token URLhttps://retool.auth0.com/oauth/token
Email keyidToken.email
First name keyidToken.given_name
Last name keyidToken.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.