Who is this guide for?

1. You are on a Retool enterprise plan and are hosting an on-premise deployment of Retool v2.79 or higher
2. Your organization uses Google Workspace
3. You would like to use Google SSO to sign in to Retool
4. You wish to map user's Google Group memberships to Retool's Permission Groups

If you answered yes to all of the above, keep reading! If not, check out our other options for SSO + Role Syncing.

Set up Google Group syncing

Set up Google as your SAML Identity Provider

In order to sync Google Groups to Retool, you must first setup Google as your SAML provider on Retool. For this part, you will need to be an admin on your Google Workspace. If you already use Google SAML you can skip ahead to the next section!

Create a custom SAML app on Google

1. Login to your Google Workspaces admin console - https://admin.google.com
2. Navigate to "Apps" -> "Web and mobile apps" on the sidebar
3. Click "Add app" -> "Add custom SAML app"
4. Follow the setup wizard to enter a name / logo for your SAML app
5. On the next screen, download IDP metadata by clicking the "Download Metadata" button and save this file carefully for use later.
6. On the "service provider details", enter the following information as shown in the screenshot below.
   6.1 Say you host retool at "retool.your-company.com", your ACS URL is: "https://retool.your-company.com/saml/login". Note that Google requires the ACS URL to be HTTPS secured.
   6.2 We recommend setting your Entity ID to simply your retool URL (without the https) e.g. "retool.your-company.com".

7. On the next screen, configure your attribute mapping as follows to correctly map your google user's details to your retool user's account.

8. Ensure that this SAML app is turned on for your intended audience (Google defaults to off). To do so navigate to the SAML app you just created and click the "User Access" panel. Then switch the "Service Status" to "On for Everyone":

Configure Retool to use the SAML app

Now that the custom SAML app is setup on your Google Workspace, you need to configure Retool to use this for SSO.

1. Navigate to Settings -> Advanced on your Retool instance
2. Copy the contents of the IdP Metadata file we downloaded in step 5 above and past it into "IdP Metadata XML" field.

3. (Optional, recommended) Turn on JIT user provisioning to allow Retool to automatically provision an account when users sign in via SAML for the first time.
4. Set the DOMAINS environment variable to match the entity ID you set in your SAML settings above. E.g.: DOMAINS=retool.your-company.com.

Setup Google Group syncing

Setup Google Secure LDAP Service

Retool uses the Google Secure LDAP Service to fetch a user's Google Group memberships for syncing with Retool. You'll need to be an admin on Google Workspace for these next steps:

1. Login to your Google Admin console - https://admin.google.com
2. Navigate to "Apps" -> "LDAP" and click "Add client"
3. Enter a name for your client in the setup wizard and under "Access permissions" set up as following. Note that the following access scopes are recommended - if you'd like you can limit to selected OUs and groups. Importantly: ensure that "Read group information" is turned on.

4. After creating the client, make sure to download the generated certificate bundle - this will be used later on.

5. Ensure that the "Service Status" for the LDAP client is turned on for everyone (Google's default is off).

Configure Retool to use this LDAP service.

To configure Retool to pull Google Groups from this LDAP service, you will need to set the following environment variables:

Your Google Workspace domain needs to be described in domain component (DC) syntax.

Role Mapping

Role mapping is used to map group email names from Google Groups to group names on Retool. The LDAP_ROLE_MAPPING environment variables uses an arrow syntax to express the mapping. For example, say you want to map the group[email protected] to the default Admin group on Retool and [email protected] to a Support Retool group. you would set:

LDAP_ROLE_MAPPING="retool-admins -> admin, support -> Support"

If you don't set this variable Retool will attempt to sync the user's group slugs only with groups that already exist on Retool; however, if you set this Mapping, Retool will automatically create the explicitly mapped groups on Retool if they don't exist already.

During initial configuration, we suggest setting LDAP_ROLE_MAPPING_DISABLED to true. When true, Retool will not actually sync or create any new groups when logging in a user, but will show you logs for the steps it would have performed. This allows you to debug your setup before actually changing groups for users.

Troubleshooting

• Insufficient Access Rights error: ensure that you have turned on the LDAP service status on your Google Admin Console.
• app_not_configured_for_user error: Make sure the service status of your Google SAML app is set to "on" (step 8 here). Also verify that you have correctly set your DOMAINS variable (step 4 here) and that it matches the entity ID you set in step 6.2 here.