Google-Plattform-App

Eine OAuth-App von TaskMonkey für alle Kunden: Cloud-Projekt, Consent-Screen, Scopes, Google-Verifizierung.

Kunden verbinden Google (Drive, Sheets, Ads, später Gmail/Kalender) mit einem Klick — ohne eigenes Cloud-Projekt, ohne Client-ID. Dafür betreibt TaskMonkey eine OAuth-App bei Google. Diese Seite beschreibt, wie sie eingerichtet und von Google verifiziert wird.

#So funktioniert es im Produkt

• Ist GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET in der Plattform-.env (config/.env) gesetzt, zeigt Verwaltung → OAuth Verbindungen → Google nur noch Anzeigename, Dienste zum Anhaken und „Mit Google verbinden“.
• Unter „Erweitert: eigene OAuth-App verwenden“ bleibt die alte Variante (Client-ID/-Secret des Kunden) für Enterprise- und Sonderfälle.
• Verbindungen über die Plattform-App speichern kein client_id/client_secret (Spalte uses_platform_client = 1). Refresh und Google-Ads-Auth nehmen den Plattform-Client aus der .env.
• Bestehende Verbindungen mit eigener App (z. B. Bloomify) bleiben unverändert und laufen weiter über ihren eigenen Client.
• Weitere Dienste kommen später per „… verbinden“ in der Verbindung dazu: der Reconnect fragt die bisherigen Scopes der Verbindung plus den neuen Dienst explizit an. Kein include_granted_scopes — Google hinge sonst alle Scopes an, die das Konto dem Plattform-Client je erteilt hat (z. B. adwords), und schon der Drive-Flow zeigte „Google hat diese App nicht überprüft“ (01.10.).
• „Mit Google verbinden“ (connect-google, Drive aus Chat/Verbindungen) fragt nur nicht-sensible Scopes an (userinfo.email + drive.file). Hat die bestehende Google-Verbindung sensible Scopes (z. B. Google Ads), wird eine eigene Drive-Verbindung angelegt statt sie zu erweitern (OAuthConnectionService::sensitiveScopes).
• Ohne die beiden .env-Werte ist alles wie vorher (altes Formular).

Konfiguration: config/oauth_providers.php → google.platform_client (Dienste = scope_groups), Client-Werte: config/app.php → OAuthPlatformClients.google.

#Scopes: was wir anfragen

Google teilt Scopes in drei Stufen ein. Die Stufe entscheidet über den Prüfaufwand:

Die Dienste im Formular:

Was drive.file kann und was nicht: Dateien und Ordner hochladen bzw. anlegen (uploadDriveFile, createDriveFile, createDriveFolder, saveInboxAttachmentToDrive, /api/drive-upload) und diese Dateien später wieder lesen. Nicht: bestehende Ordner des Kunden auflisten, durchsuchen oder fremde Dateien lesen (listDriveFiles, searchDriveFiles, readDriveFile auf Bestand). Dafür braucht es drive (eingeschränkt) — heute also die eigene OAuth-App des Kunden, bis die Plattform-App CASA hat.

#Empfehlung für den Start

Nur nicht sensible und sensible Scopes beantragen, keine eingeschränkten. Also: userinfo.email, drive.file, spreadsheets, adwords. Das hält die Verifizierung bei einigen Tagen bis wenigen Wochen und erspart CASA (Kosten, jährliche Wiederholung). Den Dienst „Drive (voller Zugriff)“ lassen wir für die Plattform-App aus (platform => false); wer ihn braucht, nimmt „Erweitert: eigene OAuth-App“. Gmail lesen/Kalender erst, wenn es ein zahlendes Szenario gibt — gmail.send und calendar.events sind sensibel, Gmail lesen ist eingeschränkt.

#Einrichtung (einmalig, Marcus)

#1. Cloud-Projekt

• console.cloud.google.com → neues Projekt, z. B. „TaskMonkey Platform“ (eigenes Projekt, nicht das Bloomify-Projekt — Verifizierung und Quoten gehören dann TaskMonkey).
• APIs & Dienste → Bibliothek: aktivieren
  • Google Drive API
  • Google Sheets API
  • Google Ads API
  • später: Gmail API, Google Calendar API

#2. Domain bestätigen

• Google Search Console → Property taskmonkey.de (Domain-Property, DNS-TXT-Eintrag bei Cloudflare). Das Google-Konto, mit dem ihr das Cloud-Projekt verwaltet, muss Inhaber der Property sein — sonst lehnt Google die Verifizierung ab.

#3. OAuth-Zustimmungsbildschirm (Google Auth Platform → Branding)

