Autorizar com delegação em todo o domínio

A API Mail Admin Quarantine foi projetada para automações do lado do servidor, como pipelines de segurança e integrações de SIEM ou SOAR. Essas automações são autenticadas com uma conta de serviço do Google Cloud que usa a delegação em todo o domínio para agir em nome de um admin do Google Workspace que tenha o privilégio de administrador necessário.

Nesta página, explicamos quais escopos do OAuth 2.0 a API exige e como configurar uma conta de serviço e receber um token de acesso.

Escopos do OAuth 2.0

A API Admin Quarantine usa os seguintes escopos do OAuth 2.0:

Escopo Significado
https://www.googleapis.com/auth/gmail.admin.quarantine Ver e gerenciar mensagens em quarentena. Necessária para liberar ou recusar mensagens, individualmente ou em lotes.
https://www.googleapis.com/auth/gmail.admin.quarantine.readonly Ver mensagens em quarentena. Suficiente para listar, pesquisar e receber mensagens, listar e receber quarentenas e receber o status de operações em lote.

A tabela a seguir mostra qual escopo cada método aceita:

Método gmail.admin.quarantine gmail.admin.quarantine.readonly
customers.quarantinedMessages.list ✓ ✓
customers.quarantinedMessages.search ✓ ✓
customers.quarantinedMessages.get ✓ ✓
customers.quarantines.list ✓ ✓
customers.quarantines.get ✓ ✓
customers.operations.get ✓ ✓
customers.quarantinedMessages.release ✓
customers.quarantinedMessages.deny ✓
customers.quarantinedMessages.batchRelease ✓
customers.quarantinedMessages.batchDeny ✓

Siga o princípio de privilégio mínimo: solicite o escopo somente leitura para integrações que apenas monitoram a quarentena.

Se uma solicitação usar um token que não inclua um escopo aceito, a API vai retornar um erro 403 com o motivo ACCESS_TOKEN_SCOPE_INSUFFICIENT.

Criar uma conta de serviço

  1. No console do Google Cloud, acesse IAM e administrador > Contas de serviço e selecione o projeto na nuvem do Google Cloud em que você ativou a API.
  2. Clique em Criar conta de serviço, insira um nome como quarantine-api-service-account e clique em Criar e continuar. Não é necessário conceder papéis do IAM à conta de serviço. Clique em Concluído.
  3. Abra a conta de serviço e, na guia Detalhes, copie o ID do cliente OAuth 2. É um número de 21 dígitos, por exemplo, 109876543210987654321. Você vai precisar desse ID na próxima seção.
  4. Na guia Chaves, clique em Adicionar chave > Criar nova chave, selecione JSON e clique em Criar. Armazene o arquivo de chave JSON salvo em um local seguro.

Para mais informações, consulte Criar credenciais para uma conta de serviço.

Autorizar a delegação em todo o domínio

Autorize a conta de serviço a acessar os escopos da API Admin Quarantine na sua conta do Google Workspace:

  1. Faça login no Google Admin Console como superadministrador.
  2. Acesse Segurança > Controle de acesso e dados > Controles de API.
  3. Em Delegação em todo o domínio, clique em Gerenciar delegação em todo o domínio.
  4. Clique em Adicionar novo.
  5. No campo ID do cliente, insira o ID do cliente OAuth 2.0 da conta de serviço. Não insira o endereço de e-mail da conta de serviço.

  6. No campo Escopos do OAuth, insira um dos seguintes escopos:

    • Para acesso de leitura e gravação: https://www.googleapis.com/auth/gmail.admin.quarantine
    • Para acesso somente leitura: https://www.googleapis.com/auth/gmail.admin.quarantine.readonly

  7. Clique em Autorizar.

Para mais detalhes, consulte Controlar o acesso às APIs com a delegação em todo o domínio.

Adquirir um token de acesso

Para chamar a API, a identidade temporária de conta de serviço personifica um administrador definindo a declaração subject (sub) da solicitação de token como o endereço de e-mail do administrador. O administrador precisa ter o privilégio de administrador necessário.

O exemplo de Python a seguir usa a biblioteca google-auth para receber um token de acesso:

from google.oauth2 import service_account
import google.auth.transport.requests

SERVICE_ACCOUNT_FILE = 'service_account.json'
# An administrator with the Access Admin Quarantine privilege.
ADMIN_EMAIL = 'admin@example.com'
SCOPES = ['https://www.googleapis.com/auth/gmail.admin.quarantine']

credentials = service_account.Credentials.from_service_account_file(
    SERVICE_ACCOUNT_FILE,
    scopes=SCOPES,
    subject=ADMIN_EMAIL,
)
credentials.refresh(google.auth.transport.requests.Request())
access_token = credentials.token

Envie o token no cabeçalho Authorization de cada solicitação:

Authorization: Bearer ACCESS_TOKEN

Os tokens de acesso expiram após uma hora. Atualize as credenciais antes de cada lote de solicitações em vez de armazenar tokens em cache por longos períodos.

Resolver problemas de autorização

Status HTTP Motivo Resolução
401 UNAUTHENTICATED O cabeçalho Authorization está ausente ou o token está incorreto ou expirou. Consiga um novo token de acesso e inclua-o como um token do portador.
403 ACCESS_TOKEN_SCOPE_INSUFFICIENT O token não inclui um escopo aceito pelo método. Solicite o escopo https://www.googleapis.com/auth/gmail.admin.quarantine para os métodos de liberação e negação e verifique se o escopo está autorizado no Admin Console.
403 PERMISSION_DENIED O administrador personificado não tem um privilégio de quarentena de administrador ou não tem acesso à quarentena que contém a mensagem. Conceda ao administrador o privilégio Acessar a quarentena de administrador ou Acessar quarentenas restritas.
403 SERVICE_DISABLED ou 404 NOT_FOUND em todos os métodos A API não está ativada no projeto na nuvem ou o projeto não está inscrito no Programa de Prévia para Desenvolvedores. Ative a API e confirme sua inscrição no Programa de prévia para desenvolvedores do Google Workspace.

Próximas etapas