Sync SAML group memberships

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 add or remove users to the groups when a user logs in to Retool.

Requirements

To use SAML group syncing, you must:

• Use Self-hosted Retool version 2.66.91 or later.
• 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.

Azure Active Directory

For Azure Active Directory, 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 Azure AD documentation for more details about group claims.

2. Enable SAML group sync in Retool

Configure the SAML_SYNC_GROUP_CLAIMS environment variable to enable SAML group sync.

SAML_SYNC_GROUP_CLAIMS=true

You must restart your Retool instance whenever you make changes to environment variables.

3. Define Retool group SAML variables

Set the SAML_GROUPS_ATTRIBUTE environment variable to the group attribute defined in your SAML assertion. SAML_GROUPS_ATTRIBUTE defaults to groups if the environment variable is not set.

SAML_GROUPS_ATTRIBUTE="groups"

4. Confirm group sync

After users log in, you can confirm group syncing by reviewing the api container logs. 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: '[email protected]',
api_1 | firstName: 'John',
api_1 | lastName: 'Doe',
api_1 | groups: [ 'samlgroup', 'Everyone', 'anothergroup' ]
api_1 | }