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.

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.

4. Navigate into the Okta application you just created. Click on the Sign On tab, and then on the Identity Provider Metadata link.

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

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 (usually found at - https://your.identityprovider.com/federationmetadata/2007-06/federationmetadata.xml. Then, 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.

Other SAML Identity Providers

While ADFS and Okta are both common Identity Provider Services, it is sometimes necessary to integrate Retool with other SAML IDP providers. To do so, please follow the steps below.

1. Customize your Entity ID. Retool by default uses the EntityID "https://tryretool.com." However, in your organization you may want to customize to a different unique name. To do so, add this line to your docker.env file.

DOMAINS=your.custom.entity.id

2. Configure service provider information using the documentation for your IDP. As part of this step, you may be asked for the following fields.

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

3. Matching attributes. Retool requires the following information for each user.

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

4. Assign users so that they are able to login into Retool.