Configure OneLogin OIDC SSO
Learn how to configure OneLogin SSO on Retool using OpenID Connect (OIDC).
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. Save configuration
On self-hosted deployments, after you set environment variables, restart your Retool instance to reload the SSO configuration. On Retool Cloud, save your settings.