Microsoft Entra ID

Use Microsoft accounts for authentication with NetBird. This supports both personal Microsoft accounts and Microsoft Entra ID (formerly Azure AD) for work and school accounts.

Connector Setup (Recommended)

Add Microsoft as a connector to the embedded IdP. Choose the appropriate connector type based on your needs:

Prerequisites

• NetBird self-hosted with embedded IdP enabled
• Access to Azure Portal or Entra Admin Center

Step 1: Create App Registration

1. Navigate to Azure Portal → Azure Active Directory (or Entra Admin Center)
2. Click App registrations → New registration
3. Fill in:
   • Name: NetBird
   • Supported account types: Choose based on your needs:
     • Personal accounts only: Personal Microsoft accounts only
     • Work/school only: Accounts in this organizational directory only
     • Both: Accounts in any organizational directory and personal Microsoft accounts
   • Redirect URI: Leave empty for now
4. Click Register
5. Note the Application (client) ID and Directory (tenant) ID

Step 2: Create Client Secret

1. Go to Certificates & secrets
2. Click New client secret
3. Add a description and expiration
4. Click Add
5. Copy the Value immediately (it won't be shown again)

Step 3: Add Connector in NetBird

1. Log in to your NetBird Dashboard
2. Navigate to Settings → Identity Providers
3. Click Add Identity Provider
4. Fill in the fields:

For Personal Microsoft Accounts:

For Microsoft Entra ID (Work/School):

5. Click Save

Step 4: Configure Redirect URI

After saving, NetBird displays the Redirect URL. Copy this URL and add it to your Azure app:

1. Return to Azure Portal → Your app registration
2. Go to Authentication
3. Click Add a platform → Single-page application
4. Add the redirect URL from NetBird
5. Click Configure

Step 5: Test the Connection

1. Log out of NetBird Dashboard
2. On the login page, you should see the Microsoft button
3. Click it and sign in with your Microsoft account
4. You should be redirected back to NetBird and logged in

Standalone Setup (Advanced)

Use Microsoft Entra ID as your primary identity provider instead of NetBird's embedded IdP. This option gives you full control over authentication and user management, is recommended for experienced Microsoft Entra ID administrators as it also requires additional setup and ongoing maintenance.

For most deployments, the embedded IdP is the simpler choice — it's built into NetBird, fully integrated, and requires minimal configuration to get started. For this implementation, go back up to the Connector Setup (Recommended) section above.

Prerequisites

• An Azure account with appropriate permissions
• Docker and Docker Compose for NetBird

Step 1: Create and Configure Azure AD Application

1. Navigate to Azure Active Directory
2. Click App Registrations → + New registration
3. Fill in:
   • Name: Netbird
   • Supported account types: Accounts in this organizational directory only (Single tenant)
   • Redirect URI: Select Single-page application (SPA) and enter https://<yournetbirddomain.com>/silent-auth
4. Click Register

Step 2: Configure Platform Settings

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

3. Scroll down and configure options as shown:

4. Click Add a Platform → Mobile and desktop applications
5. Add custom redirect URI: http://localhost:53000
6. Click Configure

Step 3: Create Application Scope

1. Click Expose an API on the left menu
2. Under Application ID URI, click Set then Save
3. Click + Add a Scope
4. Fill in:
   • Scope name: api
5. Click Add scope

6. Under Authorized client applications, click + Add a client application
7. Enter your Client ID (same as Application ID URI minus api://)
8. Click Add application

Step 4: Add API Permissions

1. Click API permissions on the left menu
2. Click Add a permission
3. Select My APIs tab → Netbird → check api permission → Add permissions

4. Click Add a permission again
5. Select Microsoft Graph → Application permissions
6. Search for User.Read and select User.Read.All
7. Click Add permissions

8. Click Grant admin consent for Default Directory → Yes

Step 5: Update Token Version

1. Click Manifest on the left menu
2. Find accessTokenAcceptedVersion and change from null to 2
3. Click Save

Step 6: Generate Client Secret

1. Click Certificates & secrets on the left menu
2. Click New client secret
3. Fill in:
   • Description: Netbird
4. Click Add
5. Copy the Value immediately

6. Click Overview and note:
   • Application (client) ID
   • Object ID
   • Directory (tenant) ID

Step 7: Configure NetBird

Your authority OIDC configuration will be available at:

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

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 8: Continue with NetBird Setup

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

Troubleshooting

"AADSTS50011: The redirect URI specified in the request does not match"

• Ensure the redirect URI in Azure exactly matches what NetBird provides
• Check platform type (SPA vs Mobile/Desktop)
• Verify no trailing slashes

"AADSTS700016: Application not found"

• Verify the Application (client) ID is correct
• Check tenant ID for single-tenant apps
• Ensure the app registration is in the correct directory

Users from wrong tenant signing in

• Use single-tenant configuration for organization-only access
• Verify "Supported account types" setting in app registration

Token validation errors

• Ensure accessTokenAcceptedVersion is set to 2 in the manifest
• Verify all scopes are properly configured
• Check that admin consent was granted

Related Resources

• Microsoft Identity Platform Documentation
• Azure Portal
• Embedded IdP Overview