Datenzugriff → Scopes hinzufügen: genau die aus der Empfehlung oben (.../auth/userinfo.email, .../auth/drive.file, .../auth/spreadsheets, .../auth/adwords). Jeder Scope, der hier steht, muss begründet und im Video gezeigt werden — nichts auf Vorrat eintragen.

Datenschutzerklärung muss zusätzlich zum Üblichen enthalten:

• welche Google-Daten TaskMonkey liest/schreibt und wofür (Drive-Dateien, Tabellen, Ads-Berichte/Kampagnen im Auftrag des Nutzers),
• dass Daten nicht verkauft, nicht für Werbung und nicht zum Trainieren allgemeiner KI-Modelle genutzt werden,
• den Satz zur Limited-Use-Policy: „Die Nutzung und Übertragung von Informationen, die TaskMonkey von Google-APIs erhält, an andere Apps erfolgt gemäß der Google API Services User Data Policy, einschließlich der Anforderungen zur eingeschränkten Nutzung (Limited Use).“
• KI-Hinweis: Werden Google-Inhalte an ein LLM (Anthropic/OpenAI) geschickt, muss das in der Erklärung stehen (Unterauftragsverarbeiter, kein Training).

#4. OAuth-Client anlegen (Google Auth Platform → Clients)

• Typ: Webanwendung, Name z. B. „TaskMonkey Web“.

• Autorisierte Weiterleitungs-URI: https://app.taskmonkey.de/manage/o-auth-connections/callback (genau so — Cake macht aus OAuthConnections o-auth-connections).

• Optional für lokale Tests: eine zweite URI mit http://localhost:<port>/manage/o-auth-connections/callback (localhost ist ohne Verifizierung erlaubt) — oder besser ein eigener Test-Client im selben Projekt.

• Client-ID und Secret nur in die Plattform-.env auf dem Server (config/.env, liegt in shared/):

  GOOGLE_OAUTH_CLIENT_ID=….apps.googleusercontent.com
  GOOGLE_OAUTH_CLIENT_SECRET=GOCSPX-…
  

  Nie ins Repo, nie in eine Workspace-.env oder apis.php. Nach dem Setzen PHP-FPM neu laden (Deploy oder Container-Neustart), damit env() die Werte sieht.

#5. Veröffentlichungsstatus

• Testmodus (Status „Testing“): nur eingetragene Testnutzer (max. 100), Refresh-Tokens laufen nach 7 Tagen ab → Kunden müssten wöchentlich neu verbinden. Nur für den eigenen Test.
• In Produktion, nicht verifiziert: jeder kann verbinden, sieht aber die Warnung „Google hat diese App nicht überprüft“ (weiter über „Erweitert → Weiter zu TaskMonkey (unsicher)“). Limit: 100 Nutzer insgesamt (Lebenszeit-Kontingent für sensible/eingeschränkte Scopes), bis die Verifizierung durch ist. Refresh-Tokens laufen nicht mehr nach 7 Tagen ab.
• In Produktion, verifiziert: keine Warnung, kein Nutzerlimit.

TaskMonkey deckelt zusätzlich selbst (platform_client.user_cap in config/oauth_providers.php): warn_at/limit für alle Workspaces zusammen und per_tenant (Standard 5) pro Workspace, damit ein einzelner Workspace das 100er-Kontingent nicht allein aufbraucht. Geprüft im Formular und noch einmal im Callback vor dem Speichern; ein Konto, das schon verbunden ist, belegt keinen neuen Platz. Abgelehnte Verbindungen werden nicht gespeichert, der Grant wird widerrufen.

Also: direkt nach dem Einrichten auf „In Produktion“ stellen und die Verifizierung beantragen — die ersten Pilotkunden kommen mit Warnung durch, der Rest nach Freigabe.

#6. Verifizierung beantragen (Google Auth Platform → Prüfzentrum / Verification Center)

Google prüft in zwei Schritten:

1. Branding-Prüfung (App-Name, Logo, Domain, Datenschutz-Link) — typischerweise 2–3 Werktage.
2. Prüfung der sensiblen Scopes — typischerweise einige Tage bis wenige Wochen, mit Rückfragen per E-Mail. Einzureichen:
   • Begründung pro Scope (1–2 Sätze, warum ein kleinerer Scope nicht reicht — z. B. spreadsheets: „Nutzer lassen TaskMonkey Tabellen, die sie selbst auswählen, auswerten und fortschreiben“; adwords: „Nutzer lassen Kampagnen, Budgets und Berichte ihres Google-Ads-Kontos verwalten“).
   • Demo-Video (YouTube, „nicht gelistet“), Englisch oder mit englischen Untertiteln empfohlen. Muss zeigen:
     • den kompletten Verbindungs-Flow in app.taskmonkey.de bis zum Google-Zustimmungsbildschirm, mit sichtbarer URL (die client_id in der Adresszeile muss zu unserem Client passen),
     • den Zustimmungsbildschirm mit App-Name „TaskMonkey“ und den angefragten Scopes,
     • für jeden Scope die Funktion, die ihn nutzt (Datei hochladen, Tabelle lesen/schreiben, Ads-Bericht abrufen),
     • wo der Nutzer die Verbindung wieder trennt (Verwaltung → OAuth Verbindungen → Löschen).
   • Datenschutzerklärung (s. o.) auf der verifizierten Domain.

