AD & Identity Integration

AD Integration, Entra ID, SSPR & Cached Credentials

Executive Summary

NetBird integrates with Microsoft Entra ID via an App Registration using Microsoft Graph API permissions (User.Read.All, Group.Read.All). It supports both user and group synchronization with automatic provisioning and deprovisioning capabilities in the cloud version and JWT-based group sync in the self-hosted version. SSPR with password writeback requires Entra ID P1 (minimum) or Microsoft 365 Business Premium, plus Microsoft Entra Connect (or Cloud Sync) configured on-premises.

The cached credential problem is a known limitation documented by Microsoft: hybrid AD-joined devices require line-of-sight to a domain controller after an SSPR password reset to update cached credentials. NetBird solves this by maintaining persistent connectivity to DCs via a machine-level always-on tunnel. NetBird does not support true pre-logon user-authenticated VPN (PLAP/credential provider) — this is an open feature request. The setup key workaround (machine-level authentication via SYSTEM service) establishes the tunnel at boot time, providing DC connectivity at the login screen. This is sufficient for the SSPR use case.

---

Findings

1. NetBird Microsoft Entra ID Integration

App Registration Setup:

• Register an application in Entra ID (Azure AD)
• Required Azure roles: Application Administrator, Cloud Application Administrator, or Global Administrator
• Store the Application (client) ID and Directory (tenant) ID
• Create a client secret

Microsoft Graph API Permissions Required:

• User.Read.All (Application permission) — read user profiles, group memberships
• Group.Read.All (Application permission) — read group information
• Admin consent must be granted

User and Group Sync:

There are two different mechanisms, and they are NOT interchangeable:

Aspect	Cloud IdP-Sync (Team plan+)	Self-Hosted JWT Sync
How it works	Polls Entra ID via Microsoft Graph API continuously	Groups embedded in JWT ID token during OIDC authentication
Sync timing	Background, automatic, continuous	At login time only
User provisioning	Users appear before they log in	Users appear only after first login
User deprovisioning	Automatic at next sync	NOT automatic — existing sessions persist
Group names	Display names (“Engineering”)	GUIDs by default (unless Azure AD Premium)
Group limit	No limit (API-based)	200 groups per JWT token

For GSISG (self-hosted): JWT group sync is workable but not equivalent to IdP-Sync. The biggest operational gap is deprovisioning — disabled Entra users cannot re-authenticate but are not auto-removed from NetBird. A documented offboarding procedure is required.

---

2. SSPR Password Writeback Technical Flow

Licensing Requirements:

• Minimum for writeback: Entra ID P1 or Microsoft 365 Business Premium
• Standalone M365 Basic and Standard do NOT include writeback

Exact Technical Flow:

1. System verifies the user has an on-prem managed password and writeback service is running
2. User passes MFA/authentication gates configured for SSPR
3. User enters and confirms new password
4. Plaintext password encrypted with 2048-bit RSA public key
5. Encrypted payload sent over HTTPS to a tenant-specific Azure Service Bus relay
6. On-prem password-reset endpoint receives the request
7. Sync engine locates the user in AD DS
8. Password set in the appropriate AD DS forest (enforces on-prem password policy)
9. Success notification to user

Security Model:

• Tenant-specific Service Bus relay with randomly generated strong password
• Password encrypted with 2048-bit RSA + 256-bit AES-GCM
• All communication over TLS/SSL (outbound port 443 only — no inbound firewall rules needed)
• Automatic key rollover every 6 months

---

3. How Always-On NetBird Solves the Cached Credential Problem

The Problem (Microsoft documentation confirms):

“Microsoft Entra hybrid-joined machines must have network connectivity line of sight to a domain controller to use the new password and update cached credentials.”

When a user resets their password via SSPR while off-network, the new password is written back to on-prem AD, but the Windows laptop still has the OLD password cached locally. Without DC connectivity, the user cannot log in with the new password.

How NetBird Solves This:

1. NetBird tunnel is UP (running as a Windows service under SYSTEM, started at boot)
2. DC reachable via NetBird network routes or routing peers
3. DNS resolution via NetBird match domain configuration directs AD DNS queries through the tunnel
4. User resets password via SSPR: New password written back to on-prem AD via Entra Connect
5. User locks workstation, then unlocks with NEW password: Windows sends the new password through the NetBird tunnel to the DC
6. Kerberos authentication (port 88): DC validates the new password, issues a new TGT
7. Cached credentials updated: Windows updates the local credential cache

Alternative flow: User logs in with OLD cached password first, then locks and unlocks with NEW password — cached credentials still update correctly.

---

4. Edge Cases

Machine account password (30+ days offline): The machine password change process is initiated by the client, not by AD. If the machine cannot reach a DC, it does NOT change its local password. When the device reconnects, the password change process succeeds normally. The TRUE risk is if an admin deletes or disables the computer account while offline.

