Configure OneLogin OIDC SSO
Learn how to configure OneLogin SSO on Retool using OpenID Connect (OIDC).
| Single Sign-On (SSO) Availability | |||
|---|---|---|---|
| Cloud | Generally Available | ||
| Self-hosted Edge 3.33 or later | Generally Available | ||
| Self-hosted Stable 3.33 or later | Generally Available | ||
Use this guide to configure OneLogin SSO with OpenID Connect (OIDC) on Retool. Once configured, users can log in to Retool with their OneLogin credentials.
Requirements
To configure OneLogin SSO, you must:
- Have permissions to add environment variables to your Retool instance.
- Have permissions to create an OIDC application in OneLogin.
1. Create an OIDC application in OneLogin
Follow the steps in the OneLogin OpenID Connect Customer Connector guide to create a new OIDC application. Use the following settings.
Configuration page
On the Configuration page, under Redirect URIs, enter https://<your_retool_domain>/oauth2sso/callback.
Parameters page
On the Parameters page, select Configured by admin under Credentials. In this section, you can add custom claims—for example, user_id.
SSO page
On the SSO page, select Web as the Application type. Select POST as the Token endpoint.
Save the Client ID and Client secret to use in Retool.
2. Update Retool settings
Configure 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). Retrieve the values for Client ID and Client secret from the SSO page in OneLogin.
| Setting | Example |
|---|---|
| Client ID | CLIENTID |
| Client secret | CLIENTSECRET |
| Scopes | openid email profile groups params |
| Auth URL | https://ONELOGINDOMAIN.onelogin.com/oidc/2/auth |
| Token URL | https://ONELOGINDOMAIN.onelogin.com/oidc/2/token |
| Email key | idToken.email |
| First name key | idToken.given_name |
| Last name key | idToken.family_name |
| Roles key | idToken.groups |
| Role mapping | devops -> admin, support -> viewer |
On self-hosted Retool versions earlier than 3.16, configure the following environment variables on your Retool instance.
Retrieve the values for CUSTOM_OAUTH2_SSO_CLIENT_ID and CUSTOM_OAUTH2_SSO_CLIENT_SECRET from the SSO page in OneLogin. Replace ONELOGINDOMAIN with your OneLogin domain.
| Environment variable | Example |
|---|---|
CUSTOM_OAUTH2_SSO_CLIENT_ID | CLIENTID |
CUSTOM_OAUTH2_SSO_CLIENT_SECRET | CLIENTSECRET |
CUSTOM_OAUTH2_SSO_SCOPES | openid email profile groups params |
CUSTOM_OAUTH2_SSO_AUTH_URL | https://ONELOGINDOMAIN.onelogin.com/oidc/2/auth |
CUSTOM_OAUTH2_SSO_TOKEN_URL | https://ONELOGINDOMAIN.onelogin.com/oidc/2/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_JWT_ROLES_KEY | idToken.groups |
CUSTOM_OAUTH2_SSO_ROLE_MAPPING | devops -> admin, support -> viewer |
You should also set the BASE_DOMAIN environment variable to ensure links using your domain are correct. Retool's backend tries to determine the BASE_DOMAIN if it is not set, but it can be incorrect if your website uses a proxy.
BASE_DOMAIN=https://retool.yourcompany.com
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.