Zum Inhalt springen
Automatische NetBird-Anbindung für microtech ERP
Administration

Automatische NetBird-Anbindung für microtech ERP

On-Premises microtech büro+ Server ohne Firewall-Portweiterleitungen via NetBird VPN und Auto-TLS anbinden.

Zuletzt geändert am 6.11.2026

Auf dieser Seite

Zielgruppe & Rolle

Rolle: IT-Administrator | Voraussetzung: Administrator-Rechte auf dem Windows Server & microtech BpConfig

Mit der automatischen NetBird-Enrollment-Funktion können Sie Ihren On-Premises microtech büro+ Server ohne manuelle Zertifikatserstellung, feste externe IP-Adressen oder Firewall-Portweiterleitungen sicher und verschlüsselt an ConnectCLOUD anbinden.

Übersicht & Funktionsweise

Die Anbindung erfolgt über ein sicheres VPN-Overlay-Netzwerk (NetBird) und selbstsignierte TLS-Zertifikate mit Ende-zu-Ende-Verschlüsselung:

sequenceDiagram
    autonumber
    participant Portal as ConnectCLOUD Portal (Einstellungen › Integrationen › microtech)
    participant PS as Windows Server (PowerShell)
    participant Bp as microtech (BpConfig.exe)

    Portal->>Portal: 1. Enrollment starten (Code & Befehl erzeugt)
    Portal->>PS: 2. PowerShell-Befehl ausführen
    PS->>PS: NetBird installieren & Peer registrieren
    PS->>PS: ECDSA TLS-Zertifikat erstellen
    PS->>Portal: Öffentliches Zertifikat hochladen
    Portal-->>Portal: Status: Zertifikat hochgeladen (Thumbprint anzeigen)
    PS->>Bp: 3. Zertifikat in BpConfig auswählen
    Portal->>Portal: 4. Klick auf "In microtech aktiviert"
    Portal-->>Portal: Status: Bereit (Dual-Trust aktiv)
  1. Enrollment starten: Im ConnectCLOUD-Portal (Einstellungen › Integrationen › microtech, Bereich NetBird-Einrichtung) wird für die Verbindung Ihres Mandanten ein einmaliger, zeitlich begrenzter Enrollment-Code (Gültigkeit: 60 Minuten) erzeugt.
  2. Bootstrap-Skript ausführen: Auf dem Windows-Server wird als Administrator ein vorgefertigter, geheimnisfreier PowerShell-Befehl ausgeführt. Das Skript installiert NetBird, verbindet den Peer, erstellt ein ECDSA-TLS-Zertifikat und lädt den öffentlichen Schlüssel zu ConnectCLOUD hoch.
  3. Zertifikat in microtech zuweisen: In BpConfig.exe wird das neue Zertifikat anhand des Thumbprints für die HTTP/2-Schnittstelle ausgewählt.
  4. Aktivierung bestätigen: Im Portal wird die Aktivierung per Klick auf „In microtech aktiviert“ abgeschlossen.

Fester DNS- und Peer-Name

Jeder Server erhält bei der ersten Einrichtung einen eindeutigen und stabilen NetBird-Peer-Namen nach dem Schema:

text
microtech-<umgebung>-<kundennummer>-<zufallssuffix>
  • Beispiel: microtech-prod-10639-81962348
  • Vollständiger Domänenname (FQDN): microtech-prod-10639-81962348.netbird.cloud
  • Automatische Basis-URL: ConnectCLOUD hinterlegt automatisch die Basis-URL https://microtech-prod-10639-81962348.netbird.cloud:8443/microtech/erp.

Dieser Name und die URL bleiben auch bei wiederholter Ausführung des Skripts oder regulärer Zertifikatsrotation unverändert erhalten.


Voraussetzungen

  • Betriebssystem: Windows Server 2016+ oder Windows 10/11 (64-Bit), auf dem microtech ERP ausgeführt wird.
  • PowerShell: Version 5.1 oder neuer (Standard auf modernen Windows-Systemen) mit Administratorrechten.
  • Netzwerk: Ausgehender Internetzugang (HTTPS / Port 443 sowie UDP für NetBird WireGuard-Verbindungen). Es sind keine eingehenden Portweiterleitungen oder öffentlichen IP-Adressen erforderlich!
  • microtech Vorbereitung: Die microtech-Anwendung für ConnectCLOUD mit Client-ID und Client-Secret muss angelegt sein (siehe Basis-Konfiguration).

