NetBird mit Microsoft Entra ID anbinden

Aus maxTechCorner

Auf einen Blick

Gilt fürNetBird selbst gehostet ab 0.62 mit eingebettetem Identity Provider (geprüft mit 0.80), NetBird Cloud; Microsoft Entra ID (ehemals Azure AD)
BereichIT-Security
Dauerca. 30 Minuten (App-Registrierung, Anbindung, Gruppen-Sync, Test)
RechteEntra ID: Anwendungsadministrator oder Cloudanwendungsadministrator; NetBird: Owner/Admin im Dashboard
StandOktober 2026

NetBird mit Microsoft Entra ID (früher Azure AD) anbinden bedeutet: Ihre Mitarbeiter melden sich am NetBird-Dashboard und beim Verbinden ihrer Geräte mit dem gewohnten Microsoft-365-Konto an – inklusive MFA und Conditional Access aus Entra ID. Über den Gruppenanspruch im Token landen zusätzlich die Entra-Gruppen in NetBird und steuern dort, wer welche Server und Netze erreicht.

Dieser Artikel zeigt Schritt für Schritt die Konfiguration auf beiden Seiten: die App-Registrierung, Tokenkonfiguration, Benutzerzuweisung und Conditional Access in Microsoft Entra ID sowie Identity Provider, JWT-Gruppensynchronisation und Zugriffsrichtlinien in NetBird. Grundlagen zu NetBird selbst erklärt der Artikel NetBird – Zero-Trust-Netzwerk mit WireGuard.

NetBird mit Microsoft Entra ID: Der NetBird-Client meldet sich über den eingebetteten Identity Provider per OpenID Connect bei Entra ID an; Entra prüft MFA und Conditional Access und liefert im ID-Token die Gruppen-IDs, aus denen NetBird per JWT-Gruppensynchronisation Gruppen für die Zugriffsrichtlinien bildet.

Varianten: Welche Entra-ID-Anbindung passt?

NetBird kennt mehrere Wege, Entra ID einzubinden. Für die meisten Unternehmen ist Variante 1 die richtige.

Variante Für wen Was passiert
1. Entra ID als externer Identity Provider (selbst gehostet, empfohlen) Selbst gehostetes NetBird ab Version 0.62 Der eingebettete IdP von NetBird bleibt aktiv; Entra ID wird im Dashboard als zusätzlicher Anmeldeweg ergänzt. Lokale Konten (z. B. ein Notfall-Admin) funktionieren weiter. Gruppen kommen über den Token-Anspruch groups.
2. Entra ID als alleiniger IdP („Standalone“, Legacy) Bestandsinstallationen vor 0.62 Entra ersetzt den IdP vollständig, Konfiguration über Umgebungsvariablen. NetBird empfiehlt das nur noch erfahrenen Entra-Administratoren; neue Installationen sollten Variante 1 nutzen.
3. NetBird Cloud mit Entra-Synchronisation NetBird Cloud (SaaS) Anmeldung per „Mit Microsoft anmelden“, zusätzlich Abgleich von Benutzern und Gruppen (mit Klarnamen) über die Microsoft-Graph-API alle ca. 5 Minuten.
4. SCIM-Provisionierung NetBird Cloud oder Self-Hosting mit kommerzieller Lizenz Entra legt Benutzer und Gruppen aktiv in NetBird an und deaktiviert ausgeschiedene Mitarbeiter automatisch. In der kostenlosen Community Edition nicht enthalten.

Der Rest des Artikels beschreibt Variante 1 ausführlich; die Besonderheiten von Variante 3 und 4 stehen weiter unten.

Voraussetzungen

  • Selbst gehosteter NetBird-Server ab Version 0.62 mit eingebettetem Identity Provider (Standard bei Installation über das getting-started.sh-Skript) und lokalem Admin-Konto.
  • Öffentlicher DNS-Name mit gültigem Zertifikat, z. B. https://netbird.example.com.
  • Zugriff auf das Microsoft Entra Admin Center (entra.microsoft.com) mit der Rolle Anwendungsadministrator, Cloudanwendungsadministrator oder Globaler Administrator.
  • Für Gruppenzuweisung an die Unternehmensanwendung und für Conditional Access: Microsoft Entra ID P1 (z. B. in Microsoft 365 Business Premium oder E3/E5 enthalten). Ohne P1 funktionieren Anmeldung und Gruppenanspruch trotzdem – nur Benutzer statt Gruppen zuweisen und MFA über die Sicherheitsstandards erzwingen.

