RBAC Technical Deep Dive

RBAC Technical Deep Dive

Zugriffskontrolle in LIVOI

LIVOI kombiniert rollenbasierte Berechtigungen, Tenant-Kontext, ressourcenspezifische Zugriffsfilter und PostgreSQL Row-Level-Security. Jeder Request soll nur die Aktionen ausführen und nur die Daten sehen können, die im aktuellen Tenant-Kontext erlaubt sind.

Grundprinzip

Die API prüft Berechtigungen nah am Use Case. Die Datenbank erzwingt dieselbe Sicherheitsgrenze zusätzlich auf SQL-Ebene.

Route-Workflow im Überblick

Der Request durchläuft zuerst die Authentifizierung, danach Tenant-Auflösung, Mitgliedschaftsprüfung, Permission-Auflösung und schließlich den Route Handler. Frühe Abbrüche liefern kontrollierte Fehlercodes, bevor fachliche Verarbeitung startet.

Kurzfassung

• Nutzer erhalten Rollen direkt oder indirekt über Gruppen.
• Rollen enthalten konkrete Permission-Strings wie chats.read, files.update.own oder agents.delete.any.
• Der effektive Zugriff wird pro Tenant berechnet.
• API-Endpunkte deklarieren die erforderlichen Permissions.
• Service-Operationen prüfen bestehende Ressourcen mit zentralen Access-Filtern.
• Die Datenbank erhält den Auth-Kontext als Session-Variablen und erzwingt RLS zusätzlich auf SQL-Ebene.
• API-Keys können eigene Permissions haben, dürfen aber nicht über die effektiven Rechte ihres Besitzers hinausgehen.
• API-Keys ohne User-Bezug beziehen ihre Permissions ausschließlich aus dem API-Key selbst.
• Resource Grants geben einzelne Ressourcen gezielt an Nutzer, Gruppen, Rollen oder API-Keys frei.
• Resource Grants werden nicht in den gecachten Security Context eingerechnet, sondern beim konkreten Ressourcenzugriff geprüft.

Datenmodell

Das RBAC-Modell besteht aus fünf zentralen Ebenen. Sie bilden zusammen den organisatorischen Sicherheitsraum, die effektiven Rollen und gezielte Freigaben auf einzelne Ressourcen.

Tenant

Ein Tenant bildet den organisatorischen Sicherheitsraum. Rollen, Gruppen, Mitgliedschaften und die meisten fachlichen Ressourcen sind tenantgebunden.

User und Membership

Ein Nutzer kann Mitglied in einem oder mehreren Tenants sein. Nur aktive Mitgliedschaften zählen für den effektiven Security Context.

Groups

Gruppen bündeln Nutzer innerhalb eines Tenants. Rollen können Nutzern direkt oder über Gruppen zugewiesen werden.

Roles und Permissions

Rollen enthalten konkrete Permission-Strings. Standardrollen werden pro Tenant initialisiert.

Resource Grants

Resource Grants geben einzelne Ressourcen frei, ohne dafür eine globale Rolle zu erweitern.

Default Roles

Rolle	Zweck
owner	Vollzugriff auf Tenant-Ressourcen, Konfiguration und Zugriffskontrolle.
admin	Administrativer Zugriff, aber ohne Tenant-Löschung.
member	Standardzugriff auf gemeinsame Tenant-Struktur und eigene Ressourcen nach dem Least-Privilege-Prinzip.

Permission-Naming

Permissions werden aus Ressourcentyp, Aktion und optionalem Scope gebildet.

<resource>.<action>
<resource>.<action>.any
<resource>.<action>.own
<resource>.<action>.granted

Beispiele

chats.read

chats.read.any

files.update.own

roles.delete.any

Aktionen

create

read

update

delete

access_manage

Permission-Katalog

Welche Permissions für eine Ressource existieren, wird aus den Ressourcenmetadaten abgeleitet. Dadurch entsteht ein zentraler Permission-Katalog statt manuell gepflegter Listen.

Permission-Scopes