Schritt-für-Schritt-Anleitung

Schritt 1: Enrollment in ConnectCLOUD starten

  1. Melden Sie sich im ConnectCLOUD-Portal an und öffnen Sie Einstellungen › Integrationen › microtech (Berechtigung tenant:settings:read zum Ansehen, tenant:settings:write zum Ändern). Jeder Mandant richtet seine eigene microtech-Verbindung ein.
  2. Tragen Sie im Bereich Verbindung die Client-ID und das Client-Secret der microtech-Anwendung ein und speichern Sie. Die Basis-URL und das TLS-Zertifikat setzt die Einrichtung selbst, sobald das Zertifikat aktiviert ist.
  3. Klicken Sie im Bereich NetBird-Einrichtung auf „Einrichtung starten“ (bei einer bestehenden Einrichtung auf „Neu einrichten“).
  4. Beantworten Sie die Frage „Läuft auf dem Server schon ein anderes VPN?“:
    • Ja: Der Befehl enthält -InstanceMode Isolated. ConnectCLOUD wird getrennt neben dem bestehenden VPN eingerichtet (siehe Parallelbetrieb mit bestehenden VPNs).
    • Nein oder Weiß nicht: Der Befehl enthält keinen zusätzlichen Parameter. Das Skript erkennt bestehende VPNs selbst. -InstanceMode Default wird bewusst nie automatisch gesetzt.
  5. Ein zweiter Schritt unter „Das passiert jetzt“ fasst zusammen, was passieren wird. War der Server bereits verbunden, wird er mit derselben Identität erneut verbunden. Erst mit „Befehl erzeugen“ wird der einmalige Einrichtungscode (gültig für 60 Minuten, nur einmal verwendbar) erzeugt und zusammen mit dem vollständigen PowerShell-Befehl angezeigt. Der Code ist nur jetzt sichtbar.

Verwaltung der Einrichtung

Solange eine Einrichtung läuft, stehen Ihnen zwei Optionen zur Verfügung:

  • Befehl neu erzeugen: Erzeugt bei Bedarf einen frischen Code, falls der vorherige abgelaufen oder nicht mehr sichtbar ist.
  • Einrichtung abbrechen: Bricht den Vorgang ab; der Einrichtungscode wird ungültig.

Das Portal zeigt den Fortschritt (Code eingelöst, NetBird installiert, NetBird verbunden, Zertifikat hochgeladen) laufend an. Die Einrichtung ist nur für NetBird-Adressen (*.netbird.cloud) möglich und muss auf der Plattform aktiviert sein.


Schritt 2: Bootstrap-Skript auf dem microtech-Server ausführen

  1. Öffnen Sie auf dem Windows-Server eine PowerShell als Administrator (Rechtsklick auf Windows Start -> Windows PowerShell (Administrator)).
  2. Kopieren Sie den angezeigten Einzeiler aus dem Portal und führen Sie ihn aus:
    powershell
    & { iwr -useb "https://microtech.mbcom.cloud/api/microtech/v1/enrollment/bootstrap.ps1" | iex } -Code "<ENROLLMENT-CODE>"
    
  3. Das Bootstrap-Skript arbeitet autonom und führt folgende Schritte aus:
    • Überprüfung der Administratorrechte und PowerShell-Version.
    • Herunterladen und Installation des offiziellen NetBird-Clients (sofern noch nicht installiert).
    • Prüfung, ob auf dem Server bereits ein anderes NetBird-Konto, Tailscale oder ein anderes WireGuard-VPN eingerichtet ist. In diesem Fall wird automatisch eine isolierte ConnectCLOUD-Instanz verwendet (siehe Parallelbetrieb mit bestehenden VPNs).
    • Einrichtung eines dedizierten NetBird-Profils (ConnectCLOUD) anstelle des Default-Profils (nur Standardinstanz).
    • Dynamische Zuweisung des WireGuard-Ports (--wireguard-port 0), um Port-Kollisionen mit Windows-Diensten (wie dem Windows DNS Server auf Port 51820) zu vermeiden.
    • Verbindung zum NetBird-VPN-Netzwerk als vorkonfigurierter Peer.
    • Erstellung oder Wiederverwendung eines TLS-Zertifikats (ECDSA P-256) im Windows-Zertifikatsspeicher (Cert:\LocalMachine\My) mit nicht-exportierbarem privaten Schlüssel.
    • Sichere Übertragung des öffentlichen Zertifikats an ConnectCLOUD.
  4. Nach Abschluss gibt das Skript den Zertifikats-Thumbprint (SHA-1 / SHA-256 Fingerabdruck) in der Konsole aus.

