Zum Inhalt springen

Autorisierung: wer welches Tool aufrufen darf

Autorisierung ist standardmäßig aktiv und braucht kein Setup. Jeder Tool-Call wird geprüft, bevor er läuft, und jede Tool-Liste zeigt einem Aufrufer nur die Tools, die er aufrufen darf. Wer was darf, legen Sie in den Begriffen fest, die ToolMesh schon aus der Authentifizierung kennt: Benutzer, Rollen, Pläne und Firmen.

Die Engine ist OpenFGA. ToolMesh betreibt sie im eigenen Prozess und speichert ihre Daten in authz.db im Datenverzeichnis. Es gibt keinen zusätzlichen Dienst, den Sie installieren oder betreiben müssen.

Für Rechte, die eine Aufgabe nur für eine Weile braucht, definieren Sie Koffer: Ein Mensch gibt sie auf Anfrage befristet frei und signiert die Freigabe.

  • jeder direkte Tool-Call,
  • jeder api.*-Aufruf in einem Code-Mode-Script,
  • jede Tool-Liste (tools/list, discover_tools, toolmesh.discover): Ein Aufrufer sieht nur, was er ausführen darf.

Die Prüfung läuft, bevor Credentials injiziert werden und bevor das Backend aufgerufen wird. Ein abgelehnter Aufruf liefert ein Fehlerergebnis und wird mit dem Status denied auditiert. Die Prüfung ist fail-closed: Lässt sie sich nicht beantworten, wird der Aufruf abgelehnt.

TOOLMESH_AUTHZ_MODE legt fest, wie die Prüfung beantwortet wird:

ModusVerhalten
embedded (Standard)ToolMesh beantwortet die Prüfungen selbst. Grants kommen aus einem Preset oder aus config/authz.yaml.
externalPrüfungen gehen an einen OpenFGA-Server, den Sie betreiben. ToolMesh liest dort nur.
disabledKeine Prüfungen. Der einzige Weg, Autorisierung abzuschalten; bei jedem Start gemeldet und im Audit-Trail festgehalten.

Ohne Grants-Datei entscheidet ein Preset, wer was darf:

PresetWer was darf
single-userDer Owner (TOOLMESH_AUTH_USER, Standard owner) und jeder Aufrufer mit der Rolle admin: jedes Tool. Alle anderen: nichts.
teamWie single-user, dazu Plan pro: jedes Tool; Plan free: jedes Tool, dessen DADL-Access-Klassifizierung read ist.
openJeder authentifizierte Aufrufer: jedes Tool. Wird bei jedem Start als gelockerte Kontrolle gemeldet.

Die Grants kommen aus dem ersten dieser Punkte, der zutrifft:

  1. der Grants-Datei (config/authz.yaml), wenn sie existiert;
  2. dem Preset aus TOOLMESH_AUTHZ_PRESET;
  3. dem Preset open, für eine Installation, die von einer Version ohne Autorisierung aktualisiert wurde;
  4. dem Preset team, wenn users.yaml oder apikeys.yaml existiert, sonst single-user.

Das einzelne Passwort oder der API-Key aus dem Quick Start meldet sich als Benutzer owner mit Plan pro und Rolle admin an. Jedes Preset erlaubt diesem Aufrufer also jedes Tool. Eine frische Installation funktioniert ohne Autorisierungs-Setup; andere Aufrufer bekommen nichts, bis ein Grant sie nennt.

Die Logzeile authorization policy applied zeigt, welches Preset gilt, woher die Grants stammen (file, env, upgrade, default) und wie viele es sind.

Für feinere Kontrolle kopieren Sie config/authz.yaml.example nach config/authz.yaml:

preset: single-user # optional: start from a preset and add to it
grants:
- plan: pro
backends: [github, deepl]
- plan: free
access: [read]
- role: support
tools: [zammad_list_tickets, zammad_get_ticket]
- company: acme
backends: [netbox]
- user: alice
all_tools: true
denies: # optional: blocks that win over every grant
- user: alice
tools: [stripe_create_refund]
- role: contractor
backends: [stripe]

Jeder Grant nennt genau ein Subjekt:

