FGA-Debugger

Der FGA-Debugger ist ein interaktives Werkzeug in der Auris-Konsole, mit dem du deine Feingranulare-Autorisierungs-(FGA-)Konfiguration in Echtzeit testen und beheben kannst. Er bietet drei Kernoperationen — Check, Expand und List Objects — jede mit einer visuellen Oberfläche zum Eingeben von Abfragen und Untersuchen von Ergebnissen.

Zugriff auf den FGA-Debugger unter Konsole → Administration → Feingranulare Autorisierung → Debugger.

Voraussetzungen

Bevor du den Debugger verwendest, benötigst du:

Ein aktives Autorisierungsmodell: Mindestens ein FGA-Modell muss erstellt und aktiviert sein. Wenn kein Modell aktiv ist, zeigt die Debugger-Seite einen leeren Zustand mit einem Link zur Modell-Seite.
Beziehungs-Tuples: Der Debugger fragt deinen tatsächlichen Tuple-Speicher ab, daher benötigst du Tuples für die Objekte und Subjekte, die du testen möchtest.
Die Berechtigung debug:fga: Dein Administratorkonto muss diese Berechtigung haben, um auf den Debugger zugreifen zu können.

Drei Operationen

Die Debugger-Seite ist in drei Tabs gegliedert: Check, Expand und List Objects. Jeder Tab bietet ein Formular zur Eingabe der Abfrageparameter und ein Ergebnisfeld darunter.

Check

Die Check-Operation beantwortet die Frage: „Hat dieses Subjekt diese Relation zu diesem Objekt?”

Dies ist die am häufigsten verwendete Operation während der Entwicklung und Fehlersuche.

Eingabefelder:

Feld	Beschreibung	Beispiel
Objekttyp	Der in deinem Autorisierungsmodell definierte Typ	`document`
Objekt-ID	Die spezifische Instanz, auf die der Zugriff geprüft wird	`readme`
Relation	Die zu prüfende Relation	`viewer`
Subjekttyp	Der Typ des Subjekts	`user`
Subjekt-ID	Das spezifische Subjekt	`alice`
Subjekt-Relation	(Optional) Wenn das Subjekt ein Userset ist, die Relation am Subjekt	`member`
Erklären	Umschalten, um den Auflösungsbaum anzuzeigen	Standardmäßig aktiviert

Verwendung:

Objekt eingeben

Wähle den Objekttyp aus dem Dropdown (aus den Typdefinitionen deines aktiven Modells befüllt) und gib die Objekt-ID ein.

Relation eingeben

Wähle die Relation aus dem Dropdown (aus den definierten Relationen des ausgewählten Objekttyps befüllt).

Subjekt eingeben

Wähle den Subjekttyp und gib die Subjekt-ID ein. Wenn ein Userset geprüft wird (z. B. „alle Mitglieder der Gruppe engineering”), gib auch die Subjekt-Relation ein (z. B. member).

Auf „Check” klicken

Der Debugger führt die Prüfungsabfrage gegen die FGA-Engine aus und zeigt das Ergebnis an.

Ergebnis:

Das Ergebnisfeld zeigt:

Erlaubt (grün) oder Verweigert (rot) — das boolesche Ergebnis
Auflösungsbaum (wenn Erklären aktiviert ist) — der vollständige Pfad, den die Engine zur Entscheidung verfolgt hat

Expand

Die Expand-Operation beantwortet die Frage: „Welche Subjekte haben diese Relation zu diesem Objekt?”

Dies ist nützlich, wenn du sehen möchtest, wer Zugriff auf eine bestimmte Ressource hat.

Eingabefelder:

Feld	Beschreibung	Beispiel
Objekttyp	Der in deinem Autorisierungsmodell definierte Typ	`document`
Objekt-ID	Die spezifische Instanz	`readme`
Relation	Die zu expandierende Relation	`viewer`

Ergebnis:

Eine Baumansicht aller Subjekte, die die angegebene Relation haben, gruppiert nach Art des Erhalts:

