Sync Google Groups to Retool

Sync your Google Groups to Retool Permission groups to easily map your organization's topology onto Retool Permissions.

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".
Example SAML settingsExample SAML settings

Example SAML settings

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

Example SAML attribute mapping

  1. 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":
Enable this SAML application for all domain usersEnable this SAML application for all domain users

Enable this SAML application for all domain users

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.
Update IdP metadata in RetoolUpdate IdP metadata in Retool

Update IdP metadata in Retool

  1. (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.
  2. 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.
Enable LDAP application for all domain usersEnable LDAP application for all domain users

Enable LDAP application for all domain users

Enable read access for all domain usersEnable read access for all domain users

Enable read access for all domain users

Enable read access to group informationEnable read access to group information

Enable read access to group information

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

Download the LDAP certificate

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

Name

Value

Description

LDAP_SYNC_GROUP_CLAIMS

true

Set this to true to enable the feature.

LDAP_SERVER_URL

ldaps://ldap.google.com:636

The LDAP server URL for Google's Secure LDAP Service.

LDAP_SERVER_NAME

ldap.google.com

LDAP server name

LDAP_BASE_DOMAIN_COMPONENTS

dc=example,dc=com

Your organization's email domain in DC format (explained below)

LDAP_SERVER_CERTIFICATE

Encoded certificate

The certificate from the previously downloaded bundle with a file name that matches Google_YYYY_MM_DD_TTTTT.crt

LDAP_SERVER_KEY

Encoded private key

The private key from the previously downloaded bundle with a file name that matches Google_YYYY_MM_DD_TTTTT.key

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

Email Domain

Domain Component (DC) format

example.com

dc=example,dc=com

mail.company.com

dc=mail,dc=company,dc=com

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.

Environment Variable

Value

Description

LDAP_ROLE_MAPPING

retool-admins -> admin, support -> Support

Used to map group email address from Google Groups to Retool group names

LDAP_ROLE_MAPPING_DISABLED

false

If true, Retool will not sync or create any groups when a user logs in. Instead, the new groups will be logged.

Troubleshooting

  • Insufficient Access Rights error: ensure that you have turned on the LDAP service status on your Google Admin Console.

Did this page help you?