Zugriffsfilter (Permission Filter)¶

Ein Zugriffsfilter legt fest, welche Inhalte und Zeilen eine Person oder Gruppe innerhalb eines Spaces sehen darf. Er ergänzt die normale Mitgliedschaft und Rolle um eine fachliche Einschränkung – und dient gleichzeitig als harte Sicherheitsgrenze.

Technisch ist er ein JSON-Objekt, das als Allowlist funktioniert:

Du gibst Tabellen explizit frei – oder implizit über einen Spaltenfilter.
Du schränkst freigegebene Tabellen bei Bedarf weiter ein.
Alles, was nicht freigegeben ist, bleibt unsichtbar.

Wann brauchst du einen Zugriffsfilter?¶

Typische Fälle:

jemand soll nur Inhalte für einen bestimmten Kunden, ein Projekt oder einen Standort sehen
ein Nutzer darf nur bestimmte Tabellen sehen
ein Team darf nur Datensätze eines Mandanten sehen
öffentliche Tabellen sollen für viele Rollen sichtbar sein
ein eingebetteter Assistent soll nur den fachlich passenden Kontext nutzen dürfen
ein Space darf zwar auf eine Datenquelle zugreifen, aber nur auf einen Teil der Zeilen

Wie funktioniert das Prinzip?¶

Ein Zugriffsfilter folgt einer einfachen Denkweise:

Lege fest, welche Merkmale Inhalte haben müssen, damit sie sichtbar sein dürfen.
Halte die Regeln so einfach und nachvollziehbar wie möglich.
Prüfe die Regeln aus Sicht der Zielgruppe und nicht nur aus Sicht der Ersteller.

Der Filter wird als Allowlist ausgewertet: Sobald ein Permission Filter nicht leer ist, werden Tabellen ohne passende Freigabe blockiert. Ein leerer Filter bedeutet keine zusätzliche Einschränkung – dann greift nur die normale Mitgliedschaft.

Gute fachliche Fragen vor dem Einrichten¶

Bevor du einen Zugriffsfilter anlegst, kläre diese Punkte:

Welche Personengruppe soll welche Inhalte sehen?
Nach welchen fachlichen Merkmalen lassen sich Inhalte sauber unterscheiden?
Sind diese Merkmale in euren Inhalten zuverlässig gepflegt?
Ist ein eigener Space vielleicht einfacher als ein komplexer Filter?

Wenn diese Fragen nicht klar beantwortet sind, wird ein Zugriffsfilter schnell unübersichtlich oder fehleranfällig.

Technischer Aufbau¶

Grundaufbau¶

Ein Permission Filter ist normales JSON. Es gibt zwei Wege, einer Tabelle Zugriff zu gewähren:

Explizit – wenn eine Tabelle vollständig ohne Zeileneinschränkung freigegeben werden soll:

{ "table": { "eq": "orders" } }

Implizit über einen Spaltenfilter – ein Eintrag der Form tabelle.spalte gewährt automatisch Zugriff auf die Tabelle und schränkt gleichzeitig die sichtbaren Zeilen ein. Ein zusätzlicher table-Eintrag ist dabei nicht nötig:

{ "orders.customer_id": { "in": [1001, 1002] } }

Dieses Beispiel bedeutet: die Tabelle orders ist erlaubt, aber nur Zeilen mit customer_id 1001 oder 1002.

Wichtig: Sobald mehrere Tabellen zusammen freigegeben werden sollen, müssen alle Einträge in einem or stehen:

{
  "or": [
    { "orders.customer_id": { "in": [1001, 1002] } },
    { "table": { "eq": "customers" } }
  ]
}

Die drei wichtigsten Bausteine¶

1. Tabellen direkt freigeben¶

Ein expliziter table-Eintrag ist sinnvoll, wenn eine Tabelle vollständig (ohne Zeileneinschränkung) freigegeben werden soll.

Eine einzelne Tabelle:

