Zum Hauptinhalt springen

Überblick

Mit Gmail können Agenten und Workflows E-Mails durchsuchen, lesen, entwerfen, senden und mit Labels versehen. In Langdock Cloud verbinden Nutzer Gmail über den Langdock OAuth-Client, dafür ist keine Einrichtung nötig. Folge diesem Guide, wenn du deinen eigenen Google OAuth-Client nutzt, zum Beispiel in einem Dedicated Deployment oder um dein eigenes Branding im Zustimmungsbildschirm zu zeigen. Er hat zwei Teile:
  1. Google OAuth-Client erstellen, damit Nutzer Gmail verbinden können.
  2. Webhook-Trigger einrichten (optional).
Authentifizierung: OAuth Kategorie: Kommunikation Verfügbarkeit: Alle Workspace-Pläne

Voraussetzungen

  • Ein Google Cloud-Projekt, das du verwalten kannst
  • Admin-Zugriff auf deinen Langdock Workspace
  • Für Webhook-Trigger: die Berechtigung, in diesem Projekt Pub/Sub-Topics, Subscriptions und Dienstkonten anzulegen

Google OAuth-Client erstellen

1

Gmail API aktivieren

Wähle in der Google Cloud Console dein Projekt aus, öffne APIs & Services → Library und aktiviere die Gmail API.
2

Zustimmungsbildschirm konfigurieren

Öffne Google Auth Platform und fülle Branding aus. Wähle unter Audience die Option Internal, wenn sich nur Nutzer deiner Google Workspace-Organisation verbinden. Gmail-Scopes sind eingeschränkt, deshalb braucht eine External-App eine Prüfung durch Google, bevor sich Nutzer außerhalb deiner Testnutzer verbinden können.Füge unter Data access die Scopes aus Berechtigungen hinzu.
3

OAuth-Client erstellen

Öffne Google Auth Platform → Clients und klicke auf Create client. Wähle als Anwendungstyp Web application.Trage unter Authorized redirect URIs die Redirect-URL aus Langdock ein. Du findest sie unter Workspace Einstellungen → Integrationen: Wähle Gmail aus und öffne unter Bring your own OAuth Client den Dialog für den OAuth-Client.
Die Redirect-URL muss exakt übereinstimmen. Jede Abweichung führt zu redirect_uri_mismatch-Fehlern bei der Authentifizierung.
Klicke auf Create und kopiere die Client ID und das Client secret.
4

Client in Langdock hinzufügen

Trage im Gmail OAuth-Client-Dialog die Client-ID und das Client-Secret ein, wähle unter Zugriff, wer den Client nutzen kann, klicke auf Speichern und bestätige. Wähle den gespeicherten Client in der Client-Liste aus und bestätige den Wechsel, um ihn zu aktivieren.Details zu Zugriffsoptionen und Gruppen-Clients findest du unter Bring Your Own OAuth Client.
5

Verbindung testen

Lass einen Nutzer sein Gmail-Konto verbinden und eine Gmail-Aktion ausführen, zum Beispiel Search emails.

Webhook-Trigger einrichten

Gmail hat zwei Arten von Triggern:
  • Polling-Trigger (Neue E-Mail, Neue E-Mail entspricht Suchkriterien, Label an E-Mail geändert) prüfen nach Zeitplan auf Änderungen. Sie funktionieren mit jedem OAuth-Client.
  • Webhook-Trigger (Monitor inbox, Monitor labels, Monitor sent emails) starten Workflows innerhalb von Sekunden. Gmail sendet Benachrichtigungen über Änderungen per Google Cloud Pub/Sub, deshalb braucht dein OAuth-Client ein Pub/Sub-Topic und eine Push-Subscription.
Ohne diese Einrichtung lassen sich die Webhook-Trigger nicht aktivieren. Polling-Trigger und Aktionen funktionieren weiterhin.
Das Topic muss im Google Cloud-Projekt deines OAuth-Clients liegen, und Google muss deine Langdock-Instanz erreichen können. Dedicated Deployments brauchen aktivierte Integrations-Webhook-Trigger.
1

Cloud Pub/Sub API aktivieren

Öffne in der Google Cloud Console das Projekt deines OAuth-Clients, gehe zu APIs & Services → Library und aktiviere die Cloud Pub/Sub API.
2

Pub/Sub-Topic erstellen

  1. Öffne Pub/Sub → Topics und klicke auf Create topic.
  2. Gib eine Topic-ID ein, zum Beispiel gmail-webhooks, deaktiviere Add a default subscription und klicke auf Create.
  3. Klicke auf der Topic-Seite oben rechts auf Show info panel. Klicke im Tab Permissions auf Add principal.
  4. Gib gmail-api-push@system.gserviceaccount.com ein, wähle die Rolle Pub/Sub Publisher und klicke auf Save.
Über dieses Konto veröffentlicht Gmail Benachrichtigungen über Änderungen in deinem Topic.
3

