Migrar correo de Google Workspace con imapsync (cuenta de servicio OAuth2)

Cuando un cliente quiere trasladar todo el correo de un dominio alojado en Google Workspace hacia nuestros servidores, la herramienta de siempre sigue siendo imapsync. El problema es que Google ya no permite conectar por IMAP usando la contraseña normal de la cuenta, así que el método clásico --password1 'lacontraseña' no funciona contra Gmail.

En esta guía explicamos las dos formas válidas de autenticar el origen Google Workspace y, en concreto, cómo configurar una cuenta de servicio (service account) con delegación a nivel de dominio, que es la vía recomendada para migrar todas las cuentas de un dominio de una sola vez sin tener que tocar a cada usuario.

Por qué ya no sirve la contraseña normal

Google ha retirado el acceso por "aplicaciones menos seguras" (basic auth) de forma escalonada:

• 15 de junio de 2024: se elimina de la consola de administración el ajuste de aplicaciones menos seguras. El administrador ya no puede activarlo (las conexiones existentes seguían funcionando temporalmente).
• 14 de marzo de 2025 (hito crítico): los protocolos IMAP, SMTP, POP, CalDAV y CardDAV dejan de funcionar con la contraseña de la cuenta (basic auth). A partir de esta fecha no hay ninguna excepción: todo acceso debe usar OAuth.
• 1 de mayo de 2025: Google confirma el fin definitivo de la autenticación por usuario y contraseña para aplicaciones de terceros; cualquier conexión que aún use basic auth falla.

Por tanto, el IMAP "normal" con la contraseña de la cuenta ya no existe en Google Workspace. Hay que autenticar con OAuth 2.0, y para ello tenemos dos caminos.

Las dos opciones

Si solo vas a migrar una o dos cuentas, las contraseñas de aplicación (descritas en Trasladar cuentas Gmail a Hostsuar) son lo más rápido. Para un dominio entero, sigue con la cuenta de servicio.

Configurar la cuenta de servicio (lo hace el administrador de Workspace)

Estos pasos los realiza una sola vez un superadministrador del dominio Google Workspace. Al terminar, se obtiene un fichero JSON que sirve para autenticar todas las cuentas del dominio.

1. Crear o seleccionar un proyecto en Google Cloud

Accede a console.cloud.google.com con la cuenta de administrador y crea un proyecto nuevo (por ejemplo migracion-correo) o selecciona uno existente.

2. Habilitar la Gmail API

En el menú lateral ve a APIs y servicios → Biblioteca, busca Gmail API y pulsa Habilitar. Este paso es imprescindible: sin la Gmail API habilitada la migración fallará al conectar.

3. Crear la cuenta de servicio y su clave JSON

Ve a APIs y servicios → Credenciales → Crear credenciales → Cuenta de servicio y ponle un nombre. El asistente te ofrecerá después dos pasos marcados como (opcional): "Permisos / Otorgar acceso al proyecto" (seleccionar un rol) y "Principales con acceso". Deja ambos vacíos y continúa: esta cuenta de servicio no necesita ningún rol IAM sobre el proyecto, porque el acceso a los buzones se concede en el paso 4 (delegación a nivel de dominio), no aquí. Pulsa Listo para crearla.

Después, dentro de la cuenta de servicio, entra en la pestaña Claves → Agregar clave → Crear clave nueva y elige el formato JSON (no uses P12).

Se descargará un fichero con esta estructura, que renombrarás a secret.xoauth2.json:

{
  "type": "service_account",
  "project_id": "...",
  "private_key_id": "...",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "xxx@proyecto.iam.gserviceaccount.com",
  "client_id": "1234567890...",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://accounts.google.com/o/oauth2/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "..."
}

Apunta el valor de client_id del JSON (un número largo): lo necesitaremos en el siguiente paso. Es el identificador OAuth2 de la cuenta de servicio y es justo el que se pega en el campo ID de cliente de la delegación a nivel de dominio (paso 4).

4. Autorizar la delegación a nivel de dominio

Este paso es en la consola de administración de Google Workspace (admin.google.com), que es un sitio distinto del Google Cloud Console donde creaste la cuenta de servicio.

Lo más rápido es ir directamente a la URL de delegación (logueado como superadministrador):

https://admin.google.com/ac/owl/domainwidedelegation

O bien, navegando: Menú (☰) → Seguridad → Control de acceso y de datos → Controles de API → "Gestionar delegación de todo el dominio". Una vez ahí, pulsa Añadir nueva y:

• En ID de cliente, pega el client_id del paso anterior.
• En Ámbitos de OAuth, introduce estos scopes (separados por coma):

https://mail.google.com/,https://www.googleapis.com/auth/gmail.imap_admin

Muy importante: https://mail.google.com/ es el scope de acceso IMAP completo y el que exige imapsync; es imprescindible. Añadimos además gmail.imap_admin, el scope específico para delegación de dominio, que fuerza a mostrar todas las etiquetas y mensajes por IMAP aunque el usuario los hubiera ocultado o tuviera límites de carpeta, de modo que no se quede nada sin migrar. Los scopes de solo lectura (gmail.readonly) no permiten iniciar sesión por IMAP y la migración no funcionará.

Pulsa Autorizar para guardar.

5. Comprobar que IMAP está habilitado

En la consola de administración, ve a Aplicaciones → Google Workspace → Gmail → Acceso de usuario final y asegúrate de que el acceso IMAP está activado (normalmente lo está por defecto).

Con esto, la parte de Google está lista. El administrador solo tiene que entregarnos el fichero secret.xoauth2.json y confirmar que autorizó el client_id con los scopes del paso 4.