diff --git a/references/workspace/scim-integration.mdx b/references/workspace/scim-integration.mdx
index 9669e136..3c47e8a5 100644
--- a/references/workspace/scim-integration.mdx
+++ b/references/workspace/scim-integration.mdx
@@ -234,7 +234,29 @@ SCIM_ENABLED=true
- ### Step 4 - Start provisioning
+ ### Step 4 - Map app roles to Lightdash organization roles (optional)
+
+ If you want to drive Lightdash organization roles from Entra app-role assignments, map the app role to the Lightdash `role` attribute using Entra's standard app-role mapping expression:
+
+ ```
+ roles[primary eq "True"].value
+ ```
+
+ Configure the mapping in **Provisioning \> Attribute mapping \> Edit attribute list for customappsso**, then edit the `roles` attribute:
+
+ - **Mapping type**: Expression
+ - **Expression**: `roles[primary eq "True"].value`
+ - **Target attribute**: `urn:lightdash:params:scim:schemas:extension:2.0:User:role` (or the standard `roles` attribute, depending on how you've configured your mappings)
+
+ For example, an Entra tenant `contoso.onmicrosoft.com` with an app registration called `Lightdash SCIM` can define a `Lightdash Editor` app role and assign it to a user. When Entra provisions that user, the mapping above resolves to `editor`, and Lightdash sets the user's organization role to `editor`.
+
+
+ Lightdash marks the organization role returned by SCIM with `primary: true`, which is what Entra's `primary eq "True"` filter selects. The unquoted form `roles[primary eq true].value` is also accepted for backward compatibility.
+
+
+ With this mapping in place, changing a user's app-role assignment in Entra replaces their existing Lightdash organization role. Earlier versions of Lightdash rejected these updates because Entra appended the new role instead of replacing the old one; this is no longer the case.
+
+ ### Step 5 - Start provisioning
1. Navigate to **Enterprise applications** and select your application.
2. Select **Provision**.