SCIM Group to Role Mapping in Elaichi

The situation

Your identity provider already decides who is in Finance, who is on the help desk and who is a contractor. You want Elaichi to follow those groups instead of an admin assigning roles by hand. SCIM provisioning is the standard your identity provider uses to create, update and deactivate accounts in another system. It does most of that work, and group mappings do the rest.

The part that catches people is the arithmetic. A SCIM group to role mapping names at most one role, and a member holds exactly one role in an Elaichi organization. So the moment two mapped groups overlap on one person, something has to give. Elaichi does not union the permissions. It picks one role, by a rule you can predict, and that rule is what this post is about.

Two definitions before anything else, since they get mixed up. A role is a bundle of permissions that says what a member may do in Elaichi. A restriction says which connectors and tools a role or a member may reach. Group mappings touch the first and never the second.

What is a scim group to role mapping in Elaichi?

A scim group to role mapping ties one group your identity provider syncs into Elaichi to one Elaichi role. Elaichi's schema caps the role list on a mapping at one entry. The server refuses more than one with a 400 role_cardinality error. The message reads: "A group mapping can confer only one role. Create a custom role that combines the permissions you need."

A mapping may also name zero roles. That is allowed by the schema, so "at most one role" is the accurate phrasing rather than "exactly one". A mapping can never name the Org Owner role.

The permissions are split as you would expect. Creating or updating a mapping needs the sso:manage permission plus a step-up confirmation from a browser session. A step-up confirmation is Elaichi asking you to prove it is you again. Reading mappings needs sso:view. Deleting one needs sso:manage with no step-up. The whole router sits behind the group_mapping plan feature, which Gold includes.

Why one role per member changes the design

A member holds exactly one role in an Elaichi organization. Role writes refuse zero roles or more than one with a 400 role_cardinality error, and the underlying table carries a unique index on the user.

That is deliberate. Because a member holds one role, each role is meant to be a complete persona: a member's permissions are their role's permissions, full stop. To combine two roles' reach, an admin authors a custom role instead. The API says as much when asked for two: "A member can hold only one role in an organization. Assign a single role, or create a custom role that combines the permissions you need."

So group mapping is not a sync in the way mailing-list membership is a sync. It is a decision about which group wins for each person. Elaichi will make that decision for you, consistently. You will like the outcome more if you chose the groups with the constraint in mind.

Custom roles need the role:manage permission and the custom_roles plan feature, which both Gold and Black include. A custom role may only include permissions its author currently holds. A custom role is always a billable seat, even one holding only view permissions.

Which role wins when a person is in two mapped groups?

Elaichi gives the member the single most privileged of the mapped roles, never a union of permissions from more than one. Privilege is ranked by the declared system role chain, with permission containment as the fallback for a role that is not on that chain.

The chain is a strict subset ladder: Guest, then Member, then Team Admin, then People Admin, then Org Admin, then Org Owner. Each tier holds everything the tier below holds plus at least one more permission. So a person in both a mapped Member group and a mapped Team Admin group lands on Team Admin. Nothing about Member is lost, because Team Admin already contains it.

That is the opposite of how some AI vendors treat role assignment. OpenAI's own documentation says permissions from ordinary ChatGPT custom roles combine additively, so a member keeps a permission if any assigned role grants it (role-based access control in ChatGPT, checked October 2026). The same page says Workspace Owners assign those roles to groups, created manually or synced through SCIM. Elaichi ranks rather than combines. The union you want has to exist as one custom role before the mapping does.

Billing Admin and Auditor sit off that chain as standalone personas. So do custom roles. For those, Elaichi falls back to permission containment: if one role's permissions contain the other's, the containing role wins. Where neither contains the other, you are relying on a comparison that is harder to predict from your side of the console. That is the practical argument for not letting two off-chain groups overlap on one person.

An example to sit with. Auditor holds 12 permissions, every one a view permission, and no tool:execute. Member holds 23 permissions including tool:execute. Neither contains the other: Auditor can read the audit log and the restriction list, and Member can run tools and create connections. Putting a compliance reviewer in both a mapped Auditor group and a mapped Member group is the overlap to avoid. Pick one, or author a custom role that holds both sets and map the group to that.

How to plan the groups before you create the mappings

Start from the roles, not the groups. Write down the personas your organization actually needs, check each one against the eight system roles, and only author a custom role where no system role fits.

