# Autorisierung: Tool-Zugriff via OpenFGA

> ToolMesh erzwingt Tool-Autorisierung via OpenFGA im User→Plan→Tool-Modell. Behandelt bypass/restrict-Modi, DADL-Access-Level und tuples.json.

Canonical: https://www.toolmesh.io/de/authorization/

ToolMesh verwendet [OpenFGA](https://openfga.dev/) für feingranulare Autorisierung. Das Modell folgt einer **User → Plan → Tool**-Beziehungsstruktur.

## Modi

| Modus | Konfiguration | Verhalten |
|-------|---------------|-----------|
| `bypass` | `OPENFGA_MODE=bypass` | Keine Autorisierungsprüfungen (Standard) |
| `restrict` | `OPENFGA_MODE=restrict` | OpenFGA wird bei jedem Tool-Call erzwungen |

Starte mit `bypass` für die Entwicklung, wechsle zu `restrict` für die Produktion.

## Autorisierungsmodell

```
User --member_of--> Plan --can_execute--> Tool
```

Jeder Benutzer (per OAuth-Login oder API-Key) hat einen zugewiesenen Plan. Pläne gewähren Zugriff auf bestimmte Tools. Wenn ein Tool-Call eingeht, prüft ToolMesh:

```
Check(user, can_execute, tool)
```

Bei Ablehnung wird die Ausführung sofort mit einem Unauthorized-Fehler gestoppt.

## DADL Access Levels

DADL-Tools deklarieren eine `access`-Klassifizierung:

| Level | Bedeutung |
|-------|-----------|
| `read` | Nur-Lese-Operationen |
| `write` | Erstell-/Update-Operationen |
| `admin` | Administrative Operationen |
| `dangerous` | Destruktive oder irreversible Operationen |
| *custom* | Mit beliebigen String-Werten erweiterbar |

Policy-Dateien bündeln diese Access-Levels in Rollen, und OpenFGA weist Benutzern Rollen zu.

## Konfiguration

```bash
OPENFGA_API_URL=http://openfga:8080    # OpenFGA-API-Endpunkt (Docker-Service-Name)
OPENFGA_STORE_ID=your-store-id          # OpenFGA Store-ID
OPENFGA_MODE=restrict                   # Erzwingung aktivieren
```

## Setup

Das Autorisierungsmodell und die Beziehungs-Tuples werden als editierbare Dateien in `config/openfga/` definiert:

| Datei | Zweck |
|-------|-------|
| `model.fga` | Autorisierungsmodell in FGA DSL |
| `tuples.json` | User/Plan/Tool-Beziehungen |
| `setup.sh` | Shell-Script, das die `fga`-CLI zum Anwenden von Modell und Tuples nutzt |

Das `setup.sh`-Script läuft auf dem Host und verwendet `docker run` mit dem `openfga/cli`-Image, um Modell und Tuples anzuwenden (das CLI-Image ist Distroless und hat keine Shell, daher kann es nicht als Docker-Compose-Service laufen):

```bash
# 1. Die OpenFGA-Services in docker-compose.yml auskommentieren (+ mysqldata Volume)
# 2. Alle Services starten
docker compose up -d

# 3. Den OpenFGA-Store bootstrappen
./config/openfga/setup.sh

# 4. Die OPENFGA_STORE_ID aus der Ausgabe in .env eintragen
# 5. OPENFGA_MODE=restrict in .env setzen
# 6. Neustarten
docker compose down && docker compose up -d
```

### Demo-Tuples

Die Standard-`tuples.json` demonstriert Autorisierung mit einem Deny-Fall:

- **Free Plan** (alle Benutzer per Wildcard): kann `echo_echo` und `echo_time` ausführen, aber **nicht** `echo_add`
- **Pro Plan** (company:acme Mitglieder): kann alle Tools ausführen

So lässt sich sofort verifizieren, dass die Autorisierung korrekt funktioniert — Free-Plan-Benutzer bekommen keinen Zugriff auf `echo_add`.

## Caller-Origin-Integration

Autorisierungsentscheidungen können auch die **CallerClass** (trusted, standard, untrusted) berücksichtigen. Das ermöglicht Policies wie „untrusted Clients können nicht auf Admin-Tools zugreifen", selbst wenn der Plan des Benutzers es normalerweise erlauben würde.