Quelltext der Seite NetBird mit Microsoft Entra ID anbinden

{{Steckbrief
| gilt_fuer   = NetBird selbst gehostet ab 0.62 mit eingebettetem Identity Provider (geprüft mit 0.80), NetBird Cloud; Microsoft Entra ID (ehemals Azure AD)
| bereich     = IT-Security
| dauer       = ca. 30 Minuten (App-Registrierung, Anbindung, Gruppen-Sync, Test)
| rechte      = Entra ID: Anwendungsadministrator oder Cloudanwendungsadministrator; NetBird: Owner/Admin im Dashboard
| stand       = Oktober 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]].

[[Datei:NetBird-Entra-ID.png|thumb|center|750px|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.

{| class="wikitable"
! 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 <code>groups</code>.
|-
| '''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 <code>getting-started.sh</code>-Skript) und lokalem Admin-Konto.
* Öffentlicher DNS-Name mit gültigem Zertifikat, z. B. <code><nowiki>https://netbird.example.com</nowiki></code>.
* Zugriff auf das Microsoft Entra Admin Center (<code>entra.microsoft.com</code>) 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.

# Im Entra Admin Center ''Identität → Anwendungen → App-Registrierungen → Neue Registrierung'' öffnen.
# '''Name:''' <code>NetBird</code> (wird Benutzern bei der Anmeldung angezeigt).
# '''Unterstützte Kontotypen:''' ''Nur Konten in diesem Organisationsverzeichnis (einzelner Mandant)''. Damit können sich ausschließlich Konten Ihres Tenants anmelden.
# '''Umleitungs-URI''' vorerst leer lassen und '''noch nicht''' auf ''Registrieren'' klicken.
# 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.
# Zurück in Entra auf ''Registrieren'' klicken.
# Auf der Übersichtsseite der App '''Anwendungs-ID (Client)''' und '''Verzeichnis-ID (Mandant)''' notieren.

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

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

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

{{Warnung|Lä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.
# ''Tokenkonfiguration → Gruppenanspruch hinzufügen''.
# 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.
# 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.

{{Hinweis|Entra 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:
# ''Identität → Anwendungen → Unternehmensanwendungen'' → App '''NetBird''' öffnen (wurde mit der App-Registrierung automatisch angelegt).
# ''Eigenschaften → Zuweisung erforderlich?'' auf '''Ja''' setzen und speichern.
# ''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 <code>netbird up</code>, 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.

{{Tipp|Phishing-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''):
{| class="wikitable"
! 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 || <code><nowiki>https://login.microsoftonline.com/</nowiki>&lt;Verzeichnis-ID&gt;/v2.0</code>
|}
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 ===
# Abmelden und über den Microsoft-Knopf mit einem zugewiesenen Testkonto anmelden.
# Ist die Benutzerfreigabe aktiv, muss ein lokaler Admin den neuen Benutzer unter ''Users'' zunächst bestätigen.
# Neue Benutzer erhalten die Rolle '''User'''. Administratoren unter ''Users'' auf ''Admin'' hochstufen.
# 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.

{{Hinweis|Bestehende 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 ===
# ''Settings → Groups'' öffnen.
# '''Enable JWT group sync''' einschalten.
# '''JWT claim:''' <code>groups</code>
# 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.
# 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. <code>3f2a8c1e-…</code>. Notieren Sie sich die Zuordnung (Entra: ''Gruppen → Alle Gruppen → Objekt-ID'') in der Beschreibung bzw. Dokumentation. NetBird Cloud (Variante 3) übernimmt dagegen die Klarnamen.

{{Warnung|Existiert 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.:
{| class="wikitable"
! 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:'''
<syntaxhighlight lang="bash">
netbird up --management-url https://netbird.example.com
# Anmeldelink im Browser öffnen, "Microsoft 365" wählen, mit Entra-Konto anmelden
netbird status
</syntaxhighlight>

== 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:
# Im NetBird-Dashboard ''Integrations → Identity Provider → Entra ID (Azure AD)'' starten. Der Assistent liefert Name, Kontotyp und Umleitungs-URI zum Kopieren.
# In Entra die App-Registrierung damit anlegen, Client- und Mandanten-ID notieren.
# ''API-Berechtigungen → Berechtigung hinzufügen → Microsoft Graph → '''Anwendungsberechtigungen''''' (nicht delegiert): <code>User.Read.All</code> und <code>Group.Read.All</code>.
# '''Administratorzustimmung erteilen''' – beide Berechtigungen müssen einen grünen Haken zeigen.
# Geheimen Clientschlüssel erstellen und Wert, Client-ID und Mandanten-ID im Assistenten eintragen.
# 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.
# In NetBird ''Integrations → Identity Provider Sync → Connect Microsoft Entra ID'' wählen, den Entra-Connector auswählen und das '''SCIM-Token''' kopieren.
# In Entra ''Unternehmensanwendungen → Neue Anwendung → Eigene Anwendung erstellen'' („NetBird SCIM“, nicht im Katalog).
# ''Bereitstellung'': Mandanten-URL <code><nowiki>https://netbird.example.com/api/scim/v2?aadOptscim062020</nowiki></code> und SCIM-Token als geheimes Token eintragen, Verbindung testen.
# '''Vor dem ersten Lauf''' in den Attributzuordnungen der Benutzer die Quelle von <code>externalId</code> von <code>mailNickname</code> auf <code>objectId</code> ändern – sonst entstehen doppelte Konten. Bei den Gruppen die Zeile <code>externalId</code> löschen.
# Benutzer und Gruppen zuweisen, ''Bereitstellung starten''. Entra synchronisiert danach etwa alle 40 Minuten.

== Fehlerbehebung ==
{| class="wikitable"
! 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 (<code>docker compose logs</code> 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 [https://www.max-it.de/it-services/microsoft-365/ Microsoft-365- und Entra-ID-Betreuung von m.a.x. it] und mit [https://www.max-it.de/it-services/cybersecurity/ Cybersecurity-Leistungen von m.a.x. it].

== Siehe auch ==
* [[NetBird – Zero-Trust-Netzwerk mit WireGuard]]
* [[OPNsense - NetBird-Plugin]]
* [[Entra ID]]
* [[Conditional Access]]
* [[Single Sign-On]]
* [[OpenID Connect]]
* [[SCIM]]
* [[MFA]]
* [[Zero Trust]]

== Links und Quellen ==
* [https://docs.netbird.io/selfhosted/identity-providers/managed/microsoft-entra-id NetBird-Dokumentation: Microsoft Entra ID with NetBird Self-Hosted]
* [https://www.max-it.de/it-services/microsoft-365/ Microsoft 365 und Entra ID mit m.a.x. it]

{{Uebermax}}
[[Kategorie:IT-Security]]