E-Mails von Google Workspace mit imapsync migrieren (OAuth2-Dienstkonto)

Wenn ein Kunde die E-Mails einer Domain, die bei Google Workspace liegt, auf unsere Server umziehen möchte, kann er imapsync verwenden. Google erlaubt Drittanwendungen nicht mehr, sich per IMAP mit dem normalen Passwort des Kontos zu verbinden. Es muss OAuth 2.0 verwendet werden oder, für eine einmalige Migration weniger Konten, sofern die Richtlinie es erlaubt, ein App-Passwort.

In dieser Anleitung erklären wir die beiden gültigen Wege, die Quelle Google Workspace zu authentifizieren, und insbesondere, wie Sie ein Dienstkonto (Service Account) mit domainweiter Delegierung einrichten. Dieselben Zugangsdaten können die autorisierten Postfächer authentifizieren, ohne jeden Benutzer anzufassen, auch wenn imapsync sie einzeln synchronisieren muss.

Warum das normale Passwort nicht mehr funktioniert

Google hat den Zugriff für „weniger sichere Apps“ (Basic Auth) schrittweise abgeschafft:

• 15. Juni 2024: Die Einstellung für weniger sichere Apps wird aus der Admin-Konsole entfernt. Der Administrator kann sie nicht mehr aktivieren (bestehende Verbindungen funktionierten vorübergehend weiter).
• 14. März 2025: Google begann, in Workspace-Konten den Zugriff von Drittanwendungen mit dem normalen Passwort zu deaktivieren.
• 1. Mai 2025: Die angekündigte Übergangsphase für diese Anwendungen endete.

Richten Sie imapsync daher nicht mit dem normalen Passwort ein. Die OAuth2-Delegierung ist die passende Option für viele Konten; ein App-Passwort ist eine Ausnahme pro Benutzer, die die Bestätigung in zwei Schritten voraussetzt und die der Administrator nicht eingeschränkt haben darf.

Die beiden Optionen

Wenn Sie nur ein oder zwei Konten migrieren, sind App-Passwörter (beschrieben unter Gmail-Konten zu Hostsuar umziehen) am schnellsten. Für eine ganze Domain fahren Sie mit dem Dienstkonto fort.

Das Dienstkonto einrichten (Aufgabe des Workspace-Administrators)

Diese Schritte führt ein Super-Administrator der Google-Workspace-Domain nur einmal aus. Am Ende erhält er eine JSON-Datei, mit der sich alle Konten der Domain authentifizieren lassen. Sie enthält einen privaten Schlüssel, der vollen Zugriff auf diese Postfächer gibt: Bewahren Sie sie wie ein Passwort auf.

1. Ein Projekt in Google Cloud erstellen oder auswählen

Öffnen Sie console.cloud.google.com mit dem Administratorkonto und erstellen Sie ein neues Projekt (zum Beispiel migracion-correo) oder wählen Sie ein vorhandenes aus.

2. Die Gmail API aktivieren (optional)

Suchen Sie unter APIs & Dienste → Bibliothek nach Gmail API und klicken Sie auf Aktivieren. Die Dokumentation von imapsync verlangt sie für diese Methode nicht, weil der Zugriff durch die Delegierung in Schritt 4 entsteht, aber viele Anleitungen von Google führen sie auf, und sie kostet nichts.

3. Das Dienstkonto und seinen JSON-Schlüssel erstellen

Gehen Sie zu APIs & Dienste → Anmeldedaten → Anmeldedaten erstellen → Dienstkonto und geben Sie ihm einen Namen. Der Assistent bietet danach zwei Schritte an, die als (optional) markiert sind: „Berechtigungen / Diesem Dienstkonto Zugriff auf das Projekt gewähren“ (eine Rolle auswählen) und „Hauptkonten mit Zugriff“. Lassen Sie beide leer und fahren Sie fort: Dieses Dienstkonto braucht keine IAM-Rolle für das Projekt, weil der Zugriff auf die Postfächer in Schritt 4 (domainweite Delegierung) gewährt wird, nicht hier. Klicken Sie auf Fertig, um es zu erstellen.

Öffnen Sie danach im Dienstkonto den Reiter Schlüssel → Schlüssel hinzufügen → Neuen Schlüssel erstellen und wählen Sie das Format JSON (verwenden Sie nicht P12).

Es wird eine Datei mit dieser Struktur heruntergeladen, die Sie in secret.xoauth2.json umbenennen:

{
  "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": "..."
}

Notieren Sie den Wert von client_id aus der JSON-Datei (eine lange Zahl): Wir brauchen ihn im nächsten Schritt. Das ist die OAuth2-Kennung des Dienstkontos, und genau sie wird in das Feld Client-ID der domainweiten Delegierung eingefügt (Schritt 4).

4. Die domainweite Delegierung autorisieren

Dieser Schritt erfolgt in der Admin-Konsole von Google Workspace (admin.google.com), einer anderen Website als der Google Cloud Console, in der Sie das Dienstkonto erstellt haben.

Am schnellsten geht es direkt über die Delegierungs-URL (als Super-Administrator angemeldet):

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

Oder über die Navigation: Menü (☰) → Sicherheit → Zugriffs- und Datenkontrolle → API-Steuerung → „Domainweite Delegierung verwalten“. Klicken Sie dort auf Neu hinzufügen und:

