Rollen & Berechtigungen API

Auris implementiert ein dreischichtiges Autorisierungsmodell. Diese API deckt zwei dieser Schichten ab:

RBAC (Rollenbasierte Zugriffssteuerung): Rollen sind benannte Gruppen von Berechtigungen. Benutzern werden Rollen zugewiesen. Berechtigungen verwenden das Format aktion:ressource (z.B. view:invoices, manage:users). Jede Berechtigung kann auf ALLOW, DENY oder INHERIT gesetzt werden (Drei-Zustands-Modell).
FGA (Feingranulare Autorisierung): Eine Zanzibar-kompatible Beziehungs-Tupel-Engine für objektbasierte Zugriffssteuerung. Die FGA-Schicht wird verwendet, wenn RBAC auf Rollenebene nicht ausreicht — zum Beispiel: “Benutzer Alice kann Dokument 42 ansehen, auch wenn sie keine view:all_documents-Berechtigung hat.”

RBAC — Rollenverwaltung

Alle Rollenverwaltungsendpunkte erfordern die manage:roles-Berechtigung und den x-tenant-Header.

GET/api/rolesRequires: manage:roles

Alle im Tenant definierten Rollen auflisten. Gibt Rollenmetadaten zurück, aber nicht die vollständige Berechtigungsliste. Verwende GET /api/roles/[id] oder GET /api/roles/[id]/permissions für Berechtigungsdetails.

Abfrageparameter

Parameter	Typ	Beschreibung
`page`	integer	Seitennummer (Standard: 1)
`limit`	integer	Elemente pro Seite (Standard: 20)
`search`	string	Nach Rollenname filtern

Erfolgsantwort


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "role_abc123",
        "name": "editor",
        "description": "Kann Inhalte erstellen und bearbeiten",
        "color": "#3b82f6",
        "userCount": 12,
        "createdAt": "2025-01-01T00:00:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 5, "totalPages": 1 }
  }
}

POST/api/rolesRequires: manage:roles

Eine neue Rolle erstellen. Rollennamen müssen im Tenant eindeutig sein und dürfen nur alphanumerische Zeichen, Bindestriche und Unterstriche enthalten.

Anforderungs-Body


{
  "name": "billing-admin",
  "description": "Verwaltet Rechnungen und Zahlungsmethoden",
  "color": "#f59e0b"
}

description und color sind optional.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "role_def456",
    "name": "billing-admin",
    "description": "Verwaltet Rechnungen und Zahlungsmethoden",
    "color": "#f59e0b",
    "createdAt": "2025-02-18T10:00:00Z"
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`NAME_TAKEN`	409	Eine Rolle mit diesem Namen existiert bereits
`VALIDATION_ERROR`	400	Ungültiges Rollennamensformat

GET/api/roles/[id]Requires: manage:roles

Eine Rolle anhand ihrer ID abrufen, einschließlich der vollständigen Berechtigungsliste mit dem ALLOW/DENY-Status für jede Berechtigung.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "role_abc123",
    "name": "editor",
    "description": "Kann Inhalte erstellen und bearbeiten",
    "color": "#3b82f6",
    "permissions": [
      { "id": "perm_1", "key": "view:invoices", "state": "ALLOW" },
      { "id": "perm_2", "key": "create:invoices", "state": "ALLOW" },
      { "id": "perm_3", "key": "delete:invoices", "state": "DENY" }
    ]
  }
}

Berechtigungsstatus: ALLOW (explizit gewährt), DENY (explizit verweigert), INHERIT (nicht explizit gesetzt — fällt auf den Systemstandard zurück, typischerweise verweigert).

PUT/api/roles/[id]Requires: manage:roles

Den Namen, die Beschreibung oder die Farbe einer Rolle aktualisieren.

Anforderungs-Body


{
  "description": "Kann Inhalte erstellen, bearbeiten und veröffentlichen",
  "color": "#8b5cf6"
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "role_abc123",
    "name": "editor",
    "description": "Kann Inhalte erstellen, bearbeiten und veröffentlichen",
    "color": "#8b5cf6"
  }
}

DELETE/api/roles/[id]Requires: manage:roles