Scope	Bedeutung
ohne Suffix	Generische Berechtigung für die Aktion auf der Ressource.
.any	Zugriff auf alle Ressourcen dieses Typs innerhalb des effektiven Tenant-Kontexts.
.own	Zugriff nur auf Ressourcen, deren Owner der effektive Nutzer ist.
.granted	Zugriff nur auf Ressourcen, für die ein gültiger Resource Grant existiert.

Nicht jeder Scope ist überall verfügbar

.own setzt eine Owner-Spalte am Modell voraus. .granted ist nur verfügbar, wenn das Modell Resource Grants unterstützt.

Effektiver Security Context

Für jeden authentifizierten Request baut LIVOI einen AuthContext. Dieser Kontext bündelt Authentifizierung, Actor-Informationen, Tenant-Auswahl, Rollen, Gruppen und effektive Permissions.

Actor und Identität

Authentifizierungsmethode, effektive User-ID, effektive Tenant-ID und Request-ID.

Rollen und Gruppen

Direkte User-Rollen, Gruppenmitgliedschaften und Gruppenrollen werden pro Tenant zusammengeführt.

Permissions

Die effektiven Permissions werden aus den zusammengeführten Rollen gesammelt und kurzzeitig gecacht.

Resource Grants

Grants werden bewusst nicht als normale Rollen-Permissions in den Kontext übernommen. Sie werden erst beim Zugriff auf eine konkrete Ressource über den Scope .granted ausgewertet.

Cache-Invalidierung

Der Cache beschleunigt die Kontextauflösung, bleibt aber nur temporär. Die verbindliche Quelle für Rollen, Gruppen, Mitgliedschaften, API-Keys und Grants bleibt die Datenbank.

Tenant-Auswahl

Der Tenant-Kontext wird über den Request bestimmt, zum Beispiel über X-Tenant-ID. Für tenantgebundene Endpunkte muss ein effektiver Tenant vorhanden sein. Ungültige oder nicht erlaubte Tenant-Angaben werden kontrolliert abgelehnt.

JWT-Requests

Wenn X-Tenant-ID gesetzt ist, muss der User aktives Mitglied dieses Tenants sein. Ohne Header wird ein aktiver Standardtenant verwendet, sofern eindeutig bestimmbar.

Mehrere Tenants

Wenn mehrere aktive Mitgliedschaften existieren und kein Default eindeutig ist, muss der Client den Tenant explizit auswählen.

API-Keys

Tenantgebundene API-Keys dürfen nur in ihrem gebundenen Tenant verwendet werden. Ein abweichender Tenant-Header wird abgelehnt.

Tenant-freie Operationen

Wenn kein Tenant-Kontext existiert, sind nur userbezogene oder globale Operationen möglich, etwa das Erstellen eines Tenants oder das Lesen eigener Basisinformationen.

Route-Level Authorization

Jede geschützte Route beschreibt fachlich, welchen Auth-Kontext sie braucht und welche Ressource-Aktion-Kombination erlaubt sein muss. Diese Einstiegsprüfung entscheidet, ob der Request überhaupt in die fachliche Verarbeitung übergehen darf.

Kontextanforderung

Die Route legt fest, ob ein User-Kontext, ein Tenant-Kontext oder nur irgendeine authentifizierte Identität erforderlich ist.

Permission-Anforderung

Für jede fachliche Aktion wird geprüft, ob der effektive Security Context eine passende Permission enthält.

Request Context

Nur bei erfolgreicher Prüfung entsteht ein Request Context, der Tenant, Actor, Datenbank-Session und Security Context konsistent zusammenführt.

1. Fehlt die Authentifizierung, wird der Request als unauthentifiziert abgelehnt.
2. Fehlt der benötigte Tenant-Kontext, wird kein fachlicher Handler ausgeführt.
3. Fehlt eine erforderliche Permission, endet der Request mit einem Permission-Fehler.
4. Erst danach darf die Route Daten lesen, schreiben oder eine Service-Operation ausführen.

Route-Prüfung ist nicht genug

Die Route-Prüfung schützt den Einstieg in die API-Funktion. Sie ersetzt nicht die ressourcenspezifischen Prüfungen für konkrete Datensätze.

Resource-Level Authorization