SubjektWen es meint
user: <id>Einen Benutzer: username in users.yaml, user_id in apikeys.yaml oder TOOLMESH_AUTH_USER
role: <name>Jeden Aufrufer mit dieser Rolle: roles in users.yaml oder apikeys.yaml, TOOLMESH_AUTH_ROLES
plan: <name>Jeden Aufrufer in diesem Plan: plan in users.yaml oder apikeys.yaml, TOOLMESH_AUTH_PLAN
company: <id>Jeden Aufrufer dieser Firma: company in users.yaml, company_id in apikeys.yaml
everyone: trueJeden authentifizierten Aufrufer

Und mindestens ein Ziel:

ZielWas es erlaubt
all_tools: trueJedes Tool, auch Tools von später hinzugefügten Backends
backends: [...]Jedes Tool dieser Backends, mit ihrem Namen aus backends.yaml (echo für die eingebauten Tools)
tools: [...]Einzelne Tools, mit vollem Namen <backend>_<tool>
access: [...]Jedes Tool, dessen DADL-Access-Klassifizierung einer dieser Werte ist (read, write, admin, dangerous oder ein eigener Wert)

Ein backends-Grant gilt für das Backend, an das ein Aufruf tatsächlich geroutet wird: Bei den Backends web und web_search deckt ein Grant auf web den Aufruf web_search_query nicht ab.

Es gibt nichts zu synchronisieren. Rollen, Pläne und Firmen bleiben dort konfiguriert, wo sie heute stehen; ein Benutzer, der in users.yaml in einen anderen Plan wechselt, wird beim nächsten Aufruf gegen die Grants dieses Plans geprüft.

Ein Deny hat dieselbe Form wie ein Grant und sperrt, was er nennt, für sein Subjekt, egal was ein Grant oder das Preset erlaubt: Ein Deny gewinnt immer. Damit nehmen Sie einem Subjekt, das sonst alle Tools hat, einzelne Tools oder Backends wieder weg, zum Beispiel alice oben, die jedes Tool behält außer stripe_create_refund. Ein gesperrtes Tool wird mit einem Fehler abgelehnt, als denied auditiert und diesem Aufrufer nicht mehr gelistet. Denies gibt es nur in der Grants-Datei; Presets haben keine.

ToolMesh liest die Datei beim Start und erneut wenige Sekunden nach jeder Änderung, auch wenn sie angelegt oder gelöscht wird. Aufrufe, die nach dem Übernehmen einer Änderung beginnen, werden gegen die neuen Regeln geprüft; während eine Änderung übernommen wird, ist kein Aufruf erlaubt, den weder die alten noch die neuen Regeln erlauben. Eine Datei, die sich nicht parsen lässt, oder ein Grant oder Deny ohne Subjekt oder Ziel stoppt den Server beim Start; bei einer späteren Änderung wird der Fehler geloggt und die Regeln bleiben, wie sie waren.

Ein Koffer (englisch kit) ist ein benanntes Bündel von Tools, das ein Aufrufer als Ganzes und befristet bekommt, definiert in derselben Datei unter kits:, zum Beispiel alles, was eine Netzdiagnose lesen muss. Ein Koffer erlaubt für sich nichts: Der Agent fragt mit request_grant danach, ein unter approvers: gelisteter Approver gibt ihn auf der Freigabeseite mit einer Signatur oder über die Approver-API frei, und der Grant endet von selbst. Discovery listet die Tools eines Koffers mit der Markierung grant_required, ein abgelehnter Aufruf nennt die Koffer, die ihn erlauben würden, und tell_me_my_rights sagt einem Aufrufer, was er darf und welche Koffer den Rest abdecken würden. Ein Deny gewinnt gegen einen Koffer wie gegen jeden Grant. Der ganze Weg, von der Definition bis zum Audit-Eintrag, steht unter Koffer und Freigaben.

DADL-Tools deklarieren eine access-Klassifizierung, auf die sich das Ziel access eines Grants bezieht:

LevelBedeutung
readNur-Lese-Operationen
writeErstell-/Update-Operationen
adminAdministrative Operationen
dangerousDestruktive oder irreversible Operationen
customMit beliebigen String-Werten erweiterbar

Tools ohne Klassifizierung, darunter die meisten Tools von MCP-Backends, deckt ein access-Grant nicht ab. Geben Sie sie per Backend oder per Name frei.

