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.
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.
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 | Action execution needs the full process set, not just the server container (see below) |
The nangohq/nango-server:hosted image runs only the server process — enough for OAuth connections, the catalog, and action discovery. Executing integration actions also needs the orchestrator, jobs, persist, and runner processes. Run those as additional containers (the deploy defines them under a nango-full Compose profile). Without them an action fails with a "runtime is starting up or not available" message.
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://ai.yoffice.ai/integrations/oauth-callback |
| Lokale Entwicklung | https://tenant-api.dev.yoffice.ai/integrations/oauth-callback |
The proxy forwards the query string, cookies, and User-Agent verbatim, relays Set-Cookie and 3xx Location headers back to the browser without following redirects itself, and caps the response body at 1 MiB. It accepts GET only. To switch the flow over, update each provider's authorised redirect URI to the proxy URL and point Nango's NANGO_SERVER_URL at the proxy so it advertises the matching redirect_uri.
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:
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.
Richten Sie die autorisierte Redirect-URI der App auf den Callback-Proxy des Tenant-Servers — für Produktion: https://ai.yoffice.ai/integrations/oauth-callback. Viele Anbieter erlauben die Registrierung mehrerer URIs, sodass Sie während der Migration eine alte beibehalten können.
Ö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.
Ö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.
Nango provider keys use hyphens, and they do not always match the Flutter catalog ID. A mismatch here is the classic cause of a "connect fails" bug. The Flutter side maps its catalog ID to the Nango key via CatalogIntegration.nangoProviderKey — that field is the source of truth.
| 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 |
Some providers serve binary content from a different host than their JSON API (Dropbox uses content.dropboxapi.com for downloads). The materializer routes those through Nango's Base-Url-Override header, so add the content host to the provider's "Base URL Override Allowlist" in the Nango provider config.
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. |
Set a strong NANGO_ENCRYPTION_KEY so stored tokens are encrypted at rest inside Nango, and verify inbound provider webhooks by their signed secret. On the Your Office AI side, stored integration credentials and API keys get an additional layer of AES-GCM encryption at the application layer.
Continue to Sprachanbieter to enable the unified voice bridge, or read the Integrationen guide for how the catalog is used day to day.