Configure OneLogin OIDC SSO

Learn how to configure OneLogin SSO on Retool using OpenID Connect (OIDC).

πŸ“˜

SSO with OneLogin OIDC is only available for organizations on the Enterprise plan running self-hosted Retool.

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. Set environment variables in Retool

In your Retool instance, set the following environment variables. 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.

VariableExample
CUSTOM_OAUTH2_SSO_CLIENT_IDCLIENTID
CUSTOM_OAUTH2_SSO_CLIENT_SECRETCLIENTSECRET
CUSTOM_OAUTH2_SSO_SCOPESopenid email profile groups params
CUSTOM_OAUTH2_SSO_AUTH_URLhttps://ONELOGINDOMAIN.onelogin.com/oidc/2/auth
CUSTOM_OAUTH2_SSO_TOKEN_URLhttps://ONELOGINDOMAIN.onelogin.com/oidc/2/token
CUSTOM_OAUTH2_SSO_JWT_EMAIL_KEYidToken.email
CUSTOM_OAUTH2_SSO_JWT_FIRST_NAME_KEYidToken.given_name
CUSTOM_OAUTH2_SSO_JWT_LAST_NAME_KEYidToken.family_name
CUSTOM_OAUTH2_SSO_JWT_ROLES_KEYidToken.groups
CUSTOM_OAUTH2_SSO_ROLE_MAPPINGdevops -> 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 guess 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. Restart Retool

After you set your environment variables, restart your Retool instance to reload the SSO configuration.