Migrer la messagerie Google Workspace avec imapsync (compte de service OAuth2)

Lorsqu'un client veut transférer vers nos serveurs la messagerie d'un domaine hébergé chez Google Workspace, il peut utiliser imapsync. Google ne permet plus aux applications tierces de se connecter en IMAP avec le mot de passe habituel du compte. Il faut utiliser OAuth 2.0 ou, pour une migration ponctuelle de quelques comptes lorsque la politique le permet, un mot de passe d'application.

Ce guide présente les deux façons valables d'authentifier l'origine Google Workspace et, plus précisément, comment configurer un compte de service (service account) avec délégation au niveau du domaine. Le même identifiant peut authentifier les boîtes mail autorisées sans intervenir sur chaque utilisateur, même si imapsync doit les synchroniser une par une.

Pourquoi le mot de passe habituel ne fonctionne plus

Google a supprimé progressivement l'accès des « applications moins sécurisées » (basic auth) :

• 15 juin 2024 : le réglage applications moins sécurisées disparaît de la console d'administration. L'administrateur ne peut plus l'activer (les connexions existantes continuaient de fonctionner temporairement).
• 14 mars 2025 : Google a commencé à désactiver, sur les comptes Workspace, l'accès des applications tierces avec le mot de passe habituel.
• 1er mai 2025 : fin de la transition annoncée pour ces applications.

Ne configurez donc pas imapsync avec le mot de passe habituel. La délégation OAuth2 est l'option adaptée pour de nombreux comptes ; un mot de passe d'application est une exception par utilisateur qui exige la validation en deux étapes et que l'administrateur ne l'ait pas restreint.

Les deux options

Si vous ne migrez qu'un ou deux comptes, les mots de passe d'application (décrits dans Transférer des comptes Gmail vers Hostsuar) sont la solution la plus rapide. Pour un domaine entier, poursuivez avec le compte de service.

Configurer le compte de service (à faire par l'administrateur Workspace)

Ces étapes sont réalisées une seule fois par un super-administrateur du domaine Google Workspace. À la fin, on obtient un fichier JSON contenant une clé privée. La délégation peut permettre d'emprunter l'identité des utilisateurs du domaine pour les champs d'application accordés : une liste de boîtes mail écrite dans un script ne limite pas techniquement ce pouvoir.

1. Créer ou sélectionner un projet dans Google Cloud

Connectez-vous à console.cloud.google.com avec le compte administrateur et créez un nouveau projet (par exemple migracion-correo) ou sélectionnez-en un existant.

2. Vérifier le projet Google Cloud

L'authentification IMAP XOAUTH2 utilise le champ d'application de messagerie autorisé dans la délégation du domaine. Activer l'API Gmail ne remplace pas cette autorisation et n'est pas une condition documentée par imapsync pour son flux via JSON. Vous pouvez l'activer si d'autres outils du projet doivent utiliser l'API, mais n'accordez pas de rôles IAM supplémentaires au compte de service pour cette migration.

3. Créer le compte de service et sa clé JSON

Allez dans API et services → Identifiants → Créer des identifiants → Compte de service et donnez-lui un nom. L'assistant vous proposera ensuite deux étapes marquées (facultatif) : « Autorisations / Accorder l'accès au projet » (choisir un rôle) et « Comptes principaux avec accès ». Laissez-les vides toutes les deux et continuez : ce compte de service n'a besoin d'aucun rôle IAM sur le projet, car l'accès aux boîtes mail est accordé à l'étape 4 (délégation au niveau du domaine), pas ici. Cliquez sur OK pour le créer.

Ensuite, dans le compte de service, ouvrez l'onglet Clés → Ajouter une clé → Créer une clé et choisissez le format JSON (n'utilisez pas P12).

Un fichier avec cette structure sera téléchargé ; renommez-le 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": "..."
}

Notez la valeur de client_id dans le JSON (un long nombre) : vous en aurez besoin à l'étape suivante. C'est l'identifiant OAuth2 du compte de service, celui qui se colle dans le champ ID client de la délégation au niveau du domaine (étape 4).

4. Autoriser la délégation au niveau du domaine

Cette étape se fait dans la console d'administration Google Workspace (admin.google.com), un site différent de la Google Cloud Console où vous avez créé le compte de service.

Le plus rapide est d'ouvrir directement l'URL de délégation (connecté en tant que super-administrateur) :

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

