Map Entra groups to ATLAS roles#

Let Microsoft Entra decide who is an Admin or Member in ATLAS, and restrict sign-in to the people you assign. You choose how Entra sends roles: through security groups or through app roles. With groups, you create the groups in Entra and ilionx enters the group IDs on the ATLAS side. With app roles, you create the roles in Entra and ilionx needs no IDs from you. For more information, see Use app roles instead of groups.

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 change applies the next time the person signs in. With groups and SCIM (System for Cross-domain Identity Management), it applies when Entra pushes the change.

An organisation uses one method at a time. ATLAS never combines groups and app roles.

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. Assigning groups to app roles needs P1 too. Assigning individual people to app roles doesn't.
• In Entra: you can create security groups and edit the app registration's Token configuration, or create App roles on the app registration.

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.

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.

Use app roles instead of groups#

App roles suit organisations that prefer to assign people to a role directly, or don't want to look up and send group Object IDs. You define the roles on your own ATLAS app registration, and Entra sends them in the sign-in token. The roles claim never triggers group overage.

Create the app roles in Entra#

ATLAS expects these values by default. The first two are required.

Values are case-sensitive and can't contain spaces. Ask your ilionx contact if you need different values. Each ATLAS role takes one value, and Owner is always managed in ATLAS.

1. In the Microsoft Entra admin center, open App registrations and select the ATLAS app registration.
2. Go to App roles > Create app role.
3. Enter a Display name and a Description. Set Allowed member types to Users/Groups, enter the Value from the table, and select Apply.
4. Repeat for each role you want to use. Create at least Atlas.Admin and Atlas.Member.

Result: the roles appear on the app registration. Entra adds them to the roles claim in the token, so you don't edit Token configuration.

Assign people to the app roles#

1. In Entra, go to Enterprise applications, select the sign-in application and open Users and groups.
2. Select Add user/group, pick the person (or group), and choose the app role.
3. Select Assign.

To stop unrelated people from starting the sign-in flow, set Assignment required? to Yes under Properties. See Restrict sign-in to assigned groups, which applies to app-role assignments too.

Ask ilionx to choose app roles#

Tell your ilionx contact that you want app roles. They set Claim type to App roles for the organisation and confirm the values. They leave Claim name as roles, which is what Entra uses.

Result: a person with a mapped app role gets that role. A person with several gets the highest base role, plus every Account Manager or Auditor role they hold. A person with no mapped app role gets no access.

An existing member with no mapped app role is suspended with the reason No upstream role, as with groups. A person who has never signed in is refused.

Switch between groups and app roles#

• Groups to app roles: ATLAS doesn't recalculate anything. People keep their role until their next sign-in. In the meantime, a person who signed in before the switch sees "Sign in again to apply your roles". Make sure people are assigned to the app roles before they sign in, or they are suspended.
• App roles to groups: your ilionx contact first sees which members would change role or be suspended. With SCIM, ATLAS recalculates roles straight away from your saved group mappings. Without SCIM, roles change at each person's next sign-in.
• ATLAS keeps the group mappings and the app role values separately, so switching back restores what you had.

Admins see the claim type, claim name and values on the organisation's Roles tab. They can't edit them.

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. With app roles, the same applies to role assignments: assigning, changing or removing an app role takes effect at the next sign-in.

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#

Related#

• Configure Microsoft Entra ID sign-in
• Provision members with SCIM
• Roles and permissions
• Identity and access