Teil 1: Microsoft Entra ID konfigurieren

Schritt 1: App-Registrierung anlegen

Die Reihenfolge ist wichtig, weil NetBird die Weiterleitungs-URL (Redirect-URI) erst im Dialog anzeigt. Arbeiten Sie deshalb mit zwei Browser-Tabs.

  1. Im Entra Admin Center Identität → Anwendungen → App-Registrierungen → Neue Registrierung öffnen.
  2. Name: NetBird (wird Benutzern bei der Anmeldung angezeigt).
  3. Unterstützte Kontotypen: Nur Konten in diesem Organisationsverzeichnis (einzelner Mandant). Damit können sich ausschließlich Konten Ihres Tenants anmelden.
  4. Umleitungs-URI vorerst leer lassen und noch nicht auf Registrieren klicken.
  5. Im zweiten Tab das NetBird-Dashboard öffnen: Settings → Identity Providers → Add Identity Provider. Als Typ Microsoft Entra ID wählen, einen Namen vergeben (z. B. „Microsoft 365“) und die angezeigte Redirect URL kopieren. Den Dialog offen lassen.
  6. Zurück in Entra auf Registrieren klicken.
  7. Auf der Übersichtsseite der App Anwendungs-ID (Client) und Verzeichnis-ID (Mandant) notieren.

Schritt 2: Umleitungs-URI eintragen

  1. In der App-Registrierung Authentifizierung → Plattform hinzufügen → Web wählen.
  2. Die aus NetBird kopierte Redirect URL exakt einfügen (ohne abschließenden Schrägstrich).
  3. Optional eine zweite Web-Umleitungs-URI für die saubere Abmeldung ergänzen: https://netbird.example.com/oauth2/logout/callback
  4. Konfigurieren bzw. Speichern.


HinweisWichtig ist die Plattform Web (vertraulicher Client mit geheimem Schlüssel). Die in älteren Anleitungen beschriebenen Plattformen „Single-Page-Anwendung“ mit /silent-auth und /auth gehören zur Legacy-Variante 2 und werden bei Variante 1 nicht benötigt.

Schritt 3: Geheimen Clientschlüssel erstellen

  1. Zertifikate & Geheimnisse → Geheime Clientschlüssel → Neuer geheimer Clientschlüssel.
  2. Beschreibung (z. B. „NetBird 2026“) und Ablauf wählen – maximal 24 Monate.
  3. Den Wert sofort kopieren – er wird nur einmal angezeigt. Nicht die Geheimnis-ID verwenden.


WarnungLäuft der Clientschlüssel ab, kann sich niemand mehr per Entra ID an NetBird anmelden (Fehler AADSTS7000222), und Clients mit abgelaufener Sitzung verlieren die Verbindung. Tragen Sie das Ablaufdatum in den Wartungskalender ein und erneuern Sie den Schlüssel rechtzeitig.

Schritt 4: Gruppenanspruch (groups-Claim) konfigurieren

Damit NetBird die Entra-Gruppen erhält, muss Entra sie in das ID-Token schreiben.

  1. Tokenkonfiguration → Gruppenanspruch hinzufügen.
  2. Gruppentyp wählen:
    • Der Anwendung zugewiesene Gruppen – empfohlen, besonders in größeren Tenants: Es landen nur die Gruppen im Token, die Sie der App in Schritt 5 zuweisen.
    • alternativ Sicherheitsgruppen – alle Sicherheitsgruppen des Benutzers.
  3. Unter ID die Option Gruppen-ID auswählen und Hinzufügen klicken.

Zusätzliche API-Berechtigungen sind für die Anmeldung nicht nötig; die standardmäßig vorhandene delegierte Berechtigung Microsoft Graph → User.Read genügt.


HinweisEntra schreibt höchstens 200 Gruppen in ein Token. Ist ein Benutzer Mitglied in mehr Gruppen, fehlt der Anspruch komplett – NetBird sieht dann gar keine Gruppen. Mit „Der Anwendung zugewiesene Gruppen“ umgehen Sie diese Grenze.

