LinkedIn
Instagram
WhatsApp
Telegrama
Calendario de Google
Únase a la comunidad SlackServicio de cuenta de Google Gmail y Delegación en todo el dominioLa Guía 2026 para Desarrolladores
Configurar una cuenta de servicio de Gmail API con delegación en todo el dominio: pasos completos en la Consola de Administración, ámbitos requeridos, límites estrictos y un marco de decisión honesto para cuando la DWD es la opción incorrecta. Además: la alternativa OAuth gestionada que omite por completo el proceso de administración.
from google.oauth2 import cuenta de servicio
from googleapiclient.discovery import construir
#: Cargar las credenciales de la cuenta de servicio
acreditaciones = service_account.Credentials
.desde_archivo_de_cuenta_de_servicio(
'clave-de-cuenta-de-servicio.json',
ámbitos=['https://mail.google.com/']
)
# Suplantar la identidad de un usuario del espacio de trabajo (DWD)
delegado = créditos.con_asunto(
'user@yourdomain.com'
)
#: Creación del servicio de Gmail
servicio = construir('Gmail', 'v1', credenciales=delegado)¿Qué es una cuenta de servicio de la API de Gmail?
A Cuenta de servicio de la API de Gmail con delegación de autoridad en todo el dominio es una identidad de Google Cloud que permite a una aplicación backend acceder a datos de Gmail para cualquier usuario en una organización de Google Workspace, sin el consentimiento individual del usuario. A la cuenta de servicio se le otorga confianza a nivel de administrador en la Consola de administración de Google Workspace, lo que le permite suplantar a cualquier usuario en el dominio utilizando la autenticación JWT de OAuth 2.0.
A diferencia del OAuth 2.0 estándar donde cada usuario autoriza su aplicación de forma interactiva, delegación a nivel de dominio de cuenta de servicio de la API de Gmail Permite que el código de tu servidor llame a las API de Gmail en nombre de cientos o miles de usuarios de Workspace con una única credencial de cuenta de servicio. La contrapartida: solo funciona en dominios de Google Workspace, no en cuentas personales @gmail.com.
Este patrón es común en herramientas empresariales: sistemas de archivo de correo electrónico, plataformas de monitoreo de cumplimiento, integraciones de CRM internas y servicios de sincronización de calendario/correo electrónico que necesitan operar en todo el dominio de una empresa sin pedir a cada empleado que autorice individualmente la aplicación.
No hay flujo de consentimiento del usuario
La cuenta de servicio accede a Gmail en nombre de los usuarios del espacio de trabajo sin activar las indicaciones de OAuth.
Autenticación de servidor a servidor
Utiliza JWT firmado con una clave privada; sin redireccionamiento del navegador, sin intercambio de código de autorización.
Acceso con ámbito de dominio
Autorizado una vez por un Superadministrador de Workspace: se aplica a todos los usuarios de la organización.
Cuenta de servicio vs. usuario OAuth: ¿cuál necesitas realmente?
Ambos patrones utilizan alcances de OAuth 2.0 para acceder a Gmail, pero son fundamentalmente diferentes en arquitectura, costo de configuración y para quién funcionan. Aquí está la comparación honesta, incluida la opción administrada que omite completamente ambas rutas de configuración.
| Criterios | Cuenta de Servicio + DWD | OAuth del lado del usuario | Unipile administrado |
|---|---|---|---|
| Se requiere Google Workspace | Requerido | No necesario | No necesario |
| soporte@gmail.com | No, solo espacio de trabajo | Sí | Sí |
| Se necesita el consentimiento del usuario | Concesiones de administrador, no por usuario | Cada usuario consiente | OAuth por usuario, manejado |
| Configuración de la Consola de Administración | Requerido - ruta compleja | No necesario | No necesario |
| Verificación del alcance por Google | Requerido para restringido | Requerido para restringido | Unipile es CASA Nivel 2 |
| evaluación CASA | Tu carga | Tu carga | Ya está hecho |
| Aptitud para software como servicio (SaaS) multi-inquilino | Administrador de inquilino por cada inquilino | Bien | Excelente |
| Tiempo hasta la primera llamada a la API | Días (aprobación administrativa + configuración) | Horas | Actas |
Utilice cuenta de servicio + DWD cuando...
Usa OAuth del lado del usuario cuando...
Límite crítico: DWD no funciona con cuentas @gmail.com
Este es el error más común que cometen los equipos al elegir delegación a nivel de dominio de cuenta de servicio de la API de Gmail. DWD solo puede hacerse pasar por usuarios que pertenezcan a un dominio de Google Workspace que haya autorizado explícitamente el ID de cliente de tu cuenta de servicio. Las direcciones personales de @gmail.com no forman parte de ningún dominio de Workspace y no puede ser suplantado; la llamada a la API devolverá un error 400 con política_de_administración_impuesta o un error de delegación inválida. Si tu producto sirve tanto a usuarios de @gmail.com como a usuarios de Workspace, la cuenta de servicio + DWD no es la opción correcta.
¿Necesitas acceder a Gmail sin ser administrador de Workspace? El OAuth gestionado de Unipile funciona para usuarios de @gmail.com y Workspace con una API unificada y única, sin necesidad de configuración DWD.
Usa la clave de UnipileCómo configurar la delegación para todo el dominio en Google Workspace (5 pasos)
A continuación se detalla el procedimiento completo de 2026 para configurar delegación a nivel de dominio de cuenta de servicio de la API de Gmail. Necesitas un proyecto de Google Cloud, un Super Administrador de Workspace y aproximadamente 30 minutos para la configuración inicial.
Crear una cuenta de servicio en Google Cloud Console
Ir a console.cloud.google.com, selecciona tu proyecto (o crea uno), luego navega a IAM y administración > Cuentas de servicio > Crear cuenta de servicio. Ponle un nombre descriptivo como gmail-dwd-servicio. En esta fase no es necesario asignar ningún rol de Cloud IAM: los permisos provienen de la Consola de administración de Google Workspace, no de Cloud IAM.
Generar y descargar la clave JSON
En la página de detalles de la cuenta de servicio, ve a Claves > Agregar clave > Crear nueva clave > JSON. Descarga el archivo: estas son las credenciales que utilizará tu aplicación para firmar los JWT. Guárdalas de forma segura: trata la clave JSON como si fuera un certificado SSL privado. Nunca la incluyas en el control de versiones.
El archivo JSON contiene el correo_cliente, clave_privaday client_id campos que tu código necesita. Como alternativa a las claves basadas en archivos, puedes usar Federación de identidades de cargas de trabajo para la autenticación sin llave en entornos de producción.
Habilita la API de Gmail e identifica los alcances necesarios
En la Consola de Google Cloud, ve a APIs y servicios > Habilitar APIs y servicios y habilita el API de Gmail. Luego decide qué ámbitos de OAuth necesita tu aplicación. Para la mayoría de las operaciones de Gmail, necesitas como mínimo https://www.googleapis.com/auth/gmail.readonly (información confidencial) o https://mail.google.com/ (restringido).
https://mail.google.com/) requieren una revisión formal de seguridad de Google y una evaluación de Nivel 2 de CASA antes de que puedas usarlos en producción. Consulta la referencia completa del alcance en la siguiente sección y en el Gmail OAuth scopes análisis a fondo para detalles sobre el proceso de revisión.Autorizar el ID de cliente en la Consola de administración
Este es el paso que requiere tu Superadministrador de Google Workspace. Navega en la Consola de Administración a:
En el cuadro de diálogo "Agregar nuevo", ingrese el de la cuenta de servicio ID de cliente numérico (el ID único que anotó en el Paso 1) y la lista de ámbitos OAuth separados por comas. Por ejemplo:
Guarda la entrada. Los cambios suelen propagarse en pocos minutos, pero pueden tardar hasta 60 minutos en organizaciones grandes. Referencia: Ayuda de Google Workspace Admin - Controlar el acceso a la API con delegación para todo el dominio.
Soy un modelo de lenguaje grande, entrenado por Google.
Con la clave de cuenta de servicio descargada y la DWD autorizada, ahora puedes llamar a las APIs de Gmail en nombre de cualquier usuario del dominio. El paso clave es llamar con_sujeto() en las credenciales para configurar el usuario del que se va a suplantar la identidad.
from google.oauth2 import cuenta de servicio
from googleapiclient.discovery import construir
ÁMBITOS = ['https://www.googleapis.com/auth/gmail.readonly']
ARCHIVO_CUENTA_DE_SERVICIO = 'clave-de-cuenta-de-servicio.json'
#: Cargar credenciales básicas desde una clave JSON
credenciales = service_account.Credentials.desde_archivo_de_cuenta_de_servicio(
SERVICE_ACCOUNT_FILE, ámbitos=ÁMBITOS
)
# Suplantar al usuario del espacio de trabajo de destino (DWD)
créditos delegados = credenciales.con_asunto('user@yourdomain.com')
#: Implementación del servicio de Gmail con credenciales delegadas
servicio = construir('Gmail', 'v1', credenciales=credenciales_delegadas)
# Mostrar las etiquetas de la bandeja de entrada del usuario
resultados = servicio.usuarios().etiquetas().list(userId=yo).ejecutar()
print(resultados)const { google } = require('googleapis');
const autenticación = new google.auth.GoogleAuth({
archivo Clave: 'clave-de-cuenta-de-servicio.json',
ámbitos: ['https://www.googleapis.com/auth/gmail.readonly'],
// Establecer el usuario a impersonar (DWD)
clientOptions: { asunto: 'user@yourdomain.com' }
});
const gmail = google.gmail({ version: 'v1'auth });
// Listar etiquetas para el usuario suplantado
const res = await gmail.usuarios.etiquetas.list({ userId: yo });
consola.log(res.data.etiquetas);Ámbitos de OAuth requeridos para Gmail DWD
Google clasifica los ámbitos de la API de Gmail en tres niveles: básico, sensibley restringido. El nivel determina cuánta escrutinio aplica Google antes de que puedas usar el ámbito en producción. Para la delegación a nivel de dominio, debes enumerar todos los ámbitos en la entrada de autorización de la Consola del Administrador. Para un desglose completo de cada ámbito y cómo se ve el proceso de verificación de Google, consulta Gmail OAuth Scopes: un análisis detallado.
| Alcance | Nivel de acceso | Nivel | Reseña de Google requerida |
|---|---|---|---|
| https://www.googleapis.com/auth/gmail.readonly | Leer todos los mensajes y metadatos | Sensible | Sí - Verificación de la pantalla de consentimiento de OAuth |
| https://www.googleapis.com/auth/gmail.send | Enviar correo electrónico en nombre del usuario | Sensible | Sí - Verificación de la pantalla de consentimiento de OAuth |
| https://www.googleapis.com/auth/gmail.modify | Leer, componer, enviar, eliminar (no permanentemente) | Sensible | Sí - Verificación de la pantalla de consentimiento de OAuth |
| https://www.googleapis.com/auth/gmail.labels | Crear, leer, actualizar, eliminar etiquetas | Básico | No |
| https://www.googleapis.com/auth/gmail.metadata | Leer metadatos del mensaje (encabezados, sin cuerpo) | Básico | No |
| https://mail.google.com/ | Acceso total: leer, escribir, enviar y eliminar todo | Restringido | Sí: evaluación de seguridad completa + CASA Nivel 2 |
| https://www.googleapis.com/auth/gmail.settings.basic | Administrar configuraciones básicas de correo (filtros, etiquetas) | Sensible | Sí - Verificación de la pantalla de consentimiento de OAuth |
| https://www.googleapis.com/auth/gmail.settings.sharing | Gestionar configuraciones sensibles (reenvío, IMAP/POP) | Restringido | Sí: evaluación de seguridad completa + CASA Nivel 2 |
Límites y problemas específicos de Gmail
Antes de comprometerse a delegación a nivel de dominio de cuenta de servicio de la API de Gmail, ten en cuenta estas restricciones. Algunas son límites técnicos estrictos impuestos por Google; otras son requisitos normativos que pueden impedir que tu aplicación se publique. Para solucionar errores como política_de_administración_impuesta, vea el Guía de errores de la API de Gmail.
1Máximo 25 delegados por usuario
Gmail impone un límite estricto de 25 delegados de correo por cuenta de usuario. Esta es una cuota por usuario que se aplica a nivel de Gmail, no a nivel de cuota de la API de Google Cloud. Si está creando una herramienta de cumplimiento o archivo que necesita operar en una gran organización, planifique su arquitectura en torno a este límite desde el principio. No puede solicitar un aumento a Google.
2Correo electrónico principal requerido, sin alias
Al llamar con_sujeto() o configurando el JWT sub reclamación, debes usar el/la de usuario correo electrónico principal, no una dirección de alias o grupal. Por ejemplo, si la dirección principal de un usuario es john@company.com pero ellos también tienen john.smith@company.com Como alias, debes usar el primario. El uso de un alias resultará en un error de autenticación de la API de Gmail.
Igualmente, las direcciones de correo electrónico de grupo (como team@company.com) no se puede suplantar con DWD; los grupos no son cuentas de usuario individuales.
3Evaluación anual CASA Nivel 2 para alcances restringidos
Si su aplicación utiliza alguna ámbitos restringidos de Gmail como https://mail.google.com/), Google te exige que pases un CASA (Evaluación de Seguridad de Aplicaciones en la Nube) Nivel 2 evaluación antes de que su aplicación pueda acceder a los datos de Gmail de usuarios externos. Este es un requisito anual, no una certificación única.
CASA Tier 2 es realizado por un evaluador de seguridad aprobado por Google. La evaluación cubre la arquitectura de seguridad de su aplicación, las prácticas de manejo de datos y los controles de acceso. Cronograma: presupuesto de 4 a 8 semanas y costo real. Esta es una barrera importante para los equipos en etapa inicial.
4Aprobaciones multipartidistas (actualización de Google agosto de 2024)
A partir de agosto de 2024, Google introdujo aprobación multipartidaria para ciertas acciones administrativas de alto privilegio en Google Workspace. Dependiendo de tu edición de Workspace (Business Standard, Enterprise, etc.) y de la configuración de seguridad de tu organización, autorizar un nuevo ID de cliente para la delegación en todo el dominio puede requerir ahora que un segundo Super Admin confirme la acción antes de que surta efecto.
Esto significa que la ruta de "conseguir que un administrador autorice DWD" ya no garantiza el éxito en un solo paso para todas las organizaciones. Revisa las políticas de administrador de Workspace de tu organización y la Blog de novedades de Google Workspace para los requisitos más recientes antes de iniciar el proceso de configuración con el equipo de TI de un cliente.
Cuándo NO usar una cuenta de servicio + DWD (el problema de los multi-inquilinos de SaaS)
Esta es la sección que más guías se saltan. La delegación de autoridad a nivel de dominio de la cuenta de servicio de la API de Gmail es una herramienta potente pero limitada. Si alguno de estos escenarios describe su situación, DWD no funcionará en absoluto o creará una sobrecarga operativa que superará el beneficio. Elegir DWD en estos casos es un error común y costoso.
Producto B2C o PLG que sirve a usuarios de @gmail.com
Si tu producto tiene un flujo de registro de autoservicio y tus usuarios incluyen personas con cuentas personales cuentas de @gmail.com, DWD es arquitectónicamente incompatible con su caso de uso. DWD no puede hacerse pasar por cuentas de @gmail.com, punto final. Necesita autorización estándar del lado del usuario OAuth para cada usuario que se registre, independientemente de si también tiene una cuenta de Workspace.
SaaS multitenant con clientes en diferentes dominios de Workspace
Si cada uno de sus clientes es una empresa diferente con su propio dominio de Google Workspace, necesitaría un separar la autorización de DWD de un Super Administrador en cada organización de cliente. Esto no es escalable. El administrador de TI de cada cliente debe seguir el proceso de configuración de 5 pasos de forma independiente. La autorización estándar del usuario en el lado de OAuth, o una solución de OAuth administrada, es mucho más adecuada para productos de múltiples inquilinos donde sus usuarios abarcan muchas organizaciones diferentes.
No acceso a un Superadministrador de Google Workspace
DWD requiere un Superadministrador de Google Workspace para autorizar el ID de cliente de su cuenta de servicio en la Consola de Administración. Si sus usuarios objetivo o su propia organización no tienen un Superadministrador disponible, o si el proceso de aprobación de TI lleva semanas o meses, DWD bloqueará todo su lanzamiento al mercado. Esto es común en industrias reguladas, grandes empresas y organizaciones con procesos estrictos de gestión de cambios.
Corto tiempo de comercialización, sin presupuesto CASA aún
Si estás en la fase pre-product-market fit y necesitas integración con Gmail corriendo en días en lugar de semanas, la línea de tiempo combinada de: (1) crear un proyecto de Google Cloud, (2) esperar la propagación de la Consola de Administración, (3) pasar por la verificación de la aplicación OAuth de Google para alcances confidenciales y (4) planificar CASA Nivel 2 para alcances restringidos, es prohibitiva. El baile administrativo por sí solo puede llevar más tiempo que tu sprint. Un proveedor de OAuth administrado que ya ha pasado estas revisiones es una elección de ingeniería legítima, no solo un atajo.
Evita el papeleo administrativo
Unipile ofrece OAuth alojado para Gmail, Outlook e IMAP. Certificado CASA Nivel 2. Sin configuración de DWD, sin Consola de Administración. Funciona tanto para usuarios de @gmail.com como de Workspace.
La alternativa gestionada: OAuth alojado con Unipile
Si tu situación te hace delegación a nivel de dominio de cuenta de servicio de la API de Gmail la elección equivocada, o si simplemente desea evitar la configuración de 5 pasos, la evaluación de CASA y la renovación anual, existe una alternativa de ingeniería legítima. Unipile actúa como intermediario técnico independiente, gestionando el flujo de OAuth en nombre de cada usuario autenticado. Esto no es una solución alternativa para la revisión de seguridad de Google. Unipile ha completado la certificación CASA Nivel 2 y opera bajo el marco aprobado por Google.
CASA certificado Nivel 2
Unipile ha superado la Evaluación de Seguridad de Aplicaciones en la Nube de Google en el Nivel 2. Tus cuentas vinculadas acceden a Gmail a través de una plataforma ya verificada, sin necesidad de evaluación de tu parte.
En nombre de cada usuario
Cada llamada a la API que Unipile realiza a Gmail se hace en nombre de cada usuario autenticado individualmente, utilizando su propio token de OAuth. No se requieren credenciales compartidas ni suplantación de identidad a nivel de dominio.
API unificada única
Una API para Gmail, Outlook e IMAP. Cambia de proveedor o añade nuevas cuentas vinculadas sin modificar tu código de integración.
Gmail
Outlook
IMAP
import solicita
# Unipile gestiona el flujo OAuth para cada cuenta vinculada
#: No se necesita una cuenta de servicio, ni DWD, ni configurar la consola de administración
cabeceras = {
"Clave API X": "TU_CLAVE_API_DE_UNIPILE",
"aceptar": "application/json"
}
#: Mostrar los correos electrónicos de una cuenta de Gmail o Outlook vinculada
response = solicitudes.consiga(
"https://api.unipile.com/api/v1/emails",
cabeceras=encabezados,
parámetros={"account_id": "acc_user_gmail_123"}
)
print(respuesta.json())Cuenta de servicio de la API de Gmail y preguntas frecuentes de DWD
Preguntas comunes sobre la delegación en todo el dominio de la cuenta de servicio de la API de Gmail, ámbitos, límites y cuándo elegir una alternativa administrada.
A Cuenta de servicio de Gmail es una identidad especial de Google Cloud (no un usuario humano) que se autentica en la API de Gmail utilizando una clave JSON privada en lugar de OAuth interactivo. Cuando se combina con delegación en todo el dominio, permite que una aplicación del lado del servidor acceda a Gmail en nombre de cualquier usuario de una organización de Google Workspace, sin necesidad de que ese usuario autorice la aplicación manualmente. Está diseñada para el acceso automatizado de servidor a servidor en entornos empresariales.
A Cuenta de servicio de la API de Gmail + DWD utiliza autenticación JWT de servidor a servidor y puede suplantar silenciosamente a cualquier usuario de Workspace, sin flujo de consentimiento por usuario. Usuario estándar del lado del cliente OAuth requiere que cada usuario pase por una pantalla de consentimiento interactiva, pero funciona para cualquier usuario de Gmail, incluidas las cuentas personales de @gmail.com. Las cuentas de servicio son adecuadas para herramientas internas empresariales; OAuth del lado del usuario es adecuado para productos SaaS con bases de usuarios diversas. Para una comparación completa, incluida la opción administrada, consulte la tabla comparativa arriba.
Aprende más sobre Página de producto de la API de Gmail de Unipile.No. Este es el límite más crítico de la delegación de dominio completo de cuentas de servicio de la API de Gmail. Las direcciones personales de @gmail.com no forman parte de un dominio de Workspace administrado, por lo que no hay un administrador para autorizar la delegación de DWD. Intentar suplantar a un usuario de @gmail.com devolverá un error de autenticación. Si su producto atiende a usuarios con cuentas de @gmail.com, debe usar la autorización estándar del lado del usuario OAuth, o un proveedor administrado como Unipile que maneja OAuth tanto para usuarios de @gmail.com como de Workspace.
En la consola de administración de Google Workspace (requiere Superadministrador), ve a: Menú > Seguridad > Control de acceso y datos > Controles de la API > Delegación en todo el dominio > Administrar delegación en todo el dominio > Agregar nuevo. Ingrese el ID numérico de cliente de su cuenta de servicio y la lista de ámbitos OAuth separada por comas. Guarde y espere hasta 60 minutos para la propagación. Para obtener los pasos completos, consulte Guía de instalación en este artículo. Referencia: Ayuda de Google Admin: Delegación en todo el dominio.
La delegación en todo el dominio es no obsoleto a partir de 2026, pero está más restringido. Google introdujo la aprobación multipartidaria para ciertas acciones administrativas de alto privilegio en agosto de 2024, las cuales pueden requerir que un segundo Superadministrador apruebe autorizaciones de DWD. Además, el uso de ámbitos restringidos de Gmail como https://mail.google.com/ ahora requiere un CASA Nivel 2 evaluación de seguridad anual. DWD sigue siendo un patrón válido para casos de uso genuinos de herramientas internas de empresa, pero la sobrecarga de cumplimiento ha aumentado.
Los ámbitos requeridos dependen de lo que haga tu aplicación. Solo lectura https://www.googleapis.com/auth/gmail.readonly (sensible, necesita verificación de Google). Enviar correo electrónico: https://www.googleapis.com/auth/gmail.send (sensible). Acceso completo al buzón: https://mail.google.com/ (restringido, requiere evaluación CASA Nivel 2). Solo metadatos: https://www.googleapis.com/auth/gmail.metadata (básico, sin revisión). Debe incluir todos los ámbitos requeridos en la entrada DWD de la Consola de administración. Ver la tabla de alcance completo en esta guía.
¿Sigues teniendo preguntas sobre la delegación de dominio para la cuenta de servicio de la API de Gmail? Nuestro equipo puede ayudarte a elegir la arquitectura adecuada para tu caso de uso.
Habla con un experto
ES 
EN 
FR 
DE 
IT 
BR 
NL 
PL 
TR