Migrar correio do Google Workspace com o imapsync (conta de serviço OAuth2)

Quando um cliente quer transferir o correio de um domínio alojado no Google Workspace para os nossos servidores, pode usar o imapsync. A Google já não permite que as aplicações de terceiros se liguem por IMAP com a palavra-passe normal da conta. Deve usar-se OAuth 2.0 ou, para uma migração pontual de poucas contas quando a política o permitir, uma palavra-passe de aplicação.

Neste guia explicamos as duas formas válidas de autenticar a origem Google Workspace e, em concreto, como configurar uma conta de serviço (service account) com delegação ao nível do domínio. A mesma credencial pode autenticar as caixas de correio autorizadas sem mexer em cada utilizador, embora o imapsync tenha de as sincronizar uma a uma.

Porque a palavra-passe normal já não serve

A Google retirou o acesso de "aplicações menos seguras" (basic auth) de forma faseada:

• 15 de junho de 2024: a definição de aplicações menos seguras é eliminada da consola de administração. O administrador já não a pode ativar (as ligações existentes continuaram a funcionar temporariamente).
• 14 de março de 2025: a Google começou a desativar nas contas do Workspace o acesso de aplicações de terceiros através da palavra-passe normal.
• 1 de maio de 2025: terminou a transição anunciada para estas aplicações.

Por isso, não configure o imapsync com a palavra-passe normal. A delegação OAuth2 é a opção adequada para muitas contas; uma palavra-passe de aplicação é uma exceção por utilizador que exige a verificação em dois passos e que o administrador não a tenha restringido.

As duas opções

Se só vai migrar uma ou duas contas, as palavras-passe de aplicação (descritas em Transferir contas Gmail para a Hostsuar) são o mais rápido. Para um domínio inteiro, continue com a conta de serviço.

Configurar a conta de serviço (feito pelo administrador do Workspace)

Estes passos são realizados uma única vez por um superadministrador do domínio Google Workspace. No fim, obtém-se um ficheiro JSON que serve para autenticar todas as contas do domínio. Contém uma chave privada que dá acesso completo a essas caixas de correio: guarde-o como uma palavra-passe.

1. Criar ou selecionar um projeto no Google Cloud

Aceda a console.cloud.google.com com a conta de administrador e crie um projeto novo (por exemplo migracion-correo) ou selecione um existente.

2. Ativar a Gmail API (opcional)

Em APIs e serviços → Biblioteca, procure Gmail API e clique em Ativar. A documentação do imapsync não a exige para este método, porque o acesso é dado pela delegação do passo 4, mas muitos guias da Google incluem-na e não tem qualquer custo.

3. Criar a conta de serviço e a sua chave JSON

Vá a APIs e serviços → Credenciais → Criar credenciais → Conta de serviço e dê-lhe um nome. O assistente vai oferecer-lhe depois dois passos marcados como (opcional): "Autorizações / Conceder acesso ao projeto" (selecionar uma função) e "Principais com acesso". Deixe ambos vazios e continue: esta conta de serviço não precisa de nenhuma função IAM sobre o projeto, porque o acesso às caixas de correio é concedido no passo 4 (delegação ao nível do domínio), não aqui. Clique em Concluído para a criar.

Depois, dentro da conta de serviço, entre no separador Chaves → Adicionar chave → Criar nova chave e escolha o formato JSON (não use P12).

Será descarregado um ficheiro com esta estrutura, que vai mudar de nome para 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": "..."
}

Anote o valor de client_id do JSON (um número longo): vamos precisar dele no passo seguinte. É o identificador OAuth2 da conta de serviço e é exatamente o que se cola no campo ID de cliente da delegação ao nível do domínio (passo 4).

4. Autorizar a delegação ao nível do domínio

Este passo é feito na consola de administração do Google Workspace (admin.google.com), que é um sítio diferente da Google Cloud Console onde criou a conta de serviço.

