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?
- You are on a Retool enterprise plan and are hosting an on-premise deployment of Retool v2.79 or higher
- Your organization uses Google Workspace
- You would like to use Google SSO to sign in to Retool
- 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
- Login to your Google Workspaces admin console - https://admin.google.com
- Navigate to "Apps" -> "Web and mobile apps" on the sidebar
- Click "Add app" -> "Add custom SAML app"
- Follow the setup wizard to enter a name / logo for your SAML app
- On the next screen, download IDP metadata by clicking the "Download Metadata" button and save this file carefully for use later.
- 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".
- On the next screen, configure your attribute mapping as follows to correctly map your google user's details to your retool user's account.
- 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.
- Navigate to Settings -> Advanced on your Retool instance
- Copy the contents of the IdP Metadata file we downloaded in step 5 above and past it into "IdP Metadata XML" field.
- (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.
- 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:
- Login to your Google Admin console - https://admin.google.com
- Navigate to "Apps" -> "LDAP" and click "Add client"
- 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.
- After creating the client, make sure to download the generated certificate bundle - this will be used later on.
- 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.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.
Updated 7 months ago