Sync SAML group memberships
Learn how to 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 | }
Updated 11 days ago