Skip to main content

Sync SAML group memberships

Learn how to sync and map SAML group memberships from your IdP to Retool.

Retool supports syncing group memberships at the time of SAML login. This requires passing group membership for users to Retool in your SAML assertion. Retool parses these memberships and adds or removes users to the groups when a user logs in to Retool.

Group syncing modify group memberships on subsequent logins. During initial configuration, test group syncing on a non-admin user or verify that a separate admin can log in with an alternate authentication method to avoid losing admin access.

Requirements​

To use SAML group syncing, you must:

  • Have SAML SSO configured on Retool.
  • Create Retool groups prior to syncing SAML groups. Retool groups are not created in the login flow.

Upon login, users are removed from any groups that do not have a corresponding IdP group. This includes users assigned to the Admin group. You should test this flow with a non-admin or test user.

1. Include groups in your SAML application​

Configure your SAML application to include group attributes in the SAML response.

Okta​

SAML Group Syncing directly matches the user groups by name, so Retool copies the naming convention you use in Okta.

In your Okta SAML application, configure the response to include Group Attributes. Set the group filter as desired. For example, you might set the name to groups and the regex filter to .* to include all of a user's groups.

See Okta documentation for more details about configuring Okta group attributes.

Microsoft Entra ID​

For Microsoft Entra ID, use group claims to add group attributes. Set the group name to "groups" to use the Retool default. Set the Source attribute to be the display name of the group, Cloud-only group display names (Preview).

See Microsoft Entra ID documentation for more details about group claims.

2. Update configuration​

Add your SAML configuration to your Retool instance through environment variables or the settings page.

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.

On Retool Cloud and self-hosted Retool versions 3.16 and later, on the Settings > Single Sign-On (SSO) page, select SAML Group Attribute under Sync Groups to Retool. In Groups attribute, enter the attribute defined in your SAML assertion. Save your settings.

3. Role mapping​

If your permission group names differ in Retool and your IdP, you can use role mapping to map your IdP groups to Retool groups. Role mapping is not necessary if your group names are the same, e.g., your admin group is named admin in both your IdP and Retool.

Roles are case sensitive. This means:

  1. Roles set in your IdP that you specify in the following settings 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.

On Retool Cloud and self-hosted Retool versions 3.16 and later, from Settings > Single Sign-On (SSO) under SAML Groups Attribute, add role mapping as a comma-separated list to the Roles mapping field. 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 can set:

retool-admins -> admin, support -> Support

Members of the retool-admin group in your IdP are now automatically added to the admin group when they log in, and support members added to Support.

4. Confirm group sync​

You can test out your configuration by logging in from an incognito window.

On self-hosted instances, you can also confirm group syncing by reviewing the api container logs after users log in. The logs contain SAML group memberships for each user who has logged in.

api_1 | [SAML] - Received SAML Login Response, parsing...
api_1 | [SAML] - Validating response...
api_1 | [SAML] - Validated response, and received the following attributes {
api_1 | email: 'johndoe@retool.com',
api_1 | firstName: 'John',
api_1 | lastName: 'Doe',
api_1 | groups: [ 'samlgroup', 'Everyone', 'anothergroup' ]
api_1 | }