Zum Inhalt springen

Authentifizierung: OAuth 2.1, API-Keys, Multi-User

ToolMesh bietet ein produktionsreifes Authentifizierungssystem mit mehreren Modi, von einfachen Single-User-Setups bis zu vollem Multi-User-OAuth. Ohne konfiguriertes Credential wird jede Anfrage abgelehnt (siehe Kein Credential konfiguriert).

Schnellstart mit Umgebungsvariablen:

Terminal-Fenster
TOOLMESH_AUTH_PASSWORD=changeme # Single-User-OAuth-Passwort
TOOLMESH_API_KEY=sk-my-key # Statischer API-Key

Vollständiges OAuth 2.1 mit PKCE S256 für interaktiven Login:

  • Benutzer in config/users.yaml definiert (bcrypt-gehashte Passwörter)
  • Jeder Benutzer hat: Username, Company, Plan, Roles
  • Dynamic Client Registration (DCR), begrenzt auf 5 Registrierungen pro Stunde von einer Client-Adresse
  • Eine Login-Seite, die nennt, wohin die Autorisierung geht, und den Benutzer um Bestätigung bittet (siehe Die Login-Seite)
  • Redis/KeyDB für State-Persistenz (Tokens, Auth-Codes, Client-Registrierungen)
config/users.yaml
users:
- username: alice
password_hash: "$2a$12$..." # bcrypt-Hash
company: acme
plan: pro
roles: [admin]

ToolMesh liest users.yaml beim Start: Änderungen daran wirken nach einem Neustart (siehe Tokens).

Für programmatischen Zugriff. Jeder Eintrag benennt seinen Key über den SHA-256 des Keys oder über einen bcrypt-Hash:

config/apikeys.yaml
keys:
- key_sha256: "<SHA-256 of the key, 64 hex characters>"
user_id: ci-bot
company_id: acme
plan: standard
roles: [read]
caller_id: github-actions

Key und Wert für key_sha256 erzeugen:

Terminal-Fenster
KEY="tm_$(openssl rand -hex 32)"
printf '%s' "$KEY" | sha256sum | cut -d' ' -f1

Jeder API-Key trägt seine eigene Identität (User, Company, Plan, Roles), die durch die gesamte Pipeline fließt.

key_sha256 wird ab der ersten Anfrage in einer Tabelle nachgeschlagen und ist für zufällig erzeugte Keys ab 128 Bit gedacht; ein von einem Menschen gewählter oder kurzer Key ließe sich aus einer durchgesickerten Datei weit schneller erraten als über bcrypt, also behalten Sie so einen Key als key_hash oder ersetzen Sie ihn. Dateien mit bcrypt-key_hash-Einträgen, wie frühere Versionen sie geschrieben haben, funktionieren unverändert weiter: Ein solcher Eintrag wird beim ersten Vorzeigen seines Keys nach dem Start per bcrypt verglichen und danach nachgeschlagen. Bis dahin kostet jedes Bearer-Credential, das sonst nichts erkennt, einen Vergleich je solchem Eintrag; deshalb loggt ToolMesh beim Start eine Warnung, solange eine Datei Einträge nur mit key_hash hat. Ergänzen Sie key_sha256 im Eintrag, um diese Kosten loszuwerden; key_hash darf daneben stehen bleiben.

Ein Bearer-Credential wird in dieser Reihenfolge geprüft: die Nachschlagetabelle der API-Keys (oder der einzelne TOOLMESH_API_KEY), dann die Access-Tokens im Token-Store, und erst dann, per bcrypt-Vergleich, die noch nicht gesehenen Einträge nur mit key_hash. Ein gültiges Access-Token kostet also nie einen bcrypt-Vergleich, und ein API-Key hängt nicht davon ab, dass der Token-Store erreichbar ist. Fehlgeschlagene API-Keys sind je Client-Adresse begrenzt (siehe Drosselung von API-Keys).

Die Schlüssel der Approver, die Koffer freigeben, sind davon getrennt: Ein Approver-Schlüssel funktioniert nur auf der Approver-API, und ein MCP-Credential gibt nie frei.

Die authentifizierte Identität fließt durch jeden Schritt:

Authentication → CallerID → OpenFGA AuthZ → Credential Store → Audit Trail

Das stellt volle Nachvollziehbarkeit sicher: Jeder Tool-Call wird einem bestimmten Benutzer zugeordnet, mit einem bestimmten Plan, von einem bestimmten Client.

