# 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.
