Stand: 2026-03-05

Übergeordnet: Auth-Architektur — Gesamtübersicht Verwandt: 2. WvdS.Shell | 4. Datenschicht | 5. Migration

Das Gateway.Service existierte bereits als HTTP-REST-Gateway mit einer vollständigen Middleware-Pipeline — Logging, Rate-Limiting, HTTPS-Enforcement, Routing. Was fehlte, war ein vollständiges Auth-Subsystem für interaktive Benutzer. Die vorhandenen Modi (Basic, ApiKey) waren für Dienst-zu-Dienst-Kommunikation ausgelegt, nicht für Session-Management mit Token-Lifecycle und Mehrfaktor-Authentifizierung.

Ein Gateway ohne vollständiges Auth-Subsystem bedeutet: Entweder werden Credentials bei jedem Request übertragen — ein fundamentales Sicherheitsproblem — oder der Client muss selbst den Zustand verwalten, was die Architektur unnötig verkompliziert. JWT-Tokens lösen das: Ein einmaliger Auth-Vorgang erzeugt ein kurzlebiges Access Token und ein langlebiges Refresh Token. Alle nachfolgenden Requests sind stateless und tragen nur den signierten Token — kein Passwort, kein serverseitiger Session-State.

Die Wahl von ML-DSA-65 für die JWT-Signierung ist dabei keine akademische Entscheidung. Klassische Signaturverfahren (RSA, ECDSA) könnten durch Quantencomputer kompromittiert werden. Mit ML-DSA-65 als post-quanten-sicherem Verfahren bleibt die Plattform auch dann vertrauenswürdig, wenn klassische Kryptografie in absehbarer Zeit nicht mehr ausreicht — ohne dass bestehende Token-Strukturen nachträglich geändert werden müssten.

Gateway.Service hat eine vollständige Middleware-Pipeline und ein Auth-Enum mit allen benötigten Modi — jedoch ist nur ein Teil davon implementiert.

Für die Shell-Integration müssen folgende Komponenten neu implementiert werden:

1. PFX Install-ID Validierung (amCertificate)
2. Kerberos/SSPI Handler (amWindows)
3. JWT Ausstellung und Validierung (amBearer)
4. TOTP Service (neu — für externen MFA-Flow)
5. Refresh Token Management (neu)
6. Feature-Flags Endpoint (neu — ENIVERSASYS-Anbindung)

Alle neuen Auth-Endpoints unter /api/v1/auth/. Ein neuer Controller WvdS.Data.Gateway.Controller.Auth wird benötigt.

Kerberos Negotiate-Handshake (mehrstufig, wie HTTP Negotiate definiert):

Request:
  POST /api/v1/auth/kerberos
  Authorization: Negotiate <Base64-SPNEGO-Token>
  X-WvdS-Install-Id: ENIVERS-2026-001

Response (ggf. mehrstufig):
  HTTP 401  Authorization: Negotiate <Base64-Challenge>   ← Server-Challenge
  HTTP 200  { "access_token": "...", "refresh_token": "...", "expires_in": 900 }

Erster Schritt des externen MFA-Flows. Gibt bei gültigem Username/Passwort eine challenge_id zurück — noch kein Token.

Request:
  { "username": "max.muster", "password": "...", "install_id": "ENIVERS-2026-001" }
 
Response 200:
  { "mfa_required": true, "challenge_id": "c7f3a..." }
 
Response 401:
  { "error": "invalid_credentials" }

Passwort wird nach Validierung sofort via FillChar zeroiert (CWE-316).

Zweiter Schritt des externen MFA-Flows. Löst die challenge_id gegen den TOTP-Code ein und gibt bei Erfolg die Token-Pair aus.

Request:
  { "challenge_id": "c7f3a...", "code": "482910" }
 
Response 200:
  { "access_token": "...", "refresh_token": "...", "expires_in": 900 }
 
Response 401:
  { "error": "invalid_code", "attempts_remaining": 2 }

Silent Token Refresh. Refresh-Token wird im Request-Body oder als Authorization: Refresh <token> übergeben.

Request:
  { "refresh_token": "..." }
 
Response 200:
  { "access_token": "...", "expires_in": 900 }
 
Response 401:
  { "error": "refresh_token_expired" }

Lädt die Feature-Flags für den authentifizierten User/die Installation. Liest aktuell aus ENIVERSCAFM (auth.*-Namespace), zukünftig aus ENIVERSASYS.

Response 200:
  { "features": ["grids", "charts", "scheduling", "docking"] }

JWT wird mit ML-DSA-65 signiert — die Bibliothek ist im Gateway bereits vorhanden (WvdS.Security.Cryptography). Kein externer Abhängigkeitsbedarf.

Standard-Header: jwt

{
  "sub":        "max.muster@corp.example.com",
  "install_id": "ENIVERS-2026-001",
  "auth_method": "windows",
  "mfa":        false,
  "iat":        1741132800,
  "exp":        1741133700,
  "jti":        "a3f9..."
}

Feature-Flags werden nicht im JWT mitgeführt — sie werden bei Bedarf frisch vom /api/v1/features-Endpoint geladen. Grund: Flags können sich ändern ohne dass ein neues Token ausgestellt werden muss.