Eine Anfrage an /mcp ohne gültiges Credential wird mit 401 Unauthorized und einer WWW-Authenticate: Bearer-Challenge beantwortet, die auf die OAuth-Protected-Resource-Metadaten des Endpunkts zeigt (/.well-known/oauth-protected-resource/mcp), wie die MCP-Autorisierungsspezifikation es verlangt. MCP-Clients reagieren auf den Status: Sie starten den OAuth-Flow oder erneuern ein abgelaufenes Token und versuchen es erneut. Der Body ist der JSON-RPC-Fehler -32001. Setzen Sie TOOLMESH_ISSUER auf die öffentliche URL, die Clients verwenden, denn die Metadaten nennen sie. Ein Reverse-Proxy muss 401 und den WWW-Authenticate-Header unverändert durchreichen, und für Origins in TOOLMESH_CORS_ORIGINS wird der Header für Browser freigegeben.

Eine Anfrage, deren Credential sich gerade nicht prüfen lässt, weil der Token-Store ausgefallen ist oder kein Passwort-Hash-Vergleich gestartet werden konnte, bekommt stattdessen 503 Service Unavailable mit Retry-After. Das sagt nichts über das Credential; ein 401 brächte einen Client dazu, ein noch gültiges Token zu verwerfen. /files/upload und DELETE /blobs/… antworten in denselben Fällen mit 401 und 503.

Abgewiesene Anfragen werden mit INFO geloggt (mcp request rejected: unauthorized) und in toolmesh_logins_total{method="anonymous"} gezählt.

Ein Server ohne jedes Credential (kein TOOLMESH_AUTH_PASSWORD, TOOLMESH_API_KEY, users.yaml oder apikeys.yaml) weist jede Anfrage an /mcp, /files/upload und DELETE /blobs/… mit 401 ab. Ist kein Passwort konfiguriert, antwortet /authorize mit 403 statt mit einem Login-Formular, und es werden keine Tokens ausgestellt oder anerkannt.

Die Login-Seite unter /authorize nennt den Host der redirect_uri des Clients, also das Ziel der Autorisierung, und den Namen, den sich der Client bei der Registrierung selbst gegeben hat, mit dem Hinweis, dass ToolMesh ihn nicht geprüft hat. Vor der Anmeldung setzt der Benutzer das Häkchen bei I trust <host> with access to my ToolMesh tools; die Schaltfläche heißt Authorize <host>. Das Häkchen ist nie vorausgewählt. Ein Login ohne diese Bestätigung wird abgewiesen, bevor das Passwort angesehen wird, und zählt nicht als fehlgeschlagener Login.

  • Skriptgesteuerte Logins, etwa Smoke-Tests mit curl, senden confirm_host=<redirect host> zusammen mit Benutzername und Passwort.
  • Redirect-Hosts einschränken. Jeder Client kann sich mit jeder https-redirect_uri registrieren. Auf einem Server, der nur bekannte Clients bedient, empfiehlt sich TOOLMESH_OAUTH_REDIRECT_HOSTS: claude.ai,claude.com für Claude, chatgpt.com für ChatGPT. Die Variable wird unter /register und erneut unter /authorize geprüft und gilt damit auch für früher registrierte Clients. Loopback-Redirect-URIs nativer Clients wie Claude Code sind immer erlaubt.
  • Abgewiesene Redirect-URIs. Eine Redirect-URI mit Fragment, ohne Host (https:host/callback) oder mit einem Host aus Nicht-ASCII-Zeichen wird unter /register und /authorize abgewiesen; ein solcher Host funktioniert in seiner Punycode-Form. Ein Client, der sich früher mit einer solchen URI registriert hat, muss sich neu registrieren.

Abgewiesene Logins werden als login failed geloggt, mit dem Grund consent_not_confirmed (keine Bestätigung) oder redirect_host_not_allowed (Host nicht in TOOLMESH_OAUTH_REDIRECT_HOSTS).