Execution Policy

Falls PowerShell die Skriptausführung mit einem Sicherheitsfehler blockiert, führen Sie den Befehl mit vorangestelltem Bypass aus:

powershell
powershell -ExecutionPolicy Bypass -Command "& { iwr -useb 'https://microtech.mbcom.cloud/api/microtech/v1/enrollment/bootstrap.ps1' | iex } -Code '<ENROLLMENT-CODE>'"

Erweiterte Parameter (Profil & WireGuard-Port)

Das Skript unterstützt optionale Parameter für spezifische Netzwerk- oder Profilanforderungen:

  • -ProfileName <Name>: Verwendet ein alternatives NetBird-Profil (Standard: ConnectCLOUD). Gilt nur für die Standardinstanz.
  • -UseDefaultWireGuardPort: Deaktiviert die dynamische Portwahl und lässt NetBird den Standardport (51820) nutzen.
  • -WireGuardPort <Port>: Erzwingt einen bestimmten WireGuard UDP-Port (z. B. -WireGuardPort 51825).
  • -InstanceMode Auto|Default|Isolated: Steuert, ob die NetBird-Standardinstanz oder eine isolierte ConnectCLOUD-Instanz verwendet wird (Standard: Auto).

Schritt 3: Zertifikat in microtech aktivieren (BpConfig)

  1. Öffnen Sie BpConfig.exe auf dem microtech-Server.
  2. Navigieren Sie zu den Einstellungen für die GraphQL / HTTP/2 API.
  3. Stellen Sie sicher, dass der HTTP/2 Port auf 8443 (oder den von Ihnen gewünschten Port) konfiguriert ist.
  4. Öffnen Sie die Zertifikatsauswahl.
  5. Wählen Sie das Zertifikat aus, dessen Thumbprint (Fingerabdruck) mit dem vom Skript ausgegebenen bzw. im ConnectCLOUD-Portal angezeigten Wert übereinstimmt.
  6. Speichern Sie die Konfiguration in BpConfig.exe und starten Sie die microtech-Dienste bei Bedarf neu.

Schritt 4: Aktivierung in ConnectCLOUD bestätigen

  1. Kehren Sie in das ConnectCLOUD-Portal zu Einstellungen › Integrationen › microtech zurück.
  2. Der Bereich NetBird-Einrichtung zeigt nun „Zertifikat hochgeladen – Aktivierung in microtech erforderlich“ an. In microtech wählen Sie das Zertifikat unter Einstellungen › Connect / ERP aus.
  3. Überprüfen Sie, ob der angezeigte Thumbprint mit dem in microtech ausgewählten Zertifikat übereinstimmt.
  4. Klicken Sie auf die Schaltfläche „In microtech aktiviert“.
  5. Das Zertifikat wird jetzt für die Verbindung genutzt, die Basis-URL ist gesetzt und der Status wechselt auf „Eingerichtet“.

Schritt 5: Mandanten abrufen & Verbindung testen

  1. Klicken Sie im Bereich Verbindung auf „Mandanten ermitteln“.
  2. ConnectCLOUD ruft über die frisch aufgebaute NetBird-Verbindung die microtech GraphQL-API ab und zeigt die gefundenen Mandanten an (nicht aktive microtech-Mandanten sind gekennzeichnet).
  3. Übernehmen Sie Ihren microtech-Mandanten per Klick in das Feld Mandant und aktivieren Sie die Verbindung.
  4. Speichern Sie und prüfen Sie die Verbindung über den Verbindungstest (Token-Abruf und Testabfrage).

