Cómo conectar Google Drive con Onyx paso a paso

Google Drive puede convertirse en una de las principales fuentes de conocimiento de Onyx. Al conectar ambos servicios, la plataforma indexa los documentos almacenados en Drive para que los usuarios puedan encontrarlos mediante búsquedas y utilizarlos como contexto en conversaciones y agentes de inteligencia artificial.

Esta integración no debe confundirse con la sincronización convencional de archivos entre ordenadores. Onyx no crea una copia local de Google Drive ni sirve para transferir documentos entre dispositivos. Su función consiste en leer el contenido autorizado, procesarlo e incorporarlo a su índice de conocimiento.

Existen dos métodos de conexión. Las organizaciones con Google Workspace pueden utilizar una cuenta de servicio, que es el sistema recomendado para entornos empresariales. También puede configurarse una aplicación OAuth, una alternativa válida para cuentas individuales y organizaciones que prefieran autorizar el acceso mediante un usuario.

Qué puede indexar Onyx desde Google Drive

El conector de Google Drive permite incorporar documentos alojados en unidades personales y espacios de trabajo autorizados. Entre los formatos compatibles se encuentran:

• Documentos, hojas de cálculo y presentaciones de Google.
• Archivos de Microsoft Word, Excel y PowerPoint.
• Documentos PDF.
• Archivos CSV y TXT.
• Otros formatos de documentos, texto e imágenes admitidos por el sistema.

Una vez indexado el contenido, Onyx puede recuperarlo durante una búsqueda o utilizarlo como contexto para generar respuestas mediante RAG. La calidad del resultado dependerá del contenido disponible, de los permisos configurados y del modelo utilizado.

También puedes crear varios conectores de Google Drive dentro de una misma instancia. Cada uno puede utilizar su propia credencial, lo que permite separar diferentes dominios de Google Workspace, departamentos o fuentes documentales.

OAuth o cuenta de servicio: qué método elegir

Característica	OAuth	Cuenta de servicio
Google Workspace obligatorio	No	Sí
Autorización	La realiza un usuario de Google	La realiza una identidad técnica
Uso recomendado	Cuenta individual o despliegue pequeño	Organizaciones y despliegues empresariales
Acceso administrativo	Solo es necesario para determinadas funciones empresariales	Requiere configuración en Google Workspace
Sincronización de permisos	Requiere una cuenta administradora de Workspace	Compatible mediante delegación en todo el dominio
Gestión de credenciales	Cliente OAuth y autorización del usuario	Archivo JSON con la clave de servicio

Para una cuenta personal, OAuth suele ser la opción más sencilla. Si necesitas indexar documentos de una organización, administrar varios espacios de trabajo o conservar los permisos de Google Drive dentro de Onyx, la cuenta de servicio ofrece un control más adecuado.

Cómo conectar Google Drive con Onyx mediante OAuth

El método OAuth permite que una persona autorice a Onyx para acceder a los documentos disponibles en su cuenta. No requiere una suscripción empresarial de Google Workspace, aunque sí tendrás que crear un proyecto y unas credenciales en Google Cloud.

Crear un proyecto y activar las API

Entra en Google Cloud Console y crea un proyecto dedicado a la integración. Después, abre la biblioteca de API y habilita estos servicios:

• Google Drive API.
• Admin SDK API.
• Google Docs API.
• Google Sheets API.

Utilizar un proyecto independiente facilita la revisión de permisos y permite revocar la integración sin afectar a otras aplicaciones de la organización.

Configurar la pantalla de consentimiento

Abre la sección de OAuth en Google Cloud y configura la pantalla de consentimiento. Dependiendo del tipo de cuenta, podrás crear una aplicación interna para usuarios de tu organización o una aplicación externa.

Si la aplicación permanece en modo de prueba, añade como usuarios de prueba las cuentas que utilizarán el conector. Una cuenta no autorizada puede recibir un error al intentar completar el inicio de sesión.

Crear el cliente OAuth

Crea unas credenciales de tipo aplicación web. Las direcciones autorizadas dependen de dónde se ejecute Onyx.

En una instalación local, el origen autorizado habitual es:

http://localhost:3000

La URI de redirección correspondiente es:

http://localhost:3000/admin/connectors/google-drive/auth/callback

