LinkedIn
Instagram
WhatsApp
Telegram
Google Agenda
Word lid van de Slack-gemeenschapGmail API Serviceaccount & Domeinbreed gedelegeerd gezag: De 2026 Gids voor Ontwikkelaars
Gmail API serviceaccount instellen met domeinwijde delegatie: volledige stappen in de Admin Console, vereiste scopes, harde limieten en een eerlijk beslissingskader voor wanneer DWD de verkeerde keuze is. Plus: het beheerde OAuth-alternatief dat de admin-dans volledig overslaat.
van google.oauth2 importeer serviceaccount
van googleapiclient.discovery importeer bouwen
# Inloggegevens van de serviceaccount laden
credit = service_account.Credentials
.van_serviceaccountbestand(
'service-account-key.json',
scopes=['https://mail.google.com/']
)
# Zich voordoen als een gebruiker van de werkruimte (DWD)
gedelegeerd = credits.met_onderwerp(
'user@yourdomain.com'
)
#: Gmail-service opzetten
service = bouwen('Gmail', 'v1', referenties=gedelegeerd)Wat is een Gmail API-serviceaccount?
A Gmail API serviceaccount met domeinbrede delegatie is een Google Cloud-identiteit waarmee een backend-applicatie toegang kan krijgen tot Gmail-gegevens van elke gebruiker in een Google Workspace-organisatie, zonder individuele toestemming van de gebruiker. Het serviceaccount krijgt beheerdersniveauvertrouwen in de Google Workspace Admin Console, waardoor het elke gebruiker in het domein kan imiteren met behulp van OAuth 2.0 JWT-authenticatie.
In tegenstelling tot standaard OAuth 2.0 waarbij elke gebruiker uw app interactief autoriseert, Gmail API serviceaccount domeinbrede delegatie laat uw servercode Gmail API's aanroepen namens honderden of duizenden Workspace-gebruikers met één serviceaccountreferentie. De afweging: het werkt alleen op Google Workspace-domeinen - niet op persoonlijke @gmail.com-accounts.
Dit patroon komt vaak voor in bedrijfssoftware: e-mailarchiveringssystemen, compliance monitoring platforms, interne CRM-integraties en agenda-/e-mailsynchronisatieservices die moeten functioneren binnen een heel bedrijfsdomein zonder dat elke werknemer de app individueel hoeft autoriseren.
Geen toestemmingsstroom voor gebruikers
Serviceaccounttoegang tot Gmail namens workspacegebruikers zonder OAuth-prompts te activeren.
Server-naar-server-auth
Gebruikt JWT ondertekend met een privésleutel - geen browseromleiding, geen uitwisseling van autorisatiecodes.
Domeingebonden toegang
Eenmalig geautoriseerd door een Workspace Super Admin - geldt voor alle gebruikers in de organisatie.
Serviceaccount versus OAuth-gebruiker aan de clientzijde: welke heb je echt nodig?
Beide patronen maken gebruik van OAuth 2.0 scopes om toegang te krijgen tot Gmail, maar ze verschillen fundamenteel op het gebied van architectuur, installatiekosten en voor wie ze geschikt zijn. Hier is de eerlijke vergelijking - inclusief de beheerde optie die beide installatiepaden volledig overslaat.
| Criteria | Serviceaccount + DWD | OAuth aan gebruikerszijde | Unipile beheerd |
|---|---|---|---|
| Google Workspace vereist | Vereist | Niet nodig | Niet nodig |
| @gmail.com ondersteuning | Nee - alleen werkruimte | Ja | Ja |
| Toestemming van de gebruiker nodig | Admin-toekenningen, geen per gebruiker | Elke gebruiker stemt in | OAuth per gebruiker, afgehandeld |
| Admin Console installatie | Vereist - complex pad | Niet nodig | Niet nodig |
| Scopeverificatie door Google | Vereist voor beperkt | Vereist voor beperkt | Unipile is CASA Tier 2 |
| CASA beoordeling | Jouw last | Jouw last | Al gedaan |
| Vriendelijkheid van multi-tenant SaaS | Hard - per-huurder admin | Goed | Uitstekend |
| Tijd tot eerste API-aanroep | Dagen (goedkeuring door beheerder + installatie) | Uren | Notulen |
Gebruik serviceaccount + DWD wanneer...
Gebruik OAuth aan de gebruikerszijde wanneer...
Kritieke limiet: DWD werkt niet op @gmail.com accounts
Dit is de meest voorkomende fout die teams maken bij het kiezen Gmail API serviceaccount domeinbrede delegatie. DWD kan alleen gebruikers imiteren die deel uitmaken van een Google Workspace-domein dat de client-ID van uw serviceaccount expliciet heeft geautoriseerd. Persoonlijke @gmail.com-adressen maken geen deel uit van een Workspace-domein en kan niet worden nagebootst - de API-aanroep zal een 400 fout geven met admin_beleid_toegepast of een ongeldige delegatiefout. Als uw product zowel @gmail.com- als Workspace-gebruikers bedient, is een serviceaccount + DWD niet de juiste keuze.
Gmail-toegang nodig zonder Workspace-beheerder? Unipile's managed OAuth werkt voor @gmail.com en Workspace-gebruikers met één uniforme API - geen DWD-configuratie vereist.
Gebruik de sleutel van UnipileHoe u domeinbrede delegatie instelt in Google Workspace (5 stappen)
Hier is de volledige procedure van 2026 voor het configureren Gmail API serviceaccount domeinbrede delegatie. Je hebt een Google Cloud-project, een Workspace Super Admin en ongeveer 30 minuten nodig voor de eerste installatie.
Maak een serviceaccount aan in de Google Cloud Console
Ga naar console.cloud.google.com, selecteer je project (of maak er een aan), ga vervolgens naar IAM & Beheer > Serviceaccounts > Serviceaccount aanmaken. Geef het een beschrijvende naam zoals gmail-dwd-service. U hoeft in dit stadium geen Cloud IAM-rollen toe te wijzen - de machtigingen zijn afkomstig van de Google Workspace Admin Console, niet van Cloud IAM.
Genereer en download de JSON-sleutel
Ga naar de detailpagina van de serviceaccount, Sleutels > Sleutel toevoegen > Nieuwe sleutel maken > JSON. Download het bestand - dit is de inloggegevens die uw applicatie zal gebruiken om JWT's te ondertekenen. Sla het veilig op: behandel de JSON-sleutel als een privé SSL-certificaat. Plaats het nooit in versiebeheer.
Het JSON-bestand bevat de e-mailadres klant, privésleutelen klant_id velden die je code nodig heeft. Als alternatief voor bestandsgebaseerde sleutels kun je Werkbelastingsidentiteitsfederatie voor sleutelloze authenticatie in productieomgevingen.
Schakel de Gmail API in en identificeer de benodigde bereiken
In de Google Cloud Console, ga naar API's en services > API's en services inschakelen en schakel de Gmail API. Beslis vervolgens welke OAuth-scopes je applicatie nodig heeft. Voor de meeste Gmail-bewerkingen heb je minimaal nodig https://www.googleapis.com/auth/gmail.readonly (gevoelig) of https://mail.google.com/ (beperkt).
https://mail.google.com/Vereisen een formele Google security review en CASA Tier 2 beoordeling voordat je ze in productie kunt gebruiken. Zie de volledige reikwijdte referentie in de volgende sectie en in de Gmail OAuth-scopes diepgaande analyse voor de details over het beoordelingsproces.Autoriseer de client-ID in de Admin Console
Dit is de stap die uw Google Workspace Superbeheerder. Navigeer in de Beheerdersconsole naar:
In het dialoogvenster "Nieuw toevoegen" voert u de serviceaccount in numeriek klant-ID (de Unieke ID die je in Stap 1 hebt genoteerd) en de lijst met OAuth-scopes gescheiden door komma's. Bijvoorbeeld:
Sla de vermelding op. Wijzigingen verspreiden zich doorgaans binnen enkele minuten, maar kunnen in grote organisaties tot 60 minuten duren. Referentie: Google Workspace Admin Help - API-toegang beheren met domeingebrede delegatie.
Doe alsof je een gebruiker uit je backend bent
Met de gedownloade serviceaccount-sleutel en geautoriseerde DWD kunt u nu Gmail API's aanroepen namens elke gebruiker in het domein. De belangrijkste stap is het aanroepen van met_onderwerp() op de referenties om de gebruiker in te stellen om te imiteren.
van google.oauth2 importeer serviceaccount
van googleapiclient.discovery importeer bouwen
SCOPES = ['https://www.googleapis.com/auth/gmail.readonly']
SERVICEACCOUNT_BESTAND = 'service-account-key.json'
# Basisgegevens laden vanuit JSON-sleutel
referenties = service_account.Credentials.van_serviceaccountbestand(
SERVICE_ACCOUNT_FILE, scope=SCOPES
)
# Zich voordoen als de gebruiker van de doelwerkruimte (DWD)
gedelegeerde_inloggegevens = inloggegevens.met_onderwerp('user@yourdomain.com')
# De Gmail-service opzetten met gedelegeerde inloggegevens
service = bouwen('Gmail', 'v1', inloggegevens=gedelegeerde_aanmeldingen
# Geef een overzicht van de labels in de inbox van de gebruiker
resultaten = service.gebruikers().labels().list(gebruikersId="mij).uitvoeren()
print(resultaten)const { google } = require('googleapis');
const auth = nieuw google.auth.GoogleAuthenticatie({
sleutelbestand: 'service-account-key.json',
scopes: ['https://www.googleapis.com/auth/gmail.readonly'],
// Stel de gebruiker in om te imiteren (DWD)
clientOpties: { onderwerp: 'user@yourdomain.com' }
});
const gmail = google.gmail({ versie: 'v1', auth });
// Labels weergeven voor de geïmiteerde gebruiker
const res = wacht op gmail.users.labels.list({ gebruikerId: "mij });
console.log(res.data.labels);Vereiste OAuth-scopes voor Gmail DWD
Google deelt Gmail API-bereiken in drie niveaus in: bas, gevoeligen beperkt. De tier bepaalt hoeveel controle Google uitvoert voordat je de scope in productie kunt gebruiken. Voor delegatie op domeinbreed niveau moet je alle scopes vermelden in de autorisatie-invoer van de Admin Console. Voor een volledige uitsplitsing van elke scope en hoe het verificatieproces van Google eruitziet, zie de Gmail OAuth Scopes diepgaande analyse.
| Reikwijdte | Toegangsniveau | Niveau | Google recensie vereist |
|---|---|---|---|
| https://www.googleapis.com/auth/gmail.readonly | Lees alle berichten en metadata | Gevoelig | Ja - OAuth-verificatie van het toestemmingsscherm |
| https://www.googleapis.com/auth/gmail.send | E-mail verzenden namens gebruiker | Gevoelig | Ja - OAuth-verificatie van het toestemmingsscherm |
| https://www.googleapis.com/auth/gmail.modify | Lezen, opstellen, verzenden, verwijderen (niet permanent) | Gevoelig | Ja - OAuth-verificatie van het toestemmingsscherm |
| https://www.googleapis.com/auth/gmail.labels | Labels maken, lezen, bijwerken, verwijderen | Basis | Geen |
| https://www.googleapis.com/auth/gmail.metadata | Berichtmetadata lezen (headers, geen hoofdtekst) | Basis | Geen |
| https://mail.google.com/ | Volledige toegang - lezen, schrijven, verzenden, alles verwijderen | Beperkt | Ja - volledige beveiligingsbeoordeling + CASA Tier 2 |
| https://www.googleapis.com/auth/gmail.settings.basic | Beheer basis e-mailinstellingen (filters, labels) | Gevoelig | Ja - OAuth-verificatie van het toestemmingsscherm |
| https://www.googleapis.com/auth/gmail.settings.sharing | Gevoelige instellingen beheren (doorsturen, IMAP/POP) | Beperkt | Ja - volledige beveiligingsbeoordeling + CASA Tier 2 |
Gmail-specifieke limieten en aandachtspunten
Voordat we ons committeren aan Gmail API serviceaccount domeinbrede delegatie, houd rekening met deze beperkingen. Sommige zijn strikte technische limieten van Google; andere zijn beleidsvereisten die kunnen voorkomen dat uw app live gaat. Voor het oplossen van fouten zoals admin_beleid_toegepast, zie de Gmail API-foutengids.
1Maximaal 25 delegaties per gebruiker
Gmail hanteert een strikte limiet van 25 maildelegaties per gebruikersaccount. Dit is een quotum per gebruiker dat op Gmail-niveau wordt afgedwongen, niet op het quotumniveau van de Google Cloud API. Als je een tool voor naleving of archivering bouwt die binnen een grote organisatie moet functioneren, neem deze beperking dan vroegtijdig op in je architectuur. Je kunt geen verhoging aanvragen bij Google.
2Primair e-mailadres vereist, geen alias
Bij het bellen met_onderwerp() of het instellen van de JWT onder eis, u moet de gebruiker's primair e-mailadres, geen alias of groepsmailadres. Bijvoorbeeld, als het primaire adres van een gebruiker is john@company.com maar ze hebben ook john.smith@company.com Als alias moet u het primaire adres gebruiken. Het gebruik van een alias resulteert in een authenticatiefout van de Gmail API.
Net als, groepsmailadressen (zoals team@company.com) kan niet worden nagebootst met DWD - groepen zijn geen individuele gebruikersaccounts.
3CASA Tier 2 jaarlijkse beoordeling voor beperkte reikwijdten
Als uw applicatie een van de navolgende gebruikt beperkte Gmail-bereiken zoals https://mail.google.com/), Google vereist dat je een CASA (Cloud Application Security Assessment) Niveau 2 evaluatie voordat uw app toegang kan krijgen tot Gmail-gegevens voor externe gebruikers. Dit is een jaarlijkse vereiste, geen eenmalige certificering.
CASA Tier 2 wordt uitgevoerd door een door Google goedgekeurde veiligheidsbeoordelaar. De beoordeling omvat de beveiligingsarchitectuur van uw app, de procedures voor gegevensverwerking en toegangscontroles. Tijdlijn: begroting 4-8 weken en reële kosten. Dit is een aanzienlijke drempel voor teams in een vroeg stadium.
4Meerpartijgoedkeuringen (Google update augustus 2024)
Vanaf augustus 2024 introduceerde Google multi-partij goedkeuring voor bepaalde administratieve acties met hoge privileges in Google Workspace. Afhankelijk van uw Workspace-editie (Business Standard, Enterprise, etc.) en de beveiligingsinstellingen van uw organisatie, kan het autoriseren van een nieuwe client-ID voor delegatie binnen het hele domein nu de bevestiging van een tweede Super Admin vereisen voordat deze van kracht wordt.
Dit betekent dat het pad van "laat één beheerder DWD autoriseren" niet meer gegarandeerd in één stap werkt voor alle organisaties. Controleer het Workspace-beleid van uw organisatiebeheerder en de Google Workspace Updates blog voor de laatste vereisten voordat u met het IT-team van een klant begint met de installatie.
Wanneer je een serviceaccount **niet** moet gebruiken + DWD (het multi-tenant SaaS-probleem)
Dit gedeelte is hetgeen de meeste gidsen overslaan. Domainwijd delegeren voor Gmail API-serviceaccounts is een krachtig maar beperkt hulpmiddel. Als een van deze scenario's op uw situatie van toepassing is, zal DWD helemaal niet werken, of operationele overhead creëren die niet opweegt tegen de voordelen. DWD kiezen in deze gevallen is een veelvoorkomende en kostbare fout.
B2C- of PLG-product dat zich richt op @gmail.com-gebruikers
Als uw product een self-service aanmeldingsproces heeft en uw gebruikers mensen met een persoonlijke @gmail.com accounts, DWD is architecturaal gezien onverenigbaar met uw use case. DWD kan geen accounts van @gmail.com nabootsen - punt uit. U hebt standaard OAuth-autorisatie aan gebruikerszijde nodig voor elke gebruiker die zich aanmeldt, ongeacht of deze toevallig ook een Workspace-account heeft.
Multi-tenant SaaS met klanten op verschillende Workspace-domeinen
Als elk van uw klanten een ander bedrijf is met hun eigen Google Workspace-domein, hebt u een scheid DWD-autorisatie van een Super Admin bij elke klantorganisatie. Dit is niet schaalbaar. Elke IT-beheerder van een klant moet het 5-stappen installatieproces zelfstandig doorlopen. Standaard OAuth-autorisatie aan de gebruikerskant - of een beheerde OAuth-oplossing - is veel beter geschikt voor multi-tenant producten waarbij uw gebruikers zich over veel verschillende organisaties verspreiden.
Geen toegang tot een Google Workspace Super Admin
DWD vereist een Superbeheerder van Google Workspace om de client-ID van uw serviceaccount te autoriseren in de Admin Console. Als uw beoogde gebruikers of uw eigen organisatie geen Super Admin beschikbaar hebben, of als het IT-goedkeuringsproces weken tot maanden duurt, zal DWD uw volledige go-to-market blokkeren. Dit komt vaak voor in gereguleerde sectoren, grote ondernemingen en organisaties met strikte wijzigingsbeheerprocessen.
Korte time-to-market, nog geen CASA-budget
Als je pre-product-market-fit bent en Gmail-integratie nodig hebt rennen in dagen in plaats van weken, de gecombineerde tijdlijn van: (1) het aanmaken van een Google Cloud project, (2) wachten op de propagatie van de Admin Console, (3) het doorlopen van Google's OAuth app-verificatie voor gevoelige scopes, en (4) het plannen van CASA Tier 2 voor beperkte scopes - is prohibitief. Alleen al de admin-dans kan langer duren dan uw sprint. Een beheerde OAuth-provider die deze beoordelingen al heeft doorstaan, is een legitieme technische keuze, niet zomaar een gemakzuchtige oplossing.
Sla de administratieve dans over
Unipile biedt gehoste OAuth voor Gmail, Outlook en IMAP. CASA Tier 2 gecertificeerd. Geen DWD-installatie, geen Admin Console. Werkt voor zowel @gmail.com als Workspace-gebruikers.
Het beheerde alternatief: gehoste OAuth met Unipile
Als je situatie je Gmail API serviceaccount domeinbrede delegatie de verkeerde keuze - of als je gewoon de 5-stappeninstallatie, de CASA-beoordeling en de jaarlijkse vernieuwing wilt vermijden - is er een legitiem technisch alternatief. Unipile fungeert als een onafhankelijke technische tussenpersoon, die de OAuth-stroom beheert namens elke geauthenticeerde gebruiker. Dit is geen tijdelijke oplossing voor de beveiligingscontrole van Google. Unipile heeft de CASA Tier 2-certificering behaald en opereert onder het goedgekeurde framework van Google.
CASA tier 2 gecertificeerd
Unipile heeft het Cloud Application Security Assessment van Google op Tier 2 doorstaan. Je gekoppelde accounts hebben toegang tot Gmail via een reeds geverifieerd platform - geen beoordeling aan jouw kant.
Namens elke gebruiker
Elke API-aanroep die Unipile doet naar Gmail gebeurt namens elke afzonderlijke geauthenticeerde gebruiker, met behulp van hun eigen OAuth-token. Geen gedeelde inloggegevens, geen domeinbrede impersonatie vereist.
Enkele uniforme API
Eén API voor Gmail, Outlook en IMAP. Wissel van provider of voeg nieuwe gekoppelde accounts toe zonder je integratiecode te wijzigen.
Gmail
Outlook
IMAP
importeer verzoekt
# Unipile regelt de OAuth-procedure voor elk gekoppeld account
# Geen serviceaccount, geen DWD, geen configuratie van de beheerconsole nodig
kopteksten = {
"X-API-SLEUTEL": "UW_UNIPILE_API_SLEUTEL",
"accepteren": "application/json"
}
# E-mails weergeven uit een gekoppeld Gmail- of Outlook-account
response = verzoeken.krijgen(
"https://api.unipile.com/api/v1/emails",
kopteksten=kop,
parameters={"account_id": "acc_user_gmail_123"}
)
print(response.json())Gmail API Service Account & DWD Veelgestelde Vragen
Veelgestelde vragen over serviceaccounts in de Gmail API, domeinbrede delegatie, bereiken, limieten en wanneer te kiezen voor een beheerd alternatief.
A Gmail serviceaccount is een speciale Google Cloud-identiteit (geen menselijke gebruiker) die zich verifieert bij de Gmail API met behulp van een privé JSON-sleutel in plaats van interactieve OAuth. In combinatie met door de hele domein heen volmacht, hiermee kan een server-side applicatie namens elke gebruiker binnen een Google Workspace-organisatie toegang krijgen tot Gmail, zonder dat die gebruiker de app handmatig hoeft te autoriseren. Het is bedoeld voor geautomatiseerde server-naar-server-toegang in bedrijfsomgevingen.
A Gmail API serviceaccount + DWD gebruikt server-naar-server JWT-authenticatie en kan gebruikers van Workspace stilzwijgend imiteren, zonder toestemmingsstroom per gebruiker. Standaard OAuth-gebruiker vereist dat elke gebruiker een interactief toestemmingsscherm doorloopt, maar werkt voor elke Gmail-gebruiker, inclusief persoonlijke @gmail.com-accounts. Serviceaccounts zijn geschikt voor interne bedrijfsapplicaties; OAuth aan de gebruikerskant is geschikt voor SaaS-producten met diverse gebruikersgroepen. Zie voor een volledige vergelijking, inclusief de beheerde optie, de vergelijkingstabel boven.
Meer informatie over Unipile Gmail API productpagina.Nee. Dit is de meest kritieke beperking van de domeingebrede delegatie van Gmail API-serviceaccounts. Persoonlijke @gmail.com-adressen maken geen deel uit van een beheerd Workspace-domein, dus er is geen beheerder die de DWD-delegatie kan autoriseren. Pogingen om een @gmail.com-gebruiker te imiteren, resulteren in een authenticatiefout. Als uw product gebruikers met @gmail.com-accounts bedient, moet u standaard OAuth-autorisatie aan de gebruikerszijde gebruiken, of een beheerde provider zoals Unipile die OAuth afhandelt voor zowel @gmail.com- als Workspace-gebruikers.
Navigeer in de Google Workspace Admin Console (vereist Super Admin) naar: Menu > Beveiliging > Toegang en gegevensbeheer > API-instellingen > Delegatie per domein > Delegatie per domein beheren > Nieuwe toevoegen. Voer de numerieke client-ID van uw serviceaccount en de door komma's gescheiden lijst met OAuth-bereiken in. Sla op en wacht maximaal 60 minuten op de verspreiding. Zie voor de volledige stapsgewijze instructies de Installatiegids in dit artikel. Referentie: Google Admin Help - Delegatie voor het hele domein.
Domeinwijd gedelegeerd beheer is niet verouderd vanaf 2026, maar het is beperkter. Google heeft in augustus 2024 multi-party goedkeuring geïntroduceerd voor bepaalde beheerdersacties met hoge bevoegdheden, wat een tweede Super Beheerder kan vereisen om DWD-autorisaties goed te keuren. Daarnaast, met behulp van beperkte Gmail-bereiken zoals https://mail.google.com/ vereist nu een CASA Tier 2 jaarlijkse veiligheidsbeoordeling. DWD blijft een geldig patroon voor echte interne bedrijfstoepassingen, maar de nalevingskosten zijn toegenomen.
Vereiste bereiken zijn afhankelijk van wat uw app doet. Alleen-lezen: https://www.googleapis.com/auth/gmail.readonly (vertrouwelijk, vereist verificatie via Google). E-mail verzenden: https://www.googleapis.com/auth/gmail.send (gevoelig). Volledige toegang tot de mailbox: https://mail.google.com/ (beperkt, vereist CASA Tier 2-beoordeling). Alleen metadata: https://www.googleapis.com/auth/gmail.metadata (basisch, geen beoordeling). Je moet alle vereiste scopes opnemen in de Admin Console DWD-vermelding. Zie de volledig omvang tabel in deze gids.
Nog steeds vragen over domeinbrede autorisatie voor Gmail API-serviceaccounts? Ons team kan u helpen de juiste architectuur te kiezen voor uw specifieke situatie.
Praat met een expert
NL 
EN 
FR 
ES 
DE 
IT 
BR 
PL 
TR