# Microsoft Entra provisioning (/platform/enterprise/scim/entra)





Use a non-gallery enterprise application in Microsoft Entra ID to create, update, and deactivate Sim organization members. Configure [single sign-on](/platform/enterprise/sso) separately for authentication.

## Before you start [#before-you-start]

* Use an Enterprise organization in Sim and an organization owner or admin account.
* [Verify each provisioned email domain](/platform/enterprise/verified-domains).
* Use an Entra administrator who can create enterprise applications and manage provisioning.
* Make Sim reachable by Entra over HTTPS. Self-hosted deployments must meet the [SCIM rollout requirements](/platform/enterprise/scim#deployment-and-upgrades).

Automated user provisioning is available with Entra ID Free. Group provisioning and group-based application assignment require P1 or higher. See [Microsoft licensing](https://learn.microsoft.com/en-us/entra/fundamentals/licensing).

Start with dedicated test accounts. Provisioned members use a seat and receive workspace access through mappings or existing grants.

## Connect Entra to Sim [#connect-entra-to-sim]

<Steps>
  <Step>
    ### Enable provisioning in Sim [#enable-provisioning-in-sim]

    Open **Settings → Organization → Single sign-on → Provisioning** and enable **Enable directory provisioning**. Copy **Connection → Base URL**. Under **Tokens**, choose an expiry and select **Issue token**. Copy the token before closing its dialog; Sim shows it once.
  </Step>

  <Step>
    ### Create the enterprise application [#create-the-enterprise-application]

    In Entra, open **Enterprise applications → New application → Create your own application**. Name the app, for example **Sim provisioning**, choose &#x2A;*Integrate any other application you don't find in the gallery (Non-gallery)**, and select **Create**.
  </Step>

  <Step>
    ### Configure the connection [#configure-the-connection]

    Open the app's **Provisioning** page, select **New configuration**, and choose **Bearer authentication**.

    | Field | Value |
    | - | - |
    | **Tenant URL** | Sim's HTTPS Base URL ending in `/api/scim/v2` |
    | **Secret token** | Your Sim token, without a `Bearer ` prefix |

    Select **Test connection**, then **Create** after it succeeds. Entra adds the bearer prefix. A successful test confirms connectivity and authentication; a test assignment verifies provisioning.

    <Image src="/static/enterprise/entra/connection.png" alt="Entra Bearer authentication fields with a redacted Tenant URL and masked Secret token" width="808" height="305" className="mx-auto h-auto w-full max-w-xl" />

    <Callout type="info">
      In Entra's legacy provisioning experience, choose **Automatic**, enter the same values under **Admin Credentials**, test, and save. See [Microsoft SCIM configuration](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/use-scim-to-provision-users-and-groups).
    </Callout>
  </Step>

  <Step>
    ### Set scope and attribute mappings [#set-scope-and-attribute-mappings]

    In the configuration's **Properties**, keep **Scope** set to **Sync only assigned users and groups**. Review accidental deletion protection before broadening the rollout.

    Under **Users and groups → Add user/group**, choose a test account and select **Assign**. On the Free plan, assign accounts individually.

    Under **Attribute mapping**, review the user mappings:

    | Entra attribute | SCIM attribute |
    | - | - |
    | `userPrincipalName` | `userName`, retained as the matching attribute |
    | `mail` | Work email |
    | `displayName` | `displayName` |

    Use an email in a verified Sim domain. If the UPN differs from the account email, adjust mappings before provisioning. When **Mail** is empty, Entra omits the work email and Sim uses `userName` as the account email; that UPN must be a valid email address in a verified domain.

    <Image src="/static/enterprise/entra/scope.png" alt="Entra Properties showing assigned-only provisioning scope, accidental deletion protection, and Skip out of scope deletions disabled" width="810" height="250" className="mx-auto h-auto w-full max-w-xl" />
  </Step>
</Steps>

## Verify the user lifecycle [#verify-the-user-lifecycle]

1. Open **Provision on demand**, search for the assigned test account, and select **Provision**. Inspect the import, scope, matching, and action results.
2. In Sim, confirm the member under **Organization → Members** and successful requests under **Single sign-on → Provisioning → Activity**.
3. Change its display name in Entra and provision again. Confirm the new name in Sim. An unchanged repeat should report that source and target already match.
4. Remove the app assignment, then provision that account on demand again. Confirm Sim deactivates the member.
5. Reassign and provision it to verify reactivation of the same account. Assignment changes can take a few minutes to reach provisioning.

<Image src="/static/enterprise/entra/provision-user.png" alt="Successful Entra on-demand import, scope, matching, and action checks with account details redacted" width="812" height="626" className="mx-auto h-auto w-full max-w-xl" />

### Deactivation and directory deletion [#deactivation-and-directory-deletion]

| Entra change | Provisioning behavior |
| - | - |
| App unassignment | Deactivates the Sim member. Entra then stops managing the account and does not send a later directory deletion. |
| Soft deletion while still managed | Deactivates the Sim member. |
| Permanent deletion while still managed | Sends SCIM `DELETE`, which removes organization membership. Entra normally permanently deletes accounts 30 days after soft deletion; an administrator can purge earlier. |

Sim deactivation suspends access while retaining membership, ownership, and the seat. See [Microsoft's deprovisioning lifecycle](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/how-provisioning-works#deprovisioning) and [Sim's lifecycle behavior](/platform/enterprise/scim#what-it-does).

<Callout type="info">
  Disabled or deleted Entra accounts do not appear in on-demand search. Start automatic provisioning and finish the initial cycle before testing those changes through a scheduled cycle. See [Microsoft on-demand limitations](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/provision-on-demand).
</Callout>

## Provision groups and verify access [#provision-groups-and-verify-access]

With P1 or higher, create a security group with **Assigned** membership and add test accounts as direct members. Assign it under **Users and groups**. Review **Attribute mapping** and keep group provisioning enabled.

1. Run **Provision on demand** for one group and select up to five test members, or wait for a scheduled cycle. Nested membership is unsupported; see [Microsoft group assignment](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/assign-user-or-group-access-portal).
2. Once the group appears under **Single sign-on → Provisioning → Group mappings** in Sim, map it to a workspace, permission group, or organization admin role. Start with a workspace mapping and confirm access.
3. Remove a test member from the group while retaining a separate direct app assignment. After synchronization, confirm the directory workspace grant is withdrawn while the account remains active.
4. Add the member back and verify access returns.

Read [How access is withdrawn](/platform/enterprise/scim#how-access-is-withdrawn) before mapping groups that overlap manual access.

## Start automatic provisioning [#start-automatic-provisioning]

After testing, return to the provisioning **Overview** and select **Start provisioning**. Wait for the initial cycle and inspect **Provisioning logs** for failures. Subsequent cycles normally run about every 40 minutes; changes are not immediate. See [Microsoft's provisioning lifecycle](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/how-provisioning-works).

Keep the scope limited to assigned accounts and groups. Use on-demand provisioning for small tests, and regular cycles for directory disablement or deletion.

Leave the job running during a scheduled lifecycle test. **Restart provisioning** clears its change watermark and starts another initial cycle; changing mappings or scoping filters also resets it. Wait for the incremental cycle and inspect the account's log before changing more settings.

## Rotate a token [#rotate-a-token]

Issue a replacement token in Sim while the current one remains active. In Entra's provisioning configuration, open **Connectivity**, replace **Secret token**, select **Test connection**, and save. Confirm a successful provisioning request before revoking the old token. Sim allows two active tokens for overlapping rotation.

## Troubleshooting [#troubleshooting]

| Symptom | Check |
| - | - |
| Connection test fails | Enter the token alone. Check the full HTTPS Tenant URL, token expiry, and Sim provisioning switch. |
| Account is out of scope | Check app assignment, provisioning scope, and scoping filters. Allow time for assignment propagation. |
| User creation fails | Verify the domain, available seats, and whether the account belongs to another Sim organization. Check mapped UPN and work email. |
| Repeat provisioning is **Skipped** | Inspect its reason. **RedundantExport** means source and target already match. |
| Disablement or deletion has not reached Sim | Inspect the scheduled log, `IsSoftDeleted` mapping to `active`, enabled **Update** actions, and accidental deletion protection. Confirm **Skip out of scope deletions** is disabled. A connection test does not verify lifecycle changes. |
| Group assignment is unavailable | Check licensing. Free supports individual assignment; group assignment and provisioning require an upgrade. |
| Member has no workspace access | Provision the directory group and add a Sim workspace mapping. User provisioning adds organization membership. |
| A disabled member still uses a seat | Deactivation suspends access; organization removal is separate. |

Use Entra's **Provisioning logs** and Sim's **Provisioning → Activity**. Invalid or revoked tokens appear only in Entra because Sim cannot associate them with a connection.

## Related docs [#related-docs]

* [Directory provisioning](/platform/enterprise/scim)
* [Single sign-on](/platform/enterprise/sso)
* [Verified domains](/platform/enterprise/verified-domains)