Eingeschränkte Scopes (voller Drive-Zugriff, Gmail lesen) bräuchten zusätzlich ein CASA-Sicherheitsassessment (Cloud Application Security Assessment, meist Tier 2) über ein von Google zugelassenes Labor: kostenpflichtig, jährlich zu wiederholen, Vorbereitung mehrere Wochen. Deshalb für den Start nicht beantragen.

#7. Google Ads: Developer-Token

Der OAuth-Scope adwords allein reicht nicht; die Google-Ads-Tools brauchen weiter einen Developer-Token (GOOGLE_ADS_DEVELOPER_TOKEN, heute pro Workspace in der .env, siehe Google Ads). Mit der Plattform-App sollte der Token langfristig einer von TaskMonkey sein (TaskMonkey-MCC, Basic Access). Vor dem ersten Kunden prüfen: ob Google den Token des Kunden zusammen mit dem Plattform-Client akzeptiert — Google koppelt Developer-Tokens an Cloud-Projekte.

#Grenzen und Hinweise

• Refresh-Token-Limit: pro Google-Konto und OAuth-Client höchstens 100 aktive Refresh-Tokens; das älteste wird still ungültig. Relevant nur, wenn ein Konto sehr oft neu verbunden wird (dann „Neu verbinden“ statt neue Verbindung anlegen).
• Widerruf: Nutzer können den Zugriff unter myaccount.google.com/permissions entziehen → Refresh schlägt mit invalid_grant fehl, die Verbindung zeigt den Fehler, „Neu verbinden“ hilft.
• Tokens in der Datenbank liegen verschlüsselt (AES-256) mit eigenem Schlüssel OAUTH_TOKEN_KEY aus config/.env (mind. 32 Zeichen; ohne ihn: Schlüssel aus SECURITY_SALT, Bestand). Die Schlüssel-ID steht im Wert (tmenc2:<kid>:…). Einrichten: Schlüssel erzeugen (php -r 'echo bin2hex(random_bytes(32)), "\n";'), in config/.env setzen, dann bin/cake oauth_reencrypt (Trockenlauf, nur Zähler) und bin/cake oauth_reencrypt --apply. Rotieren: neuen Schlüssel als OAUTH_TOKEN_KEY, alten als OAUTH_TOKEN_KEY_PREVIOUS, oauth_reencrypt --apply, danach _PREVIOUS entfernen. Den Schlüssel sicher aufbewahren: ohne ihn sind alle Verbindungen neu zu verbinden.
• Plattform-Client entfernt? Plattform-Verbindungen melden dann „Plattform-OAuth-App für google ist nicht konfiguriert“; Verbindungen mit eigener App laufen weiter.
• Secret rotieren: In der Cloud Console ein zweites Secret anlegen, in config/.env tauschen, altes Secret löschen. Refresh-Tokens bleiben gültig (sie hängen an der Client-ID, nicht am Secret).

#Checkliste für Marcus

1. Cloud-Projekt „TaskMonkey Platform“ anlegen, Drive/Sheets/Ads-API aktivieren.
2. taskmonkey.de in der Search Console bestätigen (DNS-TXT bei Cloudflare).
3. Datenschutzerklärung um Google-Abschnitt + Limited-Use-Satz + KI-Hinweis ergänzen.
4. Consent-Screen: Extern, „TaskMonkey“, Logo, Links, autorisierte Domain taskmonkey.de, die vier Scopes.
5. Web-Client mit Redirect-URI https://app.taskmonkey.de/manage/o-auth-connections/callback.
6. GOOGLE_OAUTH_CLIENT_ID / GOOGLE_OAUTH_CLIENT_SECRET in config/.env auf Prod setzen, deployen (Migrationen laufen mit).
7. Selbst testen: neue Google-Verbindung in einem Test-Workspace, Datei hochladen, Tabelle lesen, „Google Ads verbinden“.
8. Status „In Produktion“, Demo-Video aufnehmen, Verifizierung einreichen.
9. Google-Ads-Developer-Token mit Plattform-Client prüfen (Abschnitt 7).