Ein Access-Token lebt eine Stunde, ein Refresh-Token sieben Tage; jeder Refresh stellt ein neues Paar aus. Ein Refresh-Token wird nach Ablauf seiner sieben Tage abgewiesen, auch nach einem Neustart.

  • Geprüft gegen die aktuellen Benutzer. Jedes Access-Token und jeder Refresh wird gegen die geltende Benutzerkonfiguration geprüft: users.yaml, wenn sie geladen ist, sonst das einzelne Passwort. Ein Benutzer, der aus users.yaml entfernt wurde oder dessen password_hash nicht mehr verwendbar ist (etwa "!"), verliert den Zugang mit der nächsten Anfrage, auch in laufenden Sitzungen, und kein Refresh gelingt mehr für ihn. Geänderte Rollen, Pläne und Companies gelten für bestehende Tokens. Im Single-Password-Modus gilt dasselbe, wenn sich TOOLMESH_AUTH_USER ändert.
  • Änderungen wirken nach einem Neustart. users.yaml und die Variablen TOOLMESH_AUTH_* werden beim Start gelesen. Um eine Sitzung schon vor dem Neustart zu beenden, lassen sich ihre Tokens widerrufen.
  • Eine Passwortänderung beendet Sitzungen. Tokens sind an einen Fingerabdruck des Credentials gebunden, mit dem sich der Benutzer angemeldet hat. Nach einer Passwortänderung und dem Neustart, der sie lädt, enden die für das alte Passwort ausgestellten Sitzungen mit ihrer nächsten Anfrage oder ihrem nächsten Refresh.
  • Widerruf. POST /revoke (RFC 7009) nimmt token=<access or refresh token> und widerruft beide Tokens des Paars. Die Antwort ist 200, auch für ein unbekanntes Token. Wer ein Token besitzt, kann es widerrufen; die OAuth-Metadaten nennen den Endpunkt als revocation_endpoint.

Tokens, die eine Version vor 0.6.0 ausgestellt hat, tragen noch keinen Fingerabdruck. Sie werden angenommen und bei ihrem nächsten Refresh an das dann geltende Credential gebunden. Ein solches Token übersteht deshalb eine Passwortänderung nach dem Upgrade: Es wird erneuert und an das neue Passwort gebunden. Ein späteres Release schließt diese Lücke. Bis dahin gibt es bei Verdacht auf Missbrauch einer Sitzung, die älter als das Upgrade ist, zwei Wege: ihre Tokens mit POST /revoke widerrufen (dafür wird der Wert des Tokens gebraucht) oder alle Sitzungen beenden, indem die gespeicherten Tokens gelöscht werden, während ToolMesh gestoppt ist:

  • Ohne Redis: oauth-state.json im Datenverzeichnis löschen. Die Datei enthält auch die registrierten OAuth-Clients; die Clients registrieren sich also neu, und alle Benutzer melden sich neu an.
  • Mit Redis: die Redis-Schlüssel oauth:token:* und oauth:refresh:* und oauth-state.json im Datenverzeichnis löschen. Nur eines von beiden zu löschen reicht nicht: Beim Start kopiert ToolMesh die Tokens aus oauth-state.json zurück nach Redis, und im Betrieb liest es zuerst aus Redis. Die registrierten Clients bleiben in Redis erhalten.
Terminal-Fenster
redis-cli --scan --pattern 'oauth:token:*' | xargs -r redis-cli del
redis-cli --scan --pattern 'oauth:refresh:*' | xargs -r redis-cli del

Mit der mitgelieferten Compose-Datei läuft stattdessen keydb-cli im Service keydb.

Der Passwort-Login unter /authorize begrenzt fehlgeschlagene Versuche: standardmäßig 5 für ein Konto von einer Client-Adresse, 20 für ein Konto von allen Adressen zusammen und 50 von einer Adresse über alle Konten, jeweils innerhalb von 15 Minuten. Ist ein Limit erreicht, werden die Versuche, die es betrifft, mit 429 und Retry-After beantwortet, ohne dass das Passwort geprüft wird, bis das Fenster abgelaufen ist, das mit dem ersten gezählten Fehlversuch begann. Die Variablen stehen unter Konfiguration.

  • Ein unbekannter Benutzername wird gezählt und gesperrt wie ein echter und kostet denselben Passwort-Hash-Vergleich; weder die Sperre noch die Antwortzeit verrät, welche Konten es gibt.
  • Ein falsches Passwort zeigt das Login-Formular erneut, mit 401. Eine Anfrage mit unregistriertem Client oder Redirect-URI wird mit 400 abgewiesen, bevor das Passwort angesehen wird, und zählt nicht; ebenso wenig ein Login ohne die Bestätigung des Redirect-Hosts.
  • Nur neue Passwort-Logins werden verweigert. Schon ausgestellte Access- und Refresh-Tokens funktionieren weiter, ebenso API-Keys, für die ein eigenes Limit gilt.
  • Die Zähler liegen in Redis, wenn es verbunden ist; dann gelten die Limits über Replikas hinweg und überleben einen Neustart. Sonst liegen sie im Prozessspeicher. Ein Redis-Fehler fällt mit einer Warnung auf den Prozessspeicher zurück, statt die Limits aufzuheben.
  • Die Limits je Adresse zählen die Client-Adresse. Bei einem Passwort, das absichtlich viele Menschen teilen, setzen Sie das Limit je Konto auf 0 und behalten Sie die Limits je Adresse.