Für Operationen auf bestehenden Ressourcen nutzt LIVOI zentrale Access-Filter. Diese Filter kombinieren Tenant-Grenze, benötigte Aktion, vorhandene Permission, Owner-Bedingung und Resource-Grant-Bedingung.

Tenant-Filter

Ressourcen müssen im effektiven Tenant liegen, sofern die Operation tenantgebunden ist.

Owner-Filter

Bei .own muss die Owner-Spalte der Ressource auf den effektiven User zeigen.

Grant-Filter

Bei .granted muss ein aktiver Resource Grant mit der passenden Permission existieren.

Beispiel: Ein Nutzer mit files.update.own darf nicht jede Datei ändern, sondern nur Dateien, deren Owner-Spalte auf den effektiven User zeigt.

Fail closed

Ohne passende Permission entsteht kein offener Datenfilter. Der Zugriff wird entweder durch einen immer falschen Filter leer gehalten oder vor der Fachoperation mit einem Auth- beziehungsweise Permission-Fehler beendet.

Row-Level-Security in PostgreSQL

RBAC wird nicht nur in der API-Schicht geprüft. LIVOI überträgt den effektiven Auth-Kontext in die PostgreSQL-Session. RLS-Policies lesen diesen Session-Kontext und entscheiden für jede betroffene Zeile, ob sie im aktuellen Request sichtbar oder veränderbar ist.

Session-Kontext

Tenant-ID, User-ID, API-Key-ID, Request-ID und Permissions als JSON-Liste.

Datenbank-Prüfungen

Liegt die Zeile im effektiven Tenant?

Ist die erforderliche Permission vorhanden?

Passt der Owner zur effektiven User-ID?

Existiert ein gültiger Resource Grant?

Defense in Depth

Application Authorization bleibt lesbar, testbar und nah am Use Case. Database RLS sorgt zusätzlich dafür, dass SQL-Zugriffe die Tenant- und Permission-Grenzen nicht umgehen.

API-Keys

API-Keys haben eigene Permissions. Wenn ein API-Key an einen User und Tenant gebunden ist, werden seine Permissions aber mit den effektiven Permissions des Besitzers geschnitten.

• Ein API-Key kann Rechte einschränken.
• Ein API-Key kann keine Rechte ausweiten, die der Besitzer im Tenant nicht hat.
• Ein API-Key ohne User-Bezug wird über seinen Tenant aufgelöst und nutzt ausschließlich seine eigenen Permissions.
• Tenantgebundene API-Keys müssen zu einem aktiven Tenant gehören.
• Inaktive, abgelaufene oder widerrufene API-Keys werden abgelehnt.

Resource Grants

Resource Grants erlauben feinere Freigaben als Rollen. Ein Grant ist immer tenantgebunden und bezieht sich auf eine konkrete Ressource, ein Subject und eine Permission mit .granted.

Feld	Beschreibung
Ressource	Ressourcentyp, zum Beispiel files, plus konkrete Ressourcen-ID.
Subject	user, group, role oder api_key plus Subject-ID.
Permission	Immer eine passende Permission mit .granted.
Gültigkeit	Optionaler Ablaufzeitpunkt und optionaler Grant-Ersteller.

Typischer Einsatz

Resource Grants eignen sich für gezielte Freigaben, etwa wenn ein Nutzer eine einzelne Datei lesen darf, ohne eine breite Rolle für alle Dateien zu erhalten.

Validierung

Ein Grant ist nur gültig, wenn die Permission vom Permission-Katalog unterstützt wird und die Ressource Grants technisch zulässt. Ungültige Grant-Permissions werden früh abgelehnt.

Typischer Request-Ablauf

1. Client sendet einen Request mit Bearer Token oder API-Key.
2. Authentication validiert Token oder API-Key.
3. LIVOI bestimmt effektiven Tenant und effektiven User.
4. Rollen, Gruppen und Permissions werden geladen und zum AuthContext zusammengeführt.
5. Endpoint Permissions werden geprüft.
6. Die Datenbank-Session erhält den Auth-Kontext.
7. Service-Operationen bauen Resource Access Filter.
8. PostgreSQL RLS prüft die final ausgeführten Queries zusätzlich.