Parallelbetrieb mit bestehenden VPNs

Viele Server sind bereits über ein eigenes VPN angebunden – etwa über ein eigenes NetBird-Konto, Tailscale oder WireGuard. Das Bootstrap-Skript erkennt das und richtet ConnectCLOUD dann als isolierte NetBird-Instanz ein, ohne die bestehende Verbindung zu verändern.

Wann wird die isolierte Instanz verwendet?

Mit dem Standardwert -InstanceMode Auto verwendet das Skript die isolierte Instanz, wenn mindestens eine der folgenden Bedingungen zutrifft:

  • NetBird ist mit einem Konto eingerichtet, das nicht von ConnectCLOUD stammt.
  • Ein Tailscale-, WireGuard- oder ZeroTier-Dienst ist installiert.
  • Der Server wurde bereits zuvor mit der isolierten Instanz angebunden.

Ist kein anderes VPN vorhanden, wird wie bisher die NetBird-Standardinstanz verwendet. Mit -InstanceMode Default bzw. -InstanceMode Isolated lässt sich die Wahl erzwingen.

Was unterscheidet die isolierte Instanz?

Standardinstanz Isolierte Instanz
Windows-Dienst netbird NetBird-ConnectCLOUD
Programmdateien C:\Program Files\NetBird (MSI) %ProgramData%\ConnectCLOUD\NetBird\bin (eigene Kopie, nur für SYSTEM und Administratoren beschreibbar)
Daemon-Adresse Standard npipe://netbird-connectcloud
Netzwerk Netzwerkadapter wt0, Routen und DNS-Einträge Userspace-Modus: kein Netzwerkadapter, keine Routen- oder DNS-Änderungen am System
NetBird-Oberfläche (Tray) ja nein – Status nur per Kommandozeile

Da die isolierte Instanz keinen Netzwerkadapter anlegt, kollidiert sie weder mit dem Adapter eines anderen NetBird-Kontos noch mit überlappenden IP-Bereichen (z. B. 100.64.0.0/10 bei Tailscale). Eingehende Verbindungen von ConnectCLOUD auf die NetBird-Adresse leitet NetBird an 127.0.0.1 weiter.

Voraussetzungen und Hinweise

  • Lokale Erreichbarkeit: Der HTTP/2-Dienst von microtech muss auf dem Server auch über 127.0.0.1:8443 erreichbar sein (Standard bei Bindung an alle Adressen).
  • Firewall-Regel: Alle NetBird-Instanzen teilen sich die Windows-Firewall-Regeln Netbird und Netbird-v6. Damit ein Neustart der ConnectCLOUD-Instanz die Regeln der Kundeninstanz nicht entfernt, richtet das Skript die geplante Aufgabe \ConnectCLOUD\NetBird Firewall Guard ein. Sie stellt die Regeln beim Systemstart und alle 5 Minuten wieder her – für Adressen aus den NetBird-Standardbereichen (100.64.0.0/10 bzw. fc00::/7). Kann die Aufgabe nicht eingerichtet werden, wird die Anbindung trotzdem abgeschlossen und eine Warnung ausgegeben.
  • Updates: Updates der NetBird-Installation des Kunden betreffen die isolierte Instanz nicht. Zum Aktualisieren der isolierten Instanz führen Sie das Skript erneut mit -UpgradeNetBird aus.
  • Verzeichnisrechte: Existiert %ProgramData%\ConnectCLOUD oder %ProgramData%\ConnectCLOUD\NetBird bereits und gehört es nicht Administratoren bzw. SYSTEM, bricht das Skript ab. Prüfen und entfernen Sie das Verzeichnis in diesem Fall.

Signaturprüfung

Das Skript installiert bzw. entpackt NetBird nur, wenn das Installationspaket (und bei der isolierten Instanz zusätzlich netbird.exe) gültig von der NetBird GmbH signiert ist. Auf Servern ohne aktuelle Stammzertifikate (z. B. dauerhaft offline) kann die Prüfung fehlschlagen; installieren Sie dann die Windows-Stammzertifikatsupdates.

Status prüfen und isolierte Instanz entfernen

