Skip to content
ATLAS
 Docs
On this page

Map Entra groups to ATLAS roles#

Let Microsoft Entra security groups decide who is an Admin or Member in ATLAS, and restrict sign-in to the people in those groups. You create the groups in Entra, and ilionx enters the group IDs on the ATLAS side.

By default, ATLAS manages a person's organisation role itself. When Entra decides, ATLAS reads the role from the person's Microsoft sign-in, so a group change applies the next time the person signs in. With SCIM (System for Cross-domain Identity Management), it applies when Entra pushes the change.

Before you begin#

  • Sign-in works. See Configure Microsoft Entra ID sign-in.
  • Licensing: role groups and sign-in assignment restrictions need Entra ID P1 or higher.
  • In Entra: you can create security groups and edit the app registration's Token configuration.

Map groups to roles#

  1. In Entra, create one security group per role you want to grant, usually two: for example "ATLAS Admins" and "ATLAS Members". Put people directly in these groups. ATLAS doesn't evaluate nested groups.

  2. Open the app registration, go to Token configuration > Add groups claim, and select Security groups only. Under Customize token properties, restrict the claim to Groups assigned to the application.

  3. Assign the role groups to the application (see Restrict sign-in to assigned groups).

  4. For each group, copy its Object ID from Groups > the group > Overview and send it to your ilionx contact, saying which role each group should grant.

  5. ilionx switches the organisation's role source to your identity provider and maps each Object ID to a role:

    • Admin and Member each need at least one group.
    • Account Manager and Auditor are optional. If you map no group, nobody gets that role.
    • Owner is always managed in ATLAS and never comes from a group.

Warning

Avoid group overage

If the claim carries every group a person belongs to, a person in many groups triggers Entra's "groups overage" behaviour. The token then holds a pointer instead of the group list. ATLAS can't resolve that and suspends the member with the reason Group overage (identity provider sent too many groups). Limiting the claim to assigned groups avoids it.

Result: group membership now decides both access and role. A person in no mapped group gets no access. A person in several mapped groups gets the highest role.

Switch an organisation that already has members#

When an existing organisation switches to Identity provider, members keep their current role until their next sign-in, when it's re-evaluated against their groups.

  • A member in no mapped group is suspended with the reason No upstream role. ATLAS deletes nobody. When the person is added to a mapped group, ATLAS lifts the suspension automatically at their next sign-in.
  • The Owner is never affected. Pending invitations are unaffected too.
  • Switching back to roles managed in ATLAS turns the roles from the identity provider into manual roles, so nobody loses access. It doesn't resume members who were already suspended. An Admin must resume them.

You can't resume a member suspended for No upstream role while the identity provider still manages roles. Fix the group membership first.

Restrict sign-in to assigned groups#

By default, any user in your Entra tenant can try to sign in, and ATLAS then refuses those who are in no mapped group. To stop unrelated users from starting the flow:

  1. In Entra, go to Enterprise applications, select the sign-in application, and open Properties. Set Assignment required? to Yes.
  2. Open Users and groups and assign only the role groups you created.

If you use SCIM, the separate provisioning application has its own Users and groups assignment. Assign the same groups there.

Test before go-live#

Test before you roll sign-in out to everyone. A mistake can lock real people out.

  1. Sign in as a test user from each mapped group and confirm ATLAS grants the expected role.
  2. Try a user who is in no mapped group. Confirm ATLAS refuses access or suspends the member.

How group changes take effect#

Without SCIM, a group change in Entra applies at the person's next sign-in. A person who is already signed in keeps their old Entra roles until they sign in again.

In Entra Effect in ATLAS
User added to a mapped group Gains that group's role
User moved between mapped groups Role changes to the new group's role, or the highest if still in several
User removed from every mapped group Suspended with No upstream role. Restored automatically at the next sign-in after you add them to a mapped group again
User account disabled or deleted Cannot complete a Microsoft sign-in. The ATLAS member stays until you remove them
Mapped group renamed No effect. ATLAS maps by Object ID, not name
Mapped group deleted Members lose that role. The mapping shows "Group no longer exists in the identity provider" once SCIM is on
Group owner changed in Entra No effect. Group ownership is unrelated to membership

With SCIM on, Entra pushes these changes without waiting for a sign-in, and ATLAS applies them when they arrive. For more information, see Provision members with SCIM.

Troubleshooting#

Symptom Cause and remedy
A user is told they are not assigned to the application Check Assignment required? on the enterprise application and confirm the user is a direct member of an assigned group.
Role groups are ignored Check that Token configuration contains the groups claim and that it is limited to groups assigned to the application.
A member is suspended for Group overage (identity provider sent too many groups) The person belongs to too many groups for the token to carry. Limit the claim to assigned groups.
A member is suspended with No upstream role The person is in no mapped group. Add them to a mapped group.