Conectar Gmail

Esta guía te lleva —al administrador del tenant— por todo lo que hay que hacer en Google antes de conectar un buzón de Gmail desde OpenDome. Al terminar tendrás dos valores, un Client ID y un Client secret, que pegarás en la consola de OpenDome. Todo el trabajo de aquí se hace en la consola de Google Cloud, fuera de OpenDome.

Esto se hace una sola vez por organización. Hay dos formas de conectar, y la guía cubre ambas:

• Iniciar sesión con Google (recomendada para empezar): un conector sincroniza el buzón de la cuenta que autoriza. Es el camino principal de esta guía.
• Service account, para toda la organización (avanzada): un conector sincroniza una lista de buzones de tu Google Workspace, con una aprobación única del admin de Workspace y sin login por usuario. Ver Sincronizar toda la organización con una service account.

Antes de empezar: ¿Workspace o Gmail personal?

Es la decisión más importante y condiciona todos los pasos siguientes. El conector funciona en ambos casos —es la misma API de Gmail—, pero cómo registras la app cambia mucho.

Tu cuenta de Google	Tipo de app a crear	¿Verificación de Google?	¿Caduca el acceso?	Recomendado
Google Workspace (dominio corporativo)	Interna	No	No	✅ Sí
Gmail personal, en pruebas	Externa · Testing	No	Sí, a los 7 días	⚠️ Solo pruebas
Gmail personal, publicada	Externa · In production	Sí — auditoría de seguridad (CASA)	No	❌ Desaconsejado

Camino recomendado

Si vas a conectar el correo de una empresa, usa una cuenta de Google Workspace y crea la app como Interna. Es el único camino sin verificación de Google y sin caducidad del acceso — justo lo que necesita un conector que sincroniza de forma programada.

Por qué el Gmail personal es problemático

El permiso que pedimos (leer tu correo) es un permiso restringido para Google. En una app externa en modo pruebas, Google caduca el acceso a los 7 días: el conector dejaría de sincronizar cada semana hasta que alguien vuelva a autorizar a mano. Evitarlo obliga a publicar la app, y entonces Google exige una auditoría de seguridad anual (CASA), de pago y con un tercero. Por eso el Gmail personal sirve para una prueba puntual, pero no para producción.

Lo que vas a hacer

  Google Cloud Console
  ┌─────────────────────────────────────────────────────────────────────┐
  │ 1. Crear/elegir un proyecto                                         │
  │ 2. Habilitar la API de Gmail                                        │
  │ 3. Configurar la pantalla de consentimiento (Interna vs Externa)    │
  │ 4. Crear las credenciales de cliente OAuth  ──►  Client ID + Secret │
  └─────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
  OpenDome ── pegas Client ID + Secret ── pulsas "Conectar" ── eliges etiquetas

El Client secret es una contraseña: trátalo como tal (ver Seguridad).

Requisitos previos

• Una cuenta de Google con permiso para crear proyectos en Google Cloud.
  • Para el camino recomendado (app Interna), esa cuenta debe pertenecer a una organización de Google Workspace y tener rol suficiente (normalmente Propietario o Editor del proyecto).
• La URL de redirección (redirect URI) que te da OpenDome (la necesitarás en el paso 4). Es la dirección a la que Google devolverá el navegador tras autorizar: https://<tu-consola-de-tenant>/v1/oauth/callback. OpenDome te muestra la URL exacta en la pantalla de conexión del conector — cópiala de ahí.
• Opcionalmente, qué etiquetas de Gmail quieres sincronizar (las eliges después, dentro de OpenDome; en blanco sincroniza Recibidos y Enviados).

Paso 1 — Crear (o elegir) un proyecto en Google Cloud

Un proyecto de Google Cloud es el contenedor donde vive tu app OAuth.

1. Entra en console.cloud.google.com.
2. Arriba, en el selector de proyectos, pulsa New Project (Nuevo proyecto).
3. Ponle un nombre reconocible (p. ej. opendome-gmail-connector) y, si te lo pide, elige tu organización de Workspace. Pulsa Create.
4. Espera a que se cree y selecciónalo en el selector de arriba antes de seguir.

Nota

Puedes reutilizar un proyecto existente si ya tienes uno para integraciones — por ejemplo el que creaste para el conector de Google Drive. Lo importante es que los pasos 2–4 se hagan dentro del proyecto seleccionado.

