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.
- SSO settings page
- 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.
On self-hosted instances earlier than 3.16, configure the SAML_SYNC_GROUP_CLAIMS
environment variable to enable SAML group sync.
SAML_SYNC_GROUP_CLAIMS=true
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"
You must restart your Retool instance whenever you make changes to environment variables.
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:
- 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 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
.
- SSO settings page
- Environment variables
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
.
On self-hosted Retool, set the LDAP_ROLE_MAPPING
environment variable to a comma-separated list of mapped groups. 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:
LDAP_ROLE_MAPPING=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
.
You must restart your Retool instance whenever you make changes to environment variables.
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 | }