While all cloud accounts support Google SSO by default, on On-Premise deployments you are able to connect Google, Okta, Active Directory, or other SAML SSO providers.

🚧

Setting the BASE_DOMAIN environment variable

The BASE_DOMAIN variable helps Retool create links for your users, like new user invitations and forgotten password resets. The backend tries to guess this, but it can be incorrect if there’s a proxy in front of the actual website.

Set BASE_DOMAIN=https://retool.yourwebsite.com to make sure these links are properly created. In the case of SSO, setting BASE_DOMAIN will help Retool create the right redirect URIs.

📘

Using the ID Token from SSO to authenticate to resources

If you would like to use the JWT you get from signing in (with Google, Okta, or any other SSO provider) to subsequent requests to your APIs, you must set up SSO via OpenID Connect. Docs here.

Google

First, create a Google OAuth client: https://developers.google.com/identity/sign-in/web/devconsole-project

Continue through the wizard until you reach the following form, and then fill it as follows:

You will then be presented with a Google Client ID and a Google Client Secret, but these values will not be the one that we care about.

Next, navigate to your Google developer console, and then on the left navbar navigate to credentials. Click on the auto-generated Web client (Auto-created for Google Sign-in)

Then configure the screen to look like below:

Add the Google Client ID and Client Secret that is on this page to your docker.env file like below.

📘

RESTRICTED_DOMAIN environment variable

If you want to restrict sign in to SSO-only (i.e. remove the option for users to sign in with username & password), add the RESTRICTED_DOMAIN environment variable. If you want to allow users to sign in both ways, don't add this environment variable.

Note: when setting the value for RESTRICTED_DOMAIN do not include the protocol or subdomain where you have Retool deployed. Just use yourcompany.com, which should match the email address users will sign in with. More information on our environment variables page.

CLIENT_ID={YOUR_GOOGLE_CLIENT_ID}
CLIENT_SECRET={YOUR_GOOGLE_CLIENT_SECRET}
RESTRICTED_DOMAIN=yourcompany.com

Restart the server, and Google SSO should work.

In Kubernetes, place the base64 encoded version of these strings inside the Kubernetes secrets file instead of the docker.env file.

Okta

1. Go to "Add Application" in your Okta admin dashboard.
2. Search for Retool.
3. Follow the wizard to finish setting up Retool.

🚧

If you can't find the Retool Okta app

Once you sign into Okta, make sure you're Admin mode by click the "Admin" button on the top right.

4. Navigate into the Okta application you just created. Click on the Sign On tab, and then on the Identity Provider Metadata link. If you can't find this link, make sure you're viewing the page in the Classic UI and not the Developer Console –– the setting is on the left in the top nav bar.

5. Click or "Save Link As" the "Identity Provider metadata" link. If you open the link in another tab, you should see an XML file resembling the image below. (Note that Firefox might not render the XML tags on the screen.)

6. Copy the entire XML file onto your clipboard and login to Retool as an administrator. Navigate to Settings -> Advanced and add the copied XML file to the IdP Metadata XML field.

Active Directory Federation Services

Another common Identity Provider is Active Directory Federation Service. Below is a step-by-step guide for integrating Retool with ADFS 3.0

1. Single sign on URL For Step 7 (Configure URL) you will need your Retool's Single Sign on URL. This will typically be https://retool.yourcompany.com/saml/login

2. Welcome: Open up the AD FS Manager, and start the Add Relying Party Trust Wizard

3. Select Data Source: Select "Enter data about the relying party manually"

4. Specify Display Name: Enter in a description in the next step for Retool in the next screen.

5. Choose Profile: Choose the AD FS Profile, as Retool supports SAML 2.0

6. Configure Certificate: Skip the next step (do not provide an optional token encryption certificate)

7. Configure URL: Choose the "Enable support for SAML 2.0 WebSSO Protocol. For the entry box for "Relying party SAML 2.0 SSO service URL" use the following pattern: https://domain.of.onprem.retool/saml/login You may find this URL in the settings page of Retool where you can export Retool's Service Provider Metadata (see Step 1).

8. Configure Identifiers: The Relying Party trust identifier should be of the form retool.yourcompany.com

🚧

The trust identifier must exclude protocol formatting

Incorrect: https://subdomain.domain.com/
Correct: subdomain.domain.com

9. Finish wizard: Continue and press next for all the following steps in the wizard.

10. Edit Claim Rules We will create two rules in the Issuance Transform Rules section now.

11. First claim - Select "Send LDAP Attributes as Claims", and use the following screenshot as a guide.

12. Second claim Select "Transform an Incoming Claim" and use the following screenshot as a guide.

13. Save all settings.

14. Configure Retool with the Identity Provider Metadata
    Export the metadata to an XML file from your IdP. There is usually a button to trigger a download this from your IdP dashboard. Additionally, you can often find this by navigating to https://your.identityprovider.com/federationmetadata/2007-06/federationmetadata.xml.

Copy the entire XML file to your clipboard and login to Retool as an admin user. Navigate to the Settings > Advanced page and add the copied XML file to the IdP Metadata XML field.

Other SAML Identity Providers

If you don't use Okta or ADFS, please use the following steps to configure your SAML identity provider service.

1. Customize your Entity ID in Retool

By default, Retool uses the Entity ID https://tryretool.com. You will need to customize this value to match the domain where you're hosting Retool.

Add the following environment variable to your docker.env file, replacing retool.yourcompany.com with your domain. Note: adding a new environment variable requires restarting the container for it to take effect.

DOMAINS=retool.yourcomany.com

2. Configure your Identity Provider

You should reference the provided documentation from your identity provider to complete its setup. However, you will likely be asked to supply values for the Sign on URL and Reply URL fields. Use the following pattern, replacing retool.yourcompany.com with the Entity ID you supplied in step 1:

• Sign on URL: https://retool.yourcompany.com/saml/login
• Reply URL: https://retool.yourcompany.com/saml/login

3. Match user attributes & claims

Retool requires exactly the following attributes to be asserted for each user on login:

• email: The identifier for a user
• firstName: The user's first name
• lastName: The user's last name

4. Assign users access to Retool

Use your identity provider to assign users to have access to login to Retool.

5. Configure Retool with the Identity Provider Metadata

Export the metadata to an XML file from your identity provider. There's usually a button to trigger a download from your IdP dashboard. Additionally, you can often find this data by navigating to https://your.identityprovider.com/federationmetadata/2007-06/federationmetadata.xml.

Copy the entire XML file to your clipboard and login to Retool as an admin user. Navigate to the Settings > Advanced page and paste the XML data to the IdP Metadata XML field.

6. (Optional, but recommended) Turn on JIT User Provisioning

Just in time (JIT) user provisioning enables Retool to provision user accounts when users sign in via SAML for the first time. This means you won't have to manually invite each user to Retool first. To turn this on, simply toggle the switch on the Settings > Advanced page.