CachedLogonsCount = 0: If set to 0, NO cached credentials are stored and DC connectivity is required at every login. NetBird always-on tunnel becomes critical.

Kerberos time skew: Kerberos requires clock sync within 5 minutes. NTP (port 123) through the tunnel prevents this.

AD replication lag: New password may fail briefly on non-primary DCs. Resolves within minutes.

---

5. NetBird Pre-Logon VPN on Windows

NetBird does NOT support true pre-logon user-authenticated VPN. This is tracked as open feature requests (#2809, #4207).

What NetBird DOES support (machine-level pre-logon): NetBird runs as a system-wide Windows service under the SYSTEM account. When configured with a setup key:

• The service starts at boot, BEFORE any user logs in
• The WireGuard tunnel is established at the machine level
• Network routes to DCs are available at the Windows login screen
• This survives reboots and does not require user interaction

Limitations of setup key approach:

• Authenticates the MACHINE, not the USER
• Any user on the device gets the tunnel connection
• Cannot differentiate ACLs per-user on shared devices
• No SSO-style authentication at the login screen

For GSISG’s use case: The setup key approach IS sufficient for the SSPR cached credential problem. The goal is DC connectivity at login time, and machine-level authentication achieves this.

---

6. Required Ports/Protocols for Full AD Functionality

Port	Protocol	Service	Purpose
53	TCP/UDP	DNS	Domain name resolution, DC discovery via SRV records
88	TCP/UDP	Kerberos	Authentication, TGT issuance
123	UDP	NTP (W32Time)	Time synchronization (critical for Kerberos)
135	TCP	RPC Endpoint Mapper	Service discovery
389	TCP/UDP	LDAP	Directory queries, DC locator
445	TCP	SMB	Group Policy (SYSVOL), NetLogon, file shares
464	TCP/UDP	Kerberos kpasswd	Password changes and resets
636	TCP	LDAPS	Secure directory queries
3268	TCP	Global Catalog	Forest-wide searches
3269	TCP	Global Catalog SSL	Secure forest-wide searches
9389	TCP	ADWS	Active Directory Web Services
49152-65535	TCP	RPC Ephemeral	Dynamic RPC endpoints

---

7. NetBird Access Control for Role-Based Access

NetBird can restrict general users to DC-only access while giving engineers full LAN access.

Implementation:

1. Create Groups: General Users (synced from Entra ID), Engineers (synced from Entra ID), Domain Controllers (contains DC resources), Full LAN (all resources)
2. Create Policies:
   • Users to DCs: General Users -> Domain Controllers (TCP 53,88,135,389,445,464,636,3268,3269 + UDP 53,88,123,389,464)
   • Engineers to LAN: Engineers -> Full LAN (All protocols)
3. Remove Default Policy: Delete or disable the full-mesh policy

---

8. Domain-Joined vs Hybrid vs Azure AD Joined

Feature	Domain-Joined	Hybrid Azure AD Joined	Azure AD Joined
Primary authority	On-prem AD	On-prem AD + Entra ID	Entra ID (cloud)
Cached credential update after SSPR	Requires DC connectivity	Requires DC connectivity	Not required
VPN needed for SSPR?	YES	YES	NO
Best for GSISG?	Current state	Recommended transitional	Long-term goal

Key insight from Microsoft: “This issue doesn’t occur if you use Microsoft Entra joined devices.” Azure AD Join is the ultimate solution but requires migrating from GPO to Intune.

---

Architecture Recommendation

For GSISG with 100+ users, on-prem AD at Honolulu + Boulder, and Entra Connect:

1. Deploy NetBird with setup keys on all domain-joined laptops (machine-level always-on)
2. Configure routing peers at both sites (NOT the DCs themselves)
3. Configure DNS match domains for the AD domain pointing to DC IPs
4. Create access control policies: general users get DC-only; IT engineers get full LAN
5. Enable SSPR with password writeback (requires Entra ID P1 or M365 Business Premium)
6. Sync Entra ID groups to NetBird for automated provisioning
7. Migrate to Hybrid Azure AD Join for best cloud+on-prem integration
8. Long-term: Consider Azure AD Join + Intune to eliminate the cached credential problem entirely

---

Gaps & Uncertainties

1. NetBird sync interval: Exact IdP sync frequency undocumented for self-hosted.
2. Pre-logon user authentication: Feature request with community demand but no ETA.
3. SSPR at Windows login screen with NetBird routing: Needs validation in pilot phase.
4. Multi-site DC affinity: How NetBird routing interacts with AD Sites and Services is untested.

---

Sources

NetBird: docs.netbird.io (idp-sync, posture-checks, access-control, identity-providers, DNS), GitHub #1661, #2809, #4207

Microsoft: learn.microsoft.com (SSPR writeback, SSPR licensing, cached credentials FAQ, group-membership VPN issues), Microsoft TechCommunity (secure channel blog)