El catálogo de integraciones — Google, Slack, Microsoft y más — se conecta a través de Nango, un intermediario de conexiones OAuth. El servidor tenant es lo único que habla con Nango; la app Flutter nunca ve los tokens de proveedor. Esta página explica cómo ejecutar Nango, el proxy de callback, el registro de credenciales de proveedor y el refuerzo de la superficie de administración.
Nango se encarga de las conexiones OAuth, el almacenamiento de tokens y las llamadas a la API mediante proxy. No es el motor de automatización: los agentes y flujos de trabajo se ejecutan en el motor Python LangGraph. Nango es la capa de conexión por la que pasan esas herramientas.
Un usuario hace clic en Conectar; el servidor tenant inyecta las credenciales de cliente del proveedor en Nango; el usuario completa el consentimiento en el proveedor; y Nango conserva los tokens resultantes. Cada llamada API posterior se hace a través del proxy de Nango para que los tokens permanezcan en el lado del servidor.
Puedes usar Nango Cloud o ejecutar Nango tú mismo. El autoalojamiento mantiene todos los secretos OAuth en tu propia infraestructura, lo cual es la elección adecuada para despliegues sin acceso a internet o con restricciones de cumplimiento.
| Opción | Mejor para | Nota operacional |
|---|---|---|
| Nango Cloud | El camino más rápido; sin infraestructura que gestionar | Los secretos de proveedor residen en el entorno alojado de Nango |
| Nango autoalojado | Residencia completa de datos y despliegues sin acceso a internet | 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.
Los proveedores de OAuth redirigen el navegador del usuario a una URL de callback accesible públicamente, lo que de otro modo significaría exponer Nango en su propio nombre de host público — una superficie que puedes evitar fácilmente. En su lugar, el servidor tenant aloja un proxy ligero que reenvía el callback OAuth a Nango a través de la red interna de Docker, de modo que Nango nunca necesita un nombre de host público.
| Entorno | URL de callback |
|---|---|
| Producción | https://ai.yoffice.ai/integrations/oauth-callback |
| Desarrollo local | 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.
Cada proveedor que habilites necesita su propia app OAuth registrada tanto en el proveedor como en Nango. El flujo es el mismo para cada integración:
En la consola de desarrolladores del proveedor (Google Cloud Console, Slack API, Azure AD, la configuración de desarrolladores de GitHub, …) registra una app OAuth y solicita los ámbitos que necesita la integración. Anota el client ID y el client secret.
Apunta el URI de redirección autorizado de la app al proxy de callback del servidor tenant — en producción, https://ai.yoffice.ai/integrations/oauth-callback. Muchos proveedores permiten registrar más de un URI, por lo que puedes mantener el antiguo mientras haces la migración.
Abre el panel de Nango (accesible a través de un túnel SSH en una instancia autoalojada reforzada), elige Configurar nueva integración, selecciona la plantilla del proveedor y pega el client ID y el client secret. La clave de proveedor de Nango usa guiones — por ejemplo, google-mail para Gmail, no gmail.
En Your Office AI, abre Integraciones, haz clic en Conectar en la integración y completa el flujo de consentimiento. Nango almacena los tokens de acceso y actualización; la app Flutter nunca toca directamente al proveedor ni a Nango.
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.
| ID del catálogo de Flutter | Clave de proveedor de Nango |
|---|---|
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.
El panel de administración y la API de administración de Nango muestran el client ID y el secret de cada proveedor configurado, y Nango OSS se entrega con la puerta de autenticación desactivada, así que mantén la superficie de administración privada: accesible solo desde tu propia infraestructura, nunca desde internet público. Las defensas que se describen a continuación lo hacen sencillo.
| Defensa | Qué hace |
|---|---|
| Vinculación al puerto de loopback | Vincula el puerto 3003 de Nango solo a 127.0.0.1 para que nunca sea accesible desde internet público. |
| Lista de rutas permitidas en nginx | Permite solo las rutas de OAuth, Connect y webhook a través del vhost; cualquier otra ruta (incluidas /api/v1/* y el panel) devuelve 403. |
| Panel solo por túnel SSH | Accede al panel reenviando localhost:3003 por SSH. El propio túnel es el control de acceso: sin inicio de sesión público. |
| Eliminar del DNS público | Una vez que el proxy de callback esté activo, elimina completamente el vhost público de Nango y el registro DNS para que Nango no tenga ninguna superficie pública. |
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 Proveedores de voz to enable the unified voice bridge, or read the Integraciones guide for how the catalog is used day to day.