Si Onyx utiliza un dominio propio, sustituye http://localhost:3000 por la dirección pública de la instancia:

https://onyx.ejemplo.com/admin/connectors/google-drive/auth/callback

La dirección debe coincidir exactamente con la registrada en Google Cloud. Una diferencia en el protocolo, dominio, puerto o ruta puede provocar el error redirect_uri_mismatch.

Descarga el archivo JSON con las credenciales del cliente cuando finalices la configuración.

Añadir la credencial OAuth en Onyx

1. Abre el Panel de Administración de Onyx.
2. Entra en la sección para añadir conectores.
3. Selecciona Google Drive.
4. Pulsa la opción para crear una credencial nueva.
5. Selecciona el método OAuth.
6. Sube o pega el contenido del archivo JSON descargado.
7. Pulsa el botón para autenticarte con Google Drive.
8. Inicia sesión con la cuenta que contiene los documentos.
9. Revisa los permisos solicitados y completa la autorización.

Después de crear la credencial, selecciónala y continúa con la configuración del conector. El archivo de la aplicación OAuth queda asociado a esa credencial, por lo que puede reutilizarse para crear otros conectores compatibles dentro de la instancia.

Cómo conectar Google Drive mediante una cuenta de servicio

La cuenta de servicio es el método recomendado para organizaciones con Google Workspace. En lugar de depender de la sesión de una persona, Onyx utiliza una identidad técnica autorizada para consultar los documentos.

Crear el proyecto y la cuenta de servicio

Desde Google Cloud Console, crea un proyecto y habilita las siguientes API:

• Google Drive API.
• Admin SDK API.
• Google Docs API.
• Google Sheets API.

Después, abre la sección de cuentas de servicio, crea una nueva identidad y genera una clave en formato JSON. Guarda el archivo en un lugar seguro, ya que contiene una credencial que no debe publicarse ni incluirse en un repositorio.

Activar la delegación en todo el dominio

Copia el identificador único de la cuenta de servicio y entra en la Consola de Administración de Google Workspace. En la sección de delegación en todo el dominio, añade un cliente nuevo utilizando ese identificador.

Onyx necesita los siguientes ámbitos de solo lectura:

https://www.googleapis.com/auth/drive.readonly,
https://www.googleapis.com/auth/drive.metadata.readonly,
https://www.googleapis.com/auth/admin.directory.group.readonly,
https://www.googleapis.com/auth/admin.directory.user.readonly

Concede únicamente los ámbitos necesarios. No es recomendable sustituirlos por permisos generales de lectura y escritura si el conector solo necesita indexar documentos.

Preparar la cuenta administradora principal

Al crear la credencial en Onyx tendrás que indicar un correo de administrador principal. Este correo no es el de la cuenta de servicio, sino el de un usuario real de Google Workspace que pueda ser utilizado para la delegación.

La cuenta debe disponer de acceso a Drive y Documentos, además de permisos administrativos de lectura para:

• Usuarios.
• Grupos.
• Unidades organizativas.
• Configuración de Drive y Documentos.

Puedes utilizar una cuenta administradora existente o crear una cuenta específica para Onyx con los privilegios mínimos necesarios.

Crear la credencial en Onyx

1. Entra en el Panel de Administración de Onyx.
2. Selecciona el conector de Google Drive.
3. Crea una credencial nueva.
4. Elige la opción de cuenta de servicio.
5. Sube el archivo JSON generado en Google Cloud.
6. Introduce el correo del administrador principal.
7. Guarda la credencial.
8. Selecciónala y continúa con la creación del conector.

Las versiones actuales de Onyx permiten almacenar varias credenciales de Google Drive de manera independiente. Si administras más de un dominio de Workspace, crea una credencial y un conector separados para cada uno.

Cómo configurar el acceso a los documentos indexados

La autenticación determina qué contenido puede leer el conector, pero la configuración de acceso determina quién podrá consultarlo desde Onyx. Antes de iniciar la indexación, revisa cuidadosamente esta opción.

• Privado: el contenido solo está disponible para la persona que creó el conector y para los usuarios o grupos añadidos expresamente.
• Público: todos los usuarios de la instancia de Onyx pueden consultar el contenido indexado.
• Sincronización automática de permisos: Onyx mantiene una lista de acceso basada en los permisos existentes en Google Drive.