Push-Dienstkonto erstellen

  1. Öffne IAM & Admin → Service accounts und klicke auf Create service account.
  2. Gib einen Namen ein, zum Beispiel gmail-pubsub-push, und klicke auf Create and continue.
  3. Überspringe Permissions und Principals with access und klicke auf Done. Das Konto braucht keine Rollen, weil Pub/Sub es nur nutzt, um die Anfragen an Langdock zu signieren.
  4. Kopiere die E-Mail-Adresse des Dienstkontos aus der Liste. Du brauchst sie in den nächsten Schritten.
Damit du das Konto in der Push-Subscription auswählen kannst, brauchst du darauf die Rolle Service Account User. Projekt-Owner und -Editoren haben sie bereits.
4

Topic und Dienstkonto in Langdock speichern

  1. Klappe im Gmail OAuth-Client-Dialog Webhook-Trigger auf.
  2. Trage bei Pub/Sub-Topic den vollständigen Topic-Pfad ein, zum Beispiel projects/PROJECT_ID/topics/gmail-webhooks.
  3. Trage bei Dienstkonto der Push-Subscription die E-Mail-Adresse des Dienstkontos ein, zum Beispiel gmail-pubsub-push@PROJECT_ID.iam.gserviceaccount.com.
  4. Klicke auf Speichern und bestätige.
  5. Kopiere den Push-Endpunkt, der jetzt im Dialog erscheint.
5

Push-Subscription anlegen

Öffne dein Topic unter Pub/Sub → Topics und klicke auf Create subscription:
  • Delivery type: Push
  • Endpoint URL: der Push-Endpunkt aus Langdock
  • Enable authentication: aktiviert, mit dem Dienstkonto aus Schritt 3
  • Audience: leer lassen
  • Retry policy: Retry after exponential backoff delay
  • Expiration period: Never expire
Lass Audience leer. Pub/Sub nutzt dann die Endpunkt-URL als Audience, und genau die prüft Langdock. Langdock lehnt Anfragen mit jeder anderen Audience ab.
Behalte die übrigen Standardwerte bei und klicke auf Create.
Mit der Standard-Ablaufzeit löscht Google die Subscription nach 31 Tagen ohne Benachrichtigungen, und Webhook-Trigger stoppen ohne Fehlermeldung.
6

Webhook-Trigger testen

Erstelle einen Workflow mit einem Integrations-Trigger, wähle Gmail und Monitor inbox und sende dir selbst eine E-Mail. Der Workflow startet innerhalb von Sekunden.

So funktioniert es

Gmail erlaubt einen Benachrichtigungskanal pro Postfach und veröffentlicht jede Änderung in deinem Topic. Eine Benachrichtigung enthält nur die Postfachadresse und eine Änderungsmarke, niemals E-Mail-Inhalte. Pub/Sub sendet sie an Langdock, signiert mit deinem Dienstkonto. Langdock prüft Signatur und Endpunkt, danach ruft jeder abonnierte Trigger die Änderungen mit seiner eigenen Gmail-Verbindung ab. Ein Trigger sieht also nur E-Mails, die seine Verbindung lesen kann. Du brauchst nur ein Topic, ein Dienstkonto und eine Push-Subscription pro OAuth-Client. Wenn du mehrere Google OAuth-Clients hast, zeigt jeder seinen eigenen Push-Endpunkt und braucht eine eigene Push-Subscription. Liegen sie im selben Projekt, können sie sich ein Topic und ein Dienstkonto teilen.

Berechtigungen

Füge diese Scopes zu deinem Zustimmungsbildschirm hinzu. Langdock fragt die Scopes an, die die in deinem Workspace aktivierten Aktionen brauchen. Mehr dazu unter Action-Level-Scopes verwalten.

Fehlerbehebung

Prüfe, ob im Abschnitt Webhook-Trigger des OAuth-Clients sowohl das Topic als auch das Dienstkonto eingetragen sind und ob die Verbindung mit diesem OAuth-Client erstellt wurde. Verbindungen bleiben mit dem Client verknüpft, mit dem sie erstellt wurden.Prüfe außerdem, ob das Topic im selben Google Cloud-Projekt liegt wie der OAuth-Client und ob gmail-api-push@system.gserviceaccount.com darauf die Rolle Pub/Sub Publisher hat.
Öffne die Push-Subscription in der Google Cloud Console und prüfe die Antwortcodes unter Metrics → Push:
  • 401: Die Subscription hat die Authentifizierung deaktiviert, nutzt ein anderes Dienstkonto als das in Langdock gespeicherte oder hat eine Audience gesetzt.
  • 403: Eine Firewall, eine WAF oder ein Proxy vor Langdock blockiert die Anfragen von Google. Erlaube POST-Anfragen an /api/webhook-pubsub/. Langdock prüft die Signatur jeder Anfrage selbst.
  • 404: Die Endpunkt-URL stimmt nicht mit dem Push-Endpunkt in Langdock überein, oder der OAuth-Client hat keine Webhook-Trigger-Einstellungen.