NetBird mit Authentik oder Keycloak verbinden

Fernzugriff mit eigenem Identity Provider betreiben? WZ-IT plant und betreibt NetBird samt Authentik oder Keycloak - Identitäten, Gruppen und Richtlinien aus einer Hand, DSGVO-konform in der EU. Managed Secure Access ansehen

NetBird prüft keine Passwörter und keine zweiten Faktoren. Es verlässt sich darauf, dass ein Identity Provider das getan hat. Genau daran hängt der Sicherheitsgewinn des Modells - und deshalb ist die IdP-Anbindung nicht ein Konfigurationsdetail, sondern der Kern des Aufbaus. Dieser Artikel zeigt, wie die Anbindung an Authentik und Keycloak funktioniert, wo sich die beiden unterscheiden und was in der Community Edition nicht enthalten ist. Stand Juli 2026.

Inhaltsverzeichnis

• Warum der IdP der eigentliche Hebel ist
• Die drei Integrationsstufen
• Authentik anbinden
• Keycloak anbinden
• Authentik oder Keycloak
• Wo MFA tatsächlich erzwungen wird
• Fallstricke aus der Praxis

Warum der IdP der eigentliche Hebel ist

In einem klassischen VPN ist die Identität ein Zertifikat oder ein lokales Konto auf der Appliance. Beides lebt in genau einem System und muss dort separat gepflegt werden. Bei einem identitätsbasierten Overlay kehrt sich das um: Der Identity Provider ist die führende Quelle, und NetBird konsumiert nur noch dessen Aussage.

Praktisch heißt das:

• Eintritt und Austritt finden an einer Stelle statt. Wer im IdP deaktiviert wird, kommt nirgends mehr rein - auch nicht ins Netz.
• Gruppen werden einmal modelliert und steuern anschließend Zugriffsrichtlinien, ohne dass sie in NetBird gespiegelt werden müssen.
• MFA wird einmal erzwungen und gilt für alle angebundenen Anwendungen.

Wie das Overlay darunter funktioniert, steht in Was ist NetBird?. Warum der Weg über die Identität den anderen MFA-Nachrüstwegen überlegen ist, in MFA für VPN nachrüsten.

Die drei Integrationsstufen

Die Anbindung ist kein Alles-oder-nichts. Es gibt drei Stufen, die aufeinander aufbauen (Dokumentation):

Stufe 1 - Anmeldung per OIDC. Jeder Identity Provider, der OpenID Connect spricht, lässt sich anbinden. Nutzer melden sich über den IdP an, NetBird arbeitet mit dem ausgestellten Token. Das ist der Mindestumfang und deckt SSO und MFA bereits vollständig ab.

Stufe 2 - Gruppen-Sync per JWT-Claim. NetBird kann die Gruppenmitgliedschaften eines Nutzers aus dem Token lesen, wenn JWT Group Sync aktiviert und der Claim-Name hinterlegt ist. Damit steuern die IdP-Gruppen direkt die Zugriffsrichtlinien. Bemerkenswert: Dafür ist kein Zugriff auf eine Management-API des IdP nötig, der Claim im Token genügt.

Stufe 3 - SCIM-Provisionierung. Automatisches Anlegen und Deaktivieren von Nutzern und Gruppen. Hier lohnt der genaue Blick: SCIM ist nicht Teil der quelloffenen Community Edition. Im Self-Hosting beginnt es beim Commercial Starter für 2.000 Euro pro Jahr (bis 50 Nutzer und 500 Geräte), der zusätzlich Hochverfügbarkeit und Device Approvals enthält (Preisübersicht, Stand Juli 2026).

Entscheidend für die Einordnung: Stufe 1 und 2 sind in der kostenlosen Community Edition vollständig enthalten - SSO und MFA über den eigenen Identity Provider kosten also nichts. SCIM automatisiert das Anlegen und Deaktivieren von Konten; wer seine Nutzer ohnehin im IdP pflegt und die Gruppen über den JWT-Claim ausliefert, kommt für die meisten mittelständischen Setups ohne aus. Nur sollte das vor der Architekturentscheidung feststehen, nicht danach.

Authentik anbinden

In Authentik wird ein OAuth2/OpenID Provider angelegt. Die relevanten Werte (Dokumentation):