Schritt 5: Zugriff auf berechtigte Benutzer beschränken

Ohne weitere Einstellung darf sich jedes Konto Ihres Tenants bei NetBird anmelden. Besser ist eine explizite Freigabe:

  1. Identität → Anwendungen → Unternehmensanwendungen → App NetBird öffnen (wurde mit der App-Registrierung automatisch angelegt).
  2. Eigenschaften → Zuweisung erforderlich? auf Ja setzen und speichern.
  3. Benutzer und Gruppen → Benutzer/Gruppe hinzufügen – z. B. die Gruppen NetBird-Benutzer, NetBird-Admins, IT-Dienstleister zuweisen.

Nicht zugewiesene Konten erhalten bei der Anmeldung den Fehler AADSTS50105.

Schritt 6: MFA und Conditional Access

Weil die Anmeldung an NetBird über Entra läuft, greifen Ihre Richtlinien für bedingten Zugriff – auch beim Verbinden eines Geräts per netbird up, denn dafür öffnet sich ebenfalls die Microsoft-Anmeldung im Browser.

Empfohlene Richtlinie unter Schutz → Bedingter Zugriff → Neue Richtlinie:

  • Benutzer: Gruppe NetBird-Benutzer (Notfallkonten ausschließen)
  • Zielressourcen: Cloud-App NetBird
  • Gewähren: Multi-Faktor-Authentifizierung erforderlich, idealerweise zusätzlich Gerät muss als konform markiert sein (Intune)
  • Zunächst im Modus Nur Bericht testen, danach aktivieren.


TippPhishing-resistente Methoden (FIDO2-Sicherheitsschlüssel, Windows Hello for Business, Passkeys in Microsoft Authenticator) lassen sich über die Authentifizierungsstärke Phishing-resistente MFA in derselben Richtlinie erzwingen – für einen Zugang ins interne Netz ist das die beste Wahl.

Teil 2: NetBird konfigurieren

Schritt 7: Entra ID als Identity Provider hinzufügen

Zurück im offenen NetBird-Dialog (Settings → Identity Providers → Add Identity Provider):

Feld Wert
Type Microsoft Entra ID (der Typ Microsoft ist für private Microsoft-Konten gedacht)
Name Anzeigename des Anmeldeknopfs, z. B. „Microsoft 365“
Client ID Anwendungs-ID (Client) aus Schritt 1
Client Secret Wert des geheimen Clientschlüssels aus Schritt 3
Issuer URL https://login.microsoftonline.com/<Verzeichnis-ID>/v2.0

Mit Add Provider speichern. Auf der NetBird-Anmeldeseite erscheint jetzt neben „Continue with Email“ (lokale Konten) der Knopf für Microsoft.

Schritt 8: Anmeldung testen und Rollen vergeben

  1. Abmelden und über den Microsoft-Knopf mit einem zugewiesenen Testkonto anmelden.
  2. Ist die Benutzerfreigabe aktiv, muss ein lokaler Admin den neuen Benutzer unter Users zunächst bestätigen.
  3. Neue Benutzer erhalten die Rolle User. Administratoren unter Users auf Admin hochstufen.
  4. Den lokalen Admin aus der Erstinstallation als Notfallzugang behalten (sicheres Passwort, im Passwort-Tresor) – er funktioniert auch, wenn Entra ID oder der Clientschlüssel ausfällt.


HinweisBestehende Benutzer werden nicht automatisch zusammengeführt: Ein Kollege, der bisher ein lokales NetBird-Konto hatte, erhält über Entra ID ein neues Benutzerkonto (erkennbar am IdP-Abzeichen in der Benutzerliste). Seine Peers anschließend neu anmelden und das alte Konto entfernen.

Schritt 9: JWT-Gruppensynchronisation aktivieren

  1. Settings → Groups öffnen.
  2. Enable JWT group sync einschalten.
  3. JWT claim: groups
  4. Optional JWT allow groups: Nur Mitglieder dieser Gruppe dürfen sich anmelden – eine zweite Sicherung zusätzlich zu Schritt 5. Hier die Objekt-ID der Entra-Gruppe eintragen.
  5. Speichern. Nach der nächsten Anmeldung eines Benutzers erscheinen seine Gruppen unter Access Control → Groups.