Jeder fehlgeschlagene Login wird mit WARN geloggt (login failed, mit eingegebenem Benutzernamen, Client-Adresse und Grund; nie das Passwort) und in toolmesh_logins_total{method="password",result="failure"} gezählt.

Fehlgeschlagene Bearer-Credentials an /mcp, /files/upload und DELETE /blobs/… sind je Client-Adresse begrenzt: standardmäßig auf 50 im Zählfenster der Login-Limits (TOOLMESH_APIKEY_MAX_FAILURES_PER_IP; 0 schaltet das Limit ab). Ein Credential reserviert seinen Platz, bevor es geprüft wird, sodass gleichzeitige Versuche nicht alle durchkommen, bevor der erste Fehlschlag gezählt ist; ein angenommenes Credential gibt den Platz zurück. Ist das Limit erreicht, wird jedes Bearer-Credential von dieser Adresse, auch das richtige, bis zum Ende des Fensters mit 429 und Retry-After beantwortet und mit INFO als bearer authentication throttled geloggt. Clients hinter einer gemeinsamen Adresse teilen sich dieses Limit.

Die Zähler liegen in Redis, wenn es verbunden ist, was jede Anfrage mit API-Key zwei kurze Redis-Operationen kostet, sonst im Prozessspeicher. Werte in der Form eines von ToolMesh ausgestellten Access-Tokens (64 Hexadezimalzeichen in Kleinschreibung) reservieren vorab keinen Platz: Sie lassen sich nicht erraten, und abgelaufene kommen routinemäßig an, oft von den gemeinsamen Adressen gehosteter Clients. Ist ihre Adresse gedrosselt, bekommen sie 401 wie jedes unbekannte Token, sodass ein Client mit abgelaufenem Token es weiterhin erneuern kann. Ein API-Key in dieser Form (openssl rand -hex 32 ohne das empfohlene Präfix tm_) wird deshalb ebenfalls nicht gedrosselt; das ist nur unbedenklich, weil ein solcher Key zufällig ist.

Die Client-Adresse zählt für die Limits von Login, API-Keys und Registrierung und erscheint im Request-Log als remote. ToolMesh nimmt sie aus der Verbindung, aus X-Forwarded-For nur dann, wenn die Verbindung von einem vertrauenswürdigen Proxy kommt (TOOLMESH_TRUSTED_PROXIES, standardmäßig nur Loopback). Den Header liest es dann von rechts: Der erste Eintrag, der nicht selbst ein vertrauenswürdiger Proxy ist, ist der Client. Einträge mit Port (203.0.113.7:51234, [2001:db8::7]:51234) oder in eckigen Klammern gelten als Adressen. Ein Eintrag, der keine Adresse ist (unknown, leer), beendet die Auswertung, und der zuletzt gelesene vertrauenswürdige Proxy gilt als Client. IPv6-Adressen werden je /64 gezählt.

TOOLMESH_TRUSTED_PROXIES nennt die Adressen, von denen aus sich die eigenen Reverse-Proxys verbinden, nicht die Netze, in denen die Clients sitzen. Ein Client, dessen eigene Adresse eingetragen ist, kann selbst bestimmen, unter welcher Adresse er gezählt wird.

AufbauEinstellung
Reverse-Proxy auf demselben Host (Caddy, nginx, Traefik als Dienst des Hosts)Keine
Reverse-Proxy in einem Container im selben Compose-NetzDie eigene Adresse des Proxy-Containers, fest vergeben in der Compose-Datei, zum Beispiel TOOLMESH_TRUSTED_PROXIES=172.18.0.10. Nicht das Compose-Netz, siehe Proxy in einem Container.
Proxy oder CDN auf anderen Maschinen (ein Load Balancer, Cloudflare)Seine Adressen oder veröffentlichten Bereiche
Kein Proxy, Ports direkt veröffentlicht mit Rootful Docker unter LinuxKeine: Docker behält die Quelladresse des Clients
Kein Proxy mit Docker Desktop, Rootless Docker oder einem Userland-ProxyJede Verbindung kommt von einer Gateway-Adresse, also teilen sich alle Clients die Limits einer Adresse. Abhilfe: einen Reverse-Proxy vorschalten oder die Limits je Adresse anheben.

