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.
Was geprüft wird
Abschnitt betitelt „Was geprüft wird“- 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:
| Modus | Verhalten |
|---|---|
embedded (Standard) | ToolMesh beantwortet die Prüfungen selbst. Grants kommen aus einem Preset oder aus config/authz.yaml. |
external | Prüfungen gehen an einen OpenFGA-Server, den Sie betreiben. ToolMesh liest dort nur. |
disabled | Keine Prüfungen. Der einzige Weg, Autorisierung abzuschalten; bei jedem Start gemeldet und im Audit-Trail festgehalten. |
Presets
Abschnitt betitelt „Presets“Ohne Grants-Datei entscheidet ein Preset, wer was darf:
| Preset | Wer was darf |
|---|---|
single-user | Der Owner (TOOLMESH_AUTH_USER, Standard owner) und jeder Aufrufer mit der Rolle admin: jedes Tool. Alle anderen: nichts. |
team | Wie single-user, dazu Plan pro: jedes Tool; Plan free: jedes Tool, dessen DADL-Access-Klassifizierung read ist. |
open | Jeder authentifizierte Aufrufer: jedes Tool. Wird bei jedem Start als gelockerte Kontrolle gemeldet. |
Die Grants kommen aus dem ersten dieser Punkte, der zutrifft:
- der Grants-Datei (
config/authz.yaml), wenn sie existiert; - dem Preset aus
TOOLMESH_AUTHZ_PRESET; - dem Preset
open, für eine Installation, die von einer Version ohne Autorisierung aktualisiert wurde; - dem Preset
team, wennusers.yamloderapikeys.yamlexistiert, sonstsingle-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.
Grants: config/authz.yaml
Abschnitt betitelt „Grants: config/authz.yaml“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:
| Subjekt | Wen 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: true | Jeden authentifizierten Aufrufer |
Und mindestens ein Ziel:
| Ziel | Was es erlaubt |
|---|---|
all_tools: true | Jedes 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.
Änderungen an der Datei
Abschnitt betitelt „Änderungen an der Datei“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-Access-Klassen
Abschnitt betitelt „DADL-Access-Klassen“DADL-Tools deklarieren eine access-Klassifizierung, auf die sich das Ziel access eines Grants bezieht:
| Level | Bedeutung |
|---|---|
read | Nur-Lese-Operationen |
write | Erstell-/Update-Operationen |
admin | Administrative Operationen |
dangerous | Destruktive oder irreversible Operationen |
| custom | Mit 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.
Upgrade von einer Version ohne Autorisierung
Abschnitt betitelt „Upgrade von einer Version ohne Autorisierung“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.
Betrieb
Abschnitt betitelt „Betrieb“- Datenverzeichnis. Es muss beschreibbar sein und sollte persistent sein, wie im mitgelieferten
docker-compose.yml(./data). - Backups. Sichern Sie
authz.dbund die Marker-Datei.authz-bootstrapmit dem Rest des Datenverzeichnisses. Die Grants werden bei jedem Start aus Ihrer Konfiguration geschrieben, eine verloreneauthz.dbentsteht 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.dbteilen. - 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.
External Mode
Abschnitt betitelt „External Mode“TOOLMESH_AUTHZ_MODE=external schickt jede Prüfung an einen OpenFGA-Server, den Sie betreiben, zum Beispiel einen, den mehrere Anwendungen teilen:
TOOLMESH_AUTHZ_MODE=externalOPENFGA_API_URL=http://openfga:8080OPENFGA_STORE_ID=your-store-idToolMesh 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.
Autorisierung abschalten
Abschnitt betitelt „Autorisierung abschalten“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.
Caller-Class
Abschnitt betitelt „Caller-Class“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.