Paso 2 — Habilitar la API de Gmail

La app solo puede llamar a APIs que estén habilitadas en el proyecto.

1. Menú lateral → APIs & Services → Library (Biblioteca).
2. Busca Gmail API.
3. Ábrela y pulsa Enable (Habilitar).

Paso 3 — Configurar la pantalla de consentimiento de OAuth

Es la ventana que verá quien autorice (“OpenDome quiere acceder a tu Gmail”). Hay que configurarla una vez antes de poder crear credenciales.

1. Menú lateral → APIs & Services → OAuth consent screen.
2. User Type / Tipo de usuario:
   • Elige Internal (Interna) si tu cuenta es de Google Workspace ← recomendado. Solo podrán autorizar personas de tu organización y Google no exigirá verificación.
   • Elige External (Externa) si usas Gmail personal (es la única opción).
3. Rellena los datos: App name (p. ej. OpenDome – Gmail connector), User support email y Developer contact. Logo y enlaces son opcionales.
4. Scopes (permisos): pulsa Add or remove scopes y añade el permiso de solo lectura de Gmail:

   https://www.googleapis.com/auth/gmail.readonly

   Es el único que OpenDome necesita: leer, nunca enviar, modificar ni borrar. Guarda.
5. Solo si elegiste Externa: en Test users, pulsa Add users y añade la dirección de Google que va a autorizar la conexión. Sin esto, la autorización falla con un error de “app no verificada”.
6. Guarda. No hace falta pulsar “Publish app” para el camino recomendado (Interna), ni para probar con una Externa en modo pruebas.

Paso 4 — Crear las credenciales de cliente OAuth

Aquí es donde salen el Client ID y el Client secret.

1. Menú lateral → APIs & Services → Credentials (Credenciales).
2. Pulsa + Create Credentials → OAuth client ID.
3. Application type / Tipo de aplicación: elige Web application (Aplicación web).
4. Name: algo reconocible (p. ej. opendome-gmail-web).
5. Authorized redirect URIs: pulsa + Add URI y pega la URI de redirección de OpenDome (la de Requisitos previos). Debe coincidir exactamente —protocolo, host, puerto y ruta—; un solo carácter de diferencia hace que Google rechace la conexión.

   https://<tu-consola-de-tenant>/v1/oauth/callback

6. Pulsa Create. Google te muestra un cuadro con el Client ID y el Client secret.

Nota

Puedes añadir varias URIs de redirección a la misma app. No necesitas rellenar “Authorized JavaScript origins”.

Paso 5 — Copiar el Client ID y el Client secret

• Client ID — una cadena larga que termina en .apps.googleusercontent.com. No es secreto, pero cópialo tal cual.
• Client secret — empieza por GOCSPX-…. Es una contraseña. Cópialo a un sitio seguro; si lo pierdes puedes generar otro desde la misma pantalla.

Y ahora, en OpenDome

1. Entra en tu tenant → Conectores → Nuevo conector → Gmail.
2. Pega el Client ID y el Client secret en sus campos.
3. Pulsa Conectar. Se abre la ventana de Google: elige la cuenta cuyo buzón quieres sincronizar y acepta el permiso de solo lectura. Volverás a OpenDome automáticamente.
4. Ajusta si quieres el campo Etiquetas: en blanco sincroniza Recibidos y Enviados; puedes listar etiquetas concretas (p. ej. Facturas), o usar all para todo el buzón salvo Spam, Papelera y Borradores.
5. Guarda. El conector queda listo para su primera sincronización.

Nota

En el paso Conectar, OpenDome obtiene —dentro de tu celda— el “refresh token” que le permite leer el buzón de forma continuada. Ese token nunca sale de tu entorno. La primera sincronización lee todo lo que haya en las etiquetas elegidas; las siguientes solo traen lo nuevo.

Las etiquetas funcionan como en Gmail, no como carpetas

Un mensaje conserva sus etiquetas al añadirle otras — etiquetar no lo saca de Recibidos. Las etiquetas anidadas son independientes: sincronizar Facturas no incluye Facturas/2026; lista ambas si quieres ambas. Y si un filtro de Gmail archiva con “Omitir Recibidos”, ese correo nunca lleva la etiqueta de Recibidos — añade su etiqueta al conector (o usa all) para que se recoja.