Ou bien, par la navigation : Menu (☰) → Sécurité → Contrôle des accès et des données → Commandes des API → « Gérer la délégation au niveau du domaine ». Une fois sur cette page, cliquez sur Ajouter et :

• Dans ID client, collez le client_id de l'étape précédente.
• Dans Champs d'application OAuth, saisissez ce scope :

https://mail.google.com/

Très important : https://mail.google.com/ est le scope que demande le flux JSON d'imapsync pour accéder en IMAP. Autorisez uniquement ce champ d'application. gmail.readonly ne permet pas d'ouvrir une session IMAP. Google documente gmail.imap_admin comme alternative pour les clients qui demandent expressément ce champ d'application ; l'ajouter dans la console ne fait pas qu'imapsync le demande et ne garantit pas que les libellés masqués apparaissent.

Cliquez sur Autoriser pour enregistrer.

5. Vérifier qu'IMAP est activé

Dans la console d'administration, allez dans Applications → Google Workspace → Gmail → Accès des utilisateurs finaux et assurez-vous que l'accès IMAP est activé. Dans la politique des clients de messagerie de l'unité organisationnelle concernée, n'importe quel client de messagerie doit être autorisé ; une restriction à certains identifiants OAuth peut bloquer le compte de service même si la délégation existe.

La partie Google est alors prête. Le fichier secret.xoauth2.json contient une clé privée et doit être traité comme un identifiant capable d'emprunter l'identité des boîtes mail autorisées.

Tester et lancer imapsync

Ce flux nécessite une version d'imapsync compatible avec les comptes de service JSON et leurs dépendances XOAUTH2. Il ne fonctionne pas dans l'interface graphique de migration basée sur l'identifiant et le mot de passe. Lancez d'abord un test d'authentification pour un compte :

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

Retirez --justlogin seulement lorsque les deux authentifications fonctionnent. La délégation évite de créer une clé par utilisateur, mais imapsync effectue toujours une synchronisation par boîte mail. Testez d'abord un compte, vérifiez les libellés et les décomptes, puis traitez les autres de façon contrôlée. Gmail limite les téléchargements IMAP à 2 500 Mo par utilisateur et par jour selon la limite publiée, que Google peut modifier ; lorsque la limite est atteinte, arrêtez ce compte et attendez avant de reprendre. Utilisez dans SERVIDOR_IMAP_DESTINO le nom d'hôte avec un certificat valide indiqué dans Connect Devices de cPanel.

Remise et retrait sécurisé de la clé

• Transmettez le JSON par un échange chiffré à usage unique, avec expiration et accès limité à la personne qui effectuera la migration. Ne le collez pas dans le texte d'un ticket et ne l'envoyez pas par e-mail.
• Sur la machine de migration, conservez-le hors des répertoires publics, avec un propriétaire exclusif et des droits 0600 : chmod 600 secret.xoauth2.json. Ne le copiez pas dans des dépôts, des sauvegardes partagées ni des journaux de commandes.
• Limitez la délégation à la durée de la migration. Une fois les boîtes mail terminées et vérifiées, supprimez l'autorisation de délégation au niveau du domaine, révoquez et supprimez la clé du compte de service dans Google Cloud et effacez toutes les copies locales du JSON.
• Si la clé a été envoyée par un mauvais canal ou a pu être exposée, révoquez-la avant de continuer et générez-en une nouvelle ; supprimer seulement le fichier n'invalide pas une clé déjà copiée.

Définir qui peut lancer la migration

N'autorisez cette procédure que pour les boîtes mail et l'opération convenues. Le champ d'application https://mail.google.com/ n'est pas en lecture seule : lancer imapsync sans option de suppression ne réduit pas les droits dont disposerait quiconque obtiendrait la clé.

La politique IMAP restreinte à des identifiants OAuth n'accepte pas ce flux de délégation, selon Google. N'élargissez pas par commodité la politique de toute l'organisation : l'administrateur doit évaluer l'unité concernée, la durée et le rétablissement des contrôles, ou choisir une autre méthode autorisée.

Avant de traiter l'ensemble, vérifiez un compte et tenez un inventaire de l'origine, de la destination, des dossiers ignorés, des erreurs et de la dernière synchronisation. À la clôture du travail, en plus de retirer la clé et la délégation, vérifiez que les politiques temporaires ont retrouvé leur état prévu.