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

Cuando un cliente quiere trasladar el correo de un dominio alojado en Google Workspace hacia nuestros servidores, puede usar imapsync. Google ya no permite que las aplicaciones de terceros conecten por IMAP con la contraseña normal de la cuenta. Debe usarse OAuth 2.0 o, para una migración puntual de pocas cuentas cuando la política lo permita, una contraseña de aplicación.

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. La misma credencial puede autenticar los buzones autorizados sin tocar a cada usuario, aunque imapsync debe sincronizarlos uno por uno.

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: Google comenzó a desactivar en las cuentas de Workspace el acceso de aplicaciones de terceros mediante la contraseña normal.
• 1 de mayo de 2025: finalizó la transición anunciada para estas aplicaciones.

Por tanto, no configures imapsync con la contraseña normal. La delegación OAuth2 es la opción adecuada para muchas cuentas; una contraseña de aplicación es una excepción por usuario que requiere verificación en dos pasos y que el administrador no la haya restringido.

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 con una clave privada. La delegación puede permitir suplantar a usuarios del dominio para los ámbitos concedidos: una lista de buzones escrita en un script no limita técnicamente ese poder.

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. Revisar el proyecto de Google Cloud

La autenticación IMAP XOAUTH2 usa el ámbito de correo autorizado en la delegación del dominio. Habilitar la Gmail API no sustituye esa autorización y no es un requisito que imapsync documente para su flujo mediante JSON. Puedes habilitarla si otras herramientas del proyecto van a usar la API, pero no concedas roles IAM adicionales a la cuenta de servicio para esta migración.

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 este scope:

https://mail.google.com/

Muy importante: https://mail.google.com/ es el scope que solicita el flujo JSON de imapsync para acceder por IMAP. Autoriza solo ese ámbito. gmail.readonly no permite iniciar sesión por IMAP. Google documenta gmail.imap_admin como una alternativa para clientes que soliciten expresamente ese ámbito; añadirlo a la consola no hace que imapsync lo solicite ni garantiza que aparezcan etiquetas ocultas.

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. En la política de clientes de correo de la unidad organizativa afectada debe estar permitido cualquier cliente de correo; una restricción a identificadores OAuth concretos puede bloquear la cuenta de servicio aunque la delegación exista.

Con esto, la parte de Google está lista. El fichero secret.xoauth2.json contiene una clave privada y debe tratarse como una credencial con capacidad para suplantar a los buzones autorizados.

Probar y ejecutar imapsync

Este flujo requiere una versión de imapsync compatible con cuentas de servicio JSON y sus dependencias XOAUTH2. No funciona en la interfaz gráfica de migración basada en usuario y contraseña. Ejecuta primero una prueba de autenticación para una cuenta:

imapsync \
  --host1 imap.gmail.com --ssl1 --sslargs1 SSL_verify_mode=1 --user1 usuario@tudominio.com \
  --password1 /ruta/privada/secret.xoauth2.json --authmech1 XOAUTH2 \
  --host2 SERVIDOR_IMAP_DESTINO --ssl2 --sslargs2 SSL_verify_mode=1 --user2 usuario@tudominio.com \
  --passfile2 "$HOME/.imapsync-destino" --justlogin

Quita --justlogin solo cuando ambas autenticaciones funcionen. La delegación evita crear una clave por usuario, pero imapsync sigue ejecutando una sincronización por buzón. Prueba primero una cuenta, revisa etiquetas y recuentos y después procesa las demás de forma controlada. Gmail limita las descargas IMAP a 2.500 MB por usuario por día según el límite publicado, que Google puede modificar; al alcanzar el límite, detén esa cuenta y espera antes de reanudarla. Usa en SERVIDOR_IMAP_DESTINO el hostname con certificado válido indicado en Conectar dispositivos de cPanel.

Entrega y retirada segura de la clave

• Transfiere el JSON mediante un intercambio cifrado de un solo uso, con caducidad y acceso limitado a la persona que ejecutará la migración. No lo pegues en el texto de un ticket ni lo envíes por correo electrónico.
• En el equipo de migración, guárdalo fuera de directorios públicos, con propietario exclusivo y permisos 0600: chmod 600 secret.xoauth2.json. No lo copies a repositorios, copias compartidas ni registros de comandos.
• Limita la delegación a la duración de la migración. Al terminar y verificar los buzones, elimina la autorización de delegación a nivel de dominio, revoca y elimina la clave de la cuenta de servicio en Google Cloud y borra todas las copias locales del JSON.
• Si la clave se envió por un canal incorrecto o pudo quedar expuesta, revócala antes de continuar y genera una nueva; borrar solo el fichero no invalida una clave ya copiada.

Define quién puede ejecutar la migración

Autoriza este procedimiento solo para los buzones y la operación acordados. El ámbito https://mail.google.com/ no es de solo lectura: el hecho de ejecutar imapsync sin opciones de borrado no reduce los permisos que tendría quien obtenga la clave.

La política de IMAP restringida a identificadores OAuth no admite este flujo de delegación, según Google. No amplíes por comodidad la política de toda la organización: el administrador debe valorar la unidad afectada, la duración y el restablecimiento de los controles, o elegir otro método autorizado.

Antes de procesar el conjunto, comprueba una cuenta y conserva un inventario de origen, destino, carpetas omitidas, errores y última sincronización. Al cerrar el trabajo, además de retirar la clave y la delegación, revisa que las políticas temporales vuelvan a su estado previsto.