Bis Version 0.4 war Autorisierung aus, solange nicht OPENFGA_MODE=restrict gesetzt war. Damit ein Upgrade niemanden aussperrt, erkennt ToolMesh eine solche Installation beim ersten Start der neuen Version: wenn TOOLMESH_AUTHZ_MODE nicht gesetzt ist und entweder OPENFGA_MODE=bypass gesetzt ist oder das Datenverzeichnis schon Daten aus einem früheren Lauf enthält. Dann bleibt jedes Tool für jeden authentifizierten Aufrufer offen (Preset open), und ToolMesh meldet das bei jedem Start, bis Sie TOOLMESH_AUTHZ_PRESET setzen oder config/authz.yaml anlegen.

Soll eine aktualisierte Installation stattdessen mit den restriktiven Standardwerten starten, setzen Sie TOOLMESH_AUTHZ_MODE=embedded vor ihrem ersten Start mit der neuen Version, oder setzen Sie TOOLMESH_AUTHZ_PRESET.

OPENFGA_MODE ist veraltet. Es wird nur gelesen, solange TOOLMESH_AUTHZ_MODE nicht gesetzt ist: restrict wählt external, bypass wählt embedded. Solange es gesetzt ist, loggt ToolMesh eine Warnung; entfernen Sie es aus der .env.

  • Datenverzeichnis. Es muss beschreibbar sein und sollte persistent sein, wie im mitgelieferten docker-compose.yml (./data).
  • Backups. Sichern Sie authz.db und die Marker-Datei .authz-bootstrap mit dem Rest des Datenverzeichnisses. Die Grants werden bei jedem Start aus Ihrer Konfiguration geschrieben, eine verlorene authz.db entsteht also ohne Verlust neu; die Marker-Datei hält die Upgrade-Entscheidung des ersten Starts fest.
  • Ein Prozess pro Datenverzeichnis. Zwei ToolMesh-Instanzen dürfen sich keine authz.db teilen.
  • Kosten. Eine Prüfung dauert etwa 0,5 bis 0,6 ms. Tools ohne eigene Grants oder Denies, die Backend und Access-Klassifizierung teilen, werden gemeinsam entschieden; das Filtern einer Liste mit 3.000 Tools dauert so etwa 115 ms.

TOOLMESH_AUTHZ_MODE=external schickt jede Prüfung an einen OpenFGA-Server, den Sie betreiben, zum Beispiel einen, den mehrere Anwendungen teilen:

Terminal-Fenster
TOOLMESH_AUTHZ_MODE=external
OPENFGA_API_URL=http://openfga:8080
OPENFGA_STORE_ID=your-store-id

ToolMesh liest von diesem Server nur: Es schreibt weder ein Modell noch Tuples, und Presets sowie config/authz.yaml gelten nicht. Jede Prüfung fragt, ob user:<user ID> die Relation can_execute auf tool:<backend>_<tool> hat; Modell und Tuples gehören Ihnen. config/openfga/ im ToolMesh-Repository enthält ein Beispielmodell, Tuples und ein Setup-Script, und docker-compose.yml enthält auskommentierte OpenFGA-Services für diesen Modus.

TOOLMESH_AUTHZ_MODE=disabled ist der einzige Weg, die Prüfungen abzuschalten. Dann darf jeder authentifizierte Aufrufer jedes Tool aufrufen; die Authentifizierung gilt weiterhin. ToolMesh meldet das bei jedem Start in der Security-Posture-Zusammenfassung und schreibt einen Audit-Eintrag mit dem Status authz_disabled (Tool toolmesh_authz). So zeigt der Audit-Trail, ab wann Aufrufe ungeprüft liefen.

Grants entscheiden danach, wer aufruft, nicht mit welchem Client. Um einzuschränken, was eine Klasse von Clients darf, etwa untrusted-Aufrufern nur read-Tools zu erlauben, egal was ihr Plan zulässt, nutzen Sie eine Output-Gate-Policy auf ctx.user.callerClass. Das ToolMesh-Repository liefert config/policies/examples/prod-access-by-caller-class.js mit, eine Pre-Execution-Policy, die einen Aufruf nur durchlässt, wenn die Klasse des Aufrufers die DADL-Access-Klasse des Tools nutzen darf, und unbekannte Klassen sowie unklassifizierte Tools mit einer Begründung ablehnt, die Tool und Klasse nennt. Eine solche Policy weicht einem Koffer, den der Aufrufer hält, denn ein Approver hat für diesen Aufrufer und diesen Koffer entschieden; siehe Policies und Koffer.