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 variableIf 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 useyourcompany.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
- Go to "Add Application" in your Okta admin dashboard.
- Search for Retool.
- 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.


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


- 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
-
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
-
Welcome: Open up the AD FS Manager, and start the Add Relying Party Trust Wizard


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


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


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


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


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


- 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


-
Finish wizard: Continue and press next for all the following steps in the wizard.
-
Edit Claim Rules We will create two rules in the Issuance Transform Rules section now.
-
First claim - Select "Send LDAP Attributes as Claims", and use the following screenshot as a guide.


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


-
Save all settings.
-
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 userfirstName
: The user's first namelastName
: 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.


Updated 5 days ago