O mais rápido é ir diretamente ao URL de delegação (com sessão iniciada como superadministrador):

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

Ou então, navegando: Menu (☰) → Segurança → Controlo de acesso e de dados → Controlos de API → "Gerir a delegação ao nível do domínio". Aí, clique em Adicionar nova e:

• Em ID de cliente, cole o client_id do passo anterior.
• Em Âmbitos OAuth, introduza este âmbito:

https://mail.google.com/

Muito importante: https://mail.google.com/ é o âmbito pedido pelo fluxo JSON do imapsync para aceder por IMAP. Autorize apenas esse âmbito. gmail.readonly não permite iniciar sessão por IMAP. A Google documenta gmail.imap_admin como alternativa para clientes que peçam expressamente esse âmbito; adicioná-lo na consola não faz com que o imapsync o peça nem garante que apareçam etiquetas ocultas.

Clique em Autorizar para guardar.

5. Verificar se o IMAP está ativado

Na consola de administração, vá a Apps → Google Workspace → Gmail → Acesso do utilizador final e certifique-se de que o acesso IMAP está ativado. Na política de clientes de correio da unidade organizacional afetada deve estar permitido qualquer cliente de correio; uma restrição a identificadores OAuth concretos pode bloquear a conta de serviço mesmo que a delegação exista.

Com isto, a parte da Google está pronta. O administrador só tem de fazer chegar o ficheiro secret.xoauth2.json a quem executar a migração, por um canal seguro (não no texto de um ticket nem por email).

Testar e executar o imapsync

Este método não funciona na interface web do imapsync, que só admite utilizador e palavra-passe: é preciso executá-lo na linha de comandos. Se usar o imapsync a partir do código-fonte (não o binário), instale antes os módulos Perl de que o XOAUTH2 precisa:

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

Guarde a palavra-passe da caixa de correio de destino num ficheiro privado (chmod 600 ~/.imapsync-destino) e teste primeiro apenas o início de sessão de uma conta:

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

Retire --justlogin só quando ambas as autenticações funcionarem. A delegação evita criar uma chave por utilizador, mas o imapsync continua a executar uma sincronização por caixa de correio. Teste primeiro uma conta, reveja etiquetas e contagens e depois processe as restantes de forma controlada. O Gmail limita as descargas IMAP a 2.500 MB por utilizador por dia segundo o limite publicado, que a Google pode alterar; ao atingir o limite, pare essa conta e aguarde antes de a retomar. Use em SERVIDOR_IMAP_DESTINO o hostname com certificado válido indicado em Connect Devices no cPanel.

Para migrar todas as contas, prepare um ficheiro cuentas.txt com um endereço por linha e uma palavra-passe de destino por conta em ~/.imapsync-destino-USUARIO, e percorra-o:

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 aplica as definições do imapsync para o Gmail como origem: limita a velocidade para não esbarrar nos limites da Google, retira o prefixo [Gmail]/ às pastas especiais, deixa «Todo o correio» para o fim e não volta a copiar uma mensagem que já copiou a partir de outra etiqueta. Se uma conta for interrompida pelo limite diário de descarga, volte a executá-la no dia seguinte: o imapsync só copia o que faltar.

No fim da migração

Quando tiver verificado as caixas de correio no destino:

1. Em admin.google.com/ac/owl/domainwidedelegation, elimine a autorização do client_id.
2. No Google Cloud, entre na conta de serviço, separador Chaves, e elimine a chave (ou a conta de serviço inteira).
3. Apague todas as cópias do ficheiro secret.xoauth2.json.

Se a chave puder ter ficado exposta em algum momento, elimine-a e crie uma nova antes de continuar: apagar o ficheiro não invalida uma chave já copiada.

Depois, quando quiser que o correio novo chegue à Hostsuar, altere os registos MX e repita o imapsync uma última vez para copiar o que tiver entrado na Google entretanto.