Direkt: Subjekte mit einem expliziten Tuple (z. B. document:readme#viewer@user:alice)
Berechnet: Subjekte, die die Relation durch ein berechnetes Userset haben (z. B. alle editors sind auch viewers)
Geerbt: Subjekte, die die Relation von einem übergeordneten Objekt erben (z. B. via viewer from parent)

List Objects

Die List-Objects-Operation beantwortet die Frage: „Auf welche Objekte eines bestimmten Typs kann dieses Subjekt mit dieser Relation zugreifen?”

Dies ist nützlich beim Erstellen von Benutzeroberflächen, die „alle Dokumente, die Benutzer Alice sehen kann” zeigen, oder beim Debuggen, warum ein Benutzer bestimmte Ressourcen sieht (oder nicht sieht).

Eingabefelder:

Feld	Beschreibung	Beispiel
Objekttyp	Der Typ der zu durchsuchenden Objekte	`document`
Relation	Die zu prüfende Relation	`viewer`
Subjekttyp	Der Typ des Subjekts	`user`
Subjekt-ID	Das spezifische Subjekt	`alice`

Ergebnis:

Eine Liste aller Objekt-IDs des angegebenen Typs, bei denen das Subjekt die angegebene Relation hat. Jedes Ergebnis zeigt die Objekt-ID und gibt an, ob der Zugriff direkt, berechnet oder geerbt ist.

Den visuellen Auflösungsbaum lesen

Der Auflösungsbaum ist die wertvollste Debugging-Funktion. Wenn der Erklären-Modus bei einer Check-Operation aktiviert ist, zeigt der Debugger eine Baumvisualisierung, die jeden Schritt zeigt, den die FGA-Engine zur Entscheidungsfindung unternommen hat.

Knotenfarben

Jeder Knoten im Baum ist farblich kodiert:

Farbe	Bedeutung
Grün	Diese Regel wurde als wahr ausgewertet — die Bedingung war erfüllt
Rot	Diese Regel wurde als falsch ausgewertet — die Bedingung war nicht erfüllt
Blau	Intermediäres berechnetes Userset — ein Schritt im Auflösungspfad, kein Endergebnis

Knotentypen

Der Baum enthält verschiedene Knotentypen, die den sechs Umschreibtypen im FGA-Modell entsprechen:

Knotenbezeichnung	Umschreibtyp	Was es zeigt
`this`	Direkte Zuweisung	Ob ein Tuple im Speicher vorhanden ist
`computedUserset`	Berechnete Relation	Ob das Subjekt eine andere Relation am selben Objekt hat
`tupleToUserset`	Relation folgen	Das verfolgte intermediäre Objekt und das Ergebnis der Prüfung der Relation daran
`union`	ODER-Kombination	Jeder Zweig, mit dem ersten wahren Zweig hervorgehoben
`intersection`	UND-Kombination	Jeder Zweig, alle müssen wahr sein
`exclusion`	Mengendifferenz	Die Basismenge und die subtrahierte Menge

Einen Baum lesen: Beispiel

Betrachte folgendes Autorisierungsmodell:


type document
  relations
    define parent: [folder]
    define owner: [user] or owner from parent
    define editor: [user] or owner
    define viewer: [user] or editor

Ein Check für document:readme#viewer@user:alice könnte diesen Baum erzeugen:

Lesen von oben nach unten:

Die Engine prüft viewer, das als [user] or editor definiert ist (eine Union)
Erster Zweig: direktes Tuple document:readme#viewer@user:alice — nicht gefunden (rot)
Zweiter Zweig: berechnetes Userset editor — wertet editor am selben Objekt aus
editor ist [user] or owner — direktes Tuple nicht gefunden, also wird owner geprüft
owner ist [user] or owner from parent — direktes Tuple document:readme#owner@user:alice gefunden (grün)
Die Union schließt kurz: owner ist wahr, also ist editor wahr, also ist viewer wahr

Das Ergebnis: Alice kann document:readme sehen, weil sie der Eigentümer ist (und Eigentümer sind Editoren, und Editoren sind Viewer).

Häufige Debugging-Szenarien

„Warum kann Benutzer X nicht auf Dokument Y zugreifen?”

Check mit aktiviertem Erklären ausführen

Gib das Objekt, die Relation und das Subjekt ein. Stelle sicher, dass Erklären eingeschaltet ist.

Rote Knoten im Auflösungsbaum untersuchen

Rote Knoten zeigen, wo die Prüfung fehlgeschlagen ist. Schau dir an:

Welche direkten Tuples erwartet, aber nicht gefunden wurden
Welche berechneten Relationen nicht aufgelöst wurden
Welche tupleToUserset-Pfade keine intermediären Tuples hatten

Das fehlende Tuple oder die fehlende Relation identifizieren

Häufige Ursachen:

Fehlendes direktes Tuple: Der Benutzer hat keine explizite Zuweisung. Lösung: das Tuple schreiben POST /api/fga/tuples.
Fehlende übergeordnete Relation: Für geerbte Berechtigungen prüfen, ob die parent-Relation vorhanden ist (z. B. document:readme#parent@folder:engineering).
Fehlende Gruppenmitgliedschaft: Wenn der Zugriff über eine Gruppe erfolgt, prüfen, ob der Benutzer Mitglied der Gruppe ist (group:engineering#member@user:alice).
Modell-Diskrepanz: Der Relationsname in deinem Anwendungscode stimmt nicht mit der Modelldefinition überein. Rechtschreibung und Groß-/Kleinschreibung prüfen.

Die Korrektur verifizieren

Nachdem du das fehlende Tuple geschrieben hast, führe den Check erneut aus, um zu bestätigen, dass der Baum jetzt grün aufgelöst wird.

„Wer hat Editor-Zugriff auf Ordner Z?”

Verwende die Expand-Operation:

Setze Objekttyp auf folder, Objekt-ID auf Z, Relation auf editor
Klicke auf Expand
Das Ergebnis zeigt alle direkten Editoren, alle Benutzer, die durch berechnete Relationen Editoren sind (z. B. Eigentümer), und alle Mitglieder von Gruppen mit Editor-Zugriff

„Welche Dokumente kann Benutzer X sehen?”

Verwende die List-Objects-Operation:

Setze Objekttyp auf document, Relation auf viewer
Setze Subjekttyp auf user, Subjekt-ID auf X
Klicke auf List Objects
Das Ergebnis listet jede Dokument-ID auf, bei der Benutzer X Viewer-Zugriff hat, ob direkt, berechnet oder geerbt

List Objects durchsucht den gesamten Tuple-Speicher für den angegebenen Typ, daher kann es bei Tenants mit vielen Tuples langsamer als Check sein. Verwende es für Debugging- und administrative Aufgaben, nicht in häufig genutzten Anfragepfaden.

Modell-Visualisierung

Unterhalb der Debugger-Tabs enthält die Seite ein Modell-Diagramm — eine SVG-Visualisierung deines aktiven Autorisierungsmodells, die Folgendes zeigt:

Jeden Typ als Knoten
Relationen als beschriftete Kanten zwischen Typen
Berechnete Userset-Pfeile (gestrichelte Linien)
tupleToUserset-Pfeile (durchgezogene Linien mit intermediären Beschriftungen)

Das Diagramm hilft dir, die Form deines Modells auf einen Blick zu verstehen, besonders bei komplexen Modellen mit tiefen Vererbungsketten. Klicke auf einen Typknoten, um seine Relationen und verbundenen Typen hervorzuheben.

Tipps für effektives Debugging

Beginne mit Check + Erklären-Modus. Der Auflösungsbaum zeigt dir genau, was die Engine versucht hat und wo sie erfolgreich war oder gescheitert ist. Dies ist informativer als das alleinige Lesen der Modelldefinition, da es die tatsächlichen Tuples im Speicher zeigt.

Arbeite von unten nach oben. Wenn eine Prüfung fehlschlägt, beginne bei den Blattknoten des Auflösungsbaums. Diese zeigen die tatsächlichen Tuple-Lookups. Wenn du einen roten this-Knoten siehst, bedeutet das, dass ein bestimmtes Tuple im Speicher fehlt.

Teste sowohl positive als auch negative Fälle. Nachdem du Tuples geschrieben hast, verifiziere, dass autorisierte Benutzer auf die Ressource zugreifen können UND dass nicht autorisierte Benutzer korrekt verweigert werden. Ein zu permissives Modell ist genauso gefährlich wie ein zu restriktives.

Verwende Expand zur Berechtigungsprüfung. Führe regelmäßig Expand auf sensiblen Ressourcen aus, um zu verifizieren, dass nur die beabsichtigten Benutzer Zugriff haben. Dies ist besonders wichtig nach Modelländerungen oder Massen-Tuple-Operationen.

Vergleiche Modellversionen. Wenn sich das Autorisierungsverhalten unerwartet geändert hat, prüfe, ob das aktive Modell kürzlich aktualisiert wurde. Gehe zu Modelle, um den Versionsverlauf zu sehen. Es ist immer nur ein Modell aktiv — das Aktivieren einer neuen Version ersetzt die vorherige.

Zugehörige Anleitungen

FGA / Zanzibar-Modell — Konzepte: Wie das Autorisierungsmodell und der Check-Algorithmus funktionieren
Feingranulare Autorisierungs-Leitfaden — Schrittweiser Leitfaden zur Implementierung von FGA
FGA-API-Referenz — Modelle, Tuples verwalten und Checks über die REST API ausführen