Sync Google Groups
Learn how to set up Google SSO with Google Sign-in and LDAP permission groups.
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 | 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.
- On Retool Cloud, go to Settings > Single Sign-On (SSO). On self-hosted deployments, go to Settings > Advanced.
- Copy the contents of the IdP Metadata file you downloaded when creating your SAML app and paste them into the IdP Metadata XML field.
-
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.
-
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 theDEFAULT_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.
- Log in to your Google Admin console.
- Navigate to Apps > LDAP and click Add LDAP client.
- 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.
-
Create the client and download the generated certificate bundle.
-
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
- Environment variables
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. |
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:
- 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 passRetool Admin
. - 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'sadmin
role, you need to set it usingRetool 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.