Autoriza con la delegación de todo el dominio

La API de Mail Admin Quarantine está diseñada para automatizaciones del servidor, como canalizaciones de seguridad y, también, integraciones de SIEM o SOAR. Estas automatizaciones se autentican con una cuenta de servicio de Google Cloud que usa la delegación de todo el dominio para actuar en nombre de un administrador de Google Workspace que tiene el privilegio de administrador requerido.

En esta página, se explica qué permisos de OAuth 2.0 requiere la API y cómo configurar una cuenta de servicio y obtener un token de acceso.

Alcances de OAuth 2.0

La API de Admin Quarantine usa los siguientes permisos de OAuth 2.0:

Alcance Significado
https://www.googleapis.com/auth/gmail.admin.quarantine Consultar y administrar los mensajes en cuarentena Se requiere para liberar o rechazar mensajes, de forma individual o por lotes.
https://www.googleapis.com/auth/gmail.admin.quarantine.readonly Ver los mensajes en cuarentena Es suficiente para enumerar, buscar y obtener mensajes, enumerar y obtener cuarentenas, y obtener el estado de las operaciones por lotes.

En la siguiente tabla, se muestra qué permiso acepta cada método:

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 ✓

Sigue el principio de privilegio mínimo: solicita el permiso de solo lectura para las integraciones que solo supervisan la cuarentena.

Si una solicitud usa un token que no incluye un permiso aceptado, la API devuelve un error 403 con el motivo ACCESS_TOKEN_SCOPE_INSUFFICIENT.

Crea una cuenta de servicio

  1. En la consola de Google Cloud, ve a IAM y administración > Cuentas de servicio y selecciona el proyecto de Google Cloud en el que habilitaste la API.
  2. Haz clic en Crear cuenta de servicio, ingresa un nombre como quarantine-api-service-account y haz clic en Crear y continuar. No es necesario otorgar roles de IAM a la cuenta de servicio. Haz clic en Listo.
  3. Abre la cuenta de servicio y, en la pestaña Detalles, copia el ID de cliente de OAuth 2. Es un número de 21 dígitos, por ejemplo, 109876543210987654321. Necesitarás este ID en la siguiente sección.
  4. En la pestaña Claves, haz clic en Agregar clave > Crear clave nueva, selecciona JSON y haz clic en Crear. Almacena de forma segura el archivo de claves JSON que descargaste.

Para obtener más información, consulta Crea credenciales para una cuenta de servicio.

Autoriza la delegación de todo el dominio

Autoriza a la cuenta de servicio para que acceda a los permisos de la API de Admin Quarantine en tu cuenta de Google Workspace:

  1. Accede a la Consola del administrador de Google como administrador avanzado.
  2. Ve a Seguridad > Control de acceso y datos > Controles de API.
  3. En Delegación de todo el dominio, haz clic en Administrar la delegación de todo el dominio.
  4. Haz clic en Agregar nueva.
  5. En el campo ID de cliente, ingresa el ID de cliente de OAuth 2.0 de la cuenta de servicio. No ingreses la dirección de correo electrónico de la cuenta de servicio.

  6. En el campo Permisos de OAuth, ingresa uno de los siguientes permisos:

    • Para el acceso de lectura y escritura: https://www.googleapis.com/auth/gmail.admin.quarantine
    • Para obtener acceso de solo lectura, usa https://www.googleapis.com/auth/gmail.admin.quarantine.readonly.

  7. Haz clic en Autorizar.

Para obtener más información, consulta Controla el acceso a la API con la delegación de todo el dominio.

Cómo obtener un token de acceso

Para llamar a la API, la cuenta de servicio actúa en nombre de un administrador configurando la reclamación subject (sub) de la solicitud de token en la dirección de correo electrónico del administrador. El administrador debe tener el privilegio de administrador requerido.

En el siguiente ejemplo de Python, se usa la biblioteca google-auth para obtener un token de acceso:

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

Envía el token en el encabezado Authorization de cada solicitud:

Authorization: Bearer ACCESS_TOKEN

Los tokens de acceso vencen después de una hora. Actualiza las credenciales antes de cada lote de solicitudes en lugar de almacenar en caché los tokens durante períodos prolongados.

Solucionar problemas de autorización

Estado de HTTP Motivo Solución
401 UNAUTHENTICATED Falta el encabezado Authorization, o bien el token tiene un formato incorrecto o venció. Obtén un nuevo token de acceso y, luego, inclúyelo como un token del portador.
403 ACCESS_TOKEN_SCOPE_INSUFFICIENT El token no incluye un permiso que acepte el método. Solicita el permiso https://www.googleapis.com/auth/gmail.admin.quarantine para los métodos de liberación y denegación, y asegúrate de que el permiso esté autorizado en la Consola del administrador.
403 PERMISSION_DENIED El administrador suplantado no tiene un privilegio de cuarentena de administrador o no tiene acceso a la cuarentena que contiene el mensaje. Otorga al administrador el privilegio Acceso a la cuarentena de administrador o Acceso a las cuarentenas restringidas.
403 SERVICE_DISABLED o 404 NOT_FOUND en cada método La API no está habilitada en el proyecto de Cloud o el proyecto no está inscrito en el Programa de Versión preliminar para desarrolladores. Habilita la API y confirma tu inscripción en el Programa de versión preliminar para desarrolladores de Google Workspace.

Próximos pasos