Entra liefert im Token nur die Objekt-IDs (GUIDs) der Gruppen, keine Namen. In NetBird heißen die Gruppen daher z. B. 3f2a8c1e-…. Notieren Sie sich die Zuordnung (Entra: Gruppen → Alle Gruppen → Objekt-ID) in der Beschreibung bzw. Dokumentation. NetBird Cloud (Variante 3) übernimmt dagegen die Klarnamen.


WarnungExistiert in NetBird bereits eine manuell angelegte Gruppe mit identischem Namen, wird sie nicht synchronisiert. Solche Gruppen vor dem Umstieg löschen und die Richtlinien auf die neue Gruppe umstellen.

Schritt 10: Zugriffsrichtlinien auf Entra-Gruppen aufbauen

Unter Access Control → Policies verwenden Sie die synchronisierten Gruppen wie jede andere Gruppe, z. B.:

Quelle (Entra-Gruppe) Ziel (NetBird-Gruppe) Protokoll/Port
NetBird-Admins Linux-Server TCP 22
NetBird-Benutzer Fileserver TCP 445
IT-Dienstleister Wartungs-VM TCP 3389

Die Standardregel „Default“ (alle dürfen alles) danach deaktivieren – erst dann gilt das Zero-Trust-Prinzip. Verlässt ein Mitarbeiter eine Entra-Gruppe, verliert er das Recht mit seiner nächsten Anmeldung.

Schritt 11: Sitzungsdauer festlegen

Unter Settings → Authentication legt Peer login expiration fest, wie oft Benutzer ihre Geräte neu über Entra ID anmelden müssen (Standard 24 Stunden, möglich 1 Stunde bis 180 Tage). Bei jeder Neuanmeldung werden Conditional Access, MFA und die Gruppenmitgliedschaft erneut geprüft. Server, die per Setup-Key eingebunden sind, betrifft das nicht.

Clients mit Entra ID verbinden

Windows/macOS: NetBird-Client installieren, in den Einstellungen des Tray-Symbols die eigene Management-URL eintragen und Connect wählen. Der Browser öffnet die NetBird-Anmeldeseite; dort auf den Microsoft-Knopf klicken.

Linux: 

netbird up --management-url https://netbird.example.com
# Anmeldelink im Browser öffnen, "Microsoft 365" wählen, mit Entra-Konto anmelden
netbird status

NetBird Cloud: Benutzer und Gruppen aus Entra ID synchronisieren

In NetBird Cloud melden sich Benutzer direkt mit „Continue with Microsoft“ an. Zusätzlich lassen sich Benutzer und Gruppen samt Klarnamen per Microsoft Graph abgleichen:

  1. Im NetBird-Dashboard Integrations → Identity Provider → Entra ID (Azure AD) starten. Der Assistent liefert Name, Kontotyp und Umleitungs-URI zum Kopieren.
  2. In Entra die App-Registrierung damit anlegen, Client- und Mandanten-ID notieren.
  3. API-Berechtigungen → Berechtigung hinzufügen → Microsoft Graph → Anwendungsberechtigungen (nicht delegiert): User.Read.All und Group.Read.All.
  4. Administratorzustimmung erteilen – beide Berechtigungen müssen einen grünen Haken zeigen.
  5. Geheimen Clientschlüssel erstellen und Wert, Client-ID und Mandanten-ID im Assistenten eintragen.
  6. Optional Gruppen- und Benutzerfilter setzen (Standard: alle). Der Abgleich läuft etwa alle 5 Minuten.

SCIM-Provisionierung (kommerzielle Lizenz)

