LinkedIn
Instagram
WhatsApp
Telegrama
Google Agenda
Participe da comunidade do SlackConta de Serviço da API do Gmail & Delegação em todo o domínio: O Guia 2026 para Desenvolvedores
Configure a conta de serviço da API do Gmail com delegação em toda a organização: etapas completas do Admin Console, escopos necessários, limites rígidos e um framework de decisão honesto para quando a delegação em toda a organização for a escolha errada. Além disso: a alternativa gerenciada de OAuth que ignora totalmente a dança do administrador.
from google.oauth2 import conta de serviço
from googleapiclient.discovery import construir
# Carregar credenciais da conta de serviço
credenciais = service_account.Credenciais
.from_service_account_file(
'service-account-key.json',
escopos=['https://mail.google.com/']
)
# Suplantar a identidade de um usuário do espaço de trabalho (DWD)
delegado = creds.com_assunto(
'user@yourdomain.com'
)
#: Criação do serviço Gmail
serviço = construir('gmail', 'v1', credenciais=delegado)O que é um serviço de conta de serviço do Gmail?
A Conta de serviço da API do Gmail com delegação em todo o domínio é uma identidade do Google Cloud que permite a um aplicativo de backend acessar dados do Gmail de qualquer usuário em uma organização do Google Workspace - sem o consentimento individual do usuário. A conta de serviço recebe confiança em nível de administrador no Google Workspace Admin Console, o que lhe permite personificar qualquer usuário no domínio usando autenticação JWT OAuth 2.0.
Ao contrário do OAuth 2.0 padrão, onde cada usuário autoriza seu aplicativo interativamente, delegação de domínio para conta de serviço da API do Gmail permite que o código do seu servidor chame as APIs do Gmail em nome de centenas ou milhares de usuários do Workspace com uma única credencial de conta de serviço. A troca: funciona apenas em domínios do Google Workspace - não em contas pessoais @gmail.com.
Este padrão é comum em ferramentas corporativas: sistemas de arquivamento de e-mail, plataformas de monitoramento de conformidade, integrações internas de CRM e serviços de sincronização de calendário/e-mail que precisam operar em todo o domínio de uma empresa sem solicitar que cada funcionário autorize individualmente o aplicativo.
No fluxo de consentimento do usuário
Conta de serviço acessa o Gmail em nome de usuários do espaço de trabalho sem acionar prompts do OAuth.
Autenticação servidor a servidor
Usa JWT assinado com uma chave privada - sem redirecionamento para o navegador, sem troca de código de autorização.
Acesso com escopo de domínio
Autorizado uma vez por um Super Administrador do Workspace - aplica-se a todos os usuários da organização.
Conta de Serviço vs. Usuário do OAuth: Qual deles você realmente precisa?
Ambos os padrões usam escopos OAuth 2.0 para acessar o Gmail, mas são fundamentalmente diferentes em arquitetura, custo de configuração e para quem funcionam. Aqui está a comparação honesta - incluindo a opção gerenciada que ignora ambos os caminhos de configuração completamente.
| Critérios | Conta de Serviço + DWD | Usuário do OAuth | Unipile gerenciado |
|---|---|---|---|
| É necessário ter o Google Workspace | Obrigatório | Não precisa | Não precisa |
| suporte@gmail.com | Não - apenas espaço de trabalho | Sim | Sim |
| É necessário o consentimento do usuário | Concessões de admin, sem por usuário | Cada usuário concorda | OAuth por usuário, tratado |
| Configuração do Console do Administrador | Obrigatório - caminho complexo | Não precisa | Não precisa |
| Verificação de escopo pelo Google | Obrigatório para restrito | Obrigatório para restrito | Unipile é CASA Nível 2 |
| Avaliação CASA | Seu fardo | Seu fardo | Já feito |
| Amigabilidade SaaS multi-tenant | Administração por inquilino do disco | Bom | Excelente |
| Tempo para a primeira chamada de API | Dias (aprovação do admin + configuração) | Horas | Minutos |
Use conta de serviço + DWD quando...
Use OAuth do lado do usuário quando...
Limite crítico: DWD não funciona em contas @gmail.com
Este é o erro mais comum que as equipes cometem ao escolher delegação de domínio para conta de serviço da API do Gmail. O DWD só pode se passar por usuários que pertencem a um domínio do Google Workspace que autorizou explicitamente o ID do cliente da sua conta de serviço. Endereços pessoais do @gmail.com não fazem parte de nenhum domínio do Workspace e não pode ser impersonificado - a chamada da API retornará um erro 400 com administrador_política_imposta ou um erro de delegação inválida. Se o seu produto atende tanto usuários do @gmail.com quanto do Workspace, a conta de serviço + DWD não é a escolha certa.
Precisa de acesso ao Gmail sem um administrador do Workspace? O OAuth gerenciado da Unipile funciona para usuários do @gmail.com e do Workspace com uma única API unificada - sem necessidade de configuração DWD.
Use a chave UnipileComo configurar delegação em todo o domínio no Google Workspace (5 passos)
Aqui está o procedimento completo de 2026 para configurar delegação de domínio para conta de serviço da API do Gmail. Você precisa de um projeto do Google Cloud, um Super Admin do Workspace e cerca de 30 minutos para a configuração inicial.
Criar uma conta de serviço no Console do Google Cloud
Ir console.cloud.google.com, selecione seu projeto (ou crie um), em seguida, navegue até IAM & Admin > Contas de serviço > Criar conta de serviço. Dê um nome descritivo como gmail-dwd-service. Não é necessário atribuir nenhuma função do Cloud IAM nesta etapa - as permissões vêm do Google Workspace Admin Console, não do Cloud IAM.
Gerar e baixar a chave JSON
Na página de detalhes da conta de serviço, vá para Chaves > Adicionar Chave > Criar nova chave > JSON. Baixe o arquivo - esta é a credencial que seu aplicativo usará para assinar JWTs. Armazene-o com segurança: trate a chave JSON como um certificado SSL privado. Nunca a inclua em controle de versão.
O arquivo JSON contém os email_do_cliente, chave_privadae id_cliente campos que seu código precisa. Como alternativa a chavesBaseadas em arquivo, você pode usar Federação de Identidade de Carga de Trabalho para autenticação sem chave em ambientes de produção.
Habilitar a API do Gmail e identificar os escopos necessários
No Google Cloud Console, vá para APIs e Serviços > Ativar APIs e Serviços e habilitar o API do Gmail. Em seguida, decida quais escopos OAuth seu aplicativo precisa. Para a maioria das operações do Gmail, você precisa no mínimo https://www.googleapis.com/auth/gmail.readonly (sensível) ou https://mail.google.com/ (restrito).
https://mail.google.com/) exigem uma revisão formal de segurança do Google e uma avaliação CASA Nível 2 antes de poderem ser usados em produção. Veja o escopo completo na próxima seção e em Gmail OAuth scopes mergulho profundo para detalhes sobre o processo de revisão.Autorizar o ID do cliente no Console do Administrador
Este é o passo que requer sua Superadministrador do Google Workspace. Navegue no Console de Administração para:
Na caixa de diálogo "Adicionar novo", insira a conta de serviço ID numérico do cliente (o ID Único que você anotou na Etapa 1) e a lista de escopos OAuth separados por vírgulas. Por exemplo:
Salvar a entrada. As alterações geralmente se propagam em poucos minutos, mas podem levar até 60 minutos em grandes organizações. Referência: Ajuda do Google Workspace Admin - Controle o acesso à API com delegação em todo o domínio.
Finja ser um usuário do seu backend
Com a chave da conta de serviço baixada e o DWD autorizado, você pode agora chamar APIs do Gmail em nome de qualquer usuário do domínio. O passo crucial é chamar com_sujeito() nas credenciais para definir o usuário a ser personificado.
from google.oauth2 import conta de serviço
from googleapiclient.discovery import construir
ESCOPOS = ['https://www.googleapis.com/auth/gmail.readonly']
ARQUIVO_CONTA_DE_SERVICO = 'service-account-key.json'
# Carregar credenciais básicas a partir da chave JSON
credenciais = contas_de_serviço.Credenciais.from_service_account_file(
ARQUIVO_CONTA_SERVICO, escopos=ESCOPOS
)
# Assumir a identidade do usuário do espaço de trabalho de destino (DWD)
creds_delegadas = credenciais.com_assunto('user@yourdomain.com')
#: Implementar o serviço do Gmail com credenciais delegadas
serviço = construir('gmail', 'v1', credenciais=creds_delegados)
# Listar as etiquetas da caixa de entrada do usuário
resultados = service.users().labels().list(idDoUsuario="eu).executar()
print(resultados)const { google } = require('googleapis');
const autenticação = new google.auth.GoogleAuth({
arquivoChave: 'service-account-key.json',
escopos: ['https://www.googleapis.com/auth/gmail.readonly'],
// Define o usuário a ser representado (DWD)
clientOptions: { assunto: 'user@yourdomain.com' }
});
const gmail = google.gmail({ versão: 'v1', auth });
// Lista de rótulos para o usuário impersonado
const res = await gmail.users.labels.list({ userId: "eu });
console.log(res.data.labels);Escopos OAuth exigidos para Gmail DWD
O Google classifica os escopos da API do Gmail em três níveis: básico, sensívele restrito. O nível determina quanto escrutínio o Google aplica antes que você possa usar o escopo em produção. Para delegação em todo o domínio, você deve listar todos os escopos na entrada de autorização do Console do Administrador. Para uma análise completa de cada escopo e como é o processo de verificação do Google, consulte a Gmail OAuth Scopes - Análise profunda.
| Escopo | Nível de acesso | Nível | Avaliação do Google necessária |
|---|---|---|---|
| https://www.googleapis.com/auth/gmail.readonly | Ler todas as mensagens e metadados | Sensível | Sim - Verificação da tela de consentimento do OAuth |
| https://www.googleapis.com/auth/gmail.send | Enviar e-mail em nome do usuário | Sensível | Sim - Verificação da tela de consentimento do OAuth |
| https://www.googleapis.com/auth/gmail.modify | Ler, compor, enviar, excluir (não permanentemente) | Sensível | Sim - Verificação da tela de consentimento do OAuth |
| https://www.googleapis.com/auth/gmail.labels | Criar, ler, atualizar, excluir rótulos | Básico | Não |
| https://www.googleapis.com/auth/gmail.metadata | Ler metadados da mensagem (cabeçalhos, sem corpo) | Básico | Não |
| https://mail.google.com/ | Acesso total - ler, escrever, enviar, excluir tudo | Restrito | Sim - avaliação completa de segurança + CASA Tier 2 |
| https://www.googleapis.com/auth/gmail.settings.basic | Gerenciar configurações básicas de e-mail (filtros, marcadores) | Sensível | Sim - Verificação da tela de consentimento do OAuth |
| https://www.googleapis.com/auth/gmail.settings.sharing | Gerenciar configurações sensíveis (encaminhamento, IMAP/POP) | Restrito | Sim - avaliação completa de segurança + CASA Tier 2 |
Limites e observações específicas do Gmail
Antes de se comprometer com delegação de domínio para conta de serviço da API do Gmail, conheça estas restrições. Algumas são limites técnicos rígidos do Google; outras são requisitos de política que podem impedir que seu aplicativo seja lançado. Para solucionar erros como administrador_política_imposta, veja o Guia de erros da API do Gmail.
125 delegados máx. por usuário
O Gmail impõe um limite rígido de 25 delegados de e-mail por conta de usuário. Esta é uma cota por usuário imposta no nível do Gmail, não no nível da cota da API do Google Cloud. Se você estiver criando uma ferramenta de conformidade ou arquivamento que precise operar em uma organização grande, planeje sua arquitetura em torno desse limite desde o início. Você não pode solicitar um aumento ao Google.
2E-mail principal obrigatório, sem alias
Ao ligar com_sujeito() ou definindo o JWT sub reivindicação, você deve usar o do usuário endereço de e-mail principal, não um alias ou um e-mail de grupo. Por exemplo, se o endereço principal de um usuário for john@company.com mas eles também têm john.smith@company.com Como alias, você deve usar o principal. O uso de um alias resultará em um erro de autenticação da API do Gmail.
Da mesma forma, endereços de e-mail em grupo (como team@company.comnão pode ser falsificado com DWD - grupos não são contas de usuário individuais.
3Avaliação anual CASA Tier 2 para escopos restritos
Se sua aplicação usar qualquer escopos restritos do Gmail como https://mail.google.com/), o Google exige que você passe um CASA (Avaliação de Segurança de Aplicações em Nuvem) Nível 2 uma avaliação antes que seu aplicativo possa acessar dados do Gmail de usuários externos. Este é um requisito anual, não uma certificação única.
O CASA Tier 2 é conduzido por um avaliador de segurança aprovado pelo Google. A avaliação abrange a arquitetura de segurança do seu aplicativo, práticas de manuseio de dados e controles de acesso. Cronograma: estimativa de 4 a 8 semanas e custo real. Esta é uma barreira significativa para equipes em estágio inicial.
4Aprovações multipartidárias (atualização do Google de agosto de 2024)
A partir de agosto de 2024, o Google introduziu aprovação multipartidária para certas ações administrativas de alto privilégio no Google Workspace. Dependendo da sua edição do Workspace (Business Standard, Enterprise, etc.) e das configurações de segurança da sua organização, autorizar um novo ID de cliente para delegação em todo o domínio pode agora exigir que um segundo Super Admin confirme a ação antes que ela entre em vigor.
Isso significa que o caminho de "conseguir que um administrador autorize o DWD" não é mais garantido para funcionar em uma única etapa para todas as organizações. Verifique as políticas de administrador do Workspace da sua organização e a Blog de Atualizações do Google Workspace para os requisitos mais recentes antes de iniciar o processo de configuração com a equipe de TI de um cliente.
Quando NÃO usar conta de serviço + DWD (o problema multi-tenant de SaaS)
Esta seção é a que a maioria dos guias pula. A delegação em nível de domínio da conta de serviço da API do Gmail é uma ferramenta poderosa, mas com um escopo limitado. Se qualquer um desses cenários descrever sua situação, o DWD simplesmente não funcionará, ou criará uma sobrecarga operacional que supera o benefício. Escolher o DWD nesses casos é um erro comum e custoso.
Produto B2C ou PLG atendendo usuários @gmail.com
Se o seu produto possui um fluxo de inscrição self-service e seus usuários incluem pessoas com contas pessoais Contas do @gmail.com, DWD é arquiteturalmente incompatível com o seu caso de uso. O DWD não pode se passar por contas @gmail.com - ponto final. Você precisa de autorização padrão do OAuth pelo lado do usuário para cada usuário que se inscrever, independentemente de ele também ter uma conta Workspace.
SaaS multilocatário com clientes em diferentes domínios do Workspace
Se cada um dos seus clientes for uma empresa diferente com seu próprio domínio do Google Workspace, você precisaria de um separar a autorização DWD de um Super Administrador em todas as organizações de clientes. Isso não é escalável. O administrador de TI de cada cliente deve seguir o processo de configuração de 5 etapas independentemente. A autorização de usuário padrão OAuth – ou uma solução OAuth gerenciada – é muito mais adequada para produtos multilocatários onde seus usuários abrangem muitas organizações diferentes.
Sem acesso a um Superadministrador do Google Workspace
DWD exige um Superadministrador do Google Workspace para autorizar o ID do cliente da sua conta de serviço no Console do Admin. Se seus usuários-alvo ou sua própria organização não tiverem um Super Admin disponível, ou se o processo de aprovação de TI levar semanas a meses, o DWD bloqueará todo o seu lançamento no mercado. Isso é comum em setores regulamentados, grandes empresas e organizações com processos rigorosos de gerenciamento de mudanças.
Tempo de lançamento no mercado curto, sem orçamento CASA ainda
Se você está em pré-product-market fit e precisa de integração com o Gmail correndo em dias em vez de semanas, a linha do tempo combinada de: (1) criação de um projeto do Google Cloud, (2) espera pela propagação do Admin Console, (3) passando pela verificação de aplicativos OAuth do Google para escopos sensíveis e (4) planejamento do CASA Tier 2 para escopos restritos - é proibitiva. A dança administrativa sozinha pode levar mais tempo do que seu sprint. Um provedor OAuth gerenciado que já passou por essas revisões é uma escolha de engenharia legítima, não apenas um atalho.
Pule a burocracia
Unipile fornece OAuth hospedado para Gmail, Outlook e IMAP. Certificado CASA Tier 2. Sem configuração DWD, sem Console de Administração. Funciona tanto para usuários @gmail.com quanto para usuários do Workspace.
A alternativa gerenciada: OAuth hospedado com Unipile
Se a sua situação o fizer delegação de domínio para conta de serviço da API do Gmail a escolha errada - ou se você simplesmente quer evitar a configuração de 5 etapas, a avaliação CASA e a renovação anual - existe uma alternativa de engenharia legítima. Unipile atua como um intermediário técnico independente, gerenciando o fluxo OAuth em nome de cada usuário autenticado. Isso não é uma solução alternativa para a revisão de segurança do Google. A Unipile concluiu a certificação CASA Nível 2 e opera sob a estrutura aprovada pelo Google.
CASA certificada Nível 2
A Unipile passou na Avaliação de Segurança de Aplicativos na Nuvem do Google no Nível 2. Suas contas vinculadas acessam o Gmail através de uma plataforma já verificada - nenhuma avaliação do seu lado.
Em nome de cada usuário
Cada chamada de API que o Unipile faz ao Gmail é em nome de cada usuário autenticado individualmente, usando seu próprio token OAuth. Sem credenciais compartilhadas, sem necessidade de impersonação em todo o domínio.
API unificada e única
Uma única API para o Gmail, o Outlook e o IMAP. Troque de provedor ou adicione novas contas vinculadas sem precisar alterar seu código de integração.
Gmail
Perspectivas
IMAP
import solicitações
O # Unipile gerencia o fluxo OAuth para cada conta vinculada
# Não é necessária nenhuma conta de serviço, nenhum DWD nem configuração do Admin Console
cabeçalhos = {
"X-API-KEY": "SUA_CHAVE_DE_API_UNIPILE",
"aceitar": "application/json"
}
#: Listar e-mails de uma conta vinculada do Gmail ou do Outlook
response = pedidos.obter(
"https://api.unipile.com/api/v1/emails",
cabeçalhos=cabeçalhos,
parâmetros={"id_da_conta": "acc_user_gmail_123"}
)
print(response.json())Conta de Serviço da API do Gmail e FAQ do DWD
Perguntas frequentes sobre a delegação em todo o domínio, escopos e limites da conta de serviço da API do Gmail, e quando optar por uma alternativa gerenciada.
A Conta de serviço do Gmail é uma identidade especial do Google Cloud (não um usuário humano) que se autentica na API do Gmail usando uma chave JSON privada em vez de OAuth interativo. Quando combinado com delegação em nível de domínio, permite que um aplicativo do lado do servidor acesse o Gmail em nome de qualquer usuário de uma organização do Google Workspace, sem que esse usuário precise autorizar o aplicativo manualmente. Ele foi projetado para acesso automatizado de servidor para servidor em ambientes corporativos.
A Conta de serviço da API do Gmail + DWD usa autenticação JWT de servidor para servidor e pode se passar silenciosamente por qualquer usuário do Workspace, sem fluxo de consentimento por usuário. Usuário padrão do OAuth exige que cada usuário passe por uma tela interativa de consentimento, mas funciona para qualquer usuário do Gmail, incluindo contas pessoais @gmail.com. As contas de serviço são adequadas para ferramentas internas de empresas; o OAuth do lado do usuário é adequado para produtos SaaS com bases de usuários diversificadas. Para uma comparação completa, incluindo a opção gerenciada, consulte o Tabela comparativa Acima.
Saiba mais em Página do produto Unipile Gmail API.Não. Este é o limite mais crítico da delegação de domínio do Conta de Serviço da API do Gmail. Endereços @gmail.com pessoais não fazem parte de um domínio gerenciado do Workspace, portanto, não há um administrador para autorizar a delegação DWD. Tentar personificar um usuário @gmail.com retornará um erro de autenticação. Se o seu produto atende usuários com contas @gmail.com, você deve usar a autorização padrão do lado do usuário OAuth, ou um provedor gerenciado como Unipile, que cuida do OAuth para usuários @gmail.com e Workspace.
No Google Workspace Admin Console (requer Super Admin), navegue para: Menu > Segurança > Controle de acesso e dados > Controles de API > Delegação em nível de domínio > Gerenciar delegação em nível de domínio > Adicionar novo. Digite o ID numérico do cliente da sua conta de serviço e a lista de escopos OAuth separados por vírgula. Salve e aguarde até 60 minutos para a propagação. Para o passo a passo completo, consulte guia de configuração neste artigo. Referência: Ajuda do Google Admin - Delegação em todo o domínio.
Delegação em todo o domínio é não obsoleto a partir de 2026, mas com restrições adicionais. O Google introduziu a aprovação por várias partes para determinadas ações administrativas de alto privilégio em agosto de 2024, o que pode exigir que um segundo superadministrador aprove as autorizações do DWD. Além disso, o uso de escopos restritos do Gmail, como https://mail.google.com/ agora requer um CASA Nível 2 avaliação anual de segurança. O DWD continua sendo um modelo válido para casos de uso reais de ferramentas internas nas empresas, mas a carga administrativa relacionada à conformidade aumentou.
Os escopos necessários dependem do que seu aplicativo faz. Somente leitura: https://www.googleapis.com/auth/gmail.readonly (informação confidencial, requer verificação do Google). Enviar e-mail: https://www.googleapis.com/auth/gmail.send (sensível). Acesso total à caixa de correio: https://mail.google.com/ (restrito, requer avaliação CASA Nível 2). Metadados apenas: https://www.googleapis.com/auth/gmail.metadata (básico, sem revisão). Você deve incluir todos os escopos exigidos na entrada do Admin Console DWD. Veja o Tabela de escopo completo neste guia.
Ainda tem dúvidas sobre a delegação em todo o domínio da conta de serviço da API do Gmail? Nossa equipe pode te ajudar a escolher a arquitetura certa para seu caso de uso.
Fale com um especialista
BR 
EN 
FR 
ES 
DE 
IT 
NL 
PL 
TR