Add NTFS share provisioning concept

Sonstiges/LIAM_NTFS_Share_Provisionierung_und_ADGruppen_Konzept.md

@@ -0,0 +1,493 @@
+# LIAM NTFS Share-Provisionierung und AD-Gruppen - Konzept
+
+## Ziel
+
+Dieses Dokument beschreibt ein Zielkonzept, um neue Benutzer analog zum bestehenden NTFS-Ordnerprinzip auch fuer Shares ueber AD-Gruppen zu berechtigen.
+
+Betrachtet werden zwei Faelle:
+
+1. komplette Neuanlage eines Shares
+2. Erzeugung und Konfiguration passender AD-Gruppen fuer einen bereits bestehenden Share
+
+Das Dokument ist bewusst ein Konzept. Es beschreibt Zielbild, notwendige Schritte, technische Erweiterungen und offene Entscheidungen, aber keine direkte Implementierung.
+
+## Ausgangslage im aktuellen Stand
+
+Der aktuelle NTFS-Pfad deckt heute nur einen Teil des benoetigten Verhaltens ab:
+
+- `CreateDataAreaAsync(...)` erzeugt nur Verzeichnisse und NTFS-ACLs fuer einen Ordnerpfad.
+- `EnsureMissingPermissionGroupsAsync(...)` stellt fehlende AD-Gruppen und NTFS-ACLs fuer einen bestehenden Ordnerpfad sicher.
+- `cLiamNtfsShare` existiert als DataArea-Typ, aber es gibt keinen eigenen Schreibpfad fuer die Share-Neuanlage.
+- Die aktuelle Berechtigungslogik arbeitet technisch auf Dateisystempfaden und NTFS-ACLs.
+- Eine echte SMB-Share-Erzeugung oder Pflege von Share-Berechtigungen ist derzeit nicht vorhanden.
+
+Wichtig ist daher:
+
+- Das bestehende Prinzip fuer Ordner kann teilweise wiederverwendet werden.
+- Fuer Shares reicht eine reine Wiederverwendung des Ordnerpfads nicht aus.
+- Es braucht zusaetzlich einen eigenen Share-Provisionierungspfad.
+
+## Fachliche Grundentscheidung
+
+Bevor implementiert wird, sollte fachlich festgelegt werden, was "Share berechtigen" in LIAM genau bedeutet.
+
+Es gibt zwei moegliche Zielbilder:
+
+1. nur NTFS-Berechtigungen auf dem Share-Root-Ordner pflegen
+2. NTFS-Berechtigungen auf dem Share-Root-Ordner und zusaetzlich echte SMB-Share-Berechtigungen pflegen
+
+Empfehlung:
+
+- Fuer ein wirklich analoges Share-Prinzip sollten beide Ebenen gepflegt werden.
+- Nur NTFS zu pflegen waere technisch einfacher, bildet aber Share-Berechtigungen nur unvollstaendig ab.
+
+Das Konzept unten geht deshalb vom vollstaendigen Zielbild aus:
+
+- AD-Gruppen erzeugen oder wiederverwenden
+- NTFS-ACL auf dem Share-Root sicherstellen
+- SMB-Share anlegen oder aktualisieren
+- SMB-Share-Berechtigungen auf dieselben Gruppen ausrichten
+
+## Zielbild Architektur
+
+Empfohlen ist eine Trennung in zwei technische Ebenen:
+
+1. Dateisystem-/AD-Ebene
+2. Share-Ebene
+
+Die Dateisystem-/AD-Ebene kann weitgehend auf dem bestehenden `DataArea_FileSystem`-Prinzip aufbauen.
+
+Die Share-Ebene ist neu und sollte separat gekapselt werden, zum Beispiel als eigener Share-Provisionierer oder als Erweiterung von `cNetworkConnection`.
+
+Grund:
+
+- Share-Erzeugung und Share-Berechtigungen sind fachlich nicht dasselbe wie NTFS-ACLs.
+- Sie brauchen andere API-Aufrufe, andere Fehlerbehandlung und andere Validierungen.
+
+## Fall 1: komplette Neuanlage eines Shares
+
+### Ziel
+
+Ein neuer Share soll vollstaendig bereitgestellt werden:
+
+- physischer Zielordner vorhanden
+- AD-Gruppen vorhanden
+- Benutzer und Gruppenmitgliedschaften gesetzt
+- NTFS-ACLs auf dem Root-Ordner gesetzt
+- SMB-Share publiziert
+- SMB-Share-Berechtigungen gesetzt
+- Ergebnis als LIAM-DataArea nutzbar
+
+### Zusaetzliche Eingaben
+
+Fuer einen echten Share-Create reichen die bisherigen Ordnerparameter nicht aus. Noetig sind zusaetzlich mindestens:
+
+- `ServerName`
+- `ShareName`
+- `ShareLocalPath` oder ein technisch gleichwertiger physischer Zielpfad auf dem Server
+- optional `ShareDescription`
+- optional Share-spezifische CustomTags
+- Owner-/Read-/Write-SIDs analog zum bestehenden Ordnerpfad
+
+Optional sinnvoll:
+
+- gewuenschtes Caching-Verhalten des Shares
+- Offline-Availability
+- ABE oder weitere Share-Optionen
+- explizite Strategie fuer Share-Permissions
+
+### Warum ein eigener Input noetig ist
+
+Der heutige Ordner-Create-Pfad arbeitet auf einem existierenden UNC-/Dateisystempfad. Bei einem neuen Share existiert der veroeffentlichte UNC-Pfad aber noch nicht.
+
+Deshalb muss die Share-Neuanlage mit einem physischen Serverpfad arbeiten und darf nicht nur von einem spaeteren UNC-Share-Namen ausgehen.
+
+### Ablauf
+
+#### Schritt 1: Eingaben und Zielkonflikte validieren
+
+Vor der eigentlichen Anlage muessen folgende Punkte geprueft werden:
+
+- ist der Server erreichbar
+- ist der physische Zielpfad zulaessig
+- existiert der physische Zielordner bereits
+- existiert bereits ein Share mit demselben Namen
+- ist der Share-Name nach Windows-Regeln gueltig
+- ist die Ziel-OU fuer AD-Gruppen erreichbar
+- sind die benoetigten Naming-Conventions und Tags vollstaendig
+
+Abbruchkriterien:
+
+- doppelter Share-Name
+- ungueltiger Server- oder Zielpfad
+- fehlende Berechtigungen fuer Dateisystem, AD oder Share-Verwaltung
+
+#### Schritt 2: Physisches Zielverzeichnis bereitstellen
+
+Falls der Root-Ordner noch nicht existiert, muss er zuerst erstellt werden.
+
+Wichtig:
+
+- Das darf nicht ueber den spaeteren Share-UNC-Pfad geschehen.
+- Es braucht einen Zugriff auf den physischen Serverpfad.
+
+Technische Moeglichkeiten:
+
+- Zugriff ueber administrative Shares wie `\\server\\D$\\...`
+- serverseitige API oder PowerShell-Remoting
+- anderer dedizierter Remote-Mechanismus
+
+Empfehlung:
+
+- Die Share-Provisionierung sollte den physischen Serverpfad explizit kennen.
+- Die spaetere DataArea sollte daraus den veroeffentlichten UNC-Pfad ableiten.
+
+#### Schritt 3: Soll-Gruppen fuer den Share berechnen
+
+Fachlich analog zu Ordnern werden die erwarteten Gruppen berechnet:
+
+- Owner
+- Write
+- Read
+- optional Traverse, falls fuer Share-Roots gewuenscht
+- bei AGDLP zusaetzlich Domain-Local-Gruppen
+
+Hier sollte dieselbe Template- und Tag-Logik wie bei Ordnern wiederverwendet werden.
+
+Wichtig ist aber die Namensbasis:
+
+- Bei einem Share sollte die Namensbildung stabil am Share-Root ausgerichtet sein.
+- Die Namensbasis darf nicht davon abhaengen, ob spaeter unterhalb des Shares weitere Ordner existieren.
+
+Empfehlung:
+
+- zusaetzliche Platzhalter wie `SHARENAME`, `SHAREPATH`, `SHARESERVER`
+- klare Regel, ob die bestehende Ordner-Relative-Path-Logik unveraendert ausreicht oder erweitert werden muss
+
+#### Schritt 4: AD-Gruppen erzeugen oder wiederverwenden
+
+Der bestehende Ensure-Ansatz kann weitgehend uebernommen werden:
+
+- exakten Gruppennamen pruefen
+- bei nicht-striktem Modus vorhandene passende Gruppen ueber ACL-/Wildcard-Logik wiederverwenden
+- fehlende Gruppen anlegen
+- Benutzer und verschachtelte Gruppen setzen
+
+Fuer Share-Create gilt fachlich dieselbe Reihenfolge wie bei Ordnern:
+
+1. alle benoetigten Gruppen aufloesen oder erzeugen
+2. Mitgliedschaften setzen
+3. SIDs und DNs final einlesen
+
+#### Schritt 5: NTFS-ACL auf dem Share-Root setzen
+
+Auf dem physischen Root-Ordner werden die passenden NTFS-Berechtigungen gesetzt.
+
+Empfohlen:
+
+- dieselbe Rechteabbildung wie bei Ordnern
+- dieselbe Logik fuer AGP oder AGDLP
+- explizite ACL-Pruefung vor dem Schreiben
+- Ergebnis mit `addedAclEntries` und `skippedAclEntries` differenziert zurueckgeben
+
+#### Schritt 6: SMB-Share veroeffentlichen
+
+Nach erfolgreicher Dateisystem- und Gruppenanlage wird der Share selbst angelegt.
+
+Dafuer wird eine neue technische Faehigkeit benoetigt, zum Beispiel:
+
+- `CreateShare(server, shareName, localPath, description, ...)`
+
+Technisch denkbar:
+
+- Win32 `NetShareAdd`
+- PowerShell `New-SmbShare`
+- WMI/CIM
+
+Empfehlung:
+
+- moeglichst eine native, klar kapselbare Server-API nutzen
+- Fehlercodes aus der Share-Anlage explizit in `ResultToken` uebernehmen
+
+#### Schritt 7: SMB-Share-Berechtigungen setzen
+
+Nach der Share-Erzeugung muessen die Share-Berechtigungen mit den erzeugten oder wiederverwendeten AD-Gruppen synchronisiert werden.
+
+Empfohlene fachliche Abbildung:
+
+- Owner-Gruppe: Full Control oder ein explizit definierter administrativer Satz
+- Write-Gruppe: Change
+- Read-Gruppe: Read
+
+Wichtig:
+
+- Share-Rechte sind fachlich nicht identisch zu NTFS-Rechten.
+- Die Mapping-Regeln muessen explizit definiert werden.
+
+#### Schritt 8: Read-back und Rueckgabe
+
+Am Ende sollte der neu angelegte Share nochmals eingelesen werden:
+
+- existiert der Share wirklich
+- zeigt er auf den erwarteten Zielpfad
+- stimmen NTFS-ACL und Share-Permissions
+- stimmen aufgeloeste AD-Gruppen
+
+Das Ergebnis sollte danach als `NtfsShare` inklusive Gruppenreferenzen zurueckgegeben werden.
+
+## Fall 2: bestehender Share, aber fehlende AD-Gruppen
+
+### Ziel
+
+Fuer einen bereits publizierten Share sollen fehlende Gruppen und Berechtigungen analog zum bestehenden Ordner-Ensure-Pfad nachgezogen werden.
+
+### Unterschied zum heutigen Ordner-Ensure
+
+Der heutige `EnsureMissingPermissionGroupsAsync(...)` kann technisch gegen einen vorhandenen Root-Ordner laufen. Das reicht fuer Shares aber nur teilweise:
+
+- NTFS-ACL am Share-Root kann damit sichergestellt werden
+- die SMB-Share-Konfiguration selbst wird damit nicht gepflegt
+- bestehende Share-Berechtigungen werden damit nicht ausgelesen oder korrigiert
+
+Deshalb braucht es fuer Shares einen eigenen Ensure-Pfad.
+
+### Eingaben
+
+Mindestens benoetigt werden:
+
+- `SharePath` als veroeffentlichter UNC-Pfad
+- alternativ `ServerName + ShareName`
+- optional physischer Zielpfad, falls nicht sicher auslesbar
+- Owner-/Read-/Write-SIDs
+- optionale CustomTags
+
+### Ablauf
+
+#### Schritt 1: Share aufloesen und klassifizieren
+
+Der bestehende Share muss zunaechst technisch aufgeloest werden:
+
+- existiert der Share
+- auf welchem Server liegt er
+- welcher physische Zielpfad ist hinterlegt
+- ist er ein klassischer Share oder ein DFS-Link
+
+Empfehlung:
+
+- Nur klassische Shares im ersten Schritt unterstuetzen.
+- DFS-Links spaeter separat betrachten, weil dort Share-Pfad und Zielpfad auseinanderlaufen koennen.
+
+#### Schritt 2: Ist-Zustand laden
+
+Fuer den bestehenden Share muessen drei Ist-Zustaende geladen werden:
+
+- vorhandene AD-Gruppen
+- vorhandene NTFS-ACL auf dem Root-Ordner
+- vorhandene SMB-Share-Berechtigungen
+
+Nur damit kann spaeter ein echtes Delta gebildet werden.
+
+#### Schritt 3: Soll-Gruppen berechnen
+
+Die Gruppen muessen fuer den Share auf dieselbe Weise berechnet werden wie bei der Neuanlage.
+
+Dabei sollte dieselbe Namensbasis verwendet werden wie im Create-Pfad, damit Create und Ensure fachlich konsistent bleiben.
+
+#### Schritt 4: Wiederverwendung oder Neuanlage von AD-Gruppen
+
+Analog zum bestehenden Prinzip:
+
+- exakten Namen pruefen
+- bei nicht-striktem Modus vorhandene passende Gruppen wiederverwenden
+- bei mehrdeutigen Treffern nicht still entscheiden
+- fehlende Gruppen neu erzeugen
+
+Empfehlung:
+
+- die bisherige `ForceStrictAdGroupNames`-Logik fuer Shares unveraendert wiederverwenden
+- Wiederverwendung gegen bestehende ACLs nur dann zulassen, wenn eindeutig und fachlich plausibel
+
+#### Schritt 5: NTFS-ACL sicherstellen
+
+Auf dem physischen Share-Root wird anschliessend die NTFS-ACL zum Sollzustand gebracht.
+
+Dabei sollte dieselbe Logik wie im Ordner-Ensure verwendet werden:
+
+- bereits vorhandene explizite Regel erkennen
+- fehlende Regel setzen
+- Ergebnismengen getrennt dokumentieren
+
+#### Schritt 6: SMB-Share-Berechtigungen sicherstellen
+
+Zusaetzlich muessen die Share-Berechtigungen ausgewertet und auf Soll gebracht werden.
+
+Dabei sind dieselben Gruppen wie fuer die NTFS-Seite zu verwenden, aber mit einem expliziten Mapping auf Share-Rechte.
+
+Empfehlung:
+
+- Read-Gruppe -> Read
+- Write-Gruppe -> Change
+- Owner-Gruppe -> Full Control
+
+Falls im Ist-Zustand breit vergebene Standardrechte vorhanden sind, muss fachlich entschieden werden:
+
+- beibehalten und nur ergaenzen
+- oder gezielt bereinigen und auf LIAM-Gruppen normieren
+
+#### Schritt 7: Ergebnis und Warnungen
+
+Der Ensure-Pfad fuer Shares sollte im Ergebnis klar trennen:
+
+- neu angelegte Gruppen
+- wiederverwendete Gruppen
+- hinzugefuegte NTFS-ACLs
+- uebersprungene NTFS-ACLs
+- hinzugefuegte Share-Berechtigungen
+- uebersprungene Share-Berechtigungen
+- Warnungen bei Mehrdeutigkeiten, Altlasten oder nicht bereinigten Fremdeintraegen
+
+## Notwendige technische Erweiterungen
+
+### 1. Workflow- und Runtime-Oberflaeche
+
+Empfohlen sind zusaetzliche dedizierte Aufrufe:
+
+- `CreateNtfsShareAsync(...)`
+- `EnsureNtfsSharePermissionGroupsAsync(...)`
+
+Die bestehenden Ordner-Methoden sollten nicht still auf Shares umgebogen werden, weil die benoetigten Inputs und Resultate fachlich anders sind.
+
+### 2. Provider-Ebene
+
+Im NTFS-Provider braucht es einen expliziten Share-Schreibpfad:
+
+- Eingaben validieren
+- physischen Zielpfad und publizierten Share koordinieren
+- AD-/NTFS-Engine aufrufen
+- Share-Erzeugung oder Share-Update ausfuehren
+
+### 3. Engine fuer Share-Operationen
+
+Empfohlen ist eine neue technische Komponente, zum Beispiel:
+
+- `ShareProvisioningEngine`
+- oder eine klar getrennte Erweiterung von `cNetworkConnection`
+
+Noetige Faehigkeiten:
+
+- `ShareExists`
+- `GetShareInfo`
+- `CreateShare`
+- `EnsureSharePermissions`
+- optional `RemoveSharePermission`
+
+### 4. ResultToken erweitern
+
+Fuer Shares braucht es zusaetzliche Ergebnisfelder, zum Beispiel:
+
+- `createdShares`
+- `reusedShares`
+- `addedShareAclEntries`
+- `skippedShareAclEntries`
+- `shareWarnings`
+
+Alternativ kann ein eigener spezialisierter ResultToken fuer Share-Operationen eingefuehrt werden.
+
+### 5. Logging
+
+Fuer spaetere Betriebsdiagnose sollten diese Punkte explizit geloggt werden:
+
+- Server, Share-Name, physischer Zielpfad
+- exakter Create- oder Ensure-Modus
+- Quelle einer Gruppenwiederverwendung
+- Ergebnis der Share-Erzeugung
+- Ergebnis der Share-Permission-Sicherung
+- klare Trennung zwischen NTFS-ACL und Share-ACL
+
+## Wichtige offene Entscheidungen
+
+### 1. DFS-Unterstuetzung
+
+Fuer einen ersten belastbaren Schritt sollte sich die Implementierung auf klassische Shares konzentrieren.
+
+DFS-Links sind fachlich moeglich, aber deutlich komplexer:
+
+- publizierter Pfad und physischer Zielpfad koennen auseinanderfallen
+- Share- und DFS-Berechtigung sind nicht dasselbe
+- die Zielserver koennen wechseln
+
+Empfehlung:
+
+- Phase 1 nur klassische Shares
+- DFS spaeter bewusst als eigener Ausbau
+
+### 2. Share-Permissions als Pflicht oder Optional
+
+Wenn nur NTFS gesetzt wird, bleibt das Share-Modell unvollstaendig.
+
+Empfehlung:
+
+- Share-Permissions als Bestandteil des Zielbilds definieren
+- optional ueber Flag abschaltbar machen, aber nicht dauerhaft weglassen
+
+### 3. Namensbildung fuer Share-Roots
+
+Es muss eindeutig festgelegt werden, worauf sich die Gruppennamen eines Shares beziehen:
+
+- nur auf den Share-Namen
+- auf den physischen Root-Pfad
+- auf den publizierten UNC-Pfad
+
+Empfehlung:
+
+- Primaerschluessel fachlich am publizierten Share-Namen ausrichten
+- physische Pfadbestandteile nur zusaetzlich als Tags oder Beschreibung verwenden
+
+### 4. Altlasten bei bestehenden Shares
+
+Bei bestehenden Shares koennen bereits andere Gruppen oder breite Standardrechte existieren.
+
+Dafuer braucht es eine klare Strategie:
+
+- nur ergaenzen
+- normierend bereinigen
+- oder nur warnen
+
+Empfehlung:
+
+- im ersten Schritt nur ergaenzen und warnen
+- bereinigende Eingriffe erst in einem spaeteren expliziten Modus
+
+## Empfohlene Umsetzung in Phasen
+
+### Phase 1
+
+- dedizierter Ensure-Pfad fuer bestehende klassische Shares
+- AD-Gruppen sicherstellen
+- NTFS-ACL auf Share-Root sicherstellen
+- Share-Permissions lesen und setzen
+
+### Phase 2
+
+- vollstaendiger Create-Pfad fuer klassische Shares
+- physisches Root-Verzeichnis anlegen
+- Share publizieren
+- Share read-back und Ergebnisobjekt liefern
+
+### Phase 3
+
+- DFS-Sonderfaelle
+- bereinigender Modus fuer Altlasten
+- Massenverarbeitung fuer viele Shares
+
+## Kurzfazit
+
+Fuer Shares ist keine reine Kopie des bestehenden Ordnerpfads ausreichend.
+
+Noetig ist:
+
+- Wiederverwendung der vorhandenen AD-Gruppen- und NTFS-Logik
+- plus ein neuer Share-spezifischer Schreibpfad
+- plus eine klare fachliche Behandlung von SMB-Share-Berechtigungen
+
+Der sinnvollste erste Schritt ist ein eigener Ensure-Pfad fuer bestehende klassische Shares. Danach kann die vollstaendige Share-Neuanlage auf derselben Logik aufbauen.