some file

Microsoft Entra ID with NetBird Self-Hosted

This guide is a part of the NetBird Self-hosting Guide and explains how to integrate self-hosted NetBird with Azure AD.

Azure AD is a an enterprise identity service that provides single sign-on and multifactor authentication to your applications. It is a 3rd party managed service and can't be self-hosted.

If you prefer to have full control over authentication and authorization of your NetBird network, there are good self-hosted alternatives to the managed Auth0 service like Keycloak.

Before you start creating and configuring an Azure AD application, ensure that you have the following:

  • An Azure account: To create an Azure AD application, you must have an Azure account. If you don't have one, sign up for a free account at https://azure.microsoft.com/free/.

  • User account with appropriate permissions: You must have an Azure AD user account with the appropriate permissions to create and manage Azure AD applications. If you don't have the required permissions, ask your Azure AD administrator to grant them to you.

Step 1. Create and configure Azure AD application

In this step, we will create and configure NetBird application in azure AD.

  • Navigate to Azure Active Directory
  • Click App Registrations in the left menu then click on the + New registration button to create a new application.
  • Fill in the form with the following values and click Register
    • Name: Netbird
    • Account Types: Accounts in this organizational directory only (Default Directory only - Single tenant)
    • Redirect URI: select Single-page application (SPA) and URI as https://<yournetbirddomain.com>/silent-auth

high-level-dia

Step 2. Platform configurations

  • Click Authentication on the left side menu
  • Under the Single-page application Section, add another URI https://<yournetbirddomain.com>/auth

high-level-dia

  • Scroll down and setup other options as on the screenshot below and click Save

high-level-dia

  • Click Add a Platform and select Mobile and desktop applications
  • Fill in the form with the following values and click Configure
    • Custom redirect URIs: http://localhost:53000

high-level-dia

Step 3. Create a NetBird application scope

  • Click Expose an API on the left menu
  • Under Application ID URI click Set and then Save
  • Click + Add a Scope
  • Fill in the form with the following values and click Add scope
  • Scope name: api

high-level-dia

  • Under Authorized client Applications, click on + add a client application and enter the following:
  • Fill in the form with the following values and click Add application
  • Client ID: same as your Application ID URI minus the api://

high-level-dia

Step 4. Add API permissions

Add Netbird permissions

  • Click API permissions on the left menu
  • Click Add a permission
  • Click My APIs tab, and select Netbird. Next check api permission checkbox and click Add permissions.

high-level-dia

Add Delegated permissions to Microsoft Graph

  • Click Add a permission
  • Click Microsoft Graph and then click Application permissions tab
  • In Select permissions search for User.Read and under the User section select User.Read.All and click Add permissions

high-level-dia

  • Click Grant admin consent for Default Directory and click Yes

high-level-dia

Step 5. Update token version

  • Click Manifest on left menu
  • Search for accessTokenAcceptedVersion and change the value from null to 2
  • Click Save

Step 6. Generate client secret

  • Click Certificates & secrets on left menu
  • Click New client secret
  • Fill in the form with the following values and click Add
  • Description: Netbird
  • Copy Value and save it as it can be viewed only once after creation.

high-level-dia

  • Click Overview on left menu and take note of Application (client) ID, Object ID and Directory (tenant) ID will be required in next step.

Your authority OIDC configuration will be available under:

https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0/.well-known/openid-configuration

Double-check if the endpoint returns a JSON response by calling it from your browser.

  • Set properties in the setup.env file:
NETBIRD_DOMAIN="<YOUR_DOMAIN>"
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0/.well-known/openid-configuration"
NETBIRD_USE_AUTH0=false
NETBIRD_AUTH_CLIENT_ID="<Application (client) ID>"
NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access User.Read api://<Application (client) ID>/api"
NETBIRD_AUTH_AUDIENCE="<Application (client) ID>"
NETBIRD_AUTH_REDIRECT_URI="/auth"
NETBIRD_AUTH_SILENT_REDIRECT_URI="/silent-auth"
NETBIRD_AUTH_USER_ID_CLAIM="oid"
NETBIRD_TOKEN_SOURCE="idToken"

NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="none"

NETBIRD_MGMT_IDP="azure"
NETBIRD_IDP_MGMT_CLIENT_ID="<Application (client) ID>"
NETBIRD_IDP_MGMT_CLIENT_SECRET="<CLIENT_SECRET>"
NETBIRD_IDP_MGMT_EXTRA_OBJECT_ID="<Object ID>"
NETBIRD_IDP_MGMT_EXTRA_GRAPH_API_ENDPOINT="https://graph.microsoft.com/v1.0"

Step 7: Continue with the NetBird Self-hosting Guide

You've configured all required resources in Azure AD. You can now continue with the NetBird Self-hosting Guide.