Warum RBAC und RLS kombiniert werden

RBAC beantwortet, welche Aktion ein Actor grundsätzlich ausführen darf. RLS beantwortet zusätzlich, welche konkreten Datenzeilen dieser Actor im aktuellen Kontext sehen oder verändern darf.

Die Kombination verhindert typische Fehler

Ein Endpunkt kann geschützt sein und trotzdem eine Query mit fehlendem Tenant-Filter enthalten. RLS reduziert genau dieses Risiko, weil die Datenbank dieselbe Grenze erneut prüft.

Technische Entscheidungslogik

Der Zugriff wird nicht an einer einzigen Stelle entschieden. LIVOI wertet denselben Request in mehreren Schichten aus, wobei jede Schicht eine engere Aussage trifft als die vorherige.

Schicht	Technische Frage	Ergebnis
Authentifizierung	Ist der Actor durch Token oder API-Key eindeutig und gültig identifiziert?	Unauthentifizierte oder abgelaufene Credentials werden früh abgelehnt.
Tenant-Kontext	In welchem organisatorischen Sicherheitsraum soll der Request ausgeführt werden?	Der effektive Tenant begrenzt Rollen, Gruppen, Grants und Datenzeilen.
Effektive Permissions	Welche Aktionen ergeben sich aus direkten Rollen, Gruppenrollen und API-Key-Einschränkungen?	Es entsteht eine normalisierte Permission-Menge für den aktuellen Request.
Ressourcenbezug	Ist die konkrete Ressource durch Tenant, Owner oder Grant für diesen Actor erreichbar?	Listen, Reads, Updates und Deletes erhalten zusätzliche Zugriffskriterien.
Datenbankgrenze	Darf die final ausgeführte SQL-Operation die betroffene Zeile sehen oder verändern?	RLS erzwingt dieselbe Grenze unabhängig vom konkreten Query-Pfad.

Wichtig für das Verständnis

Eine Permission wie files.update.own erlaubt nicht direkt ein Update. Sie erlaubt nur ein Update, wenn zusätzlich Tenant, Owner-Beziehung und Datenbank-Policy für die konkrete Datei passen.

Einbindung neuer Ressourcen

Neue Ressourcen sollen nicht jeweils eigene Berechtigungslogik mitbringen. Sie werden über dieselben technischen Informationen in das zentrale Zugriffssystem eingebunden.

Unterstützte Aktionen

Die Ressource beschreibt, welche Aktionen grundsätzlich möglich sind, zum Beispiel create, read, update, delete oder access_manage.

Scopes

Die Ressource legt fest, ob Ownership und Resource Grants technisch unterstützt werden. Nur dann sind .own oder .granted gültige Permission-Scopes.

Datenbankgrenze

Für RLS muss klar sein, wie Tenant, Owner oder übergeordnete Tenant-Beziehungen einer Ressource bestimmt werden.

Standardrollen

Standardrollen können die neue Ressource gezielt aufnehmen, ohne dass Endpunkte eigene Sonderregeln benötigen.

Frühe Fehlererkennung

Wenn eine Route oder ein Grant eine nicht unterstützte Ressource-Aktion-Scope-Kombination nutzt, wird diese Permission bereits gegen den Permission-Katalog validiert.

Design-Prinzipien

Least Privilege

Standardrollen geben nur den nötigen Zugriff.

Tenant Isolation

Der effektive Tenant ist immer Teil der Zugriffsauswertung.

Defense in Depth

API-seitige Prüfungen und PostgreSQL-RLS ergänzen sich.

Explizite Permissions

Rechte werden als konkrete Ressource-Aktion-Scope-Kombinationen modelliert.

Delegierbare Freigaben

Resource Grants erlauben gezielte Ausnahmen ohne Rollenaufblähung.

API-Key-Begrenzung

Automatisierung darf Rechte reduzieren, aber nicht unkontrolliert erweitern.

Weitere API-Themen

Authentifizierung

Bearer Token, API-Schlüssel und sichere Schlüsselverwaltung.

Error Handling

Einheitliche Fehlerstruktur und Codes für API-Rückmeldungen.