Docs/Administration/Group Role Mapping

Group Role Mapping

Group role mapping gives members their AI governance role from the groups they belong to in your identity provider. Map a group to a built-in role or a custom role, as the organization role or as the role in one project. Mappings never set Budget AI roles; those are set in Members. Anyone in the group gets that role, and the role follows the group: add someone to AI-Security in Okta and they become Security & Compliance in the mapped project without anyone editing roles in ANTS Platform.

ℹ

Open Organization Settings → Group role mapping. The tab is visible to members who can view organization members (Owner, Governance Owner and organization-level Budget AI Owner). See Permissions for who can change mappings.

Where groups come from

A mapping uses one of two sources:

SourceShown in the dialog asWhen changes apply
SCIM groupSCIM group pushed from OktaAs soon as your identity provider pushes the change, including removals. Works with Okta Push Groups and with Entra group provisioning.
Groups claimGroups claim in the sign-in tokenAt the person's next sign-in. Works with Okta, Microsoft Entra ID and other OpenID Connect providers that have a fixed token issuer.
⚠

Use SCIM groups for privileged roles such as Owner, Governance Owner and Security & Compliance. With the groups claim, someone removed from a group in your identity provider keeps the mapped role until they sign in again.

Mappings set roles for people who are already members of the organization. They never add anyone to an organization. Membership still comes from SCIM, an invitation, the Admin API or the deployment's default organization.

Set up SCIM groups

Provision users and groups

Set up SCIM provisioning with group push turned on.

Push the groups that carry roles

In Okta, use Push Groups on the ANTS Platform app for groups such as AI-Security and Finance-Analysts. In Entra, assign the groups to the enterprise application and keep group provisioning on.

Add the mapping

In ANTS Platform, create a mapping with SCIM group pushed from Okta and choose the group from the list. The list shows each pushed group with its member count. Entra groups appear in the same list.

Set up the groups claim

ANTS Platform reads the groups claim from the ID token at sign-in. A claim only counts when all of these hold:

  • the token comes from the issuer (and, for Entra, the tenant) that was pinned on the mapping when it was saved;
  • the provider has one fixed issuer;
  • the member's email domain is verified by your organization.

Verify your email domain

Claims only count for members whose email domain your organization has verified. Add the domain under Organization Settings → AI Access Requests → Company domains, create the DNS TXT record shown, and select Verify. Only one organization can verify a domain. If that tab is not available in your organization, ask your ANTS Platform team.

Add the groups claim in your identity provider

  1. Decide which authorization server issues the tokens. The deployment's Okta issuer must match it exactly: https://<tenant>.okta.com for the org authorization server, or https://<tenant>.okta.com/oauth2/<server id> for a custom one.
  2. Org authorization server: open Applications, select the ANTS Platform app, open the Sign On tab and edit OpenID Connect ID Token. Set the groups claim type to Filter, the claim name to groups, and a filter that matches the groups you map, for example Starts with ANTS-.
  3. Custom authorization server: open Security → API, select the authorization server, open Claims and add a claim named groups, included in the ID Token, with value type Groups and the same filter.
  4. Include a group every user is in, such as Everyone, in the filter. The claim is then never empty for a healthy configuration, so a missing claim always points to a problem that the safeguard can catch. ANTS Platform only stores groups that a mapping uses.
  5. The org authorization server only sends the claim when the groups scope is requested. On a deployment managed by ANTS Platform, ask your ANTS Platform team to add it. On a self-hosted deployment, set AUTH_OKTA_SCOPE="openid email profile groups". When the variable is not set, ANTS Platform requests openid email profile.

Other OpenID Connect providers (a custom OIDC provider, Auth0, Amazon Cognito, Keycloak) work when their ID token carries a groups claim of strings and their issuer is configured. WorkOS, and a custom provider configured without ID token verification, cannot be used for claim mappings.

Add the mapping

Create a mapping with Groups claim in the sign-in token, choose the Identity provider, and enter the Group name as it appears in the claim. Matching ignores case. For Entra, enter the group's object ID.

Sign in again

Members get their mapped role at their next sign-in. Members who do not sign in keep their current role until they do.

Create a mapping

Saving a mapping needs step-up verification when it is enabled on the deployment.

Open the mappings

Go to Organization Settings → Group role mapping and select Add mapping.

Choose the group

Under Group comes from, choose SCIM group pushed from Okta and pick the SCIM group, or choose Groups claim in the sign-in token, pick the Identity provider and enter the Group name. A provider that cannot be trusted for claims is shown as (not supported) with the reason.

Choose the scope and the role

Under Scope, choose Organization role or Project role in a project. Under Role, choose a built-in role or a role from the Custom roles group. Expired custom roles cannot be chosen.

For Organization role, the list offers only Owner, Governance Owner, Governance Viewer, End User, No access and custom roles. Security & Compliance, Cost Analyst and Auditor are offered for project roles only, and Project Admin and Manager Viewer are not offered at all. Saving a mapping with a role that is not offered for its scope is refused.