Mit SCIM legt Entra ID Benutzer und Gruppen aktiv in NetBird an und deaktiviert ausgeschiedene Mitarbeiter automatisch. Für selbst gehostete Installationen erfordert das eine kommerzielle NetBird-Lizenz; der Entra-Identity-Provider aus Teil 2 muss vorher eingerichtet sein.

  1. In NetBird Integrations → Identity Provider Sync → Connect Microsoft Entra ID wählen, den Entra-Connector auswählen und das SCIM-Token kopieren.
  2. In Entra Unternehmensanwendungen → Neue Anwendung → Eigene Anwendung erstellen („NetBird SCIM“, nicht im Katalog).
  3. Bereitstellung: Mandanten-URL https://netbird.example.com/api/scim/v2?aadOptscim062020 und SCIM-Token als geheimes Token eintragen, Verbindung testen.
  4. Vor dem ersten Lauf in den Attributzuordnungen der Benutzer die Quelle von externalId von mailNickname auf objectId ändern – sonst entstehen doppelte Konten. Bei den Gruppen die Zeile externalId löschen.
  5. Benutzer und Gruppen zuweisen, Bereitstellung starten. Entra synchronisiert danach etwa alle 40 Minuten.

Fehlerbehebung

Meldung / Symptom Ursache Lösung
AADSTS50011 – Redirect URI mismatch Umleitungs-URI weicht ab oder falsche Plattform URL exakt aus NetBird kopieren, Plattform Web, kein abschließender Schrägstrich
AADSTS700016 – Application not found Falsche Client-ID oder Mandanten-ID in der Issuer URL Werte in der App-Übersicht vergleichen
AADSTS50105 – Benutzer nicht zugewiesen Zuweisung erforderlich aktiv, Benutzer nicht berechtigt Benutzer bzw. Gruppe der Unternehmensanwendung zuweisen
AADSTS7000222 – Clientschlüssel abgelaufen Geheimer Schlüssel abgelaufen Neuen Schlüssel erzeugen, in NetBird beim Provider eintragen (leeres Feld behält den alten)
Microsoft-Knopf fehlt auf der Anmeldeseite Provider nicht gespeichert oder Browser-Cache Provider unter Settings → Identity Providers prüfen, Cache leeren
Keine Gruppen in NetBird Gruppenanspruch fehlt, JWT-Sync aus, mehr als 200 Gruppen Schritt 4 und 9 prüfen, „Der Anwendung zugewiesene Gruppen“ verwenden
Benutzer wird nicht angelegt E-Mail- oder Namensanspruch fehlt, Freigabe ausstehend Logs des NetBird-Servers prüfen (docker compose logs im Installationsverzeichnis), Benutzer unter Users freigeben

Hinweise für den Betrieb

  • Notfallzugang: Mindestens ein lokales Admin-Konto behalten und in Conditional Access die Entra-Notfallkonten ausschließen.
  • Abmeldung ausgeschiedener Mitarbeiter: Ohne SCIM bleibt das NetBird-Konto bestehen, bis es gelöscht wird. Durch die Peer login expiration und Zuweisung erforderlich verliert der Benutzer aber spätestens nach Ablauf der Sitzung den Zugang. Im Offboarding-Prozess das Konto zusätzlich in NetBird entfernen.
  • Protokollierung: Entra-Anmeldeprotokolle (Überwachung → Anmeldeprotokolle, Filter auf App „NetBird“) und NetBird-Activity-Events gemeinsam auswerten – idealerweise in einem SIEM.
  • Legacy-Installationen mit Entra ID als alleinigem IdP (Variante 2) laufen weiter. Ein Umstieg auf Variante 1 ändert die Benutzer-IDs und erfordert eine geplante Migration.

Unterstützung von m.a.x. it

Sie möchten NetBird mit Ihrem Microsoft-365-Tenant verbinden, Conditional Access sauber aufsetzen oder Remote-Zugriffe nach dem Zero-Trust-Prinzip neu organisieren? m.a.x. it unterstützt Sie mit der Microsoft-365- und Entra-ID-Betreuung von m.a.x. it und mit Cybersecurity-Leistungen von m.a.x. it.

Siehe auch

Links und Quellen


Über m.a.x. it Die m.a.x. Informationstechnologie AG ist seit über 30 Jahren IT-Partner mittelständischer und großer Unternehmen in München und bietet maßgeschneiderte Lösungen und Services in den Bereichen Cloud, Cybersecurity, Netzwerk, Windows, Linux und Softwareentwicklung. Sie haben eine Frage zu diesem Artikel oder brauchen Unterstützung? Kontakt aufnehmen

Abgerufen von „http://techcorner.max-it.de/index.php?title=NetBird_mit_Microsoft_Entra_ID_anbinden&oldid=4263“