Authentifizierung und Autorisierung¶

TCM365 verwendet JWT-basierte Authentifizierung mit Unterstützung für lokale Zugangsdaten und Azure AD Single Sign-On. Dieser Leitfaden behandelt den vollständigen Authentifizierungsablauf, die Rollen-Hierarchie, das Berechtigungssystem und die NestJS Guard-Architektur.

Authentifizierungsablauf¶

Lokale Authentifizierung¶

TCM365 unterstützt lokale E-Mail/Passwort-Authentifizierung als primäre Anmeldemethode.

Schritt 1: Token erhalten¶

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "admin@tcm.local",
  "password": "Admin123!TCM"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email": "admin@tcm.local",
    "name": "Admin",
    "role": "SUPER_ADMIN"
  }
}

Schritt 2: Token verwenden¶

JWT Token im Authorization-Header für alle nachfolgenden Requests angeben:

GET /api/v1/snapshots
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Schritt 3: Token erneuern¶

Vor Ablauf des Tokens (Standard: 30 Minuten) ein neues anfordern:

POST /api/v1/auth/refresh
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token-Ablauf

Access Tokens laufen nach APP_ACCESS_TOKEN_EXPIRE_MINUTES (Standard: 30 Minuten) ab. Tokens immer vor Ablauf erneuern um Unterbrechungen von Benutzersitzungen zu vermeiden.

Azure AD Single Sign-On¶

TCM365 unterstützt Azure AD-Authentifizierung via MSAL (Microsoft Authentication Library). Dies ermöglicht Organisationen, ihre bestehenden Azure AD-Identitaeten für SSO zu nutzen.

Voraussetzungen¶

Azure AD App Registration mit folgendem Redirect URI registrieren:
```
http://localhost:8000/api/v1/auth/callback
```

Umgebungsvariablen konfigurieren:

AZURE_AD_TENANT_ID="ihre-azure-ad-tenant-id"
AZURE_AD_CLIENT_ID="ihre-azure-ad-client-id"
AZURE_AD_CLIENT_SECRET="ihr-azure-ad-client-secret"
AZURE_AD_AUTHORITY="https://login.microsoftonline.com/{tenant-id}"
AZURE_AD_REDIRECT_URI="http://localhost:8000/api/v1/auth/callback"
AZURE_AD_SCOPES="https://graph.microsoft.com/.default"

Der Authentifizierungsablauf verwendet den OAuth 2.0 Authorization Code Grant:

User -> Frontend -> /api/v1/auth/azure/login -> Azure AD -> /api/v1/auth/callback -> JWT ausgestellt

Passwortänderung¶

Authentifizierte Benutzer können ihr Passwort ändern:

POST /api/v1/auth/change-password
Authorization: Bearer eyJhbGci...
Content-Type: application/json

{
  "currentPassword": "AltesPasswort123!",
  "newPassword": "NeuesSicheresPasswort456!"
}

Rollen-Hierarchie¶

TCM365 implementiert ein rollenbasiertes Zugriffskontrollsystem (RBAC) mit vier hierarchischen Rollen. Hoehere Rollen erben alle Berechtigungen niedrigerer Rollen.

Rolle	Level	Beschreibung
`SUPER_ADMIN`	100	Vollständiger Systemzugriff, Benutzerverwaltung, Systemeinstellungen
`TENANT_ADMIN`	75	Tenant-Verwaltung, Snapshot-Erstellung, Rollback-Ausführung
`WORKFLOW_MANAGER`	50	Workflow-Verwaltung, Blueprint-Operationen, Drift-Monitoring
`VIEWER`	25	Nur-Lese-Zugriff auf Dashboards, Snapshots und Berichte

SUPER_ADMIN (100)
    |
    +-- TENANT_ADMIN (75)
            |
            +-- WORKFLOW_MANAGER (50)
                    |
                    +-- VIEWER (25)

Rollenvererbung

Ein TENANT_ADMIN kann alle Aktionen ausführen, die WORKFLOW_MANAGER und VIEWER zur Verfügung stehen. Ein SUPER_ADMIN kann alle Aktionen im gesamten System ausführen.

Berechtigungssystem¶

Berechtigungsformat¶

Berechtigungen folgen der resource:action-Konvention:

{resource}:{action}

Verfügbare Ressourcen¶

Ressource	Beschreibung
`users`	Benutzerkontenverwaltung
`tenants`	Tenant-CRUD und Verbindungsverwaltung
`workflows`	Workflow-Erstellung und -Ausführung
`snapshots`	Snapshot-Erstellung, -Vergleich, -Löschung
`audit`	Audit-Log-Zugriff
`settings`	Systemeinstellungsverwaltung

Verfügbare Aktionen¶