Eine Rolle löschen. Benutzer, denen diese Rolle zugewiesen ist, verlieren sie sofort. Die Rolle wird von allen Benutzern entfernt und dann aus dem Tenant gelöscht.

Das Löschen einer Rolle betrifft alle Benutzer, die sie haben. Überprüfe die Auswirkung mit GET /api/roles/[id], das userCount enthält, bevor du löschst.

Erfolgsantwort


{
  "ok": true,
  "data": { "deleted": true }
}

RBAC — Berechtigungsverwaltung

GET/api/roles/[id]/permissionsRequires: manage:roles

Die Berechtigungseinstellungen für eine Rolle auflisten, nach Kategorie gruppiert. Jede Berechtigung hat einen state von ALLOW, DENY oder INHERIT.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "permissions": [
      {
        "category": "Dokumente",
        "items": [
          { "id": "perm_1", "key": "view:invoices", "label": "Rechnungen ansehen", "state": "ALLOW" },
          { "id": "perm_2", "key": "create:invoices", "label": "Rechnungen erstellen", "state": "ALLOW" },
          { "id": "perm_3", "key": "delete:invoices", "label": "Rechnungen löschen", "state": "INHERIT" }
        ]
      }
    ]
  }
}

PUT/api/roles/[id]/permissionsRequires: manage:roles

Die Berechtigungsstatus für eine Rolle aktualisieren. Sende ein Array von Berechtigungsstatus-Objekten. Berechtigungen, die nicht im Array enthalten sind, werden unverändert belassen.

Anforderungs-Body


{
  "permissions": [
    { "permissionId": "perm_1", "state": "ALLOW" },
    { "permissionId": "perm_3", "state": "DENY" }
  ]
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "updated": 2,
    "permissions": [
      { "id": "perm_1", "key": "view:invoices", "state": "ALLOW" },
      { "id": "perm_3", "key": "delete:invoices", "state": "DENY" }
    ]
  }
}

Berechtigungsprüfung

POST/api/roles/checkRequires: authenticated user

Prüfen, ob der aktuell authentifizierte Benutzer eine Reihe von Berechtigungen hat. Löst Berechtigungen durch den vollständigen RBAC-Stack auf: direkte Benutzerüberschreibungen, Rollenzuweisungen und Standardrichtlinien. Optional auf eine bestimmte Anwendung beschränkt.

Dieser Endpunkt wird von Ressourcenservern (einschließlich des Auris-Dashboards) verwendet, um die Autorisierung vor der Durchführung von Operationen zu erzwingen.

Anforderungs-Body


{
  "permissions": ["view:invoices", "create:invoices", "approve:expenses"],
  "applicationId": "app_abc123"
}

applicationId ist optional. Wenn angegeben, werden nur Berechtigungen überprüft, die für den Scope dieser Anwendung konfiguriert sind.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "permissions": {
      "view:invoices": true,
      "create:invoices": true,
      "approve:expenses": false
    }
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`VALIDATION_ERROR`	400	`permissions` ist kein Array von Zeichenketten

FGA — Autorisierungsmodelle

Die Feingranulare-Autorisierungs-Engine verwendet ein DSL-basiertes Modell zur Definition von Objekttypen, Relationen und Umschreibungsregeln. Bevor Tupel geschrieben werden, muss ein Autorisierungsmodell erstellt und aktiviert werden.

Alle FGA-Endpunkte erfordern den x-tenant-Header.

GET/api/fga/modelsRequires: manage:fga_models

Alle Autorisierungsmodelle für den Tenant auflisten. Es kann immer nur ein Modell aktiv sein.

Erfolgsantwort


{
  "ok": true,
  "data": [
    {
      "id": "model_abc123",
      "name": "SaaS-Autorisierungsmodell",
      "version": 3,
      "isActive": true,
      "createdAt": "2025-02-10T00:00:00Z"
    }
  ]
}

POST/api/fga/modelsRequires: manage:fga_models

Ein neues Autorisierungsmodell erstellen, indem eine DSL-Definition bereitgestellt wird. Das DSL wird vor der Speicherung geparst und validiert. Wenn die Validierung fehlschlägt, wird eine detaillierte Fehlermeldung zurückgegeben.

