mirror of
https://github.com/netbirdio/docs.git
synced 2026-04-16 07:26:35 +00:00
198 lines
11 KiB
Plaintext
198 lines
11 KiB
Plaintext
# Provision Users and Groups From Microsoft Entra ID via API (Embedded IdP)
|
|
|
|
[Microsoft Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id),
|
|
formerly known as Azure Active Directory (Azure AD), is a cloud-based identity and access management service that provides
|
|
organizations with secure authentication, single sign-on, and user management capabilities. In the context of network security,
|
|
it can be effectively used to control network access based on organizational structure, such as groups and individual user accounts.
|
|
|
|
NetBird's Microsoft Entra ID integration allows you to synchronize users and groups from Entra ID to NetBird.
|
|
You can then use these synchronized groups to configure your network, create network access policies, and automate
|
|
onboarding and offboarding processes.
|
|
|
|
<Note>
|
|
Before creating this integration, ensure you have a Microsoft Entra ID connector configured in your embedded IdP.
|
|
If not, refer to the [Identity Providers](/selfhosted/identity-providers/managed/microsoft-entra-id) documentation to set it up.
|
|
</Note>
|
|
|
|
## Get Started with NetBird-Entra ID Integration
|
|
|
|
Navigate to `Integrations` in the left menu to access the `Identity Provider` integration. Click the `Entra ID (Azure AD)` button.
|
|
|
|
Select your **Microsoft Entra ID** identity provider connector for this integration and click **Continue** to proceed.
|
|
|
|
<p>
|
|
<img src="/docs-static/img/manage/team/idp-sync/microsoft-entra-id-sync/select-idp.png" alt="select-identity-provider" className="imagewrapper-big"/>
|
|
</p>
|
|
|
|
This will open a pop-up window featuring a user-friendly wizard, guiding you through the synchronization process between NetBird and Azure AD.
|
|
|
|
|
|
|
|
## Prerequisites
|
|
|
|
Before starting the integration process, verify that you have the required permissions in Microsoft Entra ID (Azure AD).
|
|
Specifically, you will need an Azure user account with at least one of these roles:
|
|
|
|
* Application Administrator
|
|
* Cloud Application Administrator
|
|
* Global Administrator
|
|
|
|
To check your permissions:
|
|
|
|
* Log in to the [Azure portal](portal.azure.com).
|
|
* Navigate to Manage Microsoft Entra ID and click `View`.
|
|
* Expand the `Manage` tab and click on `Roles and administrators` in the left menu.
|
|
* Look for your username and verify if you're assigned any of the above roles.
|
|
|
|
|
|
|
|
If you don't have the required permissions, contact your Azure AD administrator to grant you the appropriate role before proceeding with the NetBird integration.
|
|
|
|
## Create and Configure a Microsoft Entra ID Application for NetBird Integration
|
|
|
|
Now that you have the required permissions, return to the NetBird dashboard. Click on the `Get Started` button to initiate the integration process.
|
|
|
|
A new wizard screen will appear, offering step-by-step instructions for creating and configuring your Microsoft Entra ID application. To simplify the process, the wizard also provides quick-copy buttons for essential information:
|
|
|
|
* Name
|
|
* Account Type
|
|
* Redirect Type
|
|
* Redirect URI
|
|
|
|
|
|
|
|
For convenience, click on [Azure Active Directory](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview) (step 1). That will open the Azure dashboard. Navigate to `App registrations` in the left menu and then click `+New registration` as indicated below:
|
|
|
|
|
|
|
|
Fill in the required information:
|
|
|
|
|
|
|
|
After entering all required information, click the `Register` button at the bottom of the form to finalize the application registration process.
|
|
|
|
Upon successful registration, you'll be redirected to a confirmation screen similar to the following:
|
|
|
|
|
|
|
|
Copy and securely store the generated `Application (client) ID` and `Directory (tenant) ID` as you will need them shortly.
|
|
|
|
## Configure API Permissions for NetBird-Entra ID Integration
|
|
|
|
On the NetBird dashboard click the `Continue →` button. A new wizard screen will appear, this time, offering step-by-step instructions for setting up API permissions.
|
|
|
|
|
|
|
|
Back to Azure, in the `App registrations` screen, click on `Manage` in the left menu to expand it and then click on `API permissions`:
|
|
|
|
|
|
|
|
Look for the `+ Add a permission` button, located near the top of the permissions list and click on it.
|
|
|
|
|
|
|
|
A new pop-up window will appear, asking you to select an API. Click on `Microsoft Graph`.
|
|
|
|
|
|
|
|
On the next screen, click on the `Application permissions` button, which will let you select the appropriate permissions for NetBird to function correctly with your Microsoft Entra ID environment.
|
|
|
|
|
|
|
|
To assign user permissions:
|
|
|
|
* Locate the search bar at the top. Type `User.Read.All` into the search bar and press `Enter`.
|
|
* In the search results, click on the `User` tab to expand it and view the available permissions.
|
|
* Click on the checkbox to select and enable the `User.Read.All` permission.
|
|
|
|
|
|
|
|
The `User.Read.All` permission allows NetBird to read the full set of profile properties, group memberships, and reports of the signed-in user and other users in your organization.
|
|
|
|
Next, repeat the procedure. This time, search for `Group.Read.All` and click on the checkbox to enable it as shown below:
|
|
|
|
|
|
|
|
Once done, click the `Add permissions` button. You will see a few warnings:
|
|
|
|
|
|
|
|
Locate the `Grant admin consent for [Your Organization Name]` button (you'll find it next to `+Add a permission` button). Click on it to grant the required permissions.
|
|
|
|
A confirmation dialog will appear, asking you to verify this action. Review the permissions listed in the dialog and click `Yes` to confirm. Wait for the process to complete, this may take a few seconds.
|
|
|
|
Once finished, the status of the permissions should change to `Granted for [Your Organization Name]`. Verify that all selected permissions now show a green checkmark, indicating they've been successfully granted:
|
|
|
|
|
|
|
|
## Create a Client Secret for Secure NetBird-Entra ID Authentication
|
|
|
|
Back to the NetBird dashboard, click the `Continue →` button. A new wizard screen will appear, showing instructions for generating a client secret in Entra ID.
|
|
|
|
|
|
|
|
On Azure, click on the `Certificates & secrets` button in the left menu to open the management page. Click on `+New client secret` as shown below. Choose an expiration time that suits your security needs and click the `Add` button.
|
|
|
|
|
|
|
|
A new client secret will be generated and displayed on the screen. Copy and securely store the `Value` field immediately, as you will needed in the next step.
|
|
|
|
|
|
|
|
## Enter Application ID and Directory ID in NetBird
|
|
|
|
Paste the secret `Value` from the previous step into NetBird and click the `Continue →` button. A new wizard screen will appear, asking for the `Application (client) ID` and the `Directory (tenant) ID` credentials generated previously.
|
|
|
|
Paste the values and click the `Continue →` button.
|
|
|
|
|
|
|
|
## Choose Groups to Synchronize from Entra ID
|
|
At this stage, NetBird is set to synchronize all groups from your Microsoft Entra ID by default. You have two options:
|
|
|
|
* If you want to synchronize all groups, simply click the `Continue →` button.
|
|
* To synchronize only specific groups, click the `+ Add group filter` button, which will open a new panel where you can set criteria to include or exclude groups.
|
|
|
|
|
|
|
|
## Choose Users to Synchronize from Entra ID
|
|
After configuring group synchronization, you'll now set up user synchronization. Similar than before, NetBird is configured to synchronize all users from your Microsoft Entra ID by default.
|
|
|
|
* If you want to synchronize all users, you don't need to take any action, simply click the `Continue →` button.
|
|
* To synchronize only specific users, click the `+ Add user filter` button. This opens a new panel where you can set criteria to include or exclude users.
|
|
|
|
<Note>
|
|
You can modify these synchronization settings later if necessary.
|
|
</Note>
|
|
|
|
|
|
|
|
After configuring user and group synchronization, the setup wizard will finalize the process and you'll automatically return to the main Identity Provider screen.
|
|
|
|
On this screen, you'll see two key indicators of successful integration:
|
|
|
|
* The Microsoft Entra ID toggle will be switched on (enabled).
|
|
* Next to the toggle, you'll see a button with a status message saying `Synced a few seconds ago`.
|
|
|
|
These indicators confirm that:
|
|
|
|
* The integration between NetBird and Microsoft Entra ID is active.
|
|
* The initial synchronization has been completed successfully.
|
|
* NetBird will now automatically sync with your Microsoft Entra ID at regular intervals.
|
|
|
|
<Note>
|
|
You can manually trigger a sync or adjust settings by clicking on the Microsoft Entra ID section in the Identity Provider screen
|
|
</Note>
|
|
|
|
|
|
|
|
## Verify the Integration
|
|
|
|
To verify the synchronization, navigate to `Teams > Users` in the left menu.
|
|
You should see all the users and groups from your Microsoft Entra ID environment listed in the NetBird dashboard.
|
|
|
|
|
|
|
|
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.
|