powershell
# Status der ConnectCLOUD-Instanz
& "$env:ProgramData\ConnectCLOUD\NetBird\bin\netbird.exe" status --daemon-addr npipe://netbird-connectcloud

# Entfernen (z. B. nach Kündigung)
& "$env:ProgramData\ConnectCLOUD\NetBird\bin\netbird.exe" down --daemon-addr npipe://netbird-connectcloud
Stop-Service NetBird-ConnectCLOUD; sc.exe delete NetBird-ConnectCLOUD
Unregister-ScheduledTask -TaskPath "\ConnectCLOUD\" -TaskName "NetBird Firewall Guard" -Confirm:$false
Remove-Item "$env:ProgramData\ConnectCLOUD\NetBird" -Recurse -Force

Zertifikatsrotation & Re-Run-Verhalten

Die NetBird-Anbindung ist auf maximale Betriebssicherheit und minimale Wartung ausgelegt:

Idempotente Mehrfachausführung (Re-Run)

Das Bootstrap-Skript ist vollständig idempotent. Wenn Sie das Skript auf einem bereits angebundenen Server erneut ausführen (z. B. nach einem Server-Neustart oder zur Überprüfung), erkennt das Skript die bestehende NetBird-Peer-Verbindung und führt keine erneute Peer-Registrierung durch.

Automatische Konfigurationsbereinigung & Mandantenwechsel (Re-Enrollment)

Bei Migrationen zwischen verschiedenen ConnectCLOUD-Mandanten oder nach einer vorherigen NetBird-Deinstallation auf dem Windows-Server verbleiben standardmäßig Konfigurationsdateien in %ProgramData%\NetBird. Das Bootstrap-Skript verhindert zuverlässig, dass solche Altdaten wiederverwendet werden:

  1. Automatische Sicherung bei nicht-aktiver Verbindung: Ist NetBird nicht verbunden oder frisch installiert, verschiebt das Skript alle vorhandenen Konfigurations- und Statusdateien (config.json, default.json, state.json) automatisch in ein zeitgestempeltes Backup-Verzeichnis (%ProgramData%\NetBird\backup-YYYYMMDD-HHMMSS). Anschließend wird NetBird mit dem neuen Setup-Key sauber initialisiert.
  2. Schutz aktiver Verbindungen: Ist NetBird auf dem Server bereits mit einem fremden NetBird-Konto eingerichtet, richtet das Skript eine isolierte ConnectCLOUD-Instanz ein und lässt die bestehende Verbindung unverändert. Ist die Standardinstanz mit einem anderen ConnectCLOUD-Peer (microtech-…) verbunden oder wurde -InstanceMode Default angegeben, bricht das Skript mit einer Konfliktmeldung ab (peer_mismatch), um unbeabsichtigte Trennungen zu vermeiden.
  3. Erzwungener Mandantenwechsel mit -ResetNetbirdConfig: Soll der Server bewusst neu zugeordnet werden, kann der Parameter -ResetNetbirdConfig übergeben werden. Er wirkt immer nur auf die verwendete Instanz – in der isolierten Instanz bleibt eine NetBird-Installation des Kunden unberührt. Um die Standardinstanz bewusst zu übernehmen, kombinieren Sie ihn mit -InstanceMode Default:
    powershell
    & { iwr -useb "https://microtech.mbcom.cloud/api/microtech/v1/enrollment/bootstrap.ps1" | iex } -Code "<ENROLLMENT-CODE>" -ResetNetbirdConfig
    
    Das Skript trennt die Verbindung, sichert die bisherige Konfiguration in das Backup-Verzeichnis und verbindet NetBird frisch mit dem neuen Mandanten. Im Portal bietet die Fehlermeldung dafür „Befehl mit Neukonfiguration erzeugen“ an.
  4. Strikte Domain-Validierung: Nach jedem Verbindungsaufbau verifiziert das Skript, dass die von NetBird gemeldete Domäne (FQDN) exakt der vom Enrollment-Dienst zugewiesenen Identität entspricht. Bei einer Abweichung bricht das Setup sofort ab, bevor TLS-Zertifikate erstellt oder hochgeladen werden.

Zero-Downtime Zertifikatsrotation (Dual-Trust)

