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
Before saving, preview your SSO flow to ensure that the proper groups are being mapped, that the right user metadata is being sent from your identity provider, and that the integration works seamlessly.
Click the Test Connection button in your OpenID SSO settings.
If SSO is configured correctly, a new tab opens and displays the login flow and the response from the SSO provider. If configured incorrectly, the new tab shows the errors that occurred.
When you're satisfied with the settings, click Save.
If you added environment variables, restart your Retool instance.