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.

#Google mit einem Klick (TaskMonkey-App)

Für Google stellt TaskMonkey eine eigene OAuth-App bereit: Das Formular fragt dann nur nach Anzeigename und den gewünschten Diensten (Drive, Sheets, Google Ads) — kein Cloud-Projekt, keine Client-ID. Weitere Dienste kommen später per „… verbinden“ in der Verbindung dazu. Wer eine eigene OAuth-App vorschreibt, nutzt „Erweitert: eigene OAuth-App verwenden“. Einrichtung und Google-Verifizierung: Google-Plattform-App.

#Google Drive aus dem Chat (Builder)

Braucht der Builder Google Drive (z. B. für createCustomerSheet), zeigt er im Chat „Mit Google verbinden“. Der Button öffnet /manage/o-auth-connections/connect-google?popup=1 in einem kleinen Fenster: Plattform-App, nur drive.file + E-Mail; gibt es schon eine Google-Verbindung über die TaskMonkey-App, wird sie inkrementell um Drive erweitert (keine zweite Verbindung). Nach Googles Zustimmung landet das Fenster auf /manage/o-auth-connections/done, meldet dem Chat „verbunden“ und schließt sich; der Chat schickt „Google ist verbunden.“ und der Builder macht weiter. Status und Trennen stehen unter Verbindungen (/manage/connections, Karte „Google“); „Mit Google verbinden“ dort nutzt denselben Ein-Klick-Flow.

#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.

Die gespeicherten Scopes einer Verbindung sind die, die der Provider beim Verbinden tatsächlich erteilt hat (Feld scope der Token-Antwort) — nicht die angefragten.

#Zusätzliche Berechtigungen (Opt-in, z. B. Google Ads)

Manche Scopes fragt TaskMonkey nie ungefragt an, auch nicht beim „Neu verbinden“ — sie stehen beim Provider unter optional_scopes in config/oauth_providers.php. Bei Google heute: Google Ads (https://www.googleapis.com/auth/adwords).

• Bestehende Verbindung: Verbindung öffnen → Abschnitt „Zusätzliche Berechtigungen“ → „Google Ads verbinden“. Das startet „Neu verbinden“ mit den bisherigen Scopes plus dem neuen (/manage/o-auth-connections/reconnect/<id>?add=google_ads), gleicher OAuth-Client.
• Neue Verbindung: im Formular zusätzlich Google Ads anhaken.
• Einmal erteilt, bleibt der Scope bei jedem weiteren „Neu verbinden“ erhalten.
• Voraussetzung im Cloud-Projekt des OAuth-Clients: Google Ads API aktiviert, Scope adwords im Consent-Screen, Status „In Produktion“. Details: Google Ads.

Die Google-Ads-Tools (apis.google_ads, Auth-Type google_oauth_refresh_token mit auth.scopes) nehmen dann automatisch diese Verbindung statt eines Refresh-Tokens aus der .env.

#Sicherheit

• Access-/Refresh-Token und Client-Secret liegen verschlüsselt in der Datenbank (AES-256, Schlüssel aus Security.salt)
• Verbindungen über die TaskMonkey-App speichern gar kein Client-Secret
• Der state-Parameter des OAuth-Flows wird beim Rücksprung geprüft
• 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.