improvement(docs): document Entra SCIM setup and validation

apps/docs/content/docs/platform/enterprise/scim/entra.mdx

@@ -0,0 +1,123 @@
+---
+title: Microsoft Entra provisioning
+description: Connect Microsoft Entra ID to Sim and verify user and group provisioning
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Step, Steps } from 'fumadocs-ui/components/steps'
+
+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.
+
+## Before you start
+
+- An Enterprise organization in Sim, with an owner or administrator who can manage provisioning.
+- Each user email domain [verified in Sim](/platform/enterprise/verified-domains).
+- An Entra administrator who can create enterprise applications and manage provisioning.
+- A Sim deployment reachable by Entra over HTTPS. Self-hosted deployments must also 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 Entra ID P1 or higher. See [Microsoft's licensing comparison](https://learn.microsoft.com/en-us/entra/fundamentals/licensing).
+
+Start with dedicated test users. Provisioned members use a seat and receive workspace access only through a mapping or an existing grant.
+
+## Connect Entra to Sim
+
+<Steps>
+
+<Step>
+### Enable provisioning in Sim
+
+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.
+</Step>
+
+<Step>
+### Create the enterprise application
+
+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**.
+
+</Step>
+
+<Step>
+### Configure the connection
+
+In the new application's **Provisioning** page, select **New configuration**. Choose **Bearer authentication** and enter:
+
+| Field | Value |
+| --- | --- |
+| Tenant URL | The HTTPS Base URL copied from Sim, ending in `/api/scim/v2` |
+| Secret token | Your Sim token, without a `Bearer ` prefix |
+
+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.
+
+![Entra provisioning connection settings with the deployment URL redacted and secret token masked](/static/enterprise/entra/connection.png)
+
+<Callout type="info">
+  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).
+</Callout>
+
+</Step>
+
+<Step>
+### Limit the scope and review mappings
+
+Under the provisioning configuration's **Properties**, keep **Scope** set to **Sync only assigned users and groups**. Review accidental deletion protection before broadening the rollout.
+
+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.
+
+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.
+
+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.
+
+![Entra provisioning properties restricted to assigned users and groups](/static/enterprise/entra/scope.png)
+</Step>
+
+</Steps>
+
+## Verify a user lifecycle
+
+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.
+
+![Successful on-demand user provisioning in Entra with account details redacted](/static/enterprise/entra/provision-user.png)
+
+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.
+
+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.
+
+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.
+
+<Callout type="info">
+  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).
+</Callout>
+
+## Provision groups and map access
+
+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.
+
+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).
+
+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.
+
+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.
+
+## Start automatic provisioning
+
+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).
+
+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.
+
+## Rotate the token
+
+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.
+
+## Troubleshooting
+
+| Symptom | Check |
+| --- | --- |
+| 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. |
+| 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. |
+| 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. |
+| Repeat provisioning reports **Skipped** | Inspect the reason. **RedundantExport** means the source and target already match. |
+| Group assignment is unavailable | Check your Entra license. The Free plan supports individual user assignment but requires an upgrade for group assignment and provisioning. |
+| Member has no workspace access | Provision the directory group and add a workspace mapping in Sim. User provisioning creates organization membership. |
+| Disabled member still uses a seat | Sim suspends access on deactivation. Removing organization membership is a separate offboarding action. |
+
+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.

apps/docs/content/docs/platform/enterprise/scim/index.mdx

@@ -84,12 +84,14 @@ Okta never deletes users over SCIM. Unassigning someone, or deactivating them in
 </Tab>
 <Tab value="Microsoft Entra ID">
 
-In your enterprise application, open **Provisioning** and set Provisioning Mode to **Automatic**.
+For a step-by-step walkthrough, see [Microsoft Entra provisioning](/platform/enterprise/scim/entra).
+
+Create a non-gallery enterprise application. Open **Provisioning → New configuration** and choose **Bearer authentication**. In the legacy experience, set Provisioning Mode to **Automatic** instead.
 
 - **Tenant URL**: `https://<your-sim-domain>/api/scim/v2`
-- **Secret Token**: your Sim token
+- **Secret token**: your Sim token, without a `Bearer ` prefix
 