1. List the personas. For most companies that is something like: everyday user, team lead, people admin, compliance reviewer, finance. Five is usually enough.
2. Match each to a system role first. Org Owner holds every permission. Org Admin holds every permission except billing:manage and org:delete. People Admin is Team Admin plus member:manage. Team Admin is Member plus team:manage. Member is the base paid role. Guest holds one permission, connector:view. Billing Admin holds four billing and spend permissions. Auditor holds 12 view permissions.
3. Author a custom role only where two personas collapse into one person. The compliance reviewer who also runs tools is the classic case.
4. Check which groups overlap. Pull your identity provider's group membership and look for people in two groups you plan to map. Each overlap is a decision you are about to delegate to the privilege ranking.
5. Decide where seats matter. Guest, Billing Admin and Auditor are free seats; the console marks them "Free". Org Owner, Org Admin, People Admin, Team Admin and Member are billable. A custom role is always billable. So mapping a group of reviewers to Auditor adds no billable seat, while mapping them to a view-only custom role does.
6. Create the mappings. One group, one role, with sso:manage and a step-up confirmation from a browser session.

Where SCIM stops covers the boundary between directory sync and a person's own AI client grants.

When a mapping change takes effect

A group mapping is a deferred grant. It has no effect on anyone until the identity provider's next SCIM sync recomputes membership. That sync runs on every mutation under the SCIM endpoint and on every mapping write.

Once membership is recomputed, the role change itself reaches every surface within about two minutes. A member's roles, teams and permissions are cached for 60 seconds under keys that include a per-organization epoch. Every role, membership, team, restriction and grant change writes a new epoch. The worst case at a remote point of presence is about two minutes: up to about 60 seconds for the write to propagate, plus up to 60 seconds of edge caching on the epoch read. That is a worst case, not a typical delay.

Other AI platforms publish their own windows. Anthropic says a change to a Claude Enterprise custom role can take up to 15 minutes to take effect (manage custom roles on Enterprise plans, checked October 2026). OpenAI says ChatGPT custom-role changes can need up to 5 minutes to apply (role-based access control in ChatGPT, checked October 2026). Plan around the slowest layer you actually run, not the fastest.

That window is short, and it is also not zero. If you are moving someone down a tier because of an incident, do not treat the mapping write as the containment step. Removing or suspending a member revokes their MCP client grants in that organization, inside the same call that changes the membership. Grants are re-read on every request, so their AI clients fail on the next call rather than after the cache window. That is the fast lever.

Deleting a mapping falls its members back to the domain or connection's default join role on the next recompute. Where no default role is set, or the configured role has since been deleted, the join lands on Member.

What group mapping does not do

Group mappings assign a role. They do not place anyone in a team, and they do not touch connections, toolboxes or which connectors a member may reach.

Joining through SCIM, a verified domain or SSO puts the person in no team. Neither SCIM nor group mappings ever add anyone to a team or take them out of one. Team membership comes from an admin afterwards, or from teams preset on an invite. An invitation carries exactly one role and can preset up to 50 teams.

SCIM provisioning and deprovisioning write only a member's status, profile name and role assignment through a group mapping. Nothing in SCIM configures a member's connections, toolboxes or tool access. The one real side effect is suspension. Suspending a member is what a SCIM deprovision does, and it revokes their standing credentials, so their AI client calls stop on the next call. Elaichi's own public SCIM guide says deactivation removes organization membership. The deployed code suspends rather than removes, and the code is what runs.

Other admin consoles put tool reach beside the group list, which is one reason the two get conflated. In the Microsoft 365 admin center, an admin opens a plugin's Users setting and makes it available to all users, no users, or specific users and groups (manage plugins, skills and MCP servers, checked October 2026). In Elaichi those stay two layers. A mapping sets the role, and restrictions decide which connectors and tools that role may reach.

For that second layer, tool-level versus app-level restrictions walks through the six cases. For the role side of the same question, designing roles for AI agents starts from the one-role constraint rather than from the group list.

When you do not need group mappings at all

Suppose your organization has fewer than about thirty members and roles change a few times a year. Assigning roles by hand in Settings is less work than maintaining a group taxonomy that has to survive the one-role rule.

Mappings earn their keep in three cases. The directory is already the source of truth for who belongs where. People move teams often enough that manual assignment drifts. Or your auditors want role assignment traceable to a directory group rather than to an admin's judgment. Short of that, a default role on your verified domain plus occasional manual changes covers it.

One more case. If you are on Elaichi mainly so that Claude, ChatGPT and Cursor sign into one address, and everyone needs the same reach, one role for everybody is a legitimate design. You can add mappings later without redoing anything.

Roles you can reach from a mapping

The eight system roles are seeded into every organization and cannot be edited or deleted. Org Owner cannot be assigned by a mapping, and only an Org Owner can grant or revoke the Org Owner role at all.

A custom role can include any of the 58 permissions, but only ones its author currently holds. A role a SCIM group mapping assigns cannot be deleted until the mapping changes, which answers with a 409 role_mapped.

To see what each role can actually reach once connected, start from the connector catalog and the governance use case.