{ "table": { "eq": "orders" } }

Mehrere Tabellen:

{
  "or": [
    { "table": { "eq": "orders" } },
    { "table": { "eq": "customers" } },
    { "table": { "eq": "invoices" } }
  ]
}

Wenn dein Datenbankschema Tabellen mit Tags oder Facets beschreibt, kannst du ganze Gruppen von Tabellen freigeben.

{ "public": { "eq": true } }

Das erlaubt alle Tabellen, die im Schema das Facet public: true haben oder das Tag public tragen.

{ "eq": false } wird als gültige Form erkannt, gibt aber absichtlich keine Tabelle frei. Facet- und Tag-Einträge erzeugen selbst keine zusätzliche WHERE-Bedingung, sondern erweitern nur die Menge erlaubter Tabellen.

3. Zeilen innerhalb einer Tabelle einschränken¶

Ein Spaltenfilter der Form tabelle.spalte gewährt implizit Zugriff auf die Tabelle und schränkt gleichzeitig die sichtbaren Zeilen ein:

{ "orders.customer_id": { "in": [1001, 1002, 1003] } }

Mehrere Spaltenfilter für dieselbe Tabelle können direkt nebeneinander stehen – sie werden per AND verknüpft:

{
  "orders.status": { "eq": "open" },
  "orders.amount": { "gte": 100 }
}

Sobald verschiedene Tabellen betroffen sind, müssen die Einträge in ein or:

{
  "or": [
    { "orders.tenant_id": { "eq": 42 } },
    { "customers.tenant_id": { "eq": 42 } }
  ]
}

Unterstützte Operatoren¶

Operator	Bedeutung	Beispiel
`eq`	gleich	`{ "orders.status": { "eq": "open" } }`
`ne`	ungleich	`{ "orders.status": { "ne": "cancelled" } }`
`gt`	größer als	`{ "orders.amount": { "gt": 0 } }`
`lt`	kleiner als	`{ "orders.amount": { "lt": 1000 } }`
`gte`	größer oder gleich	`{ "orders.amount": { "gte": 100 } }`
`lte`	kleiner oder gleich	`{ "orders.amount": { "lte": 500 } }`
`in`	Wert ist in einer Liste	`{ "orders.customer_id": { "in": [1, 2, 3] } }`
`like`	Textmuster	`{ "files.path": { "like": "%/angebote/%" } }`

Zusätzlich gilt:

{ "eq": null } entspricht IS NULL
{ "ne": null } entspricht IS NOT NULL

Logische Verknüpfungen¶

Filter können mit and, or und not verschachtelt werden. Mehrere Tabellen müssen immer über or zusammengeführt werden:

{
  "or": [
    { "table": { "eq": "orders" } },
    { "public": { "eq": true } }
  ]
}

Das ist nützlich, wenn ein Space sowohl eine konkrete Tabelle als auch alle Tabellen mit dem Tag oder Facet public sehen darf.

Mehrere Zugriffsquellen werden vereinigt¶

Wenn ein Nutzer über direkte Mitgliedschaft und über Gruppenmitgliedschaften Zugriff erhält, werden die jeweiligen Filter per OR zusammengeführt. So sieht ein Nutzer die Vereinigung aller Quellen, über die er Zugriff erhält.

Schemaqualifizierte Tabellennamen¶

Wenn deine SQL-Abfragen Namen wie public.orders oder analytics.sales verwenden, kannst du beide Schreibweisen nutzen:

{ "orders.customer_id": { "in": [1001] } }

{ "public.orders.customer_id": { "in": [1001] } }

Beides ist für solche Tabellen geeignet.

Beispiele¶

Beispiel 1: Nur Bestellungen eines Mandanten¶

{ "orders.tenant_id": { "eq": 42 } }

Beispiel 2: Kunden und Rechnungen für bestimmte Organisationen¶

{
  "or": [
    { "customers.organization_id": { "in": [7, 8] } },
    { "invoices.organization_id": { "in": [7, 8] } }
  ]
}

