Provision members with SCIM#

Let Microsoft Entra ID create, update, deactivate and remove ATLAS members automatically, instead of ATLAS learning about people when they first sign in.

SCIM (System for Cross-domain Identity Management) is optional. Sign-in with role groups is complete without it. For more information, see Configure Microsoft Entra ID sign-in and Map Entra groups to ATLAS roles.

SCIM never replaces sign-in. People still sign in through the Entra sign-in application. For what changes with SCIM, see SCIM provisioning.

Before you begin#

• Entra role: you need the Application Administrator or Cloud Application Administrator role.
• Sign-in works: the organisation has Entra sign-in configured, and role groups too if groups should decide roles. See the two guides linked above.
• Verified email domain: every provisioned person's email must be on a domain verified for the organisation. ATLAS rejects anyone else.
• Free seats: provisioning a new person uses a seat. With none free, ATLAS refuses the create with a 403 seat-limit error (ERR-0132), and Entra retries on its next cycle. Free a seat, or ask your ilionx contact to raise the seat limit.
• Licensing: assigning groups to an enterprise application needs Entra ID P1 or higher.

Get the endpoint and token#

Ask your ilionx contact to turn on SCIM for your organisation. They send you, over separate secure channels:

• The Base URL. Replace <atlas-host> with your ATLAS host. It has this shape:

  https://<atlas-host>/api/v1/scim/organizations/<organization-id>/v2

• The SCIM token, shown once. If you lose it, ask your ilionx contact for a new one.

Create the provisioning application in Entra#

Use a separate enterprise application for provisioning. Don't reuse the sign-in app registration. You configure automatic provisioning to a custom SCIM endpoint on a non-gallery enterprise application. Keeping the two apart means a change to provisioning scope can't break sign-in.

1. In the Microsoft Entra admin center, go to Entra ID > Enterprise apps > New application.
2. Select Create your own application and name it, for example "ATLAS provisioning". Choose Integrate any other application you don't find in the gallery (Non-gallery) and select Create.
3. Open the application and go to Provisioning > Get started. Set Provisioning Mode to Automatic.
4. Under Admin Credentials, enter the ATLAS Base URL as the Tenant URL and the token as the Secret Token. Never leave Secret Token blank. Entra then sends a token of its own and ATLAS answers 401 Unauthorized.
5. Select Test Connection. Success means ATLAS accepted the token.
6. Select Save.
7. Under Settings, add a Notification Email and tick Send an email notification when a failure occurs. This way a paused ("quarantined") job doesn't go unnoticed.

Check the attribute mappings#

Open Provisioning > Mappings > Provision Microsoft Entra ID Users. Entra's defaults work for most tenants. ATLAS uses only the attributes below. It ignores everything else Entra sends, including job title, department, manager, phone numbers, addresses, the enterprise extension and roles.

• userName: Entra default userPrincipalName. Must be the person's email address on a verified domain. If your user principal names aren't real email addresses, change the source to mail.
• emails[type eq "work"].value: Entra default mail. Fallback when userName isn't usable as the email.
• externalId: Entra default mailNickname. Must be unique within the organisation. ATLAS refuses a duplicate with HTTP 409.
• name.givenName and name.familyName: Entra defaults givenName and surname. If both are missing, ATLAS splits displayName at the first space.
• active: Entra default IsSoftDeleted (inverted). Drives deactivation and reactivation.

Then open Provision Microsoft Entra ID Groups and keep the defaults: displayName to displayName, objectId to externalId, and members to members. ATLAS requires displayName on every group. It also needs externalId to be the group's Object ID. This is the same ID you gave your ilionx contact when mapping groups to roles. It ties a pushed group to its role mapping. The externalId must be unique among your organisation's groups. ATLAS refuses a group whose externalId another group already uses, with HTTP 409.

Choose scope and assign groups#

1. In the provisioning application, go to Provisioning > Settings > Scope and choose Sync only assigned users and groups. The alternative, syncing everything, pushes your whole directory to ATLAS.
2. Go to Users and groups > Add user/group and assign the same role security groups that are mapped to roles, for example "ATLAS Admins" and "ATLAS Members".

