ConnectCLOUDDocs

Appearance

Zielgruppe & Rolle

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

Automatische NetBird-Anbindung für microtech ERP ​

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:

  1. Enrollment starten: Im ConnectCLOUD-Portal (/customer-admin unter microtech) wird für den Server 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 Kundenportal 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 navigieren Sie zur Kunden-Administration (/customer-admin).
  2. Wechseln Sie in den Reiter microtech.
  3. Neuer Server: Klicken Sie oben auf „Server mit NetBird anbinden“.
    • Geben Sie einen sprechenden Namen ein (z. B. ERP Hauptserver).
    • Hinterlegen Sie Client-ID und Client-Secret der microtech-Anwendung.
    • Optional: Fügen Sie bereits Mandanten-Zuordnungen hinzu.
    • Klicken Sie auf „Enrollment starten“.
  4. Bestehender Server: Falls der Server bereits in der Liste existiert, klicken Sie auf der Server-Karte im Bereich NetBird Server-Enrollment auf „Enrollment starten“.
  5. Ihnen wird nun der Enrollment-Code (gültig für 60 Minuten) sowie der vollständige PowerShell-Befehl angezeigt.

Verwaltung des Enrollments

Solange ein Enrollment aktiv ist, stehen Ihnen auf der Server-Karte zwei Optionen zur Verfügung:

  • Befehl & Code neu generieren: Erzeugt bei Bedarf einen frischen Code, falls der vorherige abgelaufen ist.
  • Enrollment abbrechen: Bricht den Vorgang ab und setzt den Server-Status zurück.

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 Kundenportal 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).
    • Einrichtung eines dedizierten NetBird-Profils (ConnectCLOUD) anstelle des Default-Profils.
    • 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: MBCOM-ConnectCLOUD).
  • -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).

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 zur Kunden-Administration (Reiter microtech) zurück.
  2. Die Server-Karte zeigt nun den Status „Zertifikat hochgeladen – Aktivierung in microtech erforderlich“ an.
  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. Der Status wechselt auf „Bereit“ (grün).

Schritt 5: Mandanten abrufen & Verbindung testen ​

  1. Klicken Sie auf der Server-Karte auf „Bearbeiten“ oder nutzen Sie den Button „Mandanten abrufen“.
  2. ConnectCLOUD ruft über die frisch aufgebaute NetBird-Verbindung die microtech GraphQL-API ab und zeigt alle erkannten Mandanten an.
  3. Weisen Sie die microtech-Mandanten Ihren ConnectCLOUD-Mandanten zu und aktivieren Sie die gewünschten Einträge.
  4. Klicken Sie auf „Verbindung testen“, um den Token-Abruf und eine Testabfrage abschließend zu verifizieren.

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 aktiv mit einem fremden Netzwerk oder einem anderen Mandanten verbunden, 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:
    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.
  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.

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 NetBird auf dem Server aktiv mit einem fremden Netzwerk oder einem anderen ConnectCLOUD-Mandanten verbunden ist.
  • Lösung: 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 aktivieren und testen Sie die microtech-Komponente im Portal: microtech Mandantenkonfiguration im Portal

Zurück zur Übersicht: Basiskonfiguration Übersicht