Guía de configuración de la aplicación OAuth de OpenConnector

OOMOL OpenConnector utiliza tu propia aplicación OAuth del proveedor cuando un proveedor OAuth2 necesita autorización del usuario. Crea la aplicación en la consola de desarrollador del proveedor, copia la URL de callback exacta desde tu entorno de ejecución de OpenConnector en esa aplicación y, a continuación, guarda la configuración del cliente de la aplicación en OpenConnector.

Utiliza esta guía para proveedores OAuth2 como Gmail, Google Drive, Google Calendar, Slack, HubSpot, GitHub, Microsoft Outlook, Notion, Zoom, Zendesk, Jira, Dropbox y otros proveedores OAuth que aparecen en el catálogo de proveedores de OpenConnector.

Esta guía cubre la configuración de la aplicación OAuth. Para proveedores que utilizan otro tipo de autenticación, utiliza los campos de credenciales que muestra la página del proveedor de OpenConnector.

Lo que necesitas

Un entorno de ejecución de OOMOL OpenConnector en funcionamiento.
Acceso a la consola web de OpenConnector.
El token de administrador si OOMOL_CONNECT_ADMIN_TOKEN está configurado.
Permiso para crear una aplicación OAuth en la consola de desarrollador o de administración del proveedor.
Una cuenta de prueba en el espacio de trabajo, inquilino, organización o portal del proveedor que quieres conectar.

Si tu entorno de ejecución es accesible a través de un dominio público, un túnel o una URL de Cloudflare Worker, configura OOMOL_CONNECT_ORIGIN antes de crear aplicaciones OAuth del proveedor. El URI de redirección se deriva de este origen.

OOMOL_CONNECT_ORIGIN="https://connect.example.com" \
OOMOL_CONNECT_ADMIN_TOKEN="replace-with-an-admin-token" \
OOMOL_CONNECT_ENCRYPTION_KEY="replace-with-a-long-random-secret" \
docker compose up --build

Paso 1: Configurar la URL de callback de OpenConnector

Construye la URL de callback a partir del origen que los usuarios abren en el navegador:

<openconnector-origin>/oauth/callback

Con el entorno de ejecución local predeterminado, utiliza:

http://localhost:3000/oauth/callback

Cuando OOMOL_CONNECT_ORIGIN está configurado con un origen público, la URL de callback utiliza ese origen:

https://connect.example.com/oauth/callback

Introduce esta URL de callback exacta en la aplicación OAuth del proveedor. No añadas una barra diagonal final a menos que tu origen de OpenConnector ya incluya una.

Paso 2: Crear la aplicación OAuth del proveedor

Abre la consola de desarrollador del proveedor y crea una aplicación OAuth, integración, aplicación conectada, aplicación pública o registro de aplicación. La nomenclatura del proveedor varía, pero los campos obligatorios suelen ser los mismos.

Campo de la aplicación del proveedor	Qué introducir
Nombre de la aplicación	Un nombre que reconozcas, como `OpenConnector Local` o el nombre de tu herramienta interna.
URL de la página principal o del sitio web	La URL de tu producto, herramienta interna, repositorio o entorno de ejecución. Utiliza un valor que tus usuarios y administradores puedan reconocer.
URI de redirección, URL de callback o URL de respuesta	La URL de callback exacta de OpenConnector, como `https://connect.example.com/oauth/callback`.
Ámbitos o permisos	Los ámbitos requeridos por el proveedor de OpenConnector. Cópialos de la página del proveedor o de la guía de acciones del proveedor.
Distribución, instalación o visibilidad	Mantén la aplicación privada, solo para pruebas, interna o no listada cuando el proveedor lo permita y solo necesites tus propias cuentas.

Muchos proveedores te permiten autorizar tu propia cuenta, usuarios de prueba, espacio de trabajo u organización antes de la publicación en el marketplace. Algunos proveedores aún requieren verificación, aprobación de administrador o revisión para ámbitos sensibles, uso en producción, distribución amplia a clientes o espacios de trabajo gestionados. La pantalla de autorización y la consola de administración del proveedor son la fuente de verdad.

Paso 3: Copiar la configuración del cliente

Después de crear la aplicación del proveedor, copia los valores de cliente que necesita OpenConnector.

Valor	Obligatorio	Notas
`clientId`	Sí	Normalmente se llama Client ID, App ID, Application ID o Consumer Key.
`clientSecret`	Normalmente	Algunos proveedores utilizan flujos de cliente público y no requieren un secreto. Si OpenConnector marca el secreto del proveedor como opcional, déjalo vacío solo cuando el proveedor también lo trate como opcional.
Campos adicionales	A veces	Algunos proveedores necesitan configuración adicional del cliente OAuth, como `tenant`, `subdomain`, `developerToken` o identificadores específicos de la cuenta. Utiliza una versión de la consola que exponga los campos requeridos por ese proveedor.

No pongas secretos de cliente OAuth en código de navegador, repositorios públicos, capturas de pantalla, informes de problemas ni prompts de agentes.

Paso 4: Guardar el cliente OAuth en OpenConnector

Utiliza la consola web de OpenConnector para la ruta de configuración normal:

Abre la consola web de OpenConnector, como http://localhost:3000.
Abre Providers y selecciona el proveedor que quieres conectar.
Elige Configure OAuth Client o Edit OAuth Client.
Pega el Client ID y el Client Secret de la aplicación del proveedor.
Elige Save OAuth Client.