Set a priority if you need one

Priority (optional) takes a whole number from 1 to 1000. Leave it empty to let the most privileged role win. See How the role is chosen.

Check the preview

The dialog shows how many members would change role ("3 members would change role") and lists each member with their current and new role. It also says how many members would be released, and whether a change would be refused or would change your own role. For a new claim mapping, members are matched at their next sign-in, because ANTS Platform only keeps groups that a mapping already uses.

Save

Select Save and complete step-up verification. The mapping applies straight away to the members the preview listed.

The Mappings table lists each mapping with its Group, Scope, Role, Priority (Highest privilege when none is set) and the number of Managed members. The Managed members table lists every member whose role currently comes from a mapping, with the group and the role.

A mapping marked Inactive is not applied, because its provider, its issuer or the verified domain changed, or its project was deleted.

A mapping saved before these limits that gives a project-only role at organization level, or gives Project Admin, stays saved and shows Not applied to new members:

  • People who already hold the role keep it.
  • New members in the group are refused that role, and the refusal is written to the audit log (groupRoleMapping.roleChangeRefused, reason projectOnlyRole or discontinuedRole).
  • A member who currently holds more access than the mapped role is moved to End User at organization level (groupRoleMapping.roleUpdate).

Edit such a mapping to a role that is still offered for its scope.

How the role is chosen

The organization role and each project role are worked out separately. When a member is in several mapped groups for the same scope:

  1. A mapping with a priority beats every mapping without one. Among mappings with a priority, the lower number wins: priority 1 beats priority 2.
  2. Otherwise the most privileged role wins, in this order: Owner, Governance Owner, Project Admin, Security & Compliance, Cost Analyst, Governance Viewer, Auditor, Manager Viewer, End User, No access.
  3. A custom role ranks just above the strongest built-in role whose organization and project permissions it fully includes, and below the next built-in role up. A custom role that includes no built-in role's permissions ranks just above No access.
  4. Two custom roles at the same rank: the one granting more permissions wins, then the name in alphabetical order.
  5. Mappings to an expired custom role are skipped, so the member's other groups decide.
  6. A remaining tie goes to the oldest mapping.

Use a priority when a group is deliberately narrower. For example, map Contractors to Auditor with priority 1, and a contractor who is also in Finance-Analysts stays Auditor.

A project role from a mapping replaces the member's organization role in that project, as described in Members & Roles.

Managed members

A member in at least one mapped group for a scope is managed in that scope:

  • Their role in that scope comes from the mappings and follows their groups.
  • On the Members page, their role dropdown is locked and shows Managed by Okta group followed by the group name, or Managed by identity provider group for a claim from a provider other than Okta.
  • Role changes by hand in the console are refused, and Admin API membership updates for that scope return 409.
  • The SCIM roles attribute is ignored for a member whose organization role is managed.

A member managed only for one project can still have their organization role edited, and the other way round. Members in no mapped group keep the role set by hand, by the Admin API or by SCIM roles.

When a member leaves their last mapped group

The setting When a member leaves their last mapped group decides what happens:

OptionEffect
Reset to None (default)Their organization role becomes No access. A project role set by a mapping is removed, so they fall back to their organization role.
Keep their last roleThey keep the role they last had, and their role can be edited by hand again. The page warns: "People removed from a mapped group keep their role until someone changes it."

With Keep their last role, someone removed from an admin group in your identity provider stays an administrator in ANTS Platform until someone changes their role. Changing this setting needs organization member management access. It does not ask for step-up verification, and the change is recorded in Audit Logs.

Owners and the last administrator are protected

A mapping never changes an Owner's role; only a Super Admin can. A mapping also never downgrades the last member who can manage members (the last Owner, or the last member whose custom role has User & role management at Read & Write). Such a change is refused, the member keeps their role, and the refusal is recorded in the audit log. The preview says "Owners keep their role, and someone must still manage members." The next sign-in or group change tries again.

Missing groups claim and the safeguard

Okta leaves the groups claim out when the filter matches none of the person's groups, and Entra leaves it out when the person is in no groups. So a sign-in without the claim counts as no groups: the member's claim-mapped roles go, and the last-group setting applies at that sign-in. Every such sign-in is recorded in the audit log, and the settings page shows how many there were in the last 30 days.

If the claim stops arriving because of a configuration problem, such as the groups scope or the claim being removed, ANTS Platform pauses removals. When at least 5 of the last 10 claim-mapped sign-ins for the organization and provider within 24 hours had no claim:

  • sign-ins without the claim keep the member's roles;
  • the settings page shows "Recent sign-ins arrived without a groups claim; removals are paused until it returns." with the affected provider.

Normal behaviour returns by itself once sign-ins carry the claim again. The first few sign-ins after a configuration breaks, before the threshold is reached, are still treated as no groups.

Stored sign-in groups older than 90 days are ignored. A member who has not signed in for that long stops counting as in their claim groups at the next recompute, and the last-group setting applies.

