|
| 1 | +--- |
| 2 | +title: Microsoft Entra provisioning |
| 3 | +description: Connect Microsoft Entra ID to Sim and verify user and group provisioning |
| 4 | +--- |
| 5 | + |
| 6 | +import { Callout } from 'fumadocs-ui/components/callout' |
| 7 | +import { Step, Steps } from 'fumadocs-ui/components/steps' |
| 8 | + |
| 9 | +Use a non-gallery enterprise application in Microsoft Entra ID to create, update, and deactivate Sim members. Configure [single sign-on](/platform/enterprise/sso) separately for authentication. |
| 10 | + |
| 11 | +## Before you start |
| 12 | + |
| 13 | +- An Enterprise organization in Sim, with an owner or administrator who can manage provisioning. |
| 14 | +- Each user email domain [verified in Sim](/platform/enterprise/verified-domains). |
| 15 | +- An Entra administrator who can create enterprise applications and manage provisioning. |
| 16 | +- A Sim deployment reachable by Entra over HTTPS. Self-hosted deployments must also meet the [SCIM rollout requirements](/platform/enterprise/scim#deployment-and-upgrades). |
| 17 | + |
| 18 | +Automated user provisioning is available with Entra ID Free. Group provisioning and group-based application assignment require Entra ID P1 or higher. See [Microsoft's licensing comparison](https://learn.microsoft.com/en-us/entra/fundamentals/licensing). |
| 19 | + |
| 20 | +Start with dedicated test users. Provisioned members use a seat and receive workspace access only through a mapping or an existing grant. |
| 21 | + |
| 22 | +## Connect Entra to Sim |
| 23 | + |
| 24 | +<Steps> |
| 25 | + |
| 26 | +<Step> |
| 27 | +### Enable provisioning in Sim |
| 28 | + |
| 29 | +Open **Settings → Organization → Single sign-on → Provisioning** and turn on **Enable directory provisioning**. Copy the **Base URL** from **Connection**. Under **Tokens**, choose an expiry and select **Issue token**. Copy the token before closing its dialog; Sim shows it once. |
| 30 | +</Step> |
| 31 | + |
| 32 | +<Step> |
| 33 | +### Create the enterprise application |
| 34 | + |
| 35 | +In Microsoft Entra ID, open **Enterprise applications → New application → Create your own application**. Enter a name, such as **Sim provisioning**, select **Integrate any other application you don't find in the gallery (Non-gallery)**, and select **Create**. |
| 36 | + |
| 37 | +</Step> |
| 38 | + |
| 39 | +<Step> |
| 40 | +### Configure the connection |
| 41 | + |
| 42 | +In the new application's **Provisioning** page, select **New configuration**. Choose **Bearer authentication** and enter: |
| 43 | + |
| 44 | +| Field | Value | |
| 45 | +| --- | --- | |
| 46 | +| Tenant URL | The HTTPS Base URL copied from Sim, ending in `/api/scim/v2` | |
| 47 | +| Secret token | Your Sim token, without a `Bearer ` prefix | |
| 48 | + |
| 49 | +Select **Test connection**, then **Create** after the test succeeds. Entra adds the bearer prefix itself. A successful connection test verifies connectivity and authentication; continue with a test assignment to verify provisioning. |
| 50 | + |
| 51 | + |
| 52 | + |
| 53 | +<Callout type="info"> |
| 54 | + These steps use Entra's current provisioning experience. In the legacy experience, choose **Automatic** provisioning, enter the same credentials under **Admin Credentials**, test the connection, and save. See [Microsoft's SCIM configuration guide](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/use-scim-to-provision-users-and-groups). |
| 55 | +</Callout> |
| 56 | + |
| 57 | +</Step> |
| 58 | + |
| 59 | +<Step> |
| 60 | +### Limit the scope and review mappings |
| 61 | + |
| 62 | +Under the provisioning configuration's **Properties**, keep **Scope** set to **Sync only assigned users and groups**. Review accidental deletion protection before broadening the rollout. |
| 63 | + |
| 64 | +In the application's **Users and groups**, select **Add user/group**, choose a test user, and select **Assign**. On the Free plan, assign users individually. |
| 65 | + |
| 66 | +Under **Attribute mapping**, review the user mappings. The defaults map `userPrincipalName` to `userName`, `mail` to the work email, and `displayName` to `displayName`. Use a valid email address from a verified Sim domain; if your UPN differs from the user's email, adjust the mappings before provisioning. Keep `userName` as the matching attribute. |
| 67 | + |
| 68 | +If **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 Sim domain. |
| 69 | + |
| 70 | + |
| 71 | +</Step> |
| 72 | + |
| 73 | +</Steps> |
| 74 | + |
| 75 | +## Verify a user lifecycle |
| 76 | + |
| 77 | +Open **Provision on demand**, search for the assigned test user, and select **Provision**. Review the import, scope, matching, and action results. In Sim, confirm that the member appears under **Organization → Members** and that **Single sign-on → Provisioning → Activity** shows successful requests. |
| 78 | + |
| 79 | + |
| 80 | + |
| 81 | +Change the test user's display name in Entra and provision them again. Confirm the new name in Sim. Repeating provisioning without changes should report that the source and target already match. |
| 82 | + |
| 83 | +Remove the test user's app assignment, then run on-demand provisioning for that user again. Confirm that Sim deactivates the existing member. Reassign the user and provision again to verify reactivation of the same account. Assignment changes can take a few minutes to become available to provisioning. |
| 84 | + |
| 85 | +Sim deactivation suspends access while retaining organization membership, ownership, and the seat. See [deactivation behavior](/platform/enterprise/scim#what-it-does) before using unassignment for offboarding. |
| 86 | + |
| 87 | +<Callout type="info"> |
| 88 | + Disabled or deleted Entra users cannot be selected for on-demand provisioning. Use the scheduled provisioning cycle to verify those cases. See [Microsoft's on-demand limitations](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/provision-on-demand). |
| 89 | +</Callout> |
| 90 | + |
| 91 | +## Provision groups and map access |
| 92 | + |
| 93 | +With Entra ID P1 or higher, create a dedicated security group with **Assigned** membership and add your test users as direct members. Assign that group to the enterprise application under **Users and groups**. Review the group mapping under **Attribute mapping** and keep group provisioning enabled. |
| 94 | + |
| 95 | +Run **Provision on demand** for the group and select its test members, or wait for a scheduled cycle. On-demand provisioning supports one group with up to five selected members at a time. Nested group membership is not supported; see [Microsoft's assignment guidance](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/assign-user-or-group-access-portal). |
| 96 | + |
| 97 | +Once the group appears under **Single sign-on → Provisioning → Group mappings** in Sim, map it to a workspace, permission group, or the organization admin role. Start with a workspace mapping and confirm that the test members gain access. |
| 98 | + |
| 99 | +Remove a test user from the group while keeping a separate direct app assignment. After the group membership sync, confirm that the directory workspace grant is withdrawn while the user remains an active organization member. Add them back and verify that access returns. Read [how Sim withdraws directory access](/platform/enterprise/scim#how-access-is-withdrawn) before mapping groups that overlap with existing manual access. |
| 100 | + |
| 101 | +## Start automatic provisioning |
| 102 | + |
| 103 | +After the test succeeds, return to the provisioning **Overview** and select **Start provisioning**. Wait for the initial cycle to complete and inspect **Provisioning logs** for failures. Entra normally runs subsequent cycles 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). |
| 104 | + |
| 105 | +Keep the scope limited to assigned users and groups as you add more members. Use **Provision on demand** for a small test; use the regular cycle to verify directory account disablement and deletion. |
| 106 | + |
| 107 | +## Rotate the token |
| 108 | + |
| 109 | +Issue a replacement token in Sim while the current token remains active. In Entra, open the provisioning configuration's **Connectivity** page, replace **Secret token**, select **Test connection**, and save. Confirm a successful provisioning request before revoking the old token in Sim. Sim allows two active tokens so rotation can overlap. |
| 110 | + |
| 111 | +## Troubleshooting |
| 112 | + |
| 113 | +| Symptom | Check | |
| 114 | +| --- | --- | |
| 115 | +| Connection test fails | Enter only the token in **Secret token**. Check the complete HTTPS Tenant URL, token expiry, and whether provisioning is enabled in Sim. | |
| 116 | +| User is out of scope | Assign the user to this enterprise application and check the provisioning scope and scoping filters. Allow time for assignment changes to propagate. | |
| 117 | +| User creation fails | Verify the email domain in Sim, available seats, and whether the account belongs to another Sim organization. Review the mapped UPN and work email. | |
| 118 | +| Repeat provisioning reports **Skipped** | Inspect the reason. **RedundantExport** means the source and target already match. | |
| 119 | +| Group assignment is unavailable | Check your Entra license. The Free plan supports individual user assignment but requires an upgrade for group assignment and provisioning. | |
| 120 | +| Member has no workspace access | Provision the directory group and add a workspace mapping in Sim. User provisioning creates organization membership. | |
| 121 | +| Disabled member still uses a seat | Sim suspends access on deactivation. Removing organization membership is a separate offboarding action. | |
| 122 | + |
| 123 | +Use Entra's **Provisioning logs** and Sim's **Provisioning → Activity** to inspect failures. Invalid or revoked tokens appear only in Entra because Sim cannot associate those requests with a connection. |
0 commit comments