Si el proveedor necesita campos de cliente adicionales, rellénalos en el mismo formulario de cliente OAuth. Por ejemplo, los proveedores de Microsoft necesitan un valor de tenant. Si tu consola no muestra un campo que el proveedor requiere, actualiza OpenConnector a una versión que admita el formulario completo de cliente OAuth de ese proveedor antes de continuar.

Después de guardar, la página del proveedor muestra el cliente OAuth como configurado y mantiene el secreto del cliente oculto.

Paso 5: Conectar una cuenta de prueba

Después de guardar el cliente OAuth, permanece en la página del proveedor y elige Connect para iniciar la autorización. Aprueba la pantalla de autorización del proveedor. Después de que el proveedor redirija de vuelta a OpenConnector, confirma que la página del proveedor muestra la cuenta como conectada.

Paso 6: Probar una acción

Utiliza la página del proveedor o la lista de acciones de la consola para ejecutar una acción de lectura de bajo riesgo para el proveedor que conectaste. Los detalles de la acción muestran el esquema de entrada, los ámbitos requeridos y la identidad de la conexión actual.

Utiliza datos de demostración cuando pruebes acciones de escritura.

Notas sobre proveedores

Estos documentos de proveedores son útiles al crear aplicaciones OAuth:

Familia de proveedor	Documentos oficiales	Nota de configuración común
API de Google	Using OAuth 2.0 for Web Server Applications	Utiliza un cliente OAuth de aplicación web. Añade el URI de redirección exacto de OpenConnector a los URI de redirección autorizados. Los ámbitos sensibles o restringidos pueden requerir verificación de Google antes de un uso amplio en producción.
Slack	Installing with OAuth	Añade el URI de redirección exacto de OpenConnector a las URL de redirección de la aplicación. Utiliza un origen de entorno de ejecución público o un túnel HTTPS si Slack no acepta tu URL de callback local.
GitHub	Creating an OAuth app	Una aplicación OAuth de GitHub tiene una sola URL de callback de autorización. Crea aplicaciones separadas si necesitas URL de callback separadas para local, staging y producción.
Microsoft	Register an application with the Microsoft identity platform	Configura un URI de redirección de plataforma web y crea un secreto de cliente. Algunos proveedores de Microsoft de OpenConnector requieren un valor de `tenant` como `common`, `organizations` o un ID de inquilino.
HubSpot	Working with OAuth	Los ámbitos de la solicitud de autorización deben coincidir con los ámbitos configurados de la aplicación. Las URL de redirección de producción deben usar HTTPS; localhost puede usar HTTP para pruebas.
Notion	Authorization	Crea una conexión pública y añade el URI de redirección de OpenConnector en la configuración de OAuth. Revisa las reglas actuales de tipos de aplicación y capacidades de Notion antes de usar la aplicación más allá de tu propio espacio de trabajo.

Solución de problemas

Síntoma	Qué comprobar
El proveedor dice `redirect_uri_mismatch`, URI de redirección no válido o URL de callback no válida.	Confirma que la aplicación del proveedor usa `<openconnector-origin>/oauth/callback`. El esquema, el host, el puerto, la ruta y la barra diagonal final deben coincidir con el origen que los usuarios abren en el navegador.
El proveedor rechaza `http://localhost`.	Utiliza un proveedor que admita localhost para pruebas, o expón el entorno de ejecución a través de un túnel HTTPS o dominio público y configura `OOMOL_CONNECT_ORIGIN` con ese origen antes de reiniciar OpenConnector.
El proveedor dice que la aplicación no está verificada, no está aprobada o no está permitida en el espacio de trabajo.	Comprueba la distribución de la aplicación en el lado del proveedor, los usuarios de prueba, la aprobación de aplicaciones del espacio de trabajo y los requisitos de revisión de ámbitos sensibles. La publicación en el marketplace suele ser independiente de las pruebas privadas, pero las reglas del proveedor varían.
La autorización se realiza correctamente, pero una acción falla por ámbitos faltantes o insuficientes.	Añade los ámbitos requeridos por la acción a la aplicación del proveedor, guarda la aplicación y vuelve a conectar la cuenta del proveedor para que se concedan los nuevos ámbitos.
OpenConnector dice `oauth_client_config_not_found`.	Guarda el cliente OAuth en la misma página del proveedor donde inicias Connect.
La renovación del token falla más adelante.	Confirma que el proveedor emitió un token de renovación. Algunos proveedores requieren parámetros de acceso sin conexión o un nuevo consentimiento. Vuelve a conectar la cuenta si no hay un token de renovación disponible.
Se utiliza la cuenta incorrecta durante la ejecución.	Vuelve a conectar desde un perfil de navegador con la sesión iniciada en la cuenta deseada y, a continuación, selecciona la conexión deseada en la consola antes de probar acciones.

Lista de verificación de seguridad

Configura OOMOL_CONNECT_ENCRYPTION_KEY antes de almacenar secretos de cliente OAuth o credenciales de cuentas conectadas.
Mantén OOMOL_CONNECT_ADMIN_TOKEN privado y utiliza tokens del entorno de ejecución para los llamadores de /v1 y /mcp.
Utiliza ámbitos de privilegio mínimo cuando el proveedor y el conjunto de acciones de OpenConnector lo permitan.
Mantén aplicaciones OAuth separadas para local, staging y producción cuando las reglas de callback del proveedor hagan que sea más sencillo auditarlas.
Elimina las aplicaciones de proveedor no utilizadas, los secretos de cliente antiguos y las conexiones obsoletas de OpenConnector.