Sincronizar toda la organización con una service account (avanzado)

Un solo conector puede sincronizar muchos buzones de tu Google Workspace — sin login por usuario — usando una service account con delegación a nivel de dominio (domain-wide delegation). Requiere aprobación de un superadministrador de Workspace y sustituye al flujo de inicio de sesión de arriba (sigues necesitando los pasos 1–2: un proyecto con la API de Gmail habilitada).

1. En el proyecto: IAM & Admin → Service Accounts → + Create service account. Ponle nombre (p. ej. opendome-gmail-org); no necesita roles. Crea.
2. Abre la service account → Keys → Add key → Create new key → JSON. Se descarga un fichero .json — es una contraseña, guárdalo a buen recaudo.
3. Copia el Client ID de la service account (el Unique ID numérico largo de su página de detalle).
4. Como superadmin de Workspace, entra en admin.google.com → Seguridad → Acceso y control de datos → Controles de API → Delegación de todo el dominio → Añadir nueva:
   • ID de cliente: el ID numérico del paso anterior.
   • Ámbitos de OAuth: exactamente

     https://www.googleapis.com/auth/gmail.readonly

   • Autoriza.
5. En OpenDome, en el paso de conexión del conector de Gmail, elige la opción de service account, pega el fichero JSON completo en su campo y rellena Buzones a sincronizar con las direcciones, separadas por comas (p. ej. ana@acme.com, luis@acme.com).

Attenzione

Con la delegación, esa clave puede leer el correo de cualquier buzón que listes. Delimita la lista con intención, no compartas el JSON con nadie, y elimina la entrada de delegación en admin.google.com si dejas de usar el conector.

Problemas frecuentes

Síntoma	Causa y solución
redirect_uri_mismatch al Conectar	La URI de redirección de la app no coincide exactamente con la de OpenDome. Revisa protocolo (http/https), host, puerto y ruta (/v1/oauth/callback), sin barra final de más.
“Access blocked: app no verificada”	App Externa y no añadiste tu correo como usuario de prueba (paso 3.5), o autorizas con una cuenta que no está en la lista. Añade el usuario, o —si tienes Workspace— cambia a app Interna.
El conector deja de sincronizar tras ~1 semana	App Externa en modo pruebas: Google caduca el acceso a los 7 días. Solución real: Workspace + app Interna.
invalid_client	Client ID o Client secret mal copiados (espacios, recortes). Vuelve a copiarlos del paso 5.
“Etiqueta no encontrada” en la sincronización	El nombre de etiqueta del conector no existe en ese buzón. Los nombres son los de Gmail tal cual (sin distinguir mayúsculas); una etiqueta anidada es su ruta completa, p. ej. Facturas/2026.
unauthorized_client con service account	Falta la delegación de dominio o está mal: el ID de cliente numérico en admin.google.com debe ser el de la service account, y el ámbito exactamente https://www.googleapis.com/auth/gmail.readonly. Los cambios de delegación pueden tardar unos minutos en aplicarse.
“Refresh token no recibido”	Ocurre si reautorizas sin forzar el consentimiento. Nuestra app ya pide access_type=offline + prompt=consent, así que vuelve a pulsar Conectar y acepta de nuevo.

Seguridad

• Solo lectura. El único permiso que pedimos es gmail.readonly. OpenDome no puede enviar, modificar ni borrar nada del buzón.
• Tus credenciales no salen de tu entorno. El Client secret y el token —o la clave de la service account— viven en un Secret de tu celda; el intercambio del token OAuth ocurre dentro de tu celda. El plano de control global de OpenDome nunca los ve y nunca contacta con Google en tu nombre.
• Egress mínimo. El conector solo puede salir hacia los dominios de Google estrictamente necesarios (accounts.google.com, oauth2.googleapis.com, gmail.googleapis.com, www.googleapis.com); cualquier otra salida está bloqueada por defecto.
• Revocable en cualquier momento. Retira el acceso desde la cuenta de Google (myaccount.google.com/permissions), elimina el cliente OAuth en Google Cloud o —con service account— quita la entrada de delegación en admin.google.com; el conector pierde el acceso de lectura inmediatamente.
• Rotación del secret. Para rotar, genera un nuevo Client secret (o una nueva clave de service account) en Google Cloud y vuelve a conectarlo en OpenDome; el anterior queda invalidado.