# 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](https://docs.atlas.ilionx.dev/guides/admin/identity-and-access-configure-entra-sign-in.md) and [Map Entra groups to ATLAS roles](https://docs.atlas.ilionx.dev/guides/admin/identity-and-access-map-entra-groups-to-roles.md). > [!NOTE] > **What ilionx does** > > Your ilionx contact turns SCIM on, issues and rotates the token, finalises the cut-over, and turns SCIM off. Your own steps are in Entra. > [!NOTE] > **Entra labels and timings** > > Microsoft sets the Entra portal labels, menu paths and timings, such as the sync cycle and the retention period for deleted users. They can change. See [Microsoft's documentation](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/how-provisioning-works). If your portal differs, follow Microsoft's current guidance. If you can, try the setup in a non-production tenant first. SCIM never replaces sign-in. People still sign in through the Entra sign-in application. For what changes with SCIM, see [SCIM provisioning](https://docs.atlas.ilionx.dev/concepts/identity-and-access.md#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. > [!WARNING] > **The SCIM token is a credential** > > Anyone holding the token can create, deactivate and delete members and change their roles through group membership. Store it in a secret manager, not in tickets, chat or screenshots. Ask for a new one when people with access leave. ## 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 `` with your ATLAS host. It has this shape: ```text https:///api/v1/scim/organizations//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](https://entra.microsoft.com), 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. > [!WARNING] > **Settle email addresses first** > > ATLAS links a person's first sign-in to the provisioned member by email. If you change someone's email in Entra before they first sign in, ATLAS can't link the sign-in. ## 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](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/how-provisioning-works), 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. > [!WARNING] > **Finalising suspends people** > > Don't finalise until everyone who should keep access is provisioned. Everyone still unmanaged loses access, including guests and members from other email domains. 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](https://docs.atlas.ilionx.dev/concepts/identity-and-access.md#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](https://docs.atlas.ilionx.dev/guides/admin/identity-and-access-configure-entra-sign-in.md) - [Map Entra groups to ATLAS roles](https://docs.atlas.ilionx.dev/guides/admin/identity-and-access-map-entra-groups-to-roles.md) - [Identity and access](https://docs.atlas.ilionx.dev/concepts/identity-and-access.md) - [Manage organisation members](https://docs.atlas.ilionx.dev/guides/admin/organisations-manage-members.md)