• Fügen Sie unter Client-ID die client_id aus dem vorigen Schritt ein.
• Geben Sie unter OAuth-Bereiche diesen Scope ein:

https://mail.google.com/

Sehr wichtig: https://mail.google.com/ ist der Scope, den der JSON-Ablauf von imapsync für den IMAP-Zugriff anfordert. Autorisieren Sie nur diesen Bereich. gmail.readonly erlaubt keine IMAP-Anmeldung. Google dokumentiert gmail.imap_admin als Alternative für Clients, die ausdrücklich diesen Bereich anfordern; ihn in der Konsole hinzuzufügen, bewirkt nicht, dass imapsync ihn anfordert, und garantiert auch nicht, dass versteckte Labels erscheinen.

Klicken Sie zum Speichern auf Autorisieren.

5. Prüfen, ob IMAP aktiviert ist

Gehen Sie in der Admin-Konsole zu Apps → Google Workspace → Gmail → Endnutzerzugriff und stellen Sie sicher, dass der IMAP-Zugriff aktiviert ist. In der Richtlinie für E-Mail-Clients der betroffenen Organisationseinheit muss jeder E-Mail-Client erlaubt sein; eine Beschränkung auf bestimmte OAuth-Kennungen kann das Dienstkonto blockieren, auch wenn die Delegierung existiert.

Damit ist der Teil bei Google fertig. Der Administrator muss nur noch die Datei secret.xoauth2.json über einen sicheren Kanal an die Person übergeben, die die Migration ausführt (nicht im Text eines Tickets und nicht per E-Mail).

imapsync testen und ausführen

Diese Methode funktioniert nicht in der Weboberfläche von imapsync, die nur Benutzer und Passwort unterstützt: Sie muss auf der Kommandozeile ausgeführt werden. Wenn Sie imapsync aus dem Quellcode verwenden (nicht das Binary), installieren Sie vorher die Perl-Module, die XOAUTH2 benötigt:

sudo cpanm JSON::WebToken JSON Crypt::OpenSSL::RSA LWP HTML::Entities Encode::Byte

Speichern Sie das Passwort des Zielpostfachs in einer privaten Datei (chmod 600 ~/.imapsync-destino) und testen Sie zuerst nur die Anmeldung eines Kontos:

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

Entfernen Sie --justlogin erst, wenn beide Authentifizierungen funktionieren. Die Delegierung erspart einen Schlüssel pro Benutzer, aber imapsync führt weiterhin eine Synchronisierung pro Postfach aus. Testen Sie zuerst ein Konto, prüfen Sie Labels und Anzahl und verarbeiten Sie dann die übrigen kontrolliert. Gmail begrenzt IMAP-Downloads laut veröffentlichtem Limit auf 2.500 MB pro Benutzer und Tag, das Google ändern kann; wenn das Limit erreicht ist, stoppen Sie dieses Konto und warten Sie, bevor Sie es fortsetzen. Verwenden Sie für SERVIDOR_IMAP_DESTINO den Hostnamen mit gültigem Zertifikat, der in cPanel unter Geräte verbinden angegeben ist.

Um alle Konten zu migrieren, legen Sie eine Datei cuentas.txt mit einer Adresse pro Zeile und ein Zielpasswort pro Konto in ~/.imapsync-destino-USUARIO an und arbeiten Sie sie ab:

while read cuenta; do
  imapsync \
    --host1 imap.gmail.com --ssl1 --user1 "$cuenta" \
    --password1 /ruta/privada/secret.xoauth2.json --authmech1 XOAUTH2 \
    --host2 SERVIDOR_IMAP_DESTINO --ssl2 --user2 "$cuenta" \
    --passfile2 "$HOME/.imapsync-destino-${cuenta%@*}" \
    --gmail1 --logfile "migracion-${cuenta}.log"
done < cuentas.txt

--gmail1 wendet die imapsync-Einstellungen für Gmail als Quelle an: Es drosselt die Geschwindigkeit, um nicht an die Limits von Google zu stoßen, entfernt das Präfix [Gmail]/ von den Spezialordnern, verschiebt „Alle Nachrichten“ ans Ende und kopiert eine Nachricht nicht erneut, die bereits über ein anderes Label kopiert wurde. Wenn ein Konto wegen des täglichen Download-Limits abbricht, starten Sie es am nächsten Tag erneut: imapsync kopiert nur, was noch fehlt.

Nach Abschluss der Migration

Wenn Sie die Postfächer am Ziel geprüft haben:

1. Entfernen Sie unter admin.google.com/ac/owl/domainwidedelegation die Autorisierung der client_id.
2. Öffnen Sie in Google Cloud das Dienstkonto, Reiter Schlüssel, und löschen Sie den Schlüssel (oder das gesamte Dienstkonto).
3. Löschen Sie alle Kopien der Datei secret.xoauth2.json.

Wenn der Schlüssel zu irgendeinem Zeitpunkt offengelegt worden sein könnte, löschen Sie ihn und erstellen Sie einen neuen, bevor Sie weitermachen: Das Löschen der Datei macht einen bereits kopierten Schlüssel nicht ungültig.

Wenn danach neue E-Mails bei Hostsuar ankommen sollen, ändern Sie die MX-Einträge und führen Sie imapsync ein letztes Mal aus, um zu kopieren, was in der Zwischenzeit bei Google eingegangen ist.