TWvdSGatewayAuthHandler wird erweitert: Bei amBearer wird der JWT-Header extrahiert, ML-DSA-Signatur geprüft, exp-Claim validiert und install_id gegen die PFX-Registrierung abgeglichen.

Die gesamte TOTP-Logik liegt im Gateway — die Shell liefert nur den Code (6 Ziffern). Details: 2. Shell-Doku: TOTP Aufgabenteilung.

Algorithmus: HMAC-SHA1 (RFC 6238) über OpenSSL (WvdS.Security.Cryptography) — kein neuer Crypto-Code nötig.

Shared Secret Speicherung:

• Pro User ein Base32-kodiertes Secret
• Gespeichert AES-256-GCM-verschlüsselt in der Gateway-Datenbank (CWE-256)
• Kein Plaintext auf Disk

Validierungsfenster: ±1 Zeitfenster (30 s × 3 = 90 s Toleranz für Uhrabweichung)

Lockout-Policy: Bestehender FailedAuthPerMinute-Alert-Counter wird genutzt. Nach 5 Fehlversuchen: Challenge ungültig, neuer POST /api/v1/auth/external nötig.

Challenge-Lifetime: 5 Minuten. Challenges in Gateway-RAM (TDictionary<String, TChallengeEntry>), kein DB-Roundtrip.

Admin-seitig:
  GET /api/v1/auth/totp/enroll   (JWT des Admin-Users)
  → { "otpauth_uri": "otpauth://totp/...", "qr_base64": "..." }
  → Admin zeigt QR dem User (oder schickt URI per E-Mail)

Self-Service (Shell öffnet WebView):
  Shell navigiert zu: https://gateway/auth/enroll?token=<JWT>
  → Gateway zeigt HTML-Seite mit QR-Code
  → User scannt mit MS Authenticator
  → Enrollment-Bestätigung (User gibt ersten Code ein zum Verifizieren)

Das Gateway prüft bei jedem Auth-Request ob die install_id aus dem PFX registriert und aktiv ist.

X-WvdS-Install-Id: ENIVERS-2026-001

Dieser Header wird von der Shell bei jedem Request mitgesendet — nicht nur beim Auth-Request.

  1. X-WvdS-Install-Id Header vorhanden?
  2. install_id in Deployment-Tabelle (DB) vorhanden und aktiv?
  3. Zugehöriges Ablaufdatum noch nicht überschritten?
  4. → Validierung OK: weiter mit Auth-Flow
  5. → Validierung FAIL: HTTP 403 "unlicensed installation"

Eine neue Tabelle (z. B. WVDS_DEPLOYMENTS) in der Gateway-Datenbank speichert:

Wenn Gateway als Windows Service läuft (nicht hinter IIS/NGINX):

• AcceptSecurityContext aus Secur32.dll (Windows SSPI API)
• HTTP Authorization: Negotiate Header — mehrstufiger Handshake
• Nach Erfolg: Identität via QueryContextAttributes(SECPKG_ATTR_NAMES) lesen
• → JWT für diese Identität ausstellen

IIS übernimmt Windows Auth vollständig:

• IIS sendet LOGON_USER als CGI-Umgebungsvariable
• Gateway-FastCGI-Adapter (WvdS.Data.Gateway.FastCGI.Adapter) liest LOGON_USER
• Kein AcceptSecurityContext im Gateway nötig — IIS hat bereits validiert
• Direkt JWT ausstellen

Empfehlung: FastCGI hinter IIS für Corpnet-Deployments.
Standalone SSPI für Self-hosted Szenarien (kleinere Installationen).

1. TWvdSMetricsMiddleware
2. TWvdSLoggingMiddleware
3. TWvdSHttpsEnforcementMiddleware
4. TWvdSRequestSizeMiddleware
5. TWvdSRateLimitMiddleware
6. TWvdSGatewayAuthHandler          ← Erweiterung: amBearer + amWindows
7. TWvdSPayloadEncryptionMiddleware
8. TWvdSCompressionMiddleware
9. MapControllers

TWvdSInstallIdMiddleware greift vor der eigentlichen Auth — ein Request ohne gültige Install-ID wird mit HTTP 403 abgelehnt, bevor Credentials geprüft werden.

src/
  controllers/
    WvdS.Data.Gateway.Controller.Auth.pas       ← /api/v1/auth/*, /api/v1/features
  core/
    WvdS.Data.Gateway.Auth.JwtService.pas       ← JWT Ausstellung (ML-DSA-65), Validierung
    WvdS.Data.Gateway.Auth.TotpService.pas      ← Shared Secret, Challenge, HMAC-SHA1 (OpenSSL)
    WvdS.Data.Gateway.Auth.KerberosHandler.pas  ← SSPI AcceptSecurityContext (Windows-only)
    WvdS.Data.Gateway.Auth.CertValidator.pas    ← Install-ID gegen DB prüfen
    WvdS.Data.Gateway.Auth.RefreshStore.pas     ← Refresh Token (gehashed, DB-backed)
  middleware/
    WvdS.Data.Gateway.Middleware.InstallId.pas  ← X-WvdS-Install-Id Middleware

Alle neuen Units im src/core/ und src/middleware/ — passend zur bestehenden Schichtenstruktur.

Zusätzlich zu den bestehenden 22 CWEs kommen durch die Auth-Erweiterung: