mocode-software/meldestelle
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
bd8899a829
meldestelle/docs/01_Architecture/Onboarding-Backend.md
Stefan Mogeritsch a6fcb81594
Some checks failed
Desktop CI — Headless Tests & Build / Compose Desktop — Tests (headless) & Build (push) Failing after 3m10s
Details
Build and Publish Docker Images / build-and-push (., backend/infrastructure/gateway/Dockerfile, api-gateway, api-gateway) (push) Successful in 6m37s
Details
Build and Publish Docker Images / build-and-push (., backend/services/ping/Dockerfile, ping-service, ping-service) (push) Successful in 5m59s
Details
Build and Publish Docker Images / build-and-push (., config/docker/keycloak/Dockerfile, keycloak, keycloak) (push) Has been cancelled
Details
Build and Publish Docker Images / build-and-push (., config/docker/caddy/web-app/Dockerfile, web-app, web-app) (push) Has been cancelled
Details
feat(desktop-onboarding): neue Onboarding-UI implementiert, Backup- und Rollenmanagement hinzugefügt 
- Einbindung eines komplett überarbeiteten Onboarding-Screens mit validierten Eingaben für Gerätename, Sicherheitsschlüssel und Backup-Pfad.
- `SettingsManager` eingeführt zur Speicherung der Onboarding-Daten in `settings.json`.
- Navigation verbessert: Onboarding-Workflow startet, wenn Konfiguration fehlt; neues "Setup"-Icon in der Navigationsleiste hinzugefügt.
- Backend: Geräte-API und `DeviceSecurityFilter` für Authentifizierung per Sicherheitsschlüssel implementiert.

Signed-off-by: Stefan Mogeritsch <stefan.mo.co@gmail.com>
2026-04-15 15:49:01 +02:00

2.2 KiB
Raw Blame History

Onboarding-Backend & Desktop-Identität

Dieses Dokument beschreibt die Backend-Infrastruktur für die Identifizierung und Authentifizierung von Desktop-Clients ("Meldestelle-Biest").

🚀 Übersicht

Im Gegensatz zur Web-App (die via Keycloak/JWT authentifiziert) nutzen die Desktop-Instanzen für die Offline-Synchronisation eine Identität, die während des Onboarding-Prozesses lokal vergeben und am Server registriert wird.

🛡️ Authentifizierungs-Mechanismus

Die Authentifizierung erfolgt über zwei HTTP-Header, die bei jedem Request vom Desktop-Client mitgesendet werden müssen:

Header Beschreibung Beispiel
X-Device-Name Der beim Onboarding vergebene Gerätename Meldestelle-PC-1
X-Security-Key Der beim Onboarding vergebene Sicherheitsschlüssel secret-key-123

DeviceSecurityFilter

Ein Custom-Security-Filter (DeviceSecurityFilter) im Backend extrahiert diese Header und setzt einen Spring Security Kontext mit der Authority ROLE_DEVICE.

🛰️ API-Endpunkte (Identity Service)

1. Gerät registrieren

Wird beim Abschluss des Onboarding-Screens aufgerufen.

  • URL: POST /api/v1/devices/register
  • Body:
{
  "name": "Meldestelle-PC-1",
  "securityKeyHash": "...",
  "role": "MASTER"
}
  • Hinweis: Dieser Endpunkt ist permitAll(), um die Erstregistrierung zu ermöglichen.

2. Gerät abrufen

  • URL: GET /api/v1/devices/{name}
  • Auth: Erfordert ROLE_DEVICE oder JWT.

💾 Datenmodell (Exposed)

Die Tabelle identity_devices speichert die registrierten Instanzen:

  • id: Eindeutige UUID.
  • name: Gerätename (eindeutig).
  • security_key_hash: Der Sicherheitsschlüssel (gehasht).
  • role: MASTER oder CLIENT.
  • last_sync_at: Zeitstempel der letzten erfolgreichen Synchronisation.

🛠️ Local Test-Setup

Für lokale Tests mit curl:

curl -X GET http://localhost:8081/api/v1/devices/Meldestelle-PC-1 \
     -H "X-Device-Name: Meldestelle-PC-1" \
     -H "X-Security-Key: secret-key-123"