{ "public": { "eq": true } }

Praktisch für Stammdaten, Referenztabellen oder kontrolliert freigegebene Reporting-Tabellen, die viele Rollen lesen dürfen.

Beispiel 4: Öffentliche Tabellen freigeben und zusätzlich eine nicht-öffentliche Tabelle eingeschränkt zugänglich machen¶

{
  "or": [
    { "public": { "eq": true } },
    { "customers.status": { "eq": "active" } }
  ]
}

Bedeutung: alle als public markierten Tabellen sind frei zugänglich, zusätzlich ist die Tabelle customers erlaubt – aber nur Zeilen mit status = active.

Beispiel 5: Dateien nur aus einem bestimmten Pfad¶

{ "files.path": { "like": "%/angebote/%" } }

Beispiel 6: Nur nicht gelöschte Datensätze¶

{ "documents.deleted_at": { "eq": null } }

Beispiel 7: Alles aus einer Kategorie außer archivierte Einträge¶

{
  "articles.category": { "eq": "wissen" },
  "articles.status": { "ne": "archived" }
}

Beide Bedingungen betreffen dieselbe Tabelle und werden per AND verknüpft.

Beispiel 8: Wertebereich für Reporting¶

{ "sales.amount": { "gte": 100, "lte": 10000 } }

Mehrere Operatoren in einem Feld werden gemeinsam angewendet.

Beispiel 9: Liste erlaubter IDs¶

{ "projects.id": { "in": [11, 15, 19, 21] } }

Beispiel 10: Konkrete Tabelle und öffentliche Tabellen gleichzeitig¶

{
  "or": [
    { "table": { "eq": "orders" } },
    { "public": { "eq": true } }
  ]
}

Beispiel 11: Zwei Tabellen im Join, jede mit Zeileneinschränkung¶

{
  "or": [
    { "orders.customer_id": { "in": [1001, 1002] } },
    { "customers.country": { "eq": "DE" } }
  ]
}

Beispiel 12: Nur offene Aufgaben (kein Abschlussdatum)¶

{ "tasks.completed_at": { "eq": null } }

Beispiel 13: Nur abgeschlossene Aufgaben¶

{ "tasks.completed_at": { "ne": null } }

Beispiel 14: Tabellen über einen internen Tag freigeben¶

{ "internal": { "eq": true } }

Damit werden alle Tabellen freigegeben, die das Tag internal tragen oder im Schema das Facet internal: true haben.

Beispiel 15: Öffentliche Tabellen plus eine Spezialtabelle¶

{
  "or": [
    { "public": { "eq": true } },
    { "table": { "eq": "special_exports" } }
  ]
}

Was bei Joins wichtig ist¶

Bei einer Abfrage mit mehreren Tabellen muss jede verwendete Tabelle freigegeben sein.

Das reicht für:

SELECT * FROM orders

Das reicht nicht für:

SELECT *
FROM orders
JOIN customers ON orders.customer_id = customers.id

Denn customers ist hier nicht freigegeben. Wenn du Joins erlauben willst, müssen alle beteiligten Tabellen im Filter stehen:

{
  "or": [
    { "table": { "eq": "orders" } },
    { "table": { "eq": "customers" } }
  ]
}

Einfache Pflege in der UI¶

Die einfache UI arbeitet typischerweise mit einer Liste von Tabellen und einer Liste von Facets oder Tags. Sie erzeugt daraus intern JSON wie dieses:

{
  "or": [
    { "table": { "eq": "orders" } },
    { "table": { "eq": "customers" } },
    { "public": { "eq": true } },
    { "internal": { "eq": true } }
  ]
}

Nicht jede beliebige JSON-Form ist in diese einfache UI zurückführbar. Wenn dein Fall komplexer ist, kannst du den Filter direkt als JSON pflegen.

Häufige Stolperfallen¶