No marques como público un conector que pueda acceder a documentos confidenciales. Esta opción puede hacer que usuarios de Onyx vean información que originalmente estaba restringida dentro de Google Drive.

La sincronización automática de permisos está disponible en Onyx Cloud y en la edición Enterprise. Para Google Drive requiere una cuenta de servicio o una autorización OAuth realizada por un administrador de Google Workspace con los privilegios adecuados.

Cómo iniciar y supervisar la indexación

Después de crear el conector, Onyx comenzará a recuperar y procesar los documentos. Puedes comprobar su estado desde la sección Existing Connectors del Panel de Administración.

Los estados más habituales son:

• Scheduled: el conector está esperando a que comience la siguiente ejecución.
• Initial Indexing: se está realizando la primera indexación.
• Indexing: se están recuperando cambios nuevos.
• Indexed: la última sincronización terminó correctamente.
• Paused: la indexación está detenida.
• Error: se produjo un problema durante la recuperación o el procesamiento.

Los documentos indexados antes de un error permanecen disponibles. Onyx volverá a intentar la operación, aunque el conector puede quedar pausado si acumula demasiados errores consecutivos.

Cómo ajustar la frecuencia de actualización

Las opciones avanzadas del conector permiten controlar cuándo se recuperan los cambios y cuándo se eliminan del índice los documentos que ya no existen en Google Drive.

• Refresh Frequency: determina cada cuánto tiempo se buscan documentos nuevos o modificados. El valor predeterminado es 30 minutos.
• Prune Frequency: establece cada cuánto se retiran del índice los documentos eliminados o que han dejado de estar disponibles. El valor predeterminado es 30 días.
• Indexing Start Date: permite ignorar contenido anterior a una fecha determinada.

Reducir demasiado el intervalo de actualización puede aumentar las llamadas a las API de Google y hacer más probable que se alcancen límites temporales. Elige una frecuencia adecuada a la rapidez con la que cambian los documentos.

Errores frecuentes al conectar Google Drive con Onyx

Google muestra el error redirect_uri_mismatch

La URI registrada en Google Cloud no coincide exactamente con la utilizada por Onyx. Comprueba el protocolo, el dominio, el puerto, la ruta y la presencia de barras finales.

La cuenta no puede completar la autorización OAuth

Si la aplicación está en modo de prueba, comprueba que la cuenta aparezca entre los usuarios autorizados. En una organización, revisa también las políticas que limitan las aplicaciones OAuth de terceros.

La cuenta de servicio no puede consultar los documentos

Verifica que la delegación en todo el dominio esté activa, que el identificador de cliente sea correcto y que se hayan concedido todos los ámbitos de solo lectura requeridos.

El correo de administrador principal es rechazado

No utilices el correo de la cuenta de servicio. Debes indicar el de un usuario de Google Workspace con acceso a Drive y con los privilegios administrativos de lectura necesarios.

Algunos documentos no aparecen en las búsquedas

Comprueba que el archivo tenga un formato compatible, que la credencial utilizada pueda acceder a él y que no sea anterior a la fecha inicial de indexación. Revisa también el estado del conector y espera a que termine la indexación inicial.

Un usuario puede ver documentos que no debería

Revisa inmediatamente el tipo de acceso del conector. Si está configurado como público, todo su contenido será visible para los usuarios de Onyx. Utiliza acceso privado o sincronización automática de permisos cuando el origen contenga información restringida.

El conector entra repetidamente en estado de error

Revisa el estado de los conectores y los registros de los servicios de Onyx. En instalaciones autogestionadas puedes aumentar temporalmente el nivel de registro a debug para obtener más información, evitando mantener este nivel innecesariamente en producción.

Conectar Google Drive con Onyx permite convertir documentos dispersos en una fuente de conocimiento consultable mediante búsquedas, chat y agentes de IA. Para una cuenta individual, OAuth suele ser suficiente. En organizaciones con Google Workspace, la cuenta de servicio proporciona una administración más estable y permite aplicar funciones empresariales de sincronización de permisos.

La parte más importante no es solamente autorizar el acceso, sino configurar correctamente quién podrá consultar los documentos después de indexarlos. Antes de activar el conector en producción, prueba la integración con un conjunto reducido de archivos, revisa los permisos desde varias cuentas y confirma que Onyx no muestra información fuera del ámbito previsto.