When roles are recomputed

EventMembers recomputed
Sign-in through a provider with an active claim mappingThe person signing in, in each organization they belong to that has verified their email domain
SCIM group change (PATCH or PUT /Groups/{id})The members added or removed
SCIM group deletedEvery member of the group. Its mappings are removed.
SCIM user created or reactivatedThat user
Admin API membership created or updatedThat user
Mapping saved or removedMembers of the group, and the members the mapping managed
Verified domain removedClaim-managed members on that domain

A failure while applying mappings at sign-in never blocks the sign-in. The member keeps their previous role and the failure is recorded in the audit log.

Edit or remove a mapping

Select the edit icon to change a mapping, or the remove icon to delete it. Both show the same preview and ask for step-up verification. When a mapping is removed, its members get their role from their other mapped groups; if none is left, the last-group setting applies.

A custom role that a mapping uses cannot be deleted until the mapping is removed or changed.

Permissions

ActionWho can do it
View mappings and managed membersMembers who can view organization members (Owner, Governance Owner, organization-level Budget AI Owner)
Add, edit or remove an organization-role mappingMembers who can manage organization members (Owner, Governance Owner), with step-up verification
Add, edit or remove a project-role mappingMembers who can manage project members at organization level, with step-up verification
Map to a custom roleAdditionally needs custom role authoring (Owner only) and the rbac-custom-roles entitlement
Change the last-group settingMembers who can manage organization members

The same guards apply as for changing roles by hand: you cannot map a group to a role ranked above yours or with permissions you do not hold, and a mapping that would change your own role can only be saved by an Owner.

Audit records

Every mapping change, and every role change a mapping causes, is recorded in Audit Logs. Each role change records the mapping, the group, and whether it came from a sign-in, SCIM, the Admin API or the settings page.

ActionWhen
create, update, delete on groupRoleMappingA mapping is saved or removed, or removed because its SCIM group was deleted
groupRoleMapping.roleUpdateA mapping changed an organization or project role
groupRoleMapping.managedA member became managed without a role change
groupRoleMapping.releasedA member left their last mapped group and kept their role, or their mapping stopped applying
groupRoleMapping.roleChangeRefusedA change was refused: the last-administrator protection, an Owner, or a role not offered for the scope (projectOnlyRole, discontinuedRole)
groupRoleMapping.claimMissingA sign-in arrived without the groups claim
groupRoleMapping.signInApplyFailedApplying mappings at sign-in failed
groupRoleMapping.updateSettingsThe last-group setting changed

Self-hosted settings

VariableDefaultMeaning
AUTH_OKTA_SCOPEnot set (openid email profile)Add groups when Okta needs the scope to send the claim.
GROUP_ROLE_MAPPING_CLAIM_MAX_AGE_DAYS90Stored sign-in groups older than this are ignored and deleted.
GROUP_ROLE_MAPPING_CLAIM_MISSING_THRESHOLD5Sign-ins without the claim, within the sample, that pause removals.
GROUP_ROLE_MAPPING_CLAIM_MISSING_SAMPLE10How many recent claim-mapped sign-ins are counted.
GROUP_ROLE_MAPPING_CLAIM_MISSING_WINDOW_HOURS24Only sign-ins this recent are counted.

Limits

  • Claim mappings change roles only at sign-in. Use SCIM groups when removals must apply at once.
  • For SCIM groups, the dialog option and the managed hint say "Okta" even when Entra pushed the group.
  • A mapping that stops applying because of a configuration change, such as a changed issuer or a removed provider, releases its members: they keep their role and can be edited by hand again. A configuration mistake never demotes anyone.
  • On a shared deployment, every organization can create claim mappings against the deployment's providers. The verified-domain rule limits each organization to its own people.

Troubleshooting

SymptomCause and fix
The provider shows (not supported)Entra is configured with common, organizations or a domain name instead of a tenant ID, or the provider has no fixed issuer or skips ID token verification.
A claim mapping changes nobodyThe members' email domain is not verified for your organization, they have not signed in since the mapping was saved, or the group name does not match the claim. For Entra, use the object ID.
Members lost their mapped role at sign-inThe sign-in carried no groups claim. Check the claim filter and the groups scope. Add an all-users group to the filter.
The paused warning is shownMost recent sign-ins arrived without the claim. Fix the claim configuration; removals resume once sign-ins carry it again.
A member's role cannot be changed on the Members pageThe member is managed by a mapping. Change their groups or the mapping.
A mapping is marked InactiveIts provider, issuer, tenant or verified domain changed, or its project was deleted. Edit or remove it.
A change is listed as refused in the previewThe member is an Owner, or the change would leave the organization without anyone who can manage members.
A mapping shows Not applied to new membersIts role is not offered for its scope any more. Edit it to an offered role.

Next steps

© 2026 ANTS Platform, Inc.Docs v1.0 · Last updated June 2026