OAuth & Integrationen über Nango
Der Integrationskatalog — Google, Slack, Microsoft und weitere — wird über Nango, einen OAuth-Verbindungsvermittler, angebunden. Nur der Tenant-Server kommuniziert mit Nango; die Flutter-App sieht niemals Anbieter-Tokens. Diese Seite erklärt den Betrieb von Nango, den Callback-Proxy, die Registrierung von Anbieter-Zugangsdaten und die Absicherung der Admin-Oberfläche.
Nango übernimmt OAuth-Verbindungen, Token-Speicherung und API-Aufrufe über Proxy. Es ist nicht die Automatisierungs-Engine — Agenten und Workflows laufen auf der Python-LangGraph-Engine. Nango ist die Verbindungsschicht, über die diese Werkzeuge kommunizieren.
Wie eine Verbindung abläuft
Ein Nutzer klickt auf Verbinden; der Tenant-Server injiziert die Client-Zugangsdaten des Anbieters in Nango; der Nutzer gibt seine Zustimmung beim Anbieter; und Nango speichert die resultierenden Tokens. Jeder spätere API-Aufruf wird über Nango als Proxy geleitet, damit Tokens serverseitig bleiben.
Nango Cloud vs. selbst gehostetes Nango
Sie können Nango Cloud nutzen oder Nango selbst betreiben. Selbst-Hosting hält alle OAuth-Geheimnisse in Ihrer eigenen Infrastruktur — die richtige Wahl für ein luftdicht isoliertes oder compliance-gebundenes Deployment.
| Option | Am besten für | Betriebshinweis |
|---|---|---|
| Nango Cloud | Schnellster Einstieg; keine Infrastruktur zu betreiben | Anbieter-Geheimnisse liegen in der gehosteten Umgebung von Nango |
| Selbst gehostetes Nango | Volle Datenhoheit und luftdicht isolierte Deployments | Die Ausführung von Aktionen benötigt den vollständigen Prozesssatz, nicht nur den Container server (siehe unten) |
Das Image nangohq/nango-server:hosted führt nur den Prozess server aus — ausreichend für OAuth-Verbindungen, den Katalog und die Aktionserkennung. Das Ausführen von Integrationsaktionen benötigt außerdem die Prozesse orchestrator, jobs, persist und runner. Führen Sie diese als zusätzliche Container aus (das Deployment definiert sie unter einem Compose-Profil nango-full). Ohne sie schlägt eine Aktion mit der Meldung "runtime is starting up or not available" fehl.
Der Callback-Proxy des Tenant-Servers
OAuth-Anbieter leiten den Browser des Nutzers an eine öffentlich erreichbare Callback-URL weiter, was sonst bedeuten würde, Nango unter einem eigenen öffentlichen Hostnamen zugänglich zu machen — eine Angriffsfläche, die Sie einfach vermeiden können. Stattdessen betreibt der Tenant-Server einen schlanken Proxy, der den OAuth-Callback über das interne Docker-Netzwerk an Nango weiterleitet, sodass Nango keinen öffentlichen Hostnamen benötigt.
| Umgebung | Callback-URL |
|---|---|
| Produktion | https://tenant.yoffice.ai/integrations/oauth-callback |
| Lokale Entwicklung | https://tenant-api.dev.yoffice.ai/integrations/oauth-callback |
Der Proxy leitet Query-String, Cookies und User-Agent wortgetreu weiter, gibt Set-Cookie- und 3xx-Location-Header an den Browser zurück, ohne Weiterleitungen selbst zu folgen, und begrenzt den Antwort-Body auf 1 MiB. Er akzeptiert nur GET. Um den Flow umzustellen, aktualisieren Sie die autorisierte Redirect-URI jedes Anbieters auf die Proxy-URL und setzen Sie NANGO_SERVER_URL von Nango auf den Proxy, damit es die passende redirect_uri bekannt gibt.
Anbieter-Zugangsdaten registrieren
Jeder Anbieter, den Sie aktivieren, benötigt eine eigene OAuth-App, die sowohl beim Anbieter als auch in Nango registriert ist. Der Ablauf ist für jede Integration gleich:
- OAuth-App beim Anbieter erstellen
Registrieren Sie in der Entwicklerkonsole des Anbieters (Google Cloud Console, Slack API, Azure AD, den GitHub-Entwicklereinstellungen, …) eine OAuth-App und beantragen Sie die für die Integration benötigten Scopes. Notieren Sie Client-ID und Client-Secret.
- Redirect-URI auf den Callback-Proxy setzen
Richten Sie die autorisierte Redirect-URI der App auf den Callback-Proxy des Tenant-Servers — für Produktion: https://tenant.eu.yoffice.ai/integrations/oauth-callback. Viele Anbieter erlauben die Registrierung mehrerer URIs, sodass Sie während der Migration eine alte beibehalten können.
- Integration im Nango-Dashboard hinzufügen
Öffnen Sie das Nango-Dashboard (für eine abgesicherte selbst gehostete Instanz über einen SSH-Tunnel erreichbar), wählen Sie Neue Integration einrichten, wählen Sie die Anbietervorlage und fügen Sie Client-ID und Client-Secret ein. Nangos Anbieter-Schlüssel verwendet Bindestriche — zum Beispiel google-mail für Gmail, nicht gmail.
- Aus der App verbinden
Öffnen Sie in Your Office AI den Bereich Integrationen, klicken Sie bei der Integration auf Verbinden und schließen Sie den Zustimmungsfluss ab. Nango speichert die Zugriffs- und Aktualisierungs-Tokens; die Flutter-App berührt den Anbieter oder Nango niemals direkt.
Konventionen für Anbieter-Schlüssel
Nango-Anbieter-Schlüssel verwenden Bindestriche und stimmen nicht immer mit der Flutter-Katalog-ID überein. Eine Abweichung ist die klassische Ursache für einen "Verbindung schlägt fehl"-Fehler. Die Flutter-Seite bildet ihre Katalog-ID über CatalogIntegration.nangoProviderKey auf den Nango-Schlüssel ab — dieses Feld ist die maßgebliche Quelle.
| Flutter-Katalog-ID | Nango-Anbieter-Schlüssel |
|---|---|
google_calendar | google-calendar |
google_drive | google-drive |
gmail | google-mail (not gmail) |
google_tasks | google-tasks |
outlook_calendar | outlook-calendar |
microsoft_teams | microsoft-teams |
onedrive | onedrive |
slack | slack |
github | github |
Manche Anbieter liefern binäre Inhalte von einem anderen Host als ihrer JSON-API (Dropbox verwendet content.dropboxapi.com für Downloads). Der Materialisierer leitet diese über den Nango-Header Base-Url-Override weiter — fügen Sie daher den Content-Host zur "Base URL Override Allowlist" in der Nango-Anbieterkonfiguration hinzu.
Sicherheitsüberlegungen
Das Admin-Dashboard und die Admin-API von Nango zeigen Client-ID und Secret jedes konfigurierten Anbieters, und Nango OSS wird mit deaktiviertem Auth-Gate ausgeliefert — halten Sie daher die Admin-Oberfläche privat: nur aus Ihrer eigenen Infrastruktur erreichbar, nie aus dem öffentlichen Internet. Die nachfolgenden Schutzmaßnahmen machen das unkompliziert.
| Schutzmaßnahme | Was sie bewirkt |
|---|---|
| Loopback-Port-Bindung | Binden Sie Nangos Port 3003 ausschließlich an 127.0.0.1, sodass er vom öffentlichen Internet niemals erreichbar ist. |
| nginx-Pfad-Allowlist | Lassen Sie nur die OAuth-, Connect- und Webhook-Pfade durch den Vhost; jeder andere Pfad (einschließlich /api/v1/* und des Dashboards) gibt 403 zurück. |
| Dashboard nur über SSH-Tunnel | Erreichen Sie das Dashboard durch Weiterleitung von localhost:3003 über SSH. Der Tunnel selbst ist die Zugangskontrolle — keine öffentliche Anmeldung. |
| Aus dem öffentlichen DNS entfernen | Sobald der Callback-Proxy aktiv ist, löschen Sie den öffentlichen Nango-Vhost und den DNS-Eintrag vollständig, damit Nango keinerlei öffentliche Angriffsfläche hat. |
Setzen Sie einen starken NANGO_ENCRYPTION_KEY, damit gespeicherte Tokens in Nango verschlüsselt im Ruhezustand vorliegen, und verifizieren Sie eingehende Anbieter-Webhooks anhand ihres signierten Geheimnisses. Auf der Your Office AI-Seite erhalten gespeicherte Integrations-Zugangsdaten und API-Schlüssel eine zusätzliche AES-GCM-Verschlüsselungsschicht auf der Anwendungsebene.
Fahren Sie mit Sprachanbieter fort, um die einheitliche Sprach-Bridge zu aktivieren, oder lesen Sie die Integrationen-Anleitung für den täglichen Umgang mit dem Katalog.