Anforderungs-Body


{
  "name": "Dokumentzugriffsmodell",
  "dsl": "type user\n\ntype document\n  relations\n    define owner: [user]\n    define viewer: [user] or owner\n"
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "model_def456",
    "name": "Dokumentzugriffsmodell",
    "version": 1,
    "isActive": false,
    "schema": {
      "typeDefinitions": [
        { "type": "user", "relations": {} },
        { "type": "document", "relations": { "owner": { "this": {} }, "viewer": { "union": {} } } }
      ]
    }
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`DSL_PARSE_ERROR`	400	DSL-Syntax ist ungültig — Fehler enthält Zeilennummer und Beschreibung
`DSL_VALIDATION_ERROR`	400	DSL ist syntaktisch korrekt, referenziert aber undefinierte Typen oder Relationen

GET/api/fga/models/[id]Requires: view:fga_models

Ein bestimmtes Autorisierungsmodell abrufen, einschließlich seines vollständigen geparsten Schemas und DSL-Textes.

PUT/api/fga/models/[id]Requires: manage:fga_models

Den Namen oder das DSL eines Modells aktualisieren. Das DSL wird bei der Aktualisierung erneut geparst und validiert.

POST/api/fga/models/[id]/activateRequires: manage:fga_models

Dieses Modell als aktives Autorisierungsmodell für den Tenant setzen. Deaktiviert alle zuvor aktiven Modelle. Alle nachfolgenden check-, expand- und list-objects-Aufrufe verwenden dieses Modell.

Anforderung: Kein Body erforderlich.

Erfolgsantwort


{
  "ok": true,
  "data": { "activated": true, "modelId": "model_def456" }
}

FGA — Beziehungs-Tupel

Tupel sind die Fakten des Autorisierungssystems. Jedes Tupel stellt fest, dass ein Subjekt eine Beziehung zu einem Objekt hat.

Tupel-Format: objektTyp:objektId#relation@subjektTyp:subjektId

Beispiel: document:readme#viewer@user:alice — Benutzer alice ist ein viewer des Dokuments readme.

GET/api/fga/tuplesRequires: view:fga_tuples

Beziehungs-Tupel auflisten, mit optionaler Filterung.

Abfrageparameter

Parameter	Typ	Beschreibung
`objectType`	string	Nach Objekttyp filtern (z.B. `document`)
`objectId`	string	Nach Objekt-ID filtern
`relation`	string	Nach Relationsname filtern
`subjectType`	string	Nach Subjekttyp filtern
`subjectId`	string	Nach Subjekt-ID filtern
`page`	integer	Seitennummer
`limit`	integer	Elemente pro Seite

Erfolgsantwort


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "tuple_abc",
        "objectType": "document",
        "objectId": "readme",
        "relation": "viewer",
        "subjectType": "user",
        "subjectId": "alice",
        "createdAt": "2025-02-15T10:00:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
  }
}

POST/api/fga/tuplesRequires: manage:fga_tuples

Ein einzelnes Beziehungs-Tupel schreiben. Das Tupel wird vor der Speicherung gegen das aktive Autorisierungsmodell validiert.

Anforderungs-Body


{
  "objectType": "document",
  "objectId": "readme",
  "relation": "viewer",
  "subjectType": "user",
  "subjectId": "alice"
}

Für Subjektmengen-Referenzen (z.B. “alle Mitglieder der Gruppe Engineering können ansehen”):