TLS-Zertifikate besitzen eine begrenzte Laufzeit. Vor Ablauf des Zertifikats (< 30 Tage Restlaufzeit) kann ein neues Zertifikat erzeugt werden:

  1. Bei erneutem Enrollment generiert das Skript ein neues ECDSA-Zertifikat und lädt es als ausstehendes Zertifikat (pending) hoch.
  2. Dual-Trust-Bundle: ConnectCLOUD vertraut während des Wechsels sowohl dem bisherigen aktiven Zertifikat als auch dem neuen ausstehenden Zertifikat.
  3. Der laufende API-Verkehr wird zu keinem Zeitpunkt unterbrochen.
  4. Sie können in aller Ruhe BpConfig.exe öffnen und das neue Zertifikat hinterlegen.
  5. Nach dem Klick auf „In microtech aktiviert“ im Portal wird das neue Zertifikat zum aktiven Standard und das alte Zertifikat sicher abgelöst.

Fehlerbehebung & Häufige Fragen

NetBird-Dienst verbindet sich nicht

  • Prüfen Sie, ob der Windows-Dienst NetBird ausgeführt wird (Get-Service netbird).
  • Prüfen Sie in einer administrativen Konsole mit netbird status, ob der Peer als Connected gelistet ist.
  • Stellen Sie sicher, dass ausgehende UDP-Pakete nicht durch lokale Firmenfirewalls blockiert werden.
  • Isolierte Instanz: Dienst NetBird-ConnectCLOUD prüfen (Get-Service NetBird-ConnectCLOUD) und den Status über & "$env:ProgramData\ConnectCLOUD\NetBird\bin\netbird.exe" status --daemon-addr npipe://netbird-connectcloud abfragen. Das Log liegt unter %ProgramData%\ConnectCLOUD\NetBird\client.log.

Fehler beim Verbindungstest nach Aktivierung

  • Port: Stimmt der in BpConfig.exe eingestellte Port mit der Basis-URL überein (Standard: 8443)?
  • Zertifikatsauswahl: Wurde in BpConfig.exe tatsächlich das Zertifikat mit dem im Portal angezeigten Fingerabdruck ausgewählt?
  • GraphQL-Aktivierung: Ist GraphQL in den Firmenvorgaben des betreffenden Mandanten freigeschaltet und hat der Benutzer die Berechtigung Supervisor sowie Zugriff über GraphQL erlaubt?

Konflikt: NetBird ist bereits mit einer anderen Identität verbunden (peer_mismatch)

  • Tritt auf, wenn die NetBird-Standardinstanz mit einem anderen ConnectCLOUD-Peer verbunden ist oder -InstanceMode Default erzwungen wurde.
  • Im Portal: Die Fehlermeldung nennt die Identität, mit der der Rechner noch verbunden ist, und bietet „Befehl mit Neukonfiguration erzeugen“ an. Der neue Befehl enthält -ResetNetbirdConfig. Nur verwenden, wenn Sie sicher am richtigen Server sind: Ein anderer Server, der diese Verbindung nutzt, verliert dadurch seinen Zugang zu ConnectCLOUD.
  • Parallelbetrieb: Soll die bestehende Verbindung erhalten bleiben, führen Sie den Befehl mit -InstanceMode Isolated aus.
  • Umstellung: Wenn Sie den Server auf den neuen ConnectCLOUD-Mandanten umstellen möchten, führen Sie den Enrollment-Befehl mit dem Parameter -ResetNetbirdConfig aus:
    powershell
    & { iwr -useb "https://microtech.mbcom.cloud/api/microtech/v1/enrollment/bootstrap.ps1" | iex } -Code "<ENROLLMENT-CODE>" -ResetNetbirdConfig
    
    Alternativ können Sie die bestehende Verbindung vorab manuell über netbird down trennen.

Verwandte Dokumentation


Nächster Schritt in der Basiskonfiguration

Nach erfolgreicher Server- und NetBird-Anbindung prüfen Sie die Verbindung Ihres Mandanten im Portal: microtech Mandantenkonfiguration im Portal

Zurück zur Übersicht: Basiskonfiguration Übersicht

Hat das geholfen?