All Retool cloud accounts support Google SSO by default. Self-hosted Retool deployments support 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

1. 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.

2. 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:

3. 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

4. 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.

5. Enable JIT user provisioning

Just-in-Time (JIT) user provisioning enables Retool to provision accounts when your users sign in via Google for the first time. JIT user provisioning is not required but is highly recommended so that you won't have to manually invite each user to Retool first.

To enable JIT user provisioning, toggle the switch in the Settings > Advanced page, then set the DEFAULT_GROUP_FOR_DOMAINS environment variable.

Okta

📘

Only available for Enterprise self-hosted deployments of Retool

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.

Azure Active Directory

📘

Only available for Enterprise self-hosted deployments of Retool

1. Customize your Entity ID in Retool

• By default, Retool uses the Entity ID https://tryretool.com. You 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.yourcompany.com

2. Create an Azure Active Directory Enterprise application

• In the Azure Active Directory admin center, add a new Enterprise application
• Retool is not listed in the Azure AD Gallery, so you must select “Create your own application”
  • Name the application “Retool”
  • Select Integrate any other application you don’t find in the gallery (Non-gallery)

3. Assign users to the Retool application in Azure

In order for users to access Retool using Azure Active Directory SSO, they must:

• Be assigned to the application
• Have a First Name, Last Name, User Principal Name, and Email defined on their profile

Assign users to the Retool application and confirm their required attributes in the Azure Active Directory admin center.

4. Configure SAML settings for the Retool application in Azure

• In the Azure Active Directory admin center, select the Retool Enterprise application
• Set up single sign on for the Retool application, selecting SAML as the sign-on method
• Use the following SAML settings:
  • Basic SAML Configuration (replace retool.yourcomany.com with the domain name assigned to your Retool instance):
    • Identifier (Entity ID): retool.yourcompany.com
    • Reply URL (Assertion Consumer Service URL): https://retool.yourcompany.com/saml/login
    • Sign on URL: https://retool.yourcompany.com/saml/login
    • Relay State: leave blank
    • Logout URL: leave blank
  • Attributes & Claims:
    • Required claim
      • Unique User Identifier (Name ID): user.mail
    • Additional claims (delete default claims first)
      • firstName: user.givenname
      • lastName: user.surname
      • email: user.userprincipalname

You must also edit each claim and clear the value for the Namespace field.

5. Import Azure Federation Metadata into Retool

• On the same page where you configured SAML settings in the Azure Active Directory admin center, download the Federation Metadata XML file (listed under the SAML Signing Certificate).
• Open the XML file in a code editor and copy the contents to your clipboard.
• Log in to Retool as an admin user.
• Navigate to the Settings > Advanced page and paste the XML data to the IdP Metadata XML field. Save your changes.

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.

7. Test the integration

• Navigate to the /auth/login page for your Retool instance.
• Click the Sign in with SSO button.
• Retool redirects you to login.microsoft.com where you are prompted for credentials.
• After entering credentials for a user who is assigned to the Retool app in Azure, you are redirected back to Retool and logged into the instance.

Active Directory Federation Services

📘

Only available for Enterprise self-hosted deployments of Retool

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

📘

Only available for Enterprise self-hosted deployments of Retool

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.yourcompany.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.