Berechtigungen verstehen (CASL)
Zweck
SpeamCore steuert jede Sichtbarkeit und jede Aktion über CASL — ein offenes JavaScript-Framework für attribut- und rollenbasierte Zugriffssteuerung. Dieses Kapitel erklaert das Modell so, dass Sie als Administrator im Advanced Permission Editor Rollen und Berechtigungen korrekt zuweisen koennen — und damit jede Doku-Seite mit ihrer Berechtigungs-Liste richtig verstehen.
Voraussetzungen
Das Modell auf einen Blick
Eine Berechtigung in SpeamCore besteht aus zwei Teilen:
Action + Subject
────── ───────
view Customer
create SalesDocument
do OfflineMode
- Action — was darf gemacht werden? (
view,create,update,delete,do,is) - Subject — auf welchem Objekt? (
Customer,Workorder,SalesDocument, …)
Anwender bekommen nicht direkt Berechtigungen, sondern Rollen in Keycloak. Beim Login übersetzt SpeamCore diese Rollen in CASL-Regeln.
Die zwei Berechtigungs-Ebenen
SpeamCore trennt bewusst zwischen Frontend-Sichtbarkeit und API-Datenzugriff:
| Ebene | Beispiel-Subject | Zweck |
|---|---|---|
| Frontend-Page-Guard | FE_Customer | Darf der Anwender die Seite ueberhaupt aufrufen / im Menue sehen? |
| API-Datenzugriff | Customer | Darf der Anwender die zugrundeliegenden Daten lesen oder schreiben? |
Ein Anwender, der FE_Customer hat, aber nicht Customer:view, sieht die Seite — bekommt aber leere Listen (oder 403-Fehler bei direktem API-Zugriff).
Umgekehrt: Wer Customer:view hat, aber nicht FE_Customer, kann nicht über die UI auf Kundendaten zugreifen, wohl aber über API-Tokens (z. B. Integrationen).
In jeder Doku-Seite zu einer Funktion finden Sie deshalb zwei Tabellen:
- „Frontend-Page-Guard" — die
FE_…-Subjects. - „API-Datenzugriff" — die regulären Subjects für die jeweiligen Endpoints.
Actions im Detail
| Action | Bedeutung | Beispiel |
|---|---|---|
view | Lesen — Liste, Detail, Suche | view Customer |
create | Anlegen | create SalesDocument |
update | Ändern bestehender Datensaetze | update Workorder |
delete | Löschen | delete TextBlock |
do | Spezialaktionen, die nicht in CRUD passen | do OfflineMode, do TakeOverSalesDocument |
is | Zustands-Checks (kein Schreibzugriff) | is Admin |
do-Actions sind workflow-spezifisch — z. B. do WorkorderCreateSalesDocument schaltet den Button „Aus Auftrag Verkaufsbeleg erstellen" frei. Welche do-Actions eine Funktionsseite braucht, steht in jeder Routen-Doku.
Subjects im Detail
SpeamCore hat über 400 Subjects. Sie folgen drei Mustern:
1. API-Entitaeten — entsprechen Datenmodellen im Backend.
Customer, Location, Contact, Workorder, Service,
Product, Warehouse, SalesDocument, PurchaseDocument,
Employee, EmployeeContract, TimeTracking, Mailbox, …
2. Frontend-Page-Guards — alle mit FE_-Praefix.
FE_Customer, FE_Workorder, FE_SetupWizard,
FE_Dashboard, FE_PurchaseDocument, …
3. Custom-Capabilities — weder Datenmodell noch Page, sondern Faehigkeiten.
OfflineMode, Print, Language, BusinessAnalysis, …
Keycloak-Rollen → CASL-Regeln
Ihre Administratoren weisen in Keycloak (SpeamID) Rollen zu. SpeamCore lest diese Rollen beim Login und übersetzt sie in CASL-Regeln.
Konvention der Rollennamen:
APP_SPEAMCORE_<ACTION>_<SUBJECT>[?<FELD-MASKE>]
Beispiele:
| Keycloak-Rolle | CASL-Regel |
|---|---|
APP_SPEAMCORE_VIEW_CUSTOMER | {action: 'view', subject: 'Customer'} |
APP_SPEAMCORE_CREATE_SALESDOCUMENT | {action: 'create', subject: 'SalesDocument'} |
APP_SPEAMCORE_NOT_VIEW_PRODUCT?SELL_PRICE+CREATED_AT | Deny view Product auf den Feldern SELL_PRICE und CREATED_AT |
APP_SPEAMCORE_DO_OFFLINEMODE | {action: 'do', subject: 'OfflineMode'} |
Deny-Regeln entstehen über den NOT_-Praefix. Damit lassen sich z. B. Verkaufspreise vor bestimmten Mitarbeitern ausblenden.
Feld-Maskierung über ?<FIELD>+<FIELD>+…. Mehrere Felder mit + getrennt.
Praxis: Wie Sie eine Doku-Seite lesen
Beispiel aus der Doku zu Bestellbelegen (/purchase-documents):
casl_fe:
- FE_PurchaseDocument:view
casl:
- PurchaseDocument:view
- PurchaseDocument:create
- PurchaseDocument:update
Daraus folgt für den Administrator:
Damit der Anwender Bestellbelege voll bedienen kann, braucht die Rolle in Keycloak:
APP_SPEAMCORE_VIEW_FE_PURCHASEDOCUMENT
APP_SPEAMCORE_VIEW_PURCHASEDOCUMENT
APP_SPEAMCORE_CREATE_PURCHASEDOCUMENT
APP_SPEAMCORE_UPDATE_PURCHASEDOCUMENT
Reine Lese-Rolle (z. B. für Buchhaltung) braucht nur VIEW_FE_PURCHASEDOCUMENT und VIEW_PURCHASEDOCUMENT.
Wo Berechtigungen geprüft werden
Die Prüfung passiert an drei Stellen:
| Stelle | Mechanismus | Datei (Code-Referenz) |
|---|---|---|
| Frontend Routes | requiredAbility in routes.tsx | speamcore.com/src/routes.tsx |
| Frontend Komponenten | useAbility().can(action, subject) | überall in src/pages/... |
| Backend Routers | caslMiddleware([['<action>', '<subject>']]) | api.speamcore.com/src/routers/*.router.ts |
Wenn FE und BE divergieren — etwa weil die FE-Seite sichtbar ist, aber der API-Aufruf 403 wirft — ist eine der drei Stellen falsch. Doku und Code-Drift-Check erkennen das später automatisch.
Wiederverwendbare Konzepte
- Mandanten-Modell — wie sich Berechtigungen zwischen Mandanten unterscheiden.
Verknuepfungen zu anderen Modulen
- Jede Routen-Funktionsseite enthält eine Sektion Berechtigungen (CASL) mit den exakten Subjects.
- Die Ersteinrichtung ist nur für Mandanten-Administratoren zugaenglich (
FE_SetupWizard:view).
Häufige Fehler und Lösungen
| Fehler | Lösung |
|---|---|
| Anwender sieht Seite, bekommt aber leere Liste | API-Subject (Customer:view) fehlt — nur Page-Guard (FE_Customer:view) gesetzt. |
| Anwender bekommt 403 beim Speichern | update-Action fehlt — Page-Guard und view reichen nicht. |
| Button ist sichtbar, aber ausgegraut | Spezial-do-Subject fehlt. Doku-Seite zur Funktion prüfen. |
| Verkaufspreise sind ausgeblendet | Deny-Regel NOT_VIEW_PRODUCT?SELL_PRICE ist gesetzt. Mit Administrator klaeren. |
Versionshinweise
- 2026-04-29: Initiale Veroeffentlichung als Querschnitts-Konzept.