LinkedIn
Instagram
WhatsApp
Telegramma
Calendario di Google
Partecipare alla comunità SlackServizio e account per account di servizio Gmail API Delega a livello di dominioLa Guida 2026 per Sviluppatori
Configura l'account di servizio Gmail API con delega a livello di dominio: passaggi completi nella Console di amministrazione, ambiti richiesti, limiti rigidi e un quadro decisionale onesto per quando la delega a livello di dominio è la scelta sbagliata. In più: l'alternativa gestita di OAuth che salta del tutto la trafila amministrativa.
from google.oauth2 import account di servizio
from googleapiclient.discovery import costruire
# Carica le credenziali dell'account di servizio
crediti = service_account.Credentials
.dal_file_account_di_servizio(
'chiave-account-di-servizio.json',
ambiti=['https://mail.google.com/']
)
# Assumere l'identità di un utente dell'area di lavoro (DWD)
delegato = credenziali.con_soggetto(
'user@yourdomain.com'
)
#: Implementazione del servizio Gmail
servizio = costruire('gmail', 'v1', credenziali=delegato)Che cos'è un account di servizio dell'API Gmail?
A Account di servizio API di Gmail con delega a livello di dominio una identità di Google Cloud che consente a un'applicazione backend di accedere ai dati di Gmail per qualsiasi utente in un'organizzazione Google Workspace, senza il consenso dei singoli utenti. L'account di servizio riceve un livello di fiducia amministrativo nella Google Workspace Admin Console, che gli consente di impersonare qualsiasi utente nel dominio utilizzando l'autenticazione JWT OAuth 2.0.
A differenza di OAuth 2.0 standard in cui ogni utente autorizza la tua app in modo interattivo, delegazione a livello di dominio del servizio account API Gmail Consente al tuo codice server di chiamare le API di Gmail per conto di centinaia o migliaia di utenti Workspace con singole credenziali di account di servizio. Il compromesso: funziona solo sui domini Google Workspace, non sugli account personali @gmail.com.
Questo modello è comune negli strumenti aziendali: sistemi di archiviazione delle e-mail, piattaforme di monitoraggio della conformità, integrazioni CRM interne e servizi di sincronizzazione di calendari/e-mail che devono operare sull'intero dominio aziendale senza richiedere a ciascun dipendente di autorizzare individualmente l'app.
Nessun flusso di consenso dell'utente
L'account di servizio accede a Gmail per conto degli utenti workspace senza attivare richieste OAuth.
Autenticazione server-server
Usa JWT firmato con una chiave privata: nessuna reindirizzamento del browser, nessuno scambio di codice di autorizzazione.
Access limitato al dominio
Autorizzato una volta da un Super amministratore di Workspace - si applica a tutti gli utenti dell'organizzazione.
Account di servizio vs utente lato OAuth: quale ti serve davvero?
Entrambi i pattern utilizzano gli ambiti OAuth 2.0 per accedere a Gmail, ma sono fondamentalmente diversi nell'architettura, nei costi di configurazione e per chi funzionano. Ecco il confronto onesto, inclusa l'opzione gestita che salta completamente entrambi i percorsi di configurazione.
| Criteri | Account di servizio + DWD | lato utente OAuth | Unipile gestito |
|---|---|---|---|
| Google Workspace richiesto | Richiesto | Non necessario | Non necessario |
| supporto@gmail.com | Non - solo spazio di lavoro | Sì | Sì |
| Consenso dell'utente necessario | Concessioni amministrative, non per utente | Ogni utente acconsente | OAuth per utente, gestito |
| Configurazione console di amministrazione | Obbligatorio - percorso complesso | Non necessario | Non necessario |
| Verifica dello scopo da parte di Google | Richiesto per restrizioni | Richiesto per restrizioni | Unipile è CASA di livello 2 |
| Valutazione CASA | Il tuo fardello | Il tuo fardello | Già fatto |
| Compatibilità con ambiente multi-tenant SaaS | Amministratore per tenant difficile | Bene | Eccellente |
| Tempo alla prima chiamata API | Giorni (approvazione admin + configurazione) | Ore | Verbale |
Utilizzare il service account + DWD quando...
Usa OAuth lato utente quando...
Limite critico: DWD non funziona sugli account @gmail.com
Questo è l'errore più comune che le squadre commettono quando scelgono delegazione a livello di dominio del servizio account API Gmail. DWD può solo impersonare utenti che appartengono a un dominio Google Workspace che ha esplicitamente autorizzato l'ID client del tuo account di servizio. Gli indirizzi @gmail.com personali non fanno parte di alcun dominio Workspace e non può essere impersonato - la chiamata API restituirà un errore 400 con admin_policy_enforced o un errore di delega non valido. Se il tuo prodotto serve sia utenti @gmail.com che utenti Workspace, l'account di servizio + DWD non è la scelta giusta.
Serve accesso a Gmail senza amministratore di Workspace? L'OAuth gestito da Unipile funziona per gli utenti @gmail.com e Workspace con una singola API unificata, senza richiedere alcuna configurazione DWD.
Usa la chiave UnipileCome impostare la delega a livello di dominio in Google Workspace (5 passaggi)
Ecco la procedura completa del 2026 per la configurazione delegazione a livello di dominio del servizio account API Gmail. È necessario un progetto Google Cloud, un Super Amministratore di Workspace e circa 30 minuti per la configurazione iniziale.
Crea un account di servizio nella Google Cloud Console
Vai a console.cloud.google.com, seleziona il tuo progetto (o creane uno), quindi vai su IAM & Amministrazione > Account di servizio > Crea account di servizio. Dai un nome descrittivo come gmail-dwd-servizio. Non è necessario assegnare alcun ruolo Cloud IAM in questa fase: le autorizzazioni provengono dalla Console di amministrazione di Google Workspace, non da Cloud IAM.
Genera e scarica la chiave JSON
Nella pagina di dettaglio dell'account di servizio, vai su Chiavi > Aggiungi chiave > Crea nuova chiave > JSON. Scarica il file: questa è la credenziale che la tua applicazione utilizzerà per firmare i JWT. Conservala in modo sicuro: tratta la chiave JSON come un certificato SSL privato. Non aggiungerla mai al controllo di versione.
Il file JSON contiene il email_del_cliente, chiave_privata, e ID cliente campi di cui il tuo codice ha bisogno. In alternativa alle chiavi basate su file, puoi utilizzare Federazione delle identità di carico di lavoro per l'autenticazione senza chiave in ambienti di produzione.
Abilita l'API Gmail e identifica gli scope richiesti
Nella Google Cloud Console, vai a API e servizi > Attiva API e servizi e abilita il API Gmail. Decidi quindi quali ambiti OAuth sono necessari alla tua applicazione. Per la maggior parte delle operazioni di Gmail, come minimo avrai bisogno di https://www.googleapis.com/auth/gmail.readonly (sensibile) o https://mail.google.com/ (limitato).
https://mail.google.com/) richiedono una revisione formale della sicurezza di Google e una valutazione di livello 2 di CASA prima di poterle utilizzare in produzione. Vedere il riferimento completo dell'ambito nella sezione successiva e in Gmail OAuth ambiti approfondito per dettagli sul processo di revisione.Autorizza l'ID client nella Console di amministrazione
Questo è il passaggio che richiede il tuo Super Amministratore di Google Workspace. Naviga nella Console di amministrazione fino a:
Nella finestra di dialogo "Aggiungi nuovo", inserisci il nome del service account ID client numerico (l'ID univoco che hai annotato nel Passaggio 1) e l'elenco degli ambiti OAuth separati da virgole. Ad esempio:
Salva l'impostazione. Le modifiche solitamente vengono propagate nel giro di pochi minuti, ma possono richiedere fino a 60 minuti in grandi organizzazioni. Riferimento: Guida di Google Workspace Admin - Controlla l'accesso alle API con la delega a livello di dominio.
Impersona un utente dal tuo backend
Con la chiave dell'account di servizio scaricata e DWD autorizzato, ora puoi chiamare le API di Gmail per conto di qualsiasi utente nel dominio. Il passaggio chiave è chiamare con_soggetto() sulle credenziali per impostare l'utente da impersonare.
from google.oauth2 import account di servizio
from googleapiclient.discovery import costruire
SCOPI = ['https://www.googleapis.com/auth/gmail.readonly']
FILE_ACCOUNT_SERVICE = 'chiave-account-di-servizio.json'
# Carica le credenziali di base dalla chiave JSON
credenziali = service_account.Credentials.dal_file_account_di_servizio(
FILE_ACCOUNT_SERVICE, ambiti=SCOPI
)
# Assumere l'identità dell'utente dell'area di lavoro di destinazione (DWD)
credenziali delegate = credenziali.con_soggetto('user@yourdomain.com')
#: Implementazione del servizio Gmail con credenziali delegate
servizio = costruire('gmail', 'v1', credenziali=credenziali_delegate
# Elenca le etichette della posta in arrivo dell'utente
risultati = servizio.utenti().etichette().list(userId='me').eseguire()
printrisultaticonst google = require('googleapis');
const autenticazione = new google.auth.GoogleAuth({
fileChiave: 'chiave-account-di-servizio.json',
scope: ['https://www.googleapis.com/auth/gmail.readonly'],
// Imposta l'utente da impersonare (DWD)
clientOptions: { oggetto: 'user@yourdomain.com' }
});
const gmail = google.gmail({ versione: 'v1', auth });
// Elenca le etichette per l'utente impersonato
const res = await gmail.users.labels.list({ userId: 'me' });
console.log(res.data.etichette);Ambiti OAuth richiesti per il DWD di Gmail
Google classifica gli ambiti dell'API di Gmail in tre livelli: de base, sensibile, e limitato. Il livello determina quanto scrutinio applica Google prima che tu possa utilizzare l'ambito in produzione. Per la delega a livello di dominio, devi elencare tutti gli ambiti nella voce di autorizzazione della Console di amministrazione. Per una ripartizione completa di ogni ambito e di come appare il processo di verifica di Google, consulta la Gmail Scopes OAuth Approfondimento.
| Ambito | Livello di accesso | Livello | Recensione Google richiesta |
|---|---|---|---|
| https://www.googleapis.com/auth/gmail.readonly | Leggi tutti i messaggi e i metadati | Sensibile | Sì - verifica della schermata di consenso OAuth |
| https://www.googleapis.com/auth/gmail.send | Inviare email per conto dell'utente | Sensibile | Sì - verifica della schermata di consenso OAuth |
| https://www.googleapis.com/auth/gmail.modify | Leggi, componi, invia, elimina (non permanentemente) | Sensibile | Sì - verifica della schermata di consenso OAuth |
| https://www.googleapis.com/auth/gmail.labels | Crea, leggi, aggiorna, elimina etichette | Base | No |
| https://www.googleapis.com/auth/gmail.metadata | Leggi i metadati del messaggio (intestazioni, nessun corpo) | Base | No |
| https://mail.google.com/ | Accesso completo - legge, scrive, invia, elimina tutto | Restricted | Sì - valutazione completa della sicurezza + CASA Tier 2 |
| https://www.googleapis.com/auth/gmail.settings.basic | Gestisci le impostazioni di base delle email (filtri, etichette) | Sensibile | Sì - verifica della schermata di consenso OAuth |
| https://www.googleapis.com/auth/gmail.settings.sharing | Gestisci impostazioni sensibili (inoltro, IMAP/POP) | Restricted | Sì - valutazione completa della sicurezza + CASA Tier 2 |
Limiti e insidie specifici di Gmail
Prima di impegnarsi a delegazione a livello di dominio del servizio account API Gmail, conosci questi limiti. Alcuni sono limiti tecnici rigidi di Google; altri sono requisiti normativi che possono impedire alla tua app di andare online. Per la risoluzione dei problemi come admin_policy_enforced, vedi la Guida agli errori delle API di Gmail.
125 delegati massimo per utente
Gmail impone un limite rigido di 25 delegati di posta per account utente. Questa è una quota per utente applicata a livello di Gmail, non a livello di quota dell'API di Google Cloud. Se stai creando uno strumento di conformità o archiviazione che deve operare in tutta una grande organizzazione, pianifica la tua architettura attorno a questo limite fin dall'inizio. Non puoi richiedere un aumento a Google.
2Email principale richiesta, nessun alias
Quando chiamate con_soggetto() o impostando il JWT sub richiesta, devi usare l'utente's indirizzo email primario, non un alias o un'e-mail di gruppo. Ad esempio, se l'indirizzo principale di un utente è john@company.com ma hanno anche john.smith@company.com come alias, devi utilizzare il primario. L'utilizzo di un alias comporterà un errore di autenticazione dall'API di Gmail.
Allo stesso modo, gli indirizzi email di gruppo (come team@company.com) non può essere impersonato con DWD: i gruppi non sono account utente individuali.
3Valutazione annuale CASA di livello 2 per ambiti ristretti
Se la tua applicazione utilizza qualsiasi ambiti Gmail limitati come ad esempio https://mail.google.com/), Google richiede di passare un CASA (Cloud Application Security Assessment) Livello 2 valutazione prima che la tua app possa accedere ai dati di Gmail per utenti esterni. Questo è un requisito annuale, non una certificazione una tantum.
CASA Tier 2 è condotto da un valutatore di sicurezza approvato da Google. La valutazione copre l'architettura di sicurezza della tua app, le pratiche di gestione dei dati e i controlli degli accessi. Tempistiche: budget 4-8 settimane e costo reale. Questa è una barriera significativa per i team in fase iniziale.
4Approvazioni multi-parte (aggiornamento Google agosto 2024)
A partire da agosto 2024, Google ha introdotto approvazione multipartitica per determinate azioni amministrative di alto privilegio in Google Workspace. A seconda della tua edizione di Workspace (Business Standard, Enterprise, ecc.) e delle impostazioni di sicurezza della tua organizzazione, l'autorizzazione di un nuovo ID client per la delega a livello di dominio potrebbe ora richiedere la conferma dell'azione da parte di un secondo Super Amministratore prima che diventi effettiva.
Ciò significa che il percorso "ottenere un amministratore che autorizzi DWD" non è più garantito per funzionare in un unico passaggio per tutte le organizzazioni. Controlla le policy di amministrazione di Workspace della tua organizzazione e Blog di aggiornamenti di Google Workspace per i requisiti più recenti prima di iniziare il processo di configurazione con il team IT di un cliente.
Quando NON usare account di servizio + DWD (il problema del SaaS multi-tenant)
Questa sezione è quella che la maggior parte delle guide salta. La delega "domain-wide" dell'account di servizio dell'API Gmail è uno strumento potente ma limitato. Se uno qualsiasi di questi scenari descrive la tua situazione, il DWD non funzionerà affatto o creerà un sovraccarico operativo che supera il beneficio. Scegliere il DWD in questi casi è un errore comune e costoso.
Prodotto B2C o PLG che serve gli utenti @gmail.com
Se il tuo prodotto ha un flusso di registrazione self-service e i tuoi utenti includono persone con un profilo personale account @gmail.com, DWD è architettonicamente incompatibile con il tuo caso d'uso. DWD non può impersonare account @gmail.com, punto. Hai bisogno di un'autorizzazione standard OAuth lato utente per ogni utente che si registra, indipendentemente dal fatto che disponga anche di un account Workspace.
SaaS multi-tenant con clienti su diversi domini Workspace
Se ciascuno dei tuoi clienti fosse un'azienda diversa con il proprio dominio Google Workspace, avresti bisogno di un separare l'autorizzazione DWD da un Super Admin in ogni singola organizzazione cliente. Questo non è scalabile. L'amministratore IT di ciascun cliente deve seguire autonomamente il processo di configurazione in 5 passaggi. L'autorizzazione standard OAuth lato utente, o una soluzione OAuth gestita, è molto più adatta per prodotti multi-tenant in cui gli utenti provengono da molte organizzazioni diverse.
Nessun accesso a un Super Admin di Google Workspace
DWD richiede un Super Admin di Google Workspace per autorizzare l'ID client del tuo account di servizio nella Console di amministrazione. Se gli utenti di destinazione o la tua stessa organizzazione non hanno un Super Admin disponibile, o se il processo di approvazione IT richiede settimane o mesi, DWD bloccherà la tua intera strategia di go-to-market. Questo è comune nei settori regolamentati, nelle grandi imprese e nelle organizzazioni con processi di gestione del cambiamento rigorosi.
Tempi di commercializzazione brevi, nessun budget CASA ancora
Se sei pre-product-market-fit e hai bisogno dell'integrazione con Gmail correre in giorni anziché in settimane, La tempistica combinata di: (1) creazione di un progetto Google Cloud, (2) attesa della propagazione di Admin Console, (3) passaggio alla verifica dell'app OAuth di Google per ambiti sensibili e (4) pianificazione di CASA Tier 2 per ambiti ristretti, è proibitiva. Solo la danza amministrativa può richiedere più tempo del tuo sprint. Un provider OAuth gestito che ha già superato queste revisioni è una scelta ingegneristica legittima, non solo una scorciatoia.
Salta le procedure burocratiche
Unipile fornisce OAuth ospitato per Gmail, Outlook e IMAP. Certificato CASA Tier 2. Nessuna configurazione DWD, nessuna Console di Amministrazione. Funziona sia per gli utenti @gmail.com che per gli utenti Workspace.
L'alternativa gestita: OAuth ospitato con Unipile
Se la tua situazione ti rende delegazione a livello di dominio del servizio account API Gmail la scelta sbagliata - o se semplicemente si vuole evitare la configurazione in 5 passaggi, la valutazione CASA e il rinnovo annuale - esiste un'alternativa ingegneristica legittima. Unipile agisce come intermediario tecnico indipendente, gestendo il flusso OAuth per conto di ciascun utente autenticato. Questa non è una soluzione alternativa per la revisione della sicurezza di Google. Unipile ha completato la certificazione CASA Tier 2 e opera secondo il framework approvato da Google.
CASA certificato di livello 2
Unipile ha superato la Valutazione della Sicurezza delle Applicazioni Cloud di Google al Livello 2. I tuoi account collegati accedono a Gmail tramite una piattaforma già verificata - nessuna valutazione da parte tua.
Per conto di ciascun utente
Ogni chiamata API che Unipile effettua a Gmail avviene per conto di ciascun utente autenticato individualmente, utilizzando il proprio token OAuth. Nessuna credenziale condivisa, nessuna impersonificazione a livello di dominio richiesta.
API unificata e singola
Un'unica API per Gmail, Outlook e IMAP. Cambia provider o aggiungi nuovi account collegati senza modificare il tuo codice di integrazione.
Gmail
Prospettiva
IMAP
import richieste
# Unipile gestisce il flusso OAuth per ogni account collegato
#: non è necessario alcun account di servizio, né DWD, né la configurazione della console di amministrazione
intestazioni = {
"X-API-KEY": "LA_TUA_CHIAVE_API_UNIPILE",
"accettare": "application/json"
}
#: Elenco delle e-mail da un account Gmail o Outlook collegato
response = richieste.ottenere(
"https://api.unipile.com/api/v1/emails",
intestazioni=intestazioni,
parametri={"account_id": "acc_user_gmail_123"}
)
print(response.json())Servizio account e FAQ DWD di Gmail API
Domande comuni sulla delega a livello di dominio di account di servizio dell'API Gmail, ambiti, limiti e quando scegliere un'alternativa gestita.
A Account di servizio Gmail è un'identità speciale di Google Cloud (non un utente umano) che si autentica all'API di Gmail utilizzando una chiave JSON privata anziché OAuth interattivo. Se combinato con delega a livello di dominio, consente a un'applicazione lato server di accedere a Gmail per conto di qualsiasi utente di un'organizzazione Google Workspace, senza che l'utente debba autorizzare manualmente l'app. È progettato per l'accesso automatizzato da server a server in ambienti aziendali.
A Account di servizio API Gmail + DWD utilizza l'autenticazione JWT server-to-server e può impersonare silenziosamente qualsiasi utente di Workspace, senza alcun flusso di consenso per utente. Lato utente standard OAuth richiede a ciascun utente di passare attraverso una schermata di consenso interattiva, ma funziona per qualsiasi utente Gmail, inclusi gli account personali @gmail.com. I service account sono adatti per gli strumenti interni aziendali; OAuth lato utente è adatto per i prodotti SaaS con basi di utenti diverse. Per un confronto completo, inclusa l'opzione gestita, vedere tabella comparativa sopra.
Scopri di più su Pagina prodotto API Gmail di Unipile.No. Questo è il limite più critico del servizio API di Gmail con delega a livello di dominio per account di servizio. Gli indirizzi personali @gmail.com non fanno parte di un dominio Workspace gestito, quindi non vi è alcun amministratore per autorizzare la delega DWD. Tentare di impersonare un utente @gmail.com restituirà un errore di autenticazione. Se il tuo prodotto serve utenti con account @gmail.com, devi utilizzare l'autorizzazione standard OAuth lato utente o un provider gestito come Unipile che gestisce OAuth sia per gli utenti @gmail.com che per gli utenti Workspace.
Nella Console di amministrazione di Google Workspace (richiede i privilegi di Super amministratore), naviga su: Menu > Sicurezza > Controllo accessi e dati > Controlli API > Delega a livello di dominio > Gestisci delega a livello di dominio > Aggiungi nuovo. Inserisci l'ID client numerico del tuo account di servizio e l'elenco degli ambiti OAuth separati da virgole. Salva e attendi fino a 60 minuti per la propagazione. Per la procedura completa, vedi la guida all'installazione in questo articolo. Riferimento: Guida di Google Admin: delega a livello di dominio.
delega a livello di dominio è non deprecato a partire dal 2026, ma è più restrittivo. Google ha introdotto l'approvazione multipartitica per determinate azioni di amministrazione ad alto privilegio nell'agosto 2024, che potrebbero richiedere un secondo Super Amministratore per approvare le autorizzazioni DWD. Inoltre, l'uso di ambiti Gmail restrittivi come https://mail.google.com/ ora richiede un CASA Livello 2 valutazione annuale della sicurezza. DWD rimane un modello valido per i casi d'uso di strumenti interni aziendali autentici, ma l'overhead di conformità è aumentato.
Gli ambiti richiesti dipendono da ciò che fa la tua app. Sola lettura: https://www.googleapis.com/auth/gmail.readonly (sensibile, necessita verifica Google). Invia email: https://www.googleapis.com/auth/gmail.send (sensibile). Accesso completo alla casella di posta: https://mail.google.com/ (limitato, richiede valutazione CASA di Livello 2). Solo metadati: https://www.googleapis.com/auth/gmail.metadata (base, nessuna revisione). Devi includere tutti gli ambiti richiesti nella voce DWD della Console di amministrazione. Vedi la tabella a scopo completo in questa guida.
Hai ancora domande sulla delega a livello di dominio del service account dell'API di Gmail? Il nostro team può aiutarti a scegliere l'architettura giusta per il tuo caso d'uso.
Parla con un esperto
IT 
EN 
FR 
ES 
DE 
BR 
NL 
PL 
TR