{
  "objectType": "document",
  "objectId": "readme",
  "relation": "viewer",
  "subjectType": "group",
  "subjectId": "engineering",
  "subjectRelation": "member"
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "tuple_abc",
    "objectType": "document",
    "objectId": "readme",
    "relation": "viewer",
    "subjectType": "user",
    "subjectId": "alice"
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`NO_ACTIVE_MODEL`	400	Kein aktives Autorisierungsmodell zur Validierung
`INVALID_RELATION`	400	Relation existiert nicht auf diesem Objekttyp im aktiven Modell
`TUPLE_EXISTS`	409	Ein identisches Tupel existiert bereits (idempotentes Schreiben bevorzugt — Bulk verwenden)

DELETE/api/fga/tuplesRequires: manage:fga_tuples

Ein bestimmtes Beziehungs-Tupel löschen, indem die Tupeldaten im Anforderungs-Body angegeben werden.

Anforderungs-Body


{
  "objectType": "document",
  "objectId": "readme",
  "relation": "viewer",
  "subjectType": "user",
  "subjectId": "alice"
}

Erfolgsantwort


{
  "ok": true,
  "data": { "deleted": true }
}

POST/api/fga/tuples/bulkRequires: manage:fga_tuples

Mehrere Tupel in einer einzigen Anforderung schreiben oder löschen. Operationen werden atomar verarbeitet — wenn eine Operation die Validierung nicht besteht, wird die gesamte Massenanforderung abgelehnt.

Anforderungs-Body


{
  "writes": [
    {
      "objectType": "document",
      "objectId": "readme",
      "relation": "editor",
      "subjectType": "user",
      "subjectId": "bob"
    }
  ],
  "deletes": [
    {
      "objectType": "document",
      "objectId": "readme",
      "relation": "viewer",
      "subjectType": "user",
      "subjectId": "alice"
    }
  ]
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "written": 1,
    "deleted": 1
  }
}

FGA — Autorisierungsabfragen

POST/api/fga/checkRequires: debug:fga

Prüfen, ob ein Subjekt eine bestimmte Beziehung zu einem Objekt hat. Wertet die vollständigen Umschreibungsregeln rekursiv aus. Gibt optional den Auflösungsbaum zum Debuggen zurück.

Anforderungs-Body


{
  "objectType": "document",
  "objectId": "readme",
  "relation": "viewer",
  "subjectType": "user",
  "subjectId": "alice",
  "explain": true
}

Setze explain: true, um den Auflösungsbaum zu erhalten (nützlich zum Debuggen, warum eine Prüfung bestanden oder nicht bestanden hat).

Erfolgsantwort


{
  "ok": true,
  "data": {
    "allowed": true,
    "resolution": {
      "type": "union",
      "result": true,
      "children": [
        {
          "type": "this",
          "relation": "viewer",
          "result": true,
          "tupleFound": "document:readme#viewer@user:alice"
        }
      ]
    }
  }
}

POST/api/fga/expandRequires: debug:fga

Eine Relation erweitern, um alle Subjekte (Benutzer oder Benutzermengen) aufzulisten, die eine bestimmte Beziehung zu einem Objekt haben. Gibt eine Baumstruktur zurück, die den Umschreibungsregeln folgt.

Anforderungs-Body


{
  "objectType": "document",
  "objectId": "readme",
  "relation": "viewer"
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "tree": {
      "root": {
        "type": "union",
        "nodes": [
          {
            "type": "leaf",
            "subjects": [
              { "type": "user", "id": "alice" },
              { "type": "user", "id": "bob" }
            ]
          },
          {
            "type": "computed_userset",
            "relation": "owner",
            "subjects": [{ "type": "user", "id": "charlie" }]
          }
        ]
      }
    }
  }
}

POST/api/fga/list-objectsRequires: debug:fga

Alle Objekte eines bestimmten Typs auflisten, auf die ein Subjekt über eine bestimmte Relation zugreifen kann. Verwendet Reverse-Lookup durch den Tupel-Speicher und Umschreibungsregeln.

Anforderungs-Body


{
  "objectType": "document",
  "relation": "viewer",
  "subjectType": "user",
  "subjectId": "alice"
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "objectIds": ["readme", "api-spec", "changelog"],
    "total": 3
  }
}

Die Endpunkte check, expand und list-objects erfordern debug:fga, da sie die interne Autorisierungsmodellstruktur offenlegen. In der Produktion sollten Ressourcenserver diese Endpunkte mit einem M2M-Token mit dieser Berechtigung aufrufen, anstatt sie für Endbenutzer freizugeben.

Zugehörige Referenzen

Rollen & Berechtigungen Leitfaden — Wie RBAC in Auris funktioniert
Feingranulare Autorisierung — Erweiterte Autorisierung mit FGA
Benutzer & Rollen — Rollen über die Konsole zuweisen
Feingranulare Autorisierungs-API — Zanzibar-style Autorisierungsprüfungen