Aktion	Beschreibung
`read`	Ressourcen anzeigen und auflisten
`write`	Ressourcen erstellen und aktualisieren
`delete`	Ressourcen entfernen
`connect`	Vendor-Verbindungen herstellen (Tenants)
`execute`	Workflows und Operationen ausführen
`rollback`	Konfigurations-Rollbacks ausführen

Berechtigungsbeispiele¶

Berechtigung	Wer benötigt sie	Zweck
`snapshots:read`	VIEWER und höher	Snapshot-Liste und -Details anzeigen
`snapshots:write`	TENANT_ADMIN und höher	Neue Snapshots erstellen
`snapshots:delete`	TENANT_ADMIN und höher	Snapshots löschen (inkl. Bulk)
`tenants:connect`	TENANT_ADMIN und höher	Neue Vendor Tenants registrieren
`workflows:execute`	WORKFLOW_MANAGER+	Automatisierte Workflows ausführen
`users:write`	Nur SUPER_ADMIN	Benutzerkonten erstellen und ändern
`settings:write`	Nur SUPER_ADMIN	Systemeinstellungen ändern

NestJS Guard-Architektur¶

TCM365 verwendet ein geschichtetes Guard-System implementiert als NestJS Guards und Dekoratoren.

Guards¶

Guard	Zweck
`JwtAuthGuard`	Validiert JWT Token und extrahiert Benutzer
`LocalAuthGuard`	Validiert E-Mail/Passwort für Login-Endpoint
`RolesGuard`	Prüft ob Benutzerrolle Mindestanforderung erfüllt
`PermissionsGuard`	Prüft ob Benutzer erforderliche resource:action Permissions hat

Dekoratoren¶

Dekorator	Zweck	Verwendungsbeispiel
`@CurrentUser()`	Injiziert die authentifizierte User-Entity	`@CurrentUser() user: User`
`@Roles()`	Deklariert Mindestrolle für einen Endpoint	`@Roles(UserRole.TENANT_ADMIN)`
`@Permissions()`	Deklariert erforderliche Permissions für einen Endpoint	`@Permissions('snapshots:write')`
`@Public()`	Markiert einen Endpoint als öffentlich zugänglich	`@Public()` (umgeht JwtAuthGuard)

Tenant-Isolierung¶

Über RBAC hinaus erzwingt TCM365 eine dreischichtige Tenant-Isolierung um mandantenuebergreifenden Datenzugriff zu verhindern:

Schicht 1: TenantAccessService (Anwendungsschicht)¶

Jeder Controller, der auf Tenant-scoped Daten zugreift, validiert, dass der anfragende Benutzer zur selben Organisation gehört wie der Ziel-Tenant. Unautorisierte Zugriffsversuche werden als TENANT_ACCESS_DENIED Audit Events protokolliert.

Schicht 2: PostgreSQL Row-Level Security (Datenbankschicht)¶

Die Datenbank erzwingt Row-Level Security Policies auf 18 Tenant-scoped Tabellen. Die Anwendung setzt app.current_org_id bei jeder Datenbankverbindung, und PostgreSQL filtert automatisch Zeilen auf den aktuellen Tenant.

Schicht 3: Per-Tenant-Schemas (Schema-Isolierung)¶

Data-Plane-Tabellen (Snapshots, Workflows, Drifts, Monitors und 19 weitere) werden in Per-Tenant PostgreSQL-Schemas (tenant_{uuid}) gespeichert. Jeder Request routet Queries zum korrekten Schema basierend auf der Organisation des authentifizierten Benutzers.

IDOR-Prävention

Der TenantAccessService-Wrapper ist für alle Controller, die auf Tenant-scoped Ressourcen zugreifen, obligatorisch. Direkter Repository-Zugriff ohne Tenant-Validierung ist eine Sicherheitsverletzung.

Token-Konfiguration¶

Umgebungsvariable	Standard	Beschreibung
`APP_SECRET_KEY`	--	JWT Signing Secret (min. 32 Zeichen)
`APP_ACCESS_TOKEN_EXPIRE_MINUTES`	30	Token-Ablauf in Minuten

Produktionssicherheit

Immer ein starkes, einzigartiges APP_SECRET_KEY in Produktion setzen. Der Standard-Entwicklungsschluessel darf niemals in Produktionsumgebungen verwendet werden.

Standard-Entwicklungszugangsdaten¶

Für lokale Entwicklung erstellt der Database Seeder ein Standard-Admin-Konto:

Feld	Wert
E-Mail	`admin@tcm.local`
Passwort	`Admin123!TCM`
Rolle	`SUPER_ADMIN`

Diese Zugangsdaten werden durch Ausführen von npm run db:seed oder dem automatisierten Setup-Skript erstellt.