Hinter einem Proxy, der nicht eingetragen ist, wird jeder Client unter der Adresse des Proxys gezählt. Die Drosselung bleibt damit wirksam, aber eine Sperre trifft dann alle, und ToolMesh loggt höchstens einmal pro Stunde mit WARN die Meldung X-Forwarded-For from an address that is not a trusted proxy is ignored. Das Startlog nennt die vertrauenswürdigen Adressen (X-Forwarded-For honored from ...), und das Feld remote im Request-Log zeigt, welche Adresse ToolMesh verwendet. Der Proxy direkt vor ToolMesh muss die Adresse des Clients an X-Forwarded-For anhängen, wie es gängige Reverse-Proxys tun. none beachtet X-Forwarded-For überhaupt nicht.

Ein Reverse-Proxy, der als Container neben ToolMesh läuft, wird mit seiner eigenen Adresse eingetragen, nicht mit dem Compose-Netz. Zum Netz gehört sein Gateway (zum Beispiel 172.18.0.1), und mit Docker Desktop, Rootless Docker oder einem Userland-Proxy kommen direkte Verbindungen zum veröffentlichten Port von ToolMesh von diesem Gateway. Ist das Netz eingetragen, zählen sie als Verbindungen von einem vertrauenswürdigen Proxy.

Der Proxy bekommt deshalb eine feste Adresse, und nur diese Adresse wird eingetragen. Da der Proxy ToolMesh über das Compose-Netz erreicht, genügt es, den Port von ToolMesh nur auf 127.0.0.1 zu veröffentlichen oder gar nicht:

# docker-compose.yml, the parts that change
services:
proxy:
image: caddy:2
ports:
- "443:443"
networks:
default:
ipv4_address: 172.18.0.10
toolmesh:
ports:
- "127.0.0.1:${TOOLMESH_PORT:-8123}:8080"
networks:
default:
ipam:
config:
- subnet: 172.18.0.0/24 # a subnet no other Docker network uses
ip_range: 172.18.0.128/25 # automatic addresses for the other containers
.env
TOOLMESH_TRUSTED_PROXIES=172.18.0.10

ip_range verhindert, dass Docker die Adresse des Proxys einem anderen Container gibt. Der Proxy leitet an http://toolmesh:8080 weiter.

Bei einer bestehenden Installation legt docker compose up -d das Netz neu an, wenn sich sein ipam ändert, erstellt aber nur die Services neu, deren Konfiguration sich geändert hat. Die übrigen werden ohne ihren Service-Namen an das neue Netz angeschlossen: ToolMesh findet Redis dann nicht mehr als keydb, loggt Redis not reachable und arbeitet nur mit seinem dateibasierten Token-Speicher. Nach einer solchen Änderung deshalb docker compose up -d --force-recreate ausführen und prüfen, ob das Startlog Redis connected zeigt.

bcrypt hält einen Kern je Vergleich für Dutzende Millisekunden beschäftigt. Wie viele Vergleiche gleichzeitig laufen, ist für den ganzen Prozess begrenzt (TOOLMESH_BCRYPT_MAX_CONCURRENT, Standard die Hälfte der verfügbaren CPUs, mindestens eine); die Grenze deckt Passwort-Logins und die verbleibenden Vergleiche für API-Keys nur mit key_hash ab. Eine Anfrage, die rechtzeitig keinen Vergleich bekommt, wird mit 503 und Retry-After beantwortet; sie ist kein fehlgeschlagener Login. Anfragen, die einen Vergleich für ein Bearer-Credential brauchen, werden einzeln zugelassen; sie belegen also höchstens einen Kern und lassen Passwort-Logins nicht warten.

Starten Sie mit TOOLMESH_AUTH_PASSWORD für schnelles Prototyping. Wenn mehrere Benutzer benötigt werden, wechseln Sie zu users.yaml — keine Architekturänderung nötig. Die gleiche Pipeline verarbeitet beide Modi.

Ein Upgrade einer bestehenden Installation auf v0.6.0 ändert die Login-Seite, den Umgang mit Tokens und die Client-Adresse; siehe Upgrade auf v0.6.0.