From a551096eed7f5b3cd6b9db5cc3896050a462cd95 Mon Sep 17 00:00:00 2001
From: Thomas Stallinger <stallinger@gmx.de>
Date: Tue, 14 Jul 2026 12:56:30 +0200
Subject: [PATCH] docs: define device enrollment model

---
 architecture/11-device-enrollment.md | 186 +++++++++++++++++++++++++++
 1 file changed, 186 insertions(+)
 create mode 100644 architecture/11-device-enrollment.md

diff --git a/architecture/11-device-enrollment.md b/architecture/11-device-enrollment.md
new file mode 100644
index 0000000..8cf0d86
--- /dev/null
+++ b/architecture/11-device-enrollment.md
@@ -0,0 +1,186 @@
+# Device Enrollment
+
+**Status:** Entwurf
+
+## Zweck
+
+Dieses Dokument beschreibt die Aufnahme eines Geräts in eine Tuxflotte-Organisation.
+
+Device Enrollment ist von der Authentifizierung eines Benutzers zu unterscheiden.
+
+Die Authentifizierung beantwortet die Frage:
+
+> Wer führt den Provisionierungsvorgang aus?
+
+Das Device Enrollment beantwortet die Frage:
+
+> Darf dieses Gerät einer Organisation hinzugefügt und im Rahmen ihres Gerätekontingents provisioniert werden?
+
+## Zielmodell
+
+Der reguläre Provisionierungsablauf verwendet keine gerätespezifischen Aktivierungscodes.
+
+Eine Organisation besitzt ein Gerätekontingent.
+
+Ein neues Gerät kann nach erfolgreicher Autorisierung einer Organisation hinzugefügt werden, wenn das verfügbare Gerätekontingent dies erlaubt.
+
+Der grundlegende Ablauf ist:
+
+```text
+Authentifizierung oder Enrollment-Autorisierung
+  ↓
+Organisation bestimmen
+  ↓
+Gerät anhand des Hardware-Fingerprints erkennen
+  ↓
+Gerät bekannt?
+  ├── ja
+  │    ↓
+  │  bestehendes Device verwenden
+  │    ↓
+  │  Reprovisionierung ermöglichen
+  │
+  └── nein
+       ↓
+     Gerätekontingent prüfen
+       ↓
+     Aufnahme des Geräts explizit bestätigen
+       ↓
+     neues Device registrieren
+```
+
+## Gerätekontingent
+
+Eine Organisation kann nur die Anzahl neuer Geräte registrieren, die ihr aktuelles Gerätekontingent erlaubt.
+
+Ein neues Device belegt einen Geräteslot.
+
+Die erneute Provisionierung eines bereits registrierten Devices belegt keinen zusätzlichen Geräteslot.
+
+Die Wiedererkennung eines bestehenden Devices erfolgt über den Hardware-Fingerprint.
+
+Die interne Device-ID bleibt unabhängig von Hardwaremerkmalen.
+
+## Interaktive Geräteaufnahme
+
+Für die Provisionierung einzelner Geräte authentifiziert sich ein berechtigter Benutzer.
+
+Nach erfolgreicher Authentifizierung zeigt Tuxflotte die erkannte Organisation und den Status des Geräts an.
+
+Bei einem unbekannten Gerät zeigt der Installer eine Zusammenfassung der erfassten Hardwareinformationen und das verfügbare Gerätekontingent an.
+
+Die Aufnahme des Geräts in die Organisation muss explizit bestätigt werden.
+
+Beispiel:
+
+```text
+Organisation: Muster GmbH
+
+Neues Gerät erkannt
+
+Hersteller: Lenovo
+Modell: ThinkPad T14
+CPU: AMD Ryzen 7 PRO
+RAM: 32 GB
+Speicher: 953 GB
+
+Verfügbares Gerätekontingent: 13
+
+Dieses Gerät zur Organisation „Muster GmbH“ hinzufügen?
+[j/N]
+```
+
+Die erfolgreiche Authentifizierung eines Benutzers allein registriert kein neues Gerät.
+
+## Bekannte Geräte
+
+Wird ein bereits registriertes Device anhand seines Hardware-Fingerprints wiedererkannt, verwendet Tuxflotte die bestehende Device-ID.
+
+Es wird kein zusätzlicher Geräteslot belegt.
+
+Der Installer kann dem Benutzer eine Reprovisionierung des bestehenden Geräts anbieten.
+
+Beispiel:
+
+```text
+Bekanntes Gerät erkannt
+
+Gerät: enterprise
+Organisation: Muster GmbH
+
+Gerät erneut provisionieren?
+[j/N]
+```
+
+## Enrollment Sessions
+
+Für Massenrollouts und Werkstattumgebungen kann eine Organisation zeitlich begrenzte Enrollment Sessions erstellen.
+
+Eine Enrollment Session kann insbesondere auf folgende Eigenschaften begrenzt werden:
+
+- Organisation,
+- Gültigkeitszeitraum,
+- maximale Anzahl neuer Geräte,
+- erlaubte Provisioning-Profile.
+
+Eine Enrollment Session ist widerrufbar und auditierbar.
+
+Beispiel:
+
+```text
+Provisioning Session
+
+Organisation: Muster GmbH
+Maximale neue Geräte: 50
+Gültigkeit: 8 Stunden
+
+Erlaubte Profile:
+- Fedora Workstation
+- Linux Mint Desktop
+```
+
+Der Installer kann neben der interaktiven Benutzeranmeldung die Verwendung einer Enrollment Session anbieten.
+
+```text
+Provisionierung starten
+
+1) Mit Benutzerkonto anmelden
+2) Enrollment Session verwenden
+```
+
+Enrollment Sessions dienen der effizienten Provisionierung größerer Gerätemengen, ohne an jedem Gerät vollständige Benutzeranmeldedaten und zusätzliche Authentifizierungsfaktoren eingeben zu müssen.
+
+## Abgrenzung zu Aktivierungscodes
+
+Der bisher verwendete Aktivierungscode ist ein Bootstrap-Mechanismus zum Aufbau und Nachweis des Provisioning-Handshakes.
+
+Er ist nicht Bestandteil des langfristigen Customer-UX-Modells.
+
+Insbesondere werden keine gerätespezifischen Aktivierungscodes als regulärer Provisionierungsmechanismus vorgesehen.
+
+Das Zielmodell trennt:
+
+```text
+Authentifizierung
+→ Wer führt den Vorgang aus?
+
+Enrollment-Autorisierung
+→ Darf ein Gerät aufgenommen werden?
+
+Gerätekontingent
+→ Ist ein weiterer Geräteslot verfügbar?
+
+Hardware-Fingerprint
+→ Ist das Gerät bereits bekannt?
+```
+
+Der bestehende Aktivierungscode wird schrittweise durch dieses Enrollment-Modell ersetzt.
+
+## Sicherheitsprinzip
+
+Weder eine erfolgreiche Authentifizierung noch die Kenntnis eines Hardware-Fingerprints allein berechtigt zur Registrierung eines neuen Devices.
+
+Die Aufnahme eines unbekannten Geräts erfordert eine gültige Enrollment-Autorisierung und ein verfügbares Gerätekontingent.
+
+Bei interaktiver Geräteaufnahme muss die Registrierung des neuen Devices explizit bestätigt werden.
+