OAuth e integraciones vía Nango
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.
Cómo fluye una conexión
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.
Nango Cloud vs. Nango autoalojado
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 | La ejecución de acciones requiere el conjunto completo de procesos, no solo el contenedor server (ver más abajo) |
La imagen nangohq/nango-server:hosted ejecuta solo el proceso server: suficiente para las conexiones OAuth, el catálogo y el descubrimiento de acciones. Ejecutar acciones de integración también necesita los procesos orchestrator, jobs, persist y runner. Ejecútalos como contenedores adicionales (el despliegue los define bajo un perfil Compose nango-full). Sin ellos, una acción falla con el mensaje "runtime is starting up or not available".
El proxy de callback del servidor tenant
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://tenant.yoffice.ai/integrations/oauth-callback |
| Desarrollo local | https://tenant-api.dev.yoffice.ai/integrations/oauth-callback |
El proxy reenvía literalmente la cadena de consulta, las cookies y el User-Agent, transmite de vuelta las cabeceras Set-Cookie y Location 3xx al navegador sin seguir las redirecciones él mismo, y limita el cuerpo de la respuesta a 1 MiB. Solo acepta GET. Para redirigir el flujo, actualiza el URI de redirección autorizado de cada proveedor a la URL del proxy e indica en NANGO_SERVER_URL de Nango la dirección del proxy para que anuncie el redirect_uri correspondiente.
Registro de credenciales de proveedor
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:
- Crea la app OAuth en el proveedor
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.
- Establece el URI de redirección al proxy de callback
Apunta el URI de redirección autorizado de la app al proxy de callback del servidor tenant — en producción, https://tenant.eu.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.
- Añade la integración en el panel de Nango
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.
- Conecta desde la app
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.
Convenciones de clave de proveedor
Las claves de proveedor de Nango usan guiones y no siempre coinciden con el ID del catálogo de Flutter. Una discrepancia aquí es la causa clásica del fallo de conexión. El lado de Flutter mapea su ID de catálogo a la clave de Nango a través de CatalogIntegration.nangoProviderKey: ese campo es la fuente de verdad.
| 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 |
Algunos proveedores sirven contenido binario desde un host diferente al de su API JSON (Dropbox usa content.dropboxapi.com para las descargas). El materializador los enruta a través de la cabecera Base-Url-Override de Nango, así que añade el host de contenido a la "Lista de URLs base permitidas" en la configuración del proveedor de Nango.
Consideraciones de seguridad
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. |
Establece un NANGO_ENCRYPTION_KEY robusto para que los tokens almacenados estén cifrados en reposo dentro de Nango, y verifica los webhooks entrantes del proveedor mediante su secreto firmado. En el lado de Your Office AI, las credenciales de integración almacenadas y las claves de API reciben una capa adicional de cifrado AES-GCM en la capa de aplicación.
Continúa con Proveedores de voz para habilitar el puente de voz unificado, o consulta la guía de Integraciones para ver cómo se usa el catálogo en el día a día.