How Does SCIM Sync Custom Roles and Teams From My Identity Provider?

Last updated: May 15, 2026

SCIM can now sync both custom roles and teams (projects) from your identity provider. Each direction is configured independently, and each can resolve IdP groups via a curated mapping table (the default) or by name match with auto-create on miss. Users in multiple matched groups now receive the union of every mapped role and team — not a single priority pick.

Before You Start

You need an Enterprise subscription with SCIM enabled. Email support@gumloop.com if SCIM is not turned on yet.
You must hold the Admin organization role to configure SCIM.
Mappings live under Settings → Organization → SSO.

What Changed

Previously, SCIM only synced custom roles, and a user in multiple mapped IdP groups was assigned to a single "priority" role. Now:

Team sync is a first-class direction — IdP groups can map to Gumloop teams (projects) the same way they already map to custom roles.
Each direction is independent — you can sync roles only, teams only, both, or neither.
Multi-group membership is additive — a user in multiple mapped IdP groups receives every matched role and every matched team (deduplicated union). There is no priority order.
Each direction has a Use mapping table toggle that switches between the curated mapping table and name-based resolution.

How the Two Modes Work

Mapping Table Mode (default, non-destructive)

The curated mapping table is the source of truth. You pick which IdP groups map to which Gumloop role or team.

IdP groups that are not in the table are skipped. Users keep their current assignments for that direction.
If the table is empty, SCIM leaves that direction alone — safe to enable without immediately touching anyone's access.
IdP group names do not need to match Gumloop entity names — you pick the target per row.

Name-Based Mode (IdP is authoritative, destructive on miss)

Flip Use mapping table off for a direction to switch to name-based mode. Now Gumloop:

Matches each IdP group's display name against existing Gumloop role / team names (case- and whitespace-insensitive).
Hit → user joins the existing role / team.
Miss → Gumloop auto-creates a new role or team named after the IdP group on the next sync.
Users whose IdP groups don't resolve to any Gumloop entity have their roles or teams wiped for that direction — the IdP is treated as the only source of truth.

Switching a direction to name-based mode requires explicit confirmation in the UI. Read the dialog carefully — the next sync will descope users who no longer have a matching IdP group.

For team sync specifically, name-based mode is authoritative across organizations: a user's team memberships in other orgs not represented in the IdP target set are also removed. SCIM can still only add users to teams inside the synced org.

Recommended Setup

Provision SCIM with both directions empty and Use mapping table on. Verify users provision and deprovision cleanly without role/team changes.
Add a few mappings for one direction (e.g. roles first), keeping the toggle on. Run a manual sync and confirm only those mappings take effect.
If you want IdP groups to be the single source of truth for a direction, only then consider switching the toggle off — and only after a pilot test on a small group.

Audit Events to Watch

SCIM operations show up in audit logs. New event types include:

SCIM_USER_TEAM_CHANGED — a user's team memberships were updated (union of mapped teams).
SCIM_TEAM_MAPPING_UPDATED — the team mappings table was replaced.
SCIM_USE_MAPPING_TABLE_CHANGED — a per-direction toggle flipped between mapping-table and name-based modes.
SCIM_AUTO_CREATED_ENTITY — a new role or team was auto-created in name-based mode from an unmatched IdP group.

Common Gotchas

Empty mapping table + toggle on = no-op. Don't expect users to lose memberships when you clear the table; clear it intentionally only when you want SCIM to stop managing that direction.
Name-based mode is irreversible per sync. Auto-created roles and teams persist after you flip the toggle back. Delete them manually if no longer needed.
RBAC vs. custom roles. SCIM-provisioned users always land with the baseline Member RBAC role. Their custom roles and teams come from IdP-group mappings and don't change the RBAC role.

Still Need Help?

If this didn't resolve your issue, reach out to support at support@gumloop.com.