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. For example, if your LDAP/SAML group claim is Admins and in Retool the corresponding group is RetoolAdmins, you can map groups so members of the Admins group are added to the RetoolAdmins group on login.
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.