mirror of
https://github.com/netbirdio/docs.git
synced 2026-08-24 16:51:26 +02:00
docs: add migration and sync context to Entra ID integration guides (#769)
Answers common customer questions about the Entra ID API to SCIM migration that the public docs did not cover: - One-integration-at-a-time limit and tenant-separation workaround - Reusing an existing Enterprise Application for SCIM vs. the legacy API App Registration - Why the group externalId mapping is removed (displayName matching) - Why unused user attribute mappings are trimmed - Why externalId source changes from mailNickname to objectId - New Sync Behavior section contrasting 5-min API polling with event-driven SCIM provisioning
This commit is contained in:
Jack Carter
@@ -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.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
## 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
|
||||
|
||||
<img src="/docs-static/img/manage/team/idp-sync/entra-id-scim-sync/entra-configure-scim.png" alt="Microsoft Entra ID SCIM Configuration Setup" className="imagewrapper-big"/>
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
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.
|
||||
|
||||
<img src="/docs-static/img/manage/team/idp-sync/entra-id-scim-sync/entra-group-attribute-mapping-updated.png" alt="Microsoft Entra ID Group Attribute Mapping After Deletion" className="imagewrapper-big"/>
|
||||
@@ -125,6 +134,10 @@ Navigate back to the `Attribute mapping` section and click `Provision Microsoft
|
||||
|
||||
<img src="/docs-static/img/manage/team/idp-sync/entra-id-scim-sync/entra-user-attribute-mapping.png" alt="Microsoft Entra ID Default User Attribute Mapping" className="imagewrapper-big"/>
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
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.
|
||||
|
||||
<img src="/docs-static/img/manage/team/idp-sync/entra-id-scim-sync/entra-edit-externalid.png" alt="Microsoft Entra ID Edit External ID Attribute" className="imagewrapper-big"/>
|
||||
|
||||
Click `Ok` to save the change, then click `Save` to apply the final user attribute mapping configuration.
|
||||
|
||||
@@ -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.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
## 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
|
||||
|
||||
<img src="/docs-static/img/manage/team/idp-sync/entra-id-scim-sync/entra-configure-scim.png" alt="Microsoft Entra ID SCIM Configuration Setup" className="imagewrapper-big"/>
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
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.
|
||||
|
||||
<img src="/docs-static/img/manage/team/idp-sync/entra-id-scim-sync/entra-group-attribute-mapping-updated.png" alt="Microsoft Entra ID Group Attribute Mapping After Deletion" className="imagewrapper-big"/>
|
||||
@@ -127,6 +136,10 @@ Navigate back to the `Attribute mapping` section and click `Provision Microsoft
|
||||
|
||||
<img src="/docs-static/img/manage/team/idp-sync/entra-id-scim-sync/entra-user-attribute-mapping.png" alt="Microsoft Entra ID Default User Attribute Mapping" className="imagewrapper-big"/>
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
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.
|
||||
|
||||
<img src="/docs-static/img/manage/team/idp-sync/entra-id-scim-sync/entra-edit-externalid.png" alt="Microsoft Entra ID Edit External ID Attribute" className="imagewrapper-big"/>
|
||||
|
||||
Click `Ok` to save the change, then click `Save` to apply the final user attribute mapping configuration.
|
||||
|
||||
@@ -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.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
## 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.
|
||||
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.
|
||||
Reference in New Issue
Block a user