Microsoft and Entra ID SSO with NetBird Self-Hosted

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.

Management Setup (Recommended)

Add Microsoft as an external IdP directly in the NetBird Management Dashboard. Choose the appropriate identity provider type based on your needs:

Prerequisites

• NetBird self-hosted with embedded IdP enabled
• Access the Entra Admin Center

Step 1: Start Creating App Registration

1. Navigate to Entra Admin Center)
2. Click App registrations → New registration

3. Fill in:

   • Name: NetBird
   • Supported account types: Choose based on your needs:
     • Single tenant (your organization only): Accounts in this organizational directory only (Default Directory only - Single tenant)
     • Multi-tenant (any Entra ID organization): Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant)
     • Multi-tenant with personal accounts: Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)
     • Personal accounts only: Personal Microsoft accounts only
   • Redirect URI: Leave empty for now (you'll add this in Step 4)

4. Don't click Register yet — keep this tab open and proceed to Step 2

Step 2: Get Redirect URL from NetBird

1. Open a new tab or window and 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. Copy the Redirect URL that NetBird displays (but don't click Add Provider yet)

Step 3: Complete App Registration

1. Return to the Entra Admin Center tab
2. Click Register
3. Note the Application (client) ID and Directory (tenant) ID — you'll need these for Step 6
4. Construct the Issuer URL using the format: https://login.microsoftonline.com/{tenant-id}/v2.0 (replace {tenant-id} with your Directory (tenant) ID)

Step 4: Configure Redirect URI

1. Still in the Entra Admin Center tab, go to Authentication
2. Click Add a platform → Web
3. In the dropdown next to the redirect URI field, select Web
4. Paste the redirect URL you copied from NetBird in the Redirect URI field

5. Click Configure

Step 5: 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) — you'll need this for Step 6

Step 6: Complete NetBird Setup

1. Return to the NetBird tab
2. Fill in the fields:
   • Client ID: Paste the Application (client) ID from Step 3
   • Client Secret: Paste the Value from Step 5
   • Issuer URL: Paste the Issuer URL you constructed in Step 3 (for Entra ID only)

3. Click Add Provider

Step 7: 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. Unless your user approval setting were changed you will need to log back into your local admin account to approve the user.

Configuring JWT 'groups' Claim

To sync Entra ID groups with NetBird, you need to configure your app registration to include group claims in the ID token.

Step 1: Configure Groups Claim in Azure

1. In Entra Admin Center, go to your app registration
2. Navigate to Token configuration
3. Click Add groups claim

4. Select the group types to include:
   • Security groups - Recommended for most use cases
   • Groups assigned to the application - Recommended for large organizations (avoids token size limits)
5. Under Customize token properties by type, expand ID and select:
   • Group ID - Returns Azure object IDs (default)
6. Click Add

Step 2: Assign Groups to the Application (Recommended)

If you selected "Groups assigned to the application":

1. Go to Enterprise applications in Entra Admin Center
2. Find and select your NetBird application
3. Go to Users and groups
4. Click Add user/group
5. Select the groups you want to sync with NetBird
6. Click Assign

Step 3: Enable JWT Group Sync in NetBird

1. In NetBird Dashboard, go to Settings → Groups
2. Enable JWT group sync
3. Set JWT claim to groups
4. Optionally configure JWT allow groups to restrict access

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 Management Setup (Recommended) section above.

For detailed instructions on the standalone setup, see the Microsoft and Entra ID SSO with NetBird Self-Hosted (Legacy) documentation.

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

Related Resources

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