-Select **Test Connection**, then save and start provisioning.
+Test the connection and create the configuration. Keep **Sync only assigned users and groups** as the scope, assign a test user, and verify them with **Provision on demand** before starting automatic provisioning. Group provisioning requires Entra ID P1 or higher; individual user provisioning is available on the Free plan.
 
 Entra runs an initial cycle over everyone in scope, then incremental cycles roughly every 40 minutes. Unassignment normally sends a deactivation. Soft-deleted directory users are retained for 30 days; hard deletion can then send a SCIM DELETE during a provisioning cycle. An administrator can hard-delete earlier, and users already unassigned may no longer be managed. See [Microsoft’s provisioning lifecycle](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/how-provisioning-works).
 

apps/docs/content/docs/platform/enterprise/scim/meta.json

@@ -1,5 +1,5 @@
 {
   "title": "Directory provisioning",
-  "pages": ["index", "okta"],
+  "pages": ["index", "okta", "entra"],
   "defaultOpen": false
 }

apps/docs/content/docs/platform/enterprise/sso.mdx

@@ -105,7 +105,7 @@ For a saved connection, open **Sign-in** and select **Edit**. The Provider ID re
 
 SCIM settings save immediately in the **Provisioning** tab. Its **Disable just-in-time provisioning** rule overrides Automatic first-sign-in membership while the connection is active and entitled. Existing members can still sign in. See [directory provisioning](/platform/enterprise/scim#provisioning-and-sso-together).
 
-For Okta, follow the [provisioning walkthrough](/platform/enterprise/scim/okta) to connect a separate SCIM app and verify user and group synchronization.
+Follow the [Okta](/platform/enterprise/scim/okta) or [Microsoft Entra](/platform/enterprise/scim/entra) provisioning walkthrough to connect a SCIM app and verify synchronization separately from sign-in.
 
 ## Provider Guides
 

apps/sim/ee/scim/TESTING.md

@@ -117,10 +117,36 @@ token rotation, and downstream group deletion. Resulting names, memberships,
 and grants were checked in PostgreSQL as well as the admin interfaces.
 
 This used synthetic users and a seeded verified test domain. It did not exercise
-real DNS ownership verification, an end-user SSO login, or a Microsoft Entra
-tenant. It is a provider interoperability check, not OIN certification.
-
-## Remaining provider verification
+real DNS ownership verification or an end-user SSO login. It is a provider
+interoperability check, not OIN certification.
+
+## Live Microsoft Entra verification
+
+A non-gallery enterprise application has been exercised through the Azure
+portal against an isolated Sim organization over HTTPS. The
+[Microsoft Entra guide](../../../docs/content/docs/platform/enterprise/scim/entra.mdx)
+includes the connection, scope, and on-demand screens with private details
+redacted.
+
+The run verified connection testing with a raw secret token, direct user
+assignment and creation with default mappings (including a minimal profile with
+no Mail or structured name attributes), structured-name and display-name
+updates, display-name precedence, repeated provisioning without duplicate
+accounts, unassignment deactivation, reactivation of the same account, an initial
+scheduled cycle, reconciliation, and overlapping token rotation. Entra continued
+to match the provisioned user after the old token was revoked; the old token
+returned 401 and the replacement returned 200. PostgreSQL checks confirmed stable
+SCIM and account IDs, retained membership on deactivation, and no implicit
+workspace grants.
+
+The tenant used Entra ID Free. Live group provisioning and group access changes
+remain unverified because group assignment requires Premium. Directory account
+disablement and deletion also require a scheduled-cycle check; app unassignment
+was tested separately through on-demand provisioning. Synthetic users and a
+seeded verified domain were used, so this does not verify real DNS ownership,
+end-user SSO, or Microsoft gallery certification.
+
+## Provider verification checklist
 
 Before claiming a provider integration has been validated, use an actual Okta
 or Microsoft Entra tenant to run its connection test and provisioning job against

apps/sim/lib/copilot/generated/docs-manifest.ts

@@ -376,6 +376,7 @@ export const DOCS_MANIFEST: readonly string[] = [
   'platform/enterprise/data-retention.mdx',
   'platform/enterprise/forks.mdx',
   'platform/enterprise/scim.mdx',
+  'platform/enterprise/scim/entra.mdx',
   'platform/enterprise/scim/okta.mdx',
   'platform/enterprise/self-hosted.mdx',
   'platform/enterprise/session-policies.mdx',