• Client type: Confidential
• Authorization flow: default-provider-authorization-explicit-consent
• Signing Key: ein beliebiges vorhandenes Zertifikat, etwa das selbstsignierte von Authentik
• Redirect URI: die von NetBird angezeigte URL, im Modus Strict statt Regex. Optional zusätzlich der Logout-Callback https://netbird.example.com/oauth2/logout/callback

Auf NetBird-Seite wird unter Settings → Identity Providers ein Eintrag vom Typ Generic OIDC angelegt, mit Client ID und Secret aus Authentik sowie dem Issuer in der Form https://authentik.example.com/application/o/netbird/.

Für den Gruppen-Sync ist Authentik im Vorteil: Es liefert einen groups-Claim bereits über den profile-Scope. Nötig sind lediglich zwei Punkte - in den erweiterten Provider-Einstellungen „Include claims in id_token" aktivieren und sicherstellen, dass die Scopes profile und groups ausgewählt sind. In NetBird wird dann JWT Group Sync mit dem Claim-Namen groups eingeschaltet.

Keycloak anbinden

Bei Keycloak läuft die Grundeinrichtung ähnlich: ein Realm (in der Dokumentation netbird), darin ein OpenID-Connect-Client mit aktivierter Client-Authentifizierung, die Redirect-URI aus den NetBird-Einstellungen unter „Valid redirect URIs", anschließend Client Secret übernehmen. Der Issuer hat die Form https://keycloak.example.com/realms/netbird (Dokumentation).

Der Unterschied liegt bei den Gruppen: Keycloak liefert sie nicht standardmäßig mit. Es braucht einen eigenen Client-Scope, üblicherweise groups genannt, mit einem Group-Membership-Mapper, dessen Token-Claim-Name auf groups gesetzt ist. Dieser Scope wird dem NetBird-Client als Default-Scope zugewiesen.

Das ist der häufigste Grund, warum eine Keycloak-Anbindung funktioniert, aber alle Peers in der falschen Gruppe landen: Die Anmeldung klappt, nur enthält das Token keine Gruppen.

Authentik oder Keycloak

Beide sind quelloffen, selbst hostbar und für diesen Zweck vollständig geeignet. Die Entscheidung fällt eher am Umfeld als an NetBird:

Wer noch keinen IdP betreibt und mit dem Fernzugriff anfängt, kommt mit Authentik schneller ans Ziel. Wer bereits Keycloak für andere Anwendungen einsetzt, bindet NetBird dort an - ein zweiter IdP wäre genau der Wildwuchs, den das Modell auflösen soll.

Wo MFA tatsächlich erzwungen wird

Ein Punkt, der in Konzepten regelmäßig falsch verortet wird: NetBird prüft keinen zweiten Faktor. Es gibt in NetBird keinen Schalter „MFA erzwingen". Die Regel gehört in den Identity Provider - in Authentik in den Authentifizierungs-Flow, in Keycloak in den Authentication Flow der jeweiligen Realm.

Das ist kein Mangel, sondern der eigentliche Gewinn: Die Faktorregel wird einmal definiert und gilt für jede angebundene Anwendung. Wer sie für den Fernzugriff verschärft, verschärft sie automatisch auch für alles andere hinter demselben IdP. Hintergrund dazu in SSO & MFA für das Fernzugriffs-Portal.

Fallstricke aus der Praxis

• Gruppen fehlen im Token. Der Klassiker bei Keycloak, siehe oben. Vor dem Bau der Richtlinien prüfen, ob der Claim tatsächlich ankommt.
• Redirect-URI zu locker gefasst. Die Dokumentation nennt für Authentik ausdrücklich den Strict-Modus. Regex-Einträge sind bequem und öffnen unnötigen Spielraum.
• SCIM eingeplant, aber nicht lizenziert. Wer automatisches Deprovisioning zur Grundannahme macht, sollte den Lizenzstand vorher klären.
• Den IdP hinter das Netz stellen, das er absichert. Wenn die Anmeldung nur über den Fernzugriff erreichbar ist, den sie ermöglichen soll, entsteht eine Abhängigkeit, die im Störfall teuer wird.
• Gruppenstruktur nachträglich bauen. Sie bestimmt jede spätere Zugriffsregel. Vor dem Rollout modellieren spart mehr Zeit, als es kostet - die Reihenfolge dazu steht in FortiGate-SSL-VPN zu NetBird migrieren.