OAuth-Verbindungen

Externe Dienste (Google, Dropbox, ...) einmal autorisieren, dann von Tools nutzen.

Für alle Dienste, bei denen sich der Benutzer selbst autorisieren muss (Google Drive, Dropbox, Microsoft 365, ...), nutzt TaskMonkey OAuth. Einmal verbunden, greifen alle Tools automatisch auf gültige Tokens zu.

#Verbindung anlegen

1. Gehe auf /manage/o-auth-connections.
2. Klick auf Neue Verbindung.
3. Wähle den Provider aus der Liste.
4. Klick auf Verbinden — dich leitet der Provider zu seiner Autorisierungsseite.
5. Scopes akzeptieren — du landest zurück auf /manage/o-auth-connections.
6. Fertig: Die Verbindung hat jetzt Access- und Refresh-Token.

#Felder einer Verbindung

#Token-Refresh

Läuft automatisch. Jeder Tool-Aufruf prüft, ob der Token noch gültig ist, und fordert sonst einen neuen an. Du musst nichts tun, solange der Refresh-Token gültig ist.

Wenn der Refresh-Token abläuft (typisch nach Wochen Inaktivität oder bei Revocation durch den Benutzer), wird die Verbindung als inaktiv markiert. Dann:

• Tools, die sie nutzen, geben einen Auth-Fehler zurück
• Der Benutzer muss in /manage/o-auth-connections neu verbinden

#Tool nutzt eine Verbindung

In deiner Tool-Config referenzierst du eine API, deren Auth-Typ oauth ist:

In apis.php definierst du nur die Basis-URL:

// apis.php
'apis' => [
    'google_drive' => [
        'base_url' => 'https://www.googleapis.com/drive/v3/',
        'headers' => ['Accept' => 'application/json'],
    ],
],

Im Tool-Handler setzt du den Bearer-Token aus der OAuth-Verbindung. Den konkreten Helper, mit dem du den Token holst, erfährst du von deinem Betreiber — er hängt vom Workspace-Setup ab (je nach bereitgestellten Shared-Tools und Ctx-Methoden).

#Mehrere Verbindungen desselben Providers

Passiert oft: ein Kunde hat zwei Google-Accounts (privat + Firma). Lösung:

• Anzeigename unterscheiden — z. B. „Google Privat" vs. „Google Firma"
• Im Tool einen connection-Parameter anfordern, den das Modell auf Nachfrage setzt:

'parameters' => [
    'type' => 'object',
    'properties' => [
        'connection' => [
            'type' => 'string',
            'description' => 'Welcher Google-Account? z. B. "Firma" oder "Privat"',
        ],
    ],
    'required' => ['connection'],
],

#Scopes nachträglich erweitern

OAuth-Scopes werden beim ersten Verbinden festgelegt. Möchtest du später mehr:

• Verbindung in /manage/o-auth-connections öffnen
• Neu verbinden klicken
• Im Autorisierungs-Dialog werden die neuen Scopes angefragt

Ein Tool, das einen nicht-gewährten Scope braucht, gibt einen INSUFFICIENT_SCOPE-Fehler zurück.

#Sicherheit

• Tokens liegen verschlüsselt in der Datenbank
• Nur Tools im selben Workspace können sie nutzen
• Ein Benutzer sieht nur seine eigenen Verbindungen
• Bei Workspace-Löschung werden Verbindungen mit-gelöscht

#Debug

Bei Auth-Fehlern in tm monitor oder tm logs:

[FAIL] CHAT  listDriveFiles   401 — Invalid Credentials

Checkliste:

• Verbindung in /manage/o-auth-connections noch aktiv?
• Scopes ausreichend?
• Token-Ablauf in der Zukunft? (sonst: neu verbinden)

#Supported Provider

Aktuell verfügbar:

• Google (Drive, Docs, Sheets, Calendar, Gmail)
• Dropbox
• Microsoft
• GitHub
• Slack
• HubSpot
• Notion
• Pipedrive
• Commslayer

Frage den Betreiber, falls dein Wunsch-Provider fehlt — weitere lassen sich einrichten.