Configure group syncing and role mapping
Learn how to configure group syncing and role mapping for SSO.
Group sync and role mapping modify group memberships on subsequent logins. During initial configuration, test group sync and 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.
Retool can sync groups from your SSO provider for authorization. The approach you use depends on your configured SSO provider.
Group sync
If your groups are named the same in your IdP and Retool, group syncing happens automatically when users log in. For example, if you have an OIDC group claim of Engineers and a Retool group named Engineers, the users in the OIDC group are automatically added to the Retool group on login.
Group syncing occurs when users log in, so if you change groups in your IdP, users need to log out and in again for changes to be reflected. OIDC groups are created in Retool automatically. You assign group membership in your IdP. Manual edits to group memberships are overwritten with IdP groups on subsequent logins, so manual editing is not recommended.
Role mapping
To map the groups from your IdP to differently named groups in Retool, use role mapping. This is most commonly needed for the Admin group, since most IdPs already use a naming convention (such as Retool Admins or retool_admin_users) and cannot use the unqualified name admin.
Configure a single rule that maps your IdP's admin group to Retool's admin group, as shown in the role mapping rule example below:
| IdP group | Retool group |
|---|---|
Retool Admins | admin |
Name all other groups identically in your IdP and Retool so they sync automatically without a role mapping rule. Avoiding unnecessary mappings keeps your configuration and naming conventions simple.
Role mapping occurs when users log in, so if you change groups in your IdP, users need to log out and in again for changes to be reflected. OIDC groups are created in Retool automatically. Editing Retool group membership in Retool is disabled. You assign group membership in your IdP.
With SCIM provisioning, groups are pushed automatically from your IdP to Retool using API requests. This means you can push group membership on an automated schedule or manually from your IdP.
SCIM calls specific API endpoints to add users to groups, remove users from groups, and create groups.
SCIM matches groups by name, so user groups in your IdP and Retool need to have the same name. You can map a group name to one of Retool's 4 default groups (Admin, Viewer, Editor, All Users).
SCIM requires your Retool instance is open to API requests from your IdP. You should add your IdP's IP addresses to your instance’s allowlist.
Role mapping and Spaces
If you use Retool Spaces, you may want to namespace your IdP groups by Space if they're in the same IdP instance. For example, if you have distinct engineering teams building apps in different spaces, Retool recommends splitting "Engineering" into "Engineering - Treasury" and "Engineering - Issuing" IdP groups for your Treasury and Issuing Spaces.