Sync Google Groups

Learn how to set up Google SSO with Google Sign-in and LDAP permission groups.

Available on:
• Enterprise plan

Organizations using Google Sign-in SSO that manage users with Google Workspace can map Google Group memberships to Retool permission groups.

Requirements

To configure Google Groups in Retool, you must have administrator access to your Google Workspace.

1. Set up Google as your SAML Identity Provider

To sync Google Groups to Retool, you must first set up Google as your SAML provider on Retool. If you already use Google SAML, you can skip ahead to configure Retool to use your SAML app.

Create a custom SAML app on Google

Follow the steps in Google's instructions to create a custom SAML app using the configuration below.

On the Service provider details screen, enter the following fields.

Setting	Value
ACS URL	On Retool Cloud, https://your-company.retool.com/api/saml/login. On self-hosted Retool,https://retool.your-company.com/saml/login.
Entity ID	https://your-company.retool.com

On the Attribute mapping screen, map your Google user details to the field names to show on Retool users. Under App attributes, include email, firstName, and lastName.

By default, Google turns off SAML apps. To turn on the app for all users, in User access, change the Service status to On for everyone.

Configure Retool to use the SAML app

After creating your custom SAML app, you need to configure Retool to use it for SSO.

1. On Retool Cloud, go to Settings > Single Sign-On (SSO). On self-hosted deployments, go to Settings > Advanced.
2. Copy the contents of the IdP Metadata file you downloaded when creating your SAML app and paste them into the IdP Metadata XML field.

IDP Metadata Field in Settings

3. Enable JIT user provisioning to allow Retool to automatically provision an account when users sign in for the first time using SAML. This step is optional, but recommended.

4. Set the DOMAINS environment variable to match the entity ID you set in your SAML settings. If you enabled JIT user provisioning, you also need to set the DEFAULT_GROUP_FOR_DOMAINS environment variable.

DOMAINS=retool.your-company.com

2. Set up Google Secure LDAP service

Retool uses the Google Secure LDAP Service to fetch a user's Google Group memberships to sync with Retool.

1. Log in to your Google Admin console.
2. Navigate to Apps > LDAP and click Add LDAP client.
3. Enter a client name in the setup wizard, then add the following permissions in the Access permissions settings. Retool recommends the following access scopes, but you can also limit to selected OUs and groups.

• Under Verify user credentials, select Entire domain.
• Under Read user information, select Entire domain.
• Toggle on Read group information.

4. Create the client and download the generated certificate bundle.

5. Switch the Service status to On.

Configure Retool to use the LDAP service

Configure the following settings to retrieve Google Groups from your LDAP service.

When possible, use the Settings UI to configure SSO for a more streamlined setup. Existing environment variables pre-populate in the Settings UI, which you can override or preserve. Some settings are only available as environment variables.

SSO settings

On Retool Cloud and self-hosted Retool versions 3.16 and later, go to Settings > Single Sign-On (SSO), select Google LDAP under Group syncing, and enter the following settings.

Setting	Value	Description
Server URL	ldaps://ldap.google.com:636	The LDAP server URL for Google's Secure LDAP Service.
Server name	ldap.google.com	The LDAP server name.
Base domain components	dc=example,dc=com	Your organization's email domain in DC syntax.
Server certificate	Encoded certificate	The certificate from the downloaded bundle.
Server key	Encoded private key	The private key from the downloaded bundle.

Environment variables

On self-hosted Retool versions earlier than 3.16, add the following environment variables on your Retool instance.

Environment variable	Value	Description
LDAP_SERVER_URL	ldaps://ldap.google.com:636	The LDAP server URL for Google's Secure LDAP Service.
LDAP_SERVER_NAME	ldap.google.com	The LDAP server name.
LDAP_BASE_DOMAIN_COMPONENTS	dc=example,dc=com	Your organization's email domain in DC syntax.
LDAP_SERVER_CERTIFICATE	Encoded certificate	The certificate from the downloaded bundle.
LDAP_SERVER_KEY	Encoded private key	The private key from the downloaded bundle.
LDAP_SYNC_GROUP_CLAIMS	True	Enable the sync.

Your Google Workspace domain must use 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 modify group memberships on subsequent logins. During initial configuration, test role mapping on a non-admin user or verify that a separate admin can log in with an alternate authentication method to avoid losing admin access.

Role mapping allows you to map group email names from Google Groups to group names on Retool. The LDAP_ROLE_MAPPING environment variable uses an arrow syntax for the mapping. For example, to map the group retool-admins@yourcompany.com to the default Admin group on Retool and support@yourcompany.com to a Support Retool group, you might set the following.

Setting	Environment variable	Example value
LDAP Role Mapping	LDAP_ROLE_MAPPING	retool-admins -> admin, support -> Support

Roles set using this environment variable are case sensitive. This means:

1. Roles set within your IdP that you pass within the variable need to match exactly. For example, if you have a Retool Admin role in your IdP, you need to pass Retool Admin.
2. Roles within Retool are always lowercase. For example, if you have a Retool Admin role within your IdP, and you want to map it to Retool's admin role, you need to set it using Retool Admin → admin.

Retool automatically creates the explicitly mapped groups on Retool if they don't already exist. If LDAP_ROLE_MAPPING is not set, Retool attempts to sync the user's group slugs with existing Retool groups.

On self-hosted deployments, when you first configure group syncing, it's useful to set the LDAP_ROLE_MAPPING_DISABLED environment variable to true. When true, Retool does not actually sync or create any new groups when a user logs in, but does show you logs for the steps it would have performed. This allows you to debug your setup before actually changing groups for users.

Troubleshoot group syncing

Use the following information to resolve common issues when configuring LDAP group syncing.

Insufficient access rights

If you see an error indicating Insufficient Access Rights, ensure the LDAP service status is set to On in the Google Admin Console.

Error configuring app for user

If you see an error which contains app_not_configured_for_user, ensure the LDAP service status is set to On in the Google Admin Console. Verify that you correctly set your DOMAINS variable and that it matches the entity ID you previously set.