# 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](https://docs.atlas.ilionx.dev/reference/glossary.md) 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](https://docs.atlas.ilionx.dev/guides/admin/identity-and-access-configure-entra-sign-in.md).
- **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](https://docs.atlas.ilionx.dev/guides/admin/identity-and-access-map-entra-groups-to-roles.md#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](https://docs.atlas.ilionx.dev/guides/admin/identity-and-access-provision-members-with-scim.md#what-happens-when-people-change-in-entra).

## 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.                                                              |

## Related

- [Configure Microsoft Entra ID sign-in](https://docs.atlas.ilionx.dev/guides/admin/identity-and-access-configure-entra-sign-in.md)
- [Provision members with SCIM](https://docs.atlas.ilionx.dev/guides/admin/identity-and-access-provision-members-with-scim.md)
- [Roles and permissions](https://docs.atlas.ilionx.dev/reference/roles-and-permissions.md)
- [Identity and access](https://docs.atlas.ilionx.dev/concepts/identity-and-access.md)