diff --git a/src/pages/manage/team/idp-sync/embedded/microsoft-entra-id-scim-sync.mdx b/src/pages/manage/team/idp-sync/embedded/microsoft-entra-id-scim-sync.mdx
index fb95e995..e43d14d9 100644
--- a/src/pages/manage/team/idp-sync/embedded/microsoft-entra-id-scim-sync.mdx
+++ b/src/pages/manage/team/idp-sync/embedded/microsoft-entra-id-scim-sync.mdx
@@ -16,6 +16,10 @@ onboarding and offboarding processes.
If not, refer to the [Identity Providers](/selfhosted/identity-providers/managed/microsoft-entra-id) documentation to set it up.
+
+ The NetBird dashboard supports only one identity provider sync integration at a time. If you are migrating from the Microsoft Entra ID API integration to SCIM, plan a cutover rather than running both in parallel. A second sync integration can be configured via the NetBird API, but it must sync from a different Entra tenant to avoid identity conflicts.
+
+
## Enabling Microsoft Entra ID SCIM in NetBird
To enable SCIM synchronization in NetBird, navigate to `Integrations > Identity Provider Sync` in your NetBird dashboard. Click the `Connect Microsoft Entra ID` button.
@@ -45,6 +49,9 @@ A new wizard screen will appear, offering step-by-step instructions for creating
+
+ If you already have a NetBird Enterprise Application in Entra ID with provisioning available, you can configure SCIM on it directly without creating a new one. The App Registration used by the legacy NetBird API integration is a different application type and cannot be reused for SCIM.
+
In the [Azure portal](https://portal.azure.com), navigate to `Azure Active Directory` → `Enterprise applications`.
@@ -115,6 +122,8 @@ Click `Provision Microsoft Entra ID Groups` to configure the group attribute map
In the attribute mappings list, locate the `externalId` row and click `Delete`.
+NetBird matches synchronized groups by `displayName`. Removing the `externalId` mapping ensures Entra uses `displayName` as the matching identifier when determining whether a group already exists in NetBird.
+
Click `Save` to apply the updated group attribute mapping configuration.
@@ -125,6 +134,10 @@ Navigate back to the `Attribute mapping` section and click `Provision Microsoft
+
+ The default Entra mapping includes around 20 user attributes. NetBird only consumes the attributes listed below. Removing the unused mappings keeps the provisioning logs clean and avoids mapping errors for attributes NetBird does not accept.
+
+
Remove all attribute mappings except for the following:
* `userName`
@@ -144,6 +157,8 @@ In the attribute mappings list, locate the `externalId` row and click `Edit`.
Change the **Source attribute** from `mailNickname` to `objectId`.
+`externalId` is the stable identifier NetBird uses to link a SCIM user record to its Entra user. The Entra default of `mailNickname` is not guaranteed to be set on every user, is not guaranteed to be unique in the directory, and can change. `objectId` is the immutable Entra GUID and is the correct stable identifier. This ensures NetBird continues to recognize the same user across email address or display name changes.
+
Click `Ok` to save the change, then click `Save` to apply the final user attribute mapping configuration.
diff --git a/src/pages/manage/team/idp-sync/microsoft-entra-id-scim-sync.mdx b/src/pages/manage/team/idp-sync/microsoft-entra-id-scim-sync.mdx
index c9d08768..677e1fea 100644
--- a/src/pages/manage/team/idp-sync/microsoft-entra-id-scim-sync.mdx
+++ b/src/pages/manage/team/idp-sync/microsoft-entra-id-scim-sync.mdx
@@ -15,6 +15,10 @@ import {Note} from "@/components/mdx";
If you are running a self-hosted deployment with a [Commercial License](https://netbird.io/pricing#on-prem) and the embedded IdP, see the [Embedded IdP version](/manage/team/idp-sync/embedded/microsoft-entra-id-scim-sync) of this guide instead.
+
+ The NetBird dashboard supports only one identity provider sync integration at a time. If you are migrating from the Microsoft Entra ID API integration to SCIM, plan a cutover rather than running both in parallel. A second sync integration can be configured via the NetBird API, but it must sync from a different Entra tenant to avoid identity conflicts.
+
+
## Prerequisites
Before you begin the integration process, ensure you have the necessary admin permissions in Microsoft Entra ID. You need an Azure user account with at least one of these roles:
@@ -47,6 +51,9 @@ A new wizard screen will appear, offering step-by-step instructions for creating
+
+ If you already have a NetBird Enterprise Application in Entra ID with provisioning available, you can configure SCIM on it directly without creating a new one. The App Registration used by the legacy NetBird API integration is a different application type and cannot be reused for SCIM.
+
In the [Azure portal](https://portal.azure.com), navigate to `Azure Active Directory` → `Enterprise applications`.
@@ -117,6 +124,8 @@ Click `Provision Microsoft Entra ID Groups` to configure the group attribute map
In the attribute mappings list, locate the `externalId` row and click `Delete`.
+NetBird matches synchronized groups by `displayName`. Removing the `externalId` mapping ensures Entra uses `displayName` as the matching identifier when determining whether a group already exists in NetBird.
+
Click `Save` to apply the updated group attribute mapping configuration.
@@ -127,6 +136,10 @@ Navigate back to the `Attribute mapping` section and click `Provision Microsoft
+
+ The default Entra mapping includes around 20 user attributes. NetBird only consumes the attributes listed below. Removing the unused mappings keeps the provisioning logs clean and avoids mapping errors for attributes NetBird does not accept.
+
+
Remove all attribute mappings except for the following:
* `userName`
@@ -146,6 +159,8 @@ In the attribute mappings list, locate the `externalId` row and click `Edit`.
Change the **Source attribute** from `mailNickname` to `objectId`.
+`externalId` is the stable identifier NetBird uses to link a SCIM user record to its Entra user. The Entra default of `mailNickname` is not guaranteed to be set on every user, is not guaranteed to be unique in the directory, and can change. `objectId` is the immutable Entra GUID and is the correct stable identifier. This ensures NetBird continues to recognize the same user across email address or display name changes.
+
Click `Ok` to save the change, then click `Save` to apply the final user attribute mapping configuration.
diff --git a/src/pages/manage/team/idp-sync/microsoft-entra-id-sync.mdx b/src/pages/manage/team/idp-sync/microsoft-entra-id-sync.mdx
index cce21887..1cf4d1ef 100644
--- a/src/pages/manage/team/idp-sync/microsoft-entra-id-sync.mdx
+++ b/src/pages/manage/team/idp-sync/microsoft-entra-id-sync.mdx
@@ -15,6 +15,10 @@ import {Note} from "@/components/mdx";
If you are running a self-hosted deployment with a [Commercial License](https://netbird.io/pricing#on-prem) and the embedded IdP, see the [Embedded IdP version](/manage/team/idp-sync/embedded/microsoft-entra-id-sync) of this guide instead.
+
+ The NetBird dashboard supports only one identity provider sync integration at a time. If you want to use both the API integration and SCIM, you can configure a second integration via the NetBird API, but it must sync from a different Entra tenant to avoid identity conflicts.
+
+
## Get Started with NetBird-Entra ID Integration
To get started, navigate to [Integrations](https://app.netbird.io/integrations) in the left menu, which will take you to the
@@ -189,4 +193,10 @@ You should see all the users and groups from your Microsoft Entra ID environment
You can now proceed to configure [access control policies](/manage/access-control/manage-network-access#creating-policies) using the synchronized groups to allow or deny access to the
-synchronized users.
\ No newline at end of file
+synchronized users.
+
+## Sync Behavior
+
+The NetBird API integration polls Microsoft Graph approximately every 5 minutes. NetBird controls this interval and actively fetches users and groups from your Entra tenant on each cycle.
+
+This differs from the [SCIM integration](/manage/team/idp-sync/microsoft-entra-id-scim-sync), which is event-driven from Entra. Entra pushes changes to NetBird on its own schedule (typically every 40 minutes), and you can use Provisioning on Demand for immediate syncs of individual users or groups.
\ No newline at end of file