1. Nicht-leerer Filter blockiert alles, was nicht freigegeben ist¶

Das ist Absicht. Permission Filter sind keine lose Empfehlung, sondern eine harte Sicherheitsgrenze.

2. Regeln sind fachlich nicht sauber abgestimmt¶

Wenn Inhalte die nötigen Merkmale nicht konsistent tragen, greift der Filter unerwartet oder gar nicht.

3. Mehrere Tabellen ohne `or` auf oberster Ebene¶

{
  "orders.tenant_id": { "eq": 42 },
  "customers.tenant_id": { "eq": 42 }
}

Das ist nicht korrekt für zwei verschiedene Tabellen. Die Einträge müssen in einem or stehen:

{
  "or": [
    { "orders.tenant_id": { "eq": 42 } },
    { "customers.tenant_id": { "eq": 42 } }
  ]
}

4. Ein leeres `in` blockiert immer¶

{ "orders.customer_id": { "in": [] } }

So ein Filter lässt für diese Bedingung keine Zeile übrig.

5. `{ "eq": false }` bei Facets oder Tags gibt nichts frei¶

{ "public": { "eq": false } }

Das ist keine Negation, sondern praktisch eine leere Freigabe.

6. `search` ist kein Permission-Mechanismus¶

Der Schlüssel search ist für andere Filterzwecke gedacht und sollte nicht als Sicherheitsregel verwendet werden.

7. Ein leerer Filter bedeutet keine zusätzliche Einschränkung¶

{}

Dann greift nur die normale Mitgliedschaft, aber kein zusätzlicher Permission-Filter.

8. Zu viele Sonderfälle in einem einzelnen Filter¶

Wenn ein Filter sehr viele Ausnahmen enthält, ist oft ein eigener Space die bessere Lösung.

Empfehlungen¶

Für neue Filter¶

Bewährte Reihenfolge:

Überlege, ob Tabellen vollständig oder nur eingeschränkt zugänglich sein sollen.
Nutze Spaltenfilter (tabelle.spalte) dort, wo Zeilen eingeschränkt werden sollen – sie gewähren die Tabelle implizit mit.
Nutze explizite table.eq-Einträge nur für Tabellen ohne Zeileneinschränkung.
Fasse mehrere Tabellen immer in einem or zusammen.
Verwende Facets oder Tags für stabile, gleichartige Tabellengruppen.
Komplexe and-/or-/not-Bäume nur einsetzen, wenn die technische Semantik bekannt ist.

Für Teams¶

Einigt euch auf wenige, klare Merkmale für Sichtbarkeit.
Verwendet überall dieselben Begriffe für Kunde, Projekt, Bereich oder Freigabestatus.
Testet die Sichtbarkeit immer mit realen Beispielnutzern.
Dokumentiert kurz, warum ein bestimmter Filter existiert.
Überprüft nach Änderungen an Rollen, Zielgruppen oder Datenquellen, ob der Filter noch passt.

Wann du lieber einfacher startest¶

Ein Zugriffsfilter ist nicht immer die beste erste Lösung. Häufig ist etwas anderes einfacher:

eigener Space statt vieler Ausnahmen in einem gemeinsamen Space
klar getrennte Assistenten statt ein Assistent mit zu vielen Sonderfällen
saubere Ablagestruktur statt komplizierter Nachfilterung

Kurzcheck vor dem Speichern¶

Prüfe bei jedem neuen Filter:

Sind alle benötigten Tabellen freigegeben – entweder per table.eq, Facet/Tag oder Spaltenfilter?
Stehen alle Einträge für verschiedene Tabellen in einem or?
Sind Joins mit allen beteiligten Tabellen abgedeckt?
Sind Mandanten-, Kunden- oder Organisationsgrenzen sauber als Spaltenfilter gesetzt?
Verwende ich Tags oder Facets dort, wo viele Tabellen dieselbe Regel teilen?
Ist der Filter so einfach, dass andere ihn später noch sicher lesen können?