Three things catch people out:

• Assignment is separate from sign-in. Entra provisions only people and groups assigned to the provisioning application. Membership of a role group isn't enough if you haven't assigned the group here.
• Groups must be pushed. Roles under SCIM follow the groups Entra pushes. A role mapping whose group Entra has never pushed shows as missing in ATLAS.
• Nested groups aren't provisioned. Entra sends only direct members of an assigned group, so put people directly in the role groups.

When SCIM is on and the Identity provider manages roles, ATLAS applies the highest mapped base role (Admin over Member), plus any Account Manager and Auditor roles. It does so as soon as Entra sends a group change.

A provisioned member in no mapped base group is suspended with the reason No upstream role and regains access once added to one. The Owner's role is never changed by groups.

Test, then start provisioning#

1. In the provisioning application, go to Provisioning > Provision on demand, pick a test user who is in a role group and run it. Confirm the user and group steps succeed.
2. In ATLAS, the person shows a SCIM badge in the member list.
3. In Entra, go to Provisioning > Overview and select Start provisioning. The first cycle takes longer on large directories. Afterwards, according to Microsoft's documentation, Entra provisions about every 40 minutes.
4. Check Monitor > Provisioning logs in the application for failures.

A newly provisioned person arrives as a Member, or with the role of their mapped group. What happens to a person depends on whether ATLAS already knows them:

• Not yet known: ATLAS creates a SCIM-managed member, which uses a seat.
• Already a member of this organisation: ATLAS adopts them as SCIM-managed. Spaces, budgets and API keys are unchanged, and no extra seat is used.
• Has a pending invitation: the invitation becomes a membership, and the invited role is kept.
• Email already belongs to another organisation, or the person is already SCIM-managed: ATLAS refuses with HTTP 409. A person belongs to one organisation.

Provisioned people sign in as usual with their Microsoft account. On the first sign-in, ATLAS links the Microsoft identity to the provisioned member by email. It links only members whose email is on one of the organisation's domains. If linking fails, the person sees an error page and no session is created.

Finalise the cut-over#

While SCIM is on but not finalised, the Status reads Transition. Members not provisioned by SCIM keep working, so you can migrate without a hard stop. Finalising makes SCIM the only way in. Ask your ilionx contact to finalise once you're ready.

1. Make sure Entra provisions the organisation's Owner. Until then, ATLAS can't finalise.
2. Agree with your ilionx contact which members are still unmanaged, and provision anyone who should stay.
3. Your ilionx contact finalises the cut-over, after confirming how many members will be suspended.

Result: SCIM is enforced, and:

• ATLAS suspends every enabled member not managed through SCIM. The reason reads "Not provisioned by the organisation's identity provider". Their sessions end.
• ATLAS withdraws all pending invitations.
• ATLAS refuses anyone who isn't a member and has no invitation. They see "Access is managed by your organisation's directory".
• A suspended person who is provisioned later is reinstated automatically, seat permitting.
• You can transfer ownership only to an enabled SCIM-managed member.
• Admins can't lift SCIM suspensions by hand while SCIM is on. Provision the person instead, or ask your ilionx contact.

If you finalised too early, assign the missing people in the Entra provisioning application. ATLAS reinstates them on the next cycle, or straight away with Provision on demand.

What happens when people change in Entra#

Entra sends changes on its sync cycle, which Microsoft says runs about every 40 minutes. ATLAS applies each change in the same request.

• Group or role change: the member's role follows the mapped groups. A member in no mapped group is suspended with No upstream role.
• Account disabled, soft-deleted, unassigned or out of scope: ATLAS deactivates the member with the reason "Deactivated in identity provider", ends sessions and frees the seat. Re-enabling the account reactivates the member, seat permitting.
• Account permanently deleted: after Entra's retention period, ATLAS deletes the member with their personal API keys, space memberships and budget allocations. Project API keys keep working.
• Email changed: ATLAS updates the email and sign-in name. ATLAS refuses the change if the new domain is unverified or the email is taken.
• Mapped group deleted: members lose that role. Renaming a group has no effect, because ATLAS maps by Object ID.
• Organisation Owner disabled or deleted: ATLAS refuses the change and keeps the Owner. Transfer ownership first.

