Step 2: Entra ID Integration

This step adds Microsoft Entra ID as an external identity provider in NetBird. Users will see a “Sign in with Microsoft” button on the login page alongside the local email/password option.

Why the Management Setup (Recommended) Flow

NetBird offers two Entra ID integration paths. We use the Management Setup (Recommended) because:

• Simpler configuration (7 steps vs 8+ for the standalone/legacy flow)
• Keeps local authentication as a break-glass fallback
• Does not require Microsoft Graph API permissions
• Does not replace the embedded IdP — adds Entra ID alongside it
• The standalone flow is labeled “Legacy” in the official docs

2.1 Start the App Registration in Entra

1. Open the Entra Admin Center
2. Navigate to Identity > Applications > App registrations
3. Click + New registration
4. Fill in:

Field	Value
Name	NetBird
Supported account types	Accounts in this organizational directory only (GSISG only - Single tenant)
Redirect URI	Leave empty for now

5. Do not click Register yet — keep this tab open and proceed to Step 2.2.

Note

Single tenant is the correct choice for GSISG. This ensures only users in the GSISG Entra ID directory can authenticate.

2.2 Get the Redirect URL from NetBird

1. Open a new browser tab and sign in to the NetBird Dashboard at https://netbird.gsisg.com
2. Navigate to Settings > Identity Providers
3. Click Add Identity Provider
4. Fill in:

Field	Value
Type	Microsoft Entra ID
Name	GSISG Microsoft (display name on the login button)
Issuer URL	Leave empty for now (will fill in Step 2.4)
Client ID	Leave empty for now (will fill in Step 2.4)
Client Secret	Leave empty for now (will fill in Step 2.4)

5. Copy the Redirect URL that NetBird displays at the bottom of the form
6. Do not click “Add Provider” yet — keep this tab open

2.3 Complete the App Registration

1. Return to the Entra Admin Center tab
2. Click Register to create the app registration
3. On the app’s Overview page, note these values:

Value	Where to Find It
Application (client) ID	Overview page, top section
Directory (tenant) ID	Overview page, top section

4. Construct the Issuer URL:

   https://login.microsoftonline.com/<DIRECTORY_TENANT_ID>/v2.0

   Replace <DIRECTORY_TENANT_ID> with the actual tenant ID from the Overview page.

2.4 Configure the Redirect URI

1. Still in the Entra Admin Center, click Authentication in the left menu
2. Click Add a platform > Web
3. In the Redirect URI field, paste the URL you copied from NetBird in Step 2.2
4. Click Configure

Caution

Select Web as the platform type, not “Single-page application” or “Mobile and desktop applications.” The Management Setup flow requires a Web redirect.

2.5 Create a Client Secret

1. Click Certificates & secrets in the left menu
2. Click + New client secret
3. Fill in:

Field	Value
Description	NetBird SSO
Expires	24 months (set a calendar reminder to rotate before expiry)

4. Click Add
5. Immediately copy the “Value” column (not the Secret ID) — it is shown only once

Copy the Secret Value Now

The client secret value is displayed only at creation time. If you navigate away without copying it, you must create a new secret. Store it in your password manager.

2.6 Complete the NetBird Configuration

1. Return to the NetBird Dashboard tab (from Step 2.2)
2. Fill in the remaining fields:

Field	Value
Issuer URL	https://login.microsoftonline.com/<TENANT_ID>/v2.0
Client ID	The Application (client) ID from Step 2.3
Client Secret	The secret Value you copied in Step 2.5

3. Click Add Provider

2.7 Test SSO Login

1. Log out of the NetBird Dashboard
2. On the login page, you should now see:
   • “Continue with Email” (local authentication)
   • “GSISG Microsoft” button (or whatever name you used)
3. Click the Microsoft button
4. Sign in with a GSISG Entra ID account
5. On first login, the user appears in NetBird but may require approval (depending on your settings)

Note

The first Entra ID user who logs in will be created with the “User” role. You need to log back in with your local admin account to approve the user and optionally promote them to Admin or Owner.

2.8 Create Break-Glass Local Admin Accounts

Create at least two local admin accounts that do not depend on Entra ID. These serve as emergency access if Entra ID is unavailable.

1. Sign in as the original local admin
2. Navigate to Team > Users
3. Invite a second local admin user (use a shared IT distribution list or a dedicated service account email)
4. Set their role to Admin

Break-Glass Best Practice

Store the credentials for both local admin accounts in a secure, offline location (e.g., sealed envelope in a safe, or a separate password vault entry accessible to at least two IT staff members).

2.9 Configure JWT Group Sync (Optional)

What this does: When a user signs into NetBird with their Microsoft account, Entra ID includes their group memberships in the login token (JWT). NetBird reads these groups and automatically assigns the user to matching NetBird groups. This means you don’t have to manually assign users to groups in the NetBird dashboard — if someone is in the “Hawaii-Engineers” Entra group, they automatically get the Hawaii-Engineers access policies in NetBird.

When to skip this: For ~200 users with only 4-5 groups, it’s often simpler to just create the groups manually in the NetBird dashboard and assign users by hand. JWT group sync adds complexity (GUIDs instead of names, 200-group token limit) that may not be worth it at this scale.

If you do want automatic group sync from Entra ID:

In Entra Admin Center

1. Go to your NetBird app registration
2. Click Token configuration
3. Click Add groups claim
4. Select Security groups
5. Under Customize token properties by type, expand ID and select Group ID
6. Click Add

In Entra Enterprise Applications

1. Go to Enterprise applications > find NetBird
2. Click Users and groups > + Add user/group
3. Select the specific Entra groups you want synced to NetBird
4. Click Assign

In NetBird Dashboard

1. Go to Settings > Groups
2. Enable JWT group sync
3. Set JWT claim to groups

Entra ID Groups Appear as GUIDs

Entra ID returns group object IDs (GUIDs) by default, not display names. Your synced groups will appear as IDs like a1b2c3d4-5678-90ab-cdef-1234567890ab. Azure AD Premium with cloud-only groups is required to get display names instead. For most deployments, it is simpler to create groups manually in NetBird rather than relying on JWT group sync.

Token Size Limit

Entra ID limits groups to 200 per JWT token. If a user belongs to more than 200 groups, the groups claim is omitted entirely. Use “Groups assigned to the application” (Step 2.9, Entra Enterprise Applications section) to restrict which groups are included.

Verification

At this point you should have:

• Entra ID app registration (NetBird, single-tenant) in the GSISG tenant
• Redirect URI configured as a Web platform
• Client secret created and stored securely
• Entra ID added as an identity provider in NetBird Dashboard
• Successful SSO login test with a GSISG Entra ID account
• At least two local break-glass admin accounts
• (Optional) JWT group sync configured

Next Step

Proceed to Step 3: Routing Peers to deploy the routing VMs at Honolulu and Boulder.