LinkedIn
Instagram
WhatsApp
Telegram
Google Agenda
Rejoindre la communauté SlackCompte de service de l'API Gmail et Délégation à l'échelle du domaine: Le Guide 2026 pour les développeurs
Configurez le compte de service de l'API Gmail avec délégation à l'échelle du domaine : étapes complètes de la console d'administration, portées requises, limites strictes et cadre de décision honnête pour savoir quand la délégation à l'échelle du domaine est le mauvais choix. De plus : l'alternative OAuth gérée qui évite complètement la danse administrative.
from google.oauth2 import compte de service
from googleapiclient.discovery import construire
# Charger les identifiants du compte de service
identifiants = service_account.Credentials
.depuis_fichier_compte_service(
'clé-de-compte-de-service.json',
lunettes de visée=['https://mail.google.com/']
)
# Se faire passer pour un utilisateur de l'espace de travail (DWD)
délégué = identifiants.avec_sujet(
'user@yourdomain.com'
)
# : mise en place du service Gmail
service = construire('Gmail', 'v1', identifiants=délégué)Qu'est-ce qu'un compte de service de l'API Gmail ?
Une Compte de service API Gmail avec délégation à l'échelle du domaine Il s'agit d'une identité Google Cloud qui permet à une application backend d'accéder aux données Gmail de n'importe quel utilisateur d'une organisation Google Workspace, sans le consentement individuel de l'utilisateur. Le compte de service bénéficie d'un niveau de confiance d'administrateur dans la console d'administration Google Workspace, ce qui lui permet de se faire passer pour n'importe quel utilisateur du domaine à l'aide de l'authentification JWT OAuth 2.0.
Contrairement à OAuth 2.0 standard où chaque utilisateur autorise votre application interactivement, Délégation à l'échelle du domaine pour un compte de service de l'API Gmail laissez le code de votre serveur appeler les API Gmail au nom de centaines ou de milliers d'utilisateurs Workspace avec une seule autorisation de compte de service. Le compromis : cela ne fonctionne que sur les domaines Google Workspace – pas sur les comptes personnels @gmail.com.
Ce modèle est courant dans les outils d'entreprise : systèmes d'archivage des e-mails, plateformes de contrôle de la conformité, intégrations CRM internes et services de synchronisation des calendriers et des e-mails qui doivent fonctionner à l'échelle de l'ensemble du domaine de l'entreprise sans que chaque employé ait à autoriser l'application individuellement.
Pas de procédure de consentement de l'utilisateur
Le compte de service accède à Gmail au nom des utilisateurs de l'espace de travail sans déclencher d'invites OAuth.
Authentification de serveur à serveur
Utilise des JWT signés avec une clé privée : pas de redirection par le navigateur, pas d'échange de code d'autorisation.
Accès au niveau du domaine
Autorisé une fois par un Super Administrateur Workspace - s'applique à tous les utilisateurs de l'organisation.
Compte de service vs utilisateur OAuth : lequel vous faut-il réellement ?
Les deux méthodes utilisent des étendues OAuth 2.0 pour accéder à Gmail, mais elles sont fondamentalement différentes en termes d'architecture, de coût de mise en place et de public visé. Voici une comparaison honnête, y compris l'option gérée qui évite complètement les deux parcours de configuration.
| Critères | Compte de service + DWD | Côté utilisateur OAuth | Unipile géré |
|---|---|---|---|
| Google Workspace requis | Requis | Pas nécessaire | Pas nécessaire |
| assistance@gmail.com | Non - espace de travail uniquement | Oui, | Oui, |
| Le consentement de l'utilisateur est requis | Missions d'administration, pas par utilisateur | Chaque utilisateur donne son consentement | OAuth par utilisateur, géré |
| Configuration de la console d'administration | Obligatoire - chemin d'accès complexe | Pas nécessaire | Pas nécessaire |
| Vérification de la portée par Google | Requis pour restricted | Requis pour restricted | Unipile est CASA de niveau 2 |
| Évaluation CASA | Ton fardeau | Ton fardeau | C'est déjà fait |
| Compatibilité avec les applications SaaS multi-locataires | Difficile – actuellement admin | Bien | Excellent |
| Temps du premier appel API | Jours (approbation admin + configuration) | Heures | rapidement |
Utiliser le compte de service + DWD quand...
Utilisez OAuth côté utilisateur lorsque...
Limite critique : DWD ne fonctionne pas sur les comptes @gmail.com
C'est l'erreur la plus courante que les équipes commettent lors du choix Délégation à l'échelle du domaine pour un compte de service de l'API Gmail. DWD ne peut usurper l'identité que des utilisateurs appartenant à un domaine Google Workspace qui a explicitement autorisé l'ID client de votre compte de service. Les adresses @gmail.com personnelles ne font partie d'aucun domaine Workspace et ne peut pas être usurpé - l'appel API renverra une erreur 400 avec politique_admin_appliquée ou une erreur de délégation invalide. Si votre produit sert à la fois les utilisateurs @gmail.com et Workspace, le compte de service + DWD n'est pas le bon choix.
Accès à Gmail sans administrateur Workspace ? L'OAuth géré par Unipile fonctionne pour les utilisateurs @gmail.com et Workspace avec une seule API unifiée, aucune configuration DWD n'est requise.
Utilisez la clé d'UnipileComment configurer la délégation à l'échelle du domaine dans Google Workspace (5 étapes)
Voici la procédure complète de 2026 pour la configuration Délégation à l'échelle du domaine pour un compte de service de l'API Gmail. Vous avez besoin d'un projet Google Cloud, d'un Super Administrateur Workspace et d'environ 30 minutes pour la première configuration.
Créer un compte de service dans la Google Cloud Console
Aller à console.cloud.google.com, sélectionnez votre projet (ou créez-en un), puis accédez à IAM & Admin > Comptes de service > Créer un compte de service. Donnez-lui un nom descriptif comme service-gmail-dwd. Vous n'avez pas besoin d'attribuer de rôles Cloud IAM à ce stade - les autorisations proviennent de la Google Workspace Admin Console, pas de Cloud IAM.
Générer et télécharger la clé JSON
Dans la page de détail du compte de service, allez à Clés > Ajouter une clé > Créer une nouvelle clé > JSON. Téléchargez le fichier - c'est l'identifiant que votre application utilisera pour signer les JWT. Stockez-le en toute sécurité : traitez la clé JSON comme un certificat SSL privé. Ne le commettez jamais dans le contrôle de version.
Le fichier JSON contient le email_client, clé_privée, ou encore client_id champs dont votre code a besoin. Alternativement aux clés basées sur des fichiers, vous pouvez utiliser Fédération d'identité de charge de travail pour l'authentification sans clé dans les environnements de production.
Activer l'API Gmail et identifier les champs d'application requis
Dans la console Google Cloud, accédez à API et services > Activer les API et services et activer le API Gmail. Ensuite, décidez des champs d’application OAuth dont votre application a besoin. Pour la plupart des opérations Gmail, vous avez besoin au minimum https://www.googleapis.com/auth/gmail.readonly (sensible) ou https://mail.google.com/ (restreint).
https://mail.google.com/) nécessitent un examen de sécurité Google formel et une évaluation CASA de niveau 2 avant de pouvoir être utilisés en production. Voir la portée complète de référence dans la section suivante et dans le Plongée en profondeur dans les scopes OAuth de Gmail pour plus de détails sur le processus d'examen.Autoriser l'ID client dans la console d'administration
C'est l'étape qui nécessite votre Super administrateur Google Workspace. Naviguez dans la console d'administration jusqu'à :
Dans la boîte de dialogue " Ajouter ", saisissez le compte de service identifiant client numérique (l'ID unique que vous avez noté à l'étape 1) et la liste des étendues OAuth séparées par des virgules. Par exemple :
Enregistrer l'entrée. Les modifications sont généralement répercutées en quelques minutes, mais peuvent prendre jusqu'à 60 minutes dans les grandes organisations. Référence : Google Workspace Admin Aide - Contrôler l'accès aux API avec la délégation à l'échelle du domaine.
Faites semblant d'être un utilisateur de votre backend
Avec la clé de compte de service téléchargée et DWD autorisé, vous pouvez désormais appeler les API Gmail au nom de n'importe quel utilisateur du domaine. L'étape clé consiste à appeler avec_sujet() sur les identifiants pour définir l'utilisateur à usurper.
from google.oauth2 import compte de service
from googleapiclient.discovery import construire
PORTÉES = ['https://www.googleapis.com/auth/gmail.readonly']
FICHIER_COMPTE_SERVEUR = 'clé-de-compte-de-service.json'
# Charger les informations d'identification de base à partir d'une clé JSON
pouvoirs = service_account.Credentials.depuis_fichier_compte_service(
FICHIER_DE_COMPTE_DE_SERVICE, étendues=PORTÉES
)
# Se faire passer pour l'utilisateur de l'espace de travail cible (DWD)
créances déléguées = identifiants.avec_sujet('user@yourdomain.com')
# Mise en place du service Gmail avec des identifiants délégués
service = construire('Gmail', 'v1', identifiants=crédits délégués)
# Afficher les libellés de la boîte de réception de l'utilisateur
résultats = service.users().labels().list(userId=moi).exécutez()
print(résultats)const { google } = require('googleapis');
const authentification = new google.auth.GoogleAuthentification({
file clé : 'clé-de-compte-de-service.json',
portées : ['https://www.googleapis.com/auth/gmail.readonly'],
// Définir l'utilisateur à imiter (DWD)
clientOptions: { sujet: 'user@yourdomain.com' }
});
const gmail = google.gmail({ version : 'v1', auth }) ;
// Listez les étiquettes pour l'utilisateur usurpé
const res = await gmail.users.labels.list({ userId: moi });
console.log(res.data.étiquettes);Portées OAuth requises pour le DWD de Gmail
Google classe les étendues de l'API Gmail en trois niveaux : de base, sensible, ou encore restreint. Le niveau détermine le niveau de contrôle que Google applique avant que vous ne puissiez utiliser la portée en production. Pour la délégation à l'échelle du domaine, vous devez répertorier toutes les portées dans l'entrée d'autorisation de la console d'administration. Pour une analyse complète de chaque portée et du processus de vérification de Google, consultez la Approfondissement des étendues OAuth Gmail.
| Portée | Niveau d'accès | Niveau | Commentaire Google requis |
|---|---|---|---|
| https://www.googleapis.com/auth/gmail.readonly | Lire tous les messages et métadonnées | Sensible | Oui - vérification de l'écran de consentement OAuth |
| https://www.googleapis.com/auth/gmail.send | Envoyer un e-mail au nom de l'utilisateur | Sensible | Oui - vérification de l'écran de consentement OAuth |
| https://www.googleapis.com/auth/gmail.modify | Lire, composer, envoyer, supprimer (pas définitivement) | Sensible | Oui - vérification de l'écran de consentement OAuth |
| https://www.googleapis.com/auth/gmail.labels | Créer, lire, mettre à jour, supprimer des étiquettes | De base | Non |
| https://www.googleapis.com/auth/gmail.metadata | Lire les métadonnées du message (en-têtes, pas de corps) | De base | Non |
| https://mail.google.com/ | Accès complet - lire, écrire, envoyer, supprimer tout | Accès restreint | Oui - évaluation complète de la sécurité + CASA Niveau 2 |
| https://www.googleapis.com/auth/gmail.settings.basic | Gérer les paramètres de base des e-mails (filtres, étiquettes) | Sensible | Oui - vérification de l'écran de consentement OAuth |
| https://www.googleapis.com/auth/gmail.settings.sharing | Gérer les paramètres sensibles (transfert, IMAP/POP) | Accès restreint | Oui - évaluation complète de la sécurité + CASA Niveau 2 |
Limites et pièges spécifiques à Gmail
Avant de vous engager à Délégation à l'échelle du domaine pour un compte de service de l'API Gmail, connaissance de ces contraintes. Certaines sont des limites techniques strictes de Google ; d'autres sont des exigences de politique qui peuvent empêcher la mise en ligne de votre application. Pour résoudre les erreurs telles que politique_admin_appliquée, voir les Guide des erreurs de l'API Gmail.
125 délégués maximum par utilisateur
Gmail impose une limite stricte de 25 délégués de messagerie par compte utilisateur. Il s'agit d'une limite par utilisateur appliquée au niveau de Gmail, et non au niveau de la quota de l'API Google Cloud. Si vous créez un outil de conformité ou d'archivage qui doit fonctionner dans une grande organisation, planifiez votre architecture autour de cette limite dès le début. Vous ne pouvez pas demander d'augmentation à Google.
2Email principal requis, pas de pseudonyme
Lors de l'appel avec_sujet() ou définir le JWT sous réclamation, vous devez utiliser l'utilisateur adresse e-mail principale, pas un alias ou une adresse e-mail de groupe. Par exemple, si l'adresse principale d'un utilisateur est john@company.com mais ils ont aussi john.smith@company.com En tant qu'alias, vous devez utiliser le primaire. L'utilisation d'un alias entraînera une erreur d'authentification de l'API Gmail.
De même, les adresses e-mail de groupe (comme team@company.comne peut pas être usurpé avec DWD - les groupes ne sont pas des comptes d'utilisateurs individuels.
3Évaluation annuelle CASA de niveau 2 pour les champs d'application restreints
Si votre application utilise quoi que ce soit portées Gmail restreintes comme https://mail.google.com/), Google vous demande de passer un CASA (Cloud Application Security Assessment) Niveau 2 évaluation avant que votre application puisse accéder aux données Gmail des utilisateurs externes. Il s'agit d'une exigence annuelle, et non d'une certification unique.
Le CASA de niveau 2 est réalisé par un évaluateur de sécurité approuvé par Google. L'évaluation couvre l'architecture de sécurité de votre application, vos pratiques de gestion des données et vos contrôles d'accès. Délai : budget de 4 à 8 semaines et coût réel. C'est un obstacle important pour les équipes en phase de démarrage.
4Approbations multipartites (mise à jour Google août 2024)
À partir d'août 2024, Google a introduit approbation multipartite pour certaines actions administratives à privilèges élevés dans Google Workspace. Selon votre édition Workspace (Business Standard, Enterprise, etc.) et les paramètres de sécurité de votre organisation, l'autorisation d'un nouvel ID client pour la délégation à l'échelle du domaine peut désormais nécessiter la confirmation de l'action par un deuxième Super Administrateur avant qu'elle ne prenne effet.
Cela signifie que la voie consistant à "obtenir l'autorisation d'un administrateur pour DWD" n'est plus garantie de fonctionner en une seule étape pour toutes les organisations. Vérifiez les politiques d'administrateur Workspace de votre organisation et le Blog des mises à jour de Google Workspace pour les dernières exigences avant de commencer le processus d'installation avec l'équipe informatique d'un client.
Quand NE PAS utiliser un compte de service + DWD (le problème du SaaS multi-locataire)
Cette section est celle que la plupart des guides sautent. La délégation de droits d'administrateur pour le compte de service Gmail API est un outil puissant mais limité. Si l'un de ces scénarios décrit votre situation, DWD ne fonctionnera pas du tout ou créera des frais d'exploitation qui dépassent les avantages. Choisir DWD dans ces cas est une erreur courante et coûteuse.
Produit B2C ou PLG servant les utilisateurs @gmail.com
Si votre produit propose un flux d'inscription en libre-service et que vos utilisateurs incluent des personnes ayant une disposition personnelle comptes @gmail.com, DWD est architecturalement incompatible avec votre cas d'utilisation. DWD ne peut pas usurper l'identité des comptes @gmail.com - point final. Vous avez besoin d'une autorisation standard côté utilisateur OAuth pour chaque utilisateur qui s'inscrit, qu'il possède également un compte Workspace ou non.
SaaS multi-locataire avec des clients sur différents domaines Workspace
Si chacun de vos clients est une entreprise différente avec son propre domaine Google Workspace, vous auriez besoin d'un séparer l'autorisation DWD d'un Super Admin dans chaque organisation cliente. Cela n'est pas évolutif. Chaque administrateur informatique du client doit suivre indépendamment le processus de configuration en 5 étapes. L'autorisation standard côté utilisateur d'OAuth - ou une solution OAuth gérée - est beaucoup mieux adaptée aux produits multi-locataires où vos utilisateurs s'étendent à de nombreuses organisations différentes.
Pas d'accès à un super administrateur Google Workspace
DWD requiert un Super administrateur Google Workspace pour autoriser l'ID client de votre compte de service dans la console d'administration. Si vos utilisateurs cibles ou votre propre organisation ne disposent pas d'un Super Administrateur, ou si le processus d'approbation informatique prend des semaines, voire des mois, DWD bloquera entièrement votre mise sur le marché. Ceci est courant dans les industries réglementées, les grandes entreprises et les organisations ayant des processus de gestion du changement stricts.
Délai de mise sur le marché court, pas encore de budget CASA
Si vous n'avez pas encore atteint l'adéquation produit-marché et que vous avez besoin d'une intégration Gmail COURIR EN JOURS PLUTÔT QU EN SEMAINES, le calendrier combiné comprenant : (1) la création d'un projet Google Cloud, (2) l'attente de la propagation d'Admin Console, (3) le passage par la vérification de l'application OAuth de Google pour les champs d'application sensibles, et (4) la planification de la CASA Tier 2 pour les champs d'application restreints - est prohibitif. La danse administrative seule peut prendre plus de temps que votre sprint. Un fournisseur OAuth géré qui a déjà passé ces examens est un choix d'ingénierie légitime, pas seulement un raccourci.
Évitez la bureaucratie
Unipile fournit OAuth hébergé pour Gmail, Outlook et IMAP. Certifié CASA Tier 2. Pas de configuration DWD, pas de console d'administration. Fonctionne aussi bien pour les utilisateurs @gmail.com que pour ceux de Workspace.
L'alternative gérée : OAuth hébergé avec Unipile
Si votre situation rend Délégation à l'échelle du domaine pour un compte de service de l'API Gmail le mauvais choix - ou si vous souhaitez simplement éviter l'installation en 5 étapes, l'évaluation CASA et le renouvellement annuel - il existe une alternative d'ingénierie légitime. Unipile agit comme un intermédiaire technique indépendant, gérant le flux OAuth au nom de chaque utilisateur authentifié. Ce n'est pas une solution de contournement pour l'examen de sécurité de Google. Unipile a obtenu la certification CASA de niveau 2 et opère dans le cadre approuvé par Google.
Certifié CASA de niveau 2
Unipile a passé l'évaluation de sécurité des applications Google Cloud au niveau 2. Vos comptes liés accèdent à Gmail via une plateforme déjà vérifiée - aucune évaluation de votre côté.
Au nom de chaque utilisateur
Chaque appel API qu'Unipile effectue à Gmail est fait au nom de chaque utilisateur authentifié individuellement, en utilisant son propre jeton OAuth. Pas de partage d'identifiants, pas d'usurpation d'identité à l'échelle du domaine requise.
API unique et unifiée
Une API unique pour Gmail, Outlook et IMAP. Changez de fournisseur ou ajoutez de nouveaux comptes liés sans modifier votre code d'intégration.
Gmail
Outlook
IMAP
import demandes
# Unipile gère le flux OAuth pour chaque compte associé
# : aucun compte de service, aucun DWD, aucune configuration de la console d'administration requise
en-têtes = {
"X-API-KEY": "VOTRE_CLE_API_UNIPILE",
"accepter": "application/json"
}
# : Afficher les e-mails d'un compte Gmail ou Outlook associé
response = requêtes.obtenir(
"https://api.unipile.com/api/v1/emails",
en-têtes=en-têtes,
paramètres={"account_id": "acc_utilisateur_gmail_123"}
)
print(response.json())Compte de service de l'API Gmail et FAQ sur DWD
Questions courantes sur le compte de service de l'API Gmail, la délégation sur l'ensemble du domaine, les champs d'application, les limites et quand choisir une alternative gérée.
Une Compte de service Gmail est une identité Google Cloud spéciale (pas un utilisateur humain) qui s'authentifie auprès de l'API Gmail à l'aide d'une clé JSON privée plutôt qu'OAuth interactif. Lorsqu'elle est combinée avec délégation à l'échelle du domaine, elle permet à une application côté serveur d'accéder à Gmail au nom de n'importe quel utilisateur d'une organisation Google Workspace, sans que cet utilisateur n'ait à autoriser l'application manuellement. Elle est conçue pour un accès automatisé de serveur à serveur dans les environnements d'entreprise.
Une Compte de service de l'API Gmail + DWD utilise l'authentification JWT serveur à serveur et peut usurper l'identité de n'importe quel utilisateur Workspace en silence, sans flux de consentement par utilisateur. Côté utilisateur OAuth standard nécessite que chaque utilisateur passe par un écran de consentement interactif, mais fonctionne pour n'importe quel utilisateur Gmail, y compris les comptes personnels @gmail.com. Les comptes de service conviennent aux outils internes d'entreprise ; les utilisateurs côté OAuth conviennent aux produits SaaS avec des bases d'utilisateurs diverses. Pour une comparaison complète, y compris l'option gérée, voir le tableau comparatif au-dessus.
En savoir plus sur Page produit de l'API Gmail Unipile.Non. Voici la limite la plus critique du délégué à l'échelle du domaine pour le compte de service de l'API Gmail. Les adresses @gmail.com personnelles ne font pas partie d'un domaine Workspace géré, il n'y a donc pas d'administrateur pour autoriser la délégation DWD. Tenter d'usurper l'identité d'un utilisateur @gmail.com retournera une erreur d'authentification. Si votre produit sert des utilisateurs ayant des comptes @gmail.com, vous devez utiliser l'autorisation OAuth standard côté utilisateur, ou un fournisseur géré comme Unipile qui gère l'OAuth pour les utilisateurs @gmail.com et Workspace.
Dans la console d'administration Google Workspace (nécessite un super-administrateur), accédez à : Menu > Sécurité > Contrôle d'accès et des données > Contrôles d'API > Délégation à l'échelle du domaine > Gérer la délégation à l'échelle du domaine > Ajouter un nouveau. Entrez l'ID client numérique de votre compte de service et la liste des étendues OAuth séparées par des virgules. Enregistrez et attendez jusqu'à 60 minutes pour la propagation. Pour les étapes complètes, consultez la Guide d'installation Dans cet article. Référence : Aide Google Admin - Délégation à l'échelle du domaine.
La délégation à l'échelle du domaine est pas déprécié en 2026, mais il est plus restreint. Google a introduit l'approbation multipartite pour certaines actions d'administrateur à privilèges élevés en août 2024, ce qui peut nécessiter qu'un deuxième Super Admin approuve les autorisations DWD. De plus, l'utilisation de scopes Gmail restreints comme https://mail.google.com/ exige désormais un CASA Niveau 2 évaluation annuelle de la sécurité. DWD reste un modèle valide pour les cas d'utilisation d'outils internes d'entreprise authentiques, mais les frais généraux de conformité ont augmenté.
Les étendues requises dépendent de ce que fait votre application. Lecture seule : https://www.googleapis.com/auth/gmail.readonly (sensible, nécessite une vérification Google). Envoyer un email : https://www.googleapis.com/auth/gmail.send (sensible). Accès complet à la boîte aux lettres : https://mail.google.com/ (restreint, nécessite une évaluation CASA niveau 2). Métadonnées uniquement : https://www.googleapis.com/auth/gmail.metadata (de base, sans révision). Vous devez inclure toutes les étendues requises dans l'entrée DWD de la console d'administration. Voir le tableau de pleine portée dans ce guide.
Vous avez encore des questions sur la délégation à l'échelle du domaine du compte de service de l'API Gmail ? Notre équipe peut vous aider à choisir l'architecture adaptée à votre cas d'utilisation.
Parlez à un expert
FR 
EN 
ES 
DE 
IT 
BR 
NL 
PL 
TR