For more information, see SCIM provisioning.

Replace or revoke the SCIM token#

Ask for a new token on a schedule and whenever someone with access leaves. The token has no other expiry.

1. Ask your ilionx contact for a new token. They send it to you over a secure channel, and it's shown only once.
2. In Entra, open the provisioning application, go to Provisioning > Admin Credentials, replace Secret Token, select Test Connection and then Save.

Result: provisioning continues with the new token.

To cut access immediately, for example after a leak, ask your ilionx contact to revoke the token. ATLAS refuses Entra's requests until your ilionx contact issues a new token. SCIM stays on, and members don't change.

Turn off SCIM#

Turn SCIM off to go back if a cut-over goes wrong.

1. Ask your ilionx contact to turn SCIM off.
2. In Entra, set the provisioning application to Off, or delete it, so it stops failing.

Result:

• The SCIM token stops working, and ATLAS refuses Entra's requests.
• If you had finalised the cut-over, ATLAS restores people suspended as not provisioned, seat permitting. Anyone left out stays suspended until a seat is free.
• ATLAS removes the Account Manager and Auditor roles that SCIM granted, and deletes the SCIM groups. If Entra decides roles, SCIM-managed Admins become Members. The Owner keeps their role.
• After that, roles follow the organisation's role source. If roles are managed in ATLAS, they apply on the person's next request and an Admin edits them in Manage > Members. If Entra decides, a person's role comes from their groups at their next sign-in.
• ATLAS deletes no member. Members deactivated by Entra stay deactivated until an Admin resumes them.

Troubleshooting#

Check Monitor > Provisioning logs in the Entra application first. It shows ATLAS's response for each failure.

• Test Connection fails with 401: The Secret Token is blank, wrong, revoked, or replaced by a newer token. Paste the current token.
• Test Connection fails with 404: The Tenant URL is incomplete. It must end in /v2 and contain the correct organisation identifier.
• Provisioning is quarantined, or every request returns 401 "Authentication failed.": Check that the Secret Token in Entra is the current token and that nobody replaced or revoked it. If it's correct, ask your ilionx contact to confirm that SCIM is still enabled for your organisation, then restart provisioning in Entra.
• Users don't appear in ATLAS: Check that the user is assigned to the provisioning application, not only the sign-in application. Check that the scope is Sync only assigned users and groups, and that you aren't relying on nested groups.
• A create is refused: The email domain isn't verified for the organisation, the email belongs to another organisation, or no seat is free. Verify the domain or change the userName mapping source. Free a seat, or ask your ilionx contact to raise the seat limit. Entra retries on its next cycle.
• Duplicate externalId (409): Two Entra users map to the same externalId, often through mailNickname. Change the mapping source.
• A role from a group isn't applied: Confirm that the group is assigned to the provisioning application and that the person is a direct member. Also check that its Object ID equals the group ID mapped to the role and that the mapping isn't flagged as missing.
• A member is suspended with "No upstream role": They are in no mapped base group. Add them to one.
• A member shows "Deactivated in identity provider": The account is disabled, unassigned or soft-deleted in Entra. Re-enable or reassign it there.
• A person sees "Access is managed by your organisation's directory": They aren't provisioned, and the cut-over has been finalised. Assign them in the provisioning application.
• First sign-in fails after provisioning: The person's email in Entra changed after provisioning, so ATLAS can't link the identity. Restore the original email and retry.
• The Owner can't be deactivated or deleted: Transfer ownership to another SCIM-managed member first.
• Admins can't resume a suspended member: While SCIM is on, only provisioning the person or your ilionx contact can lift deactivation and not-provisioned suspensions. Nobody can resume a suspension for No upstream role while the identity provider manages roles.

Related#

• Configure Microsoft Entra ID sign-in
• Map Entra groups to ATLAS roles
• Identity and access
• Manage organisation members