Perché l’assistente possa leggere la posta in Google Workspace e creare lì le bozze, gli serve l’accesso tramite la Gmail API. Per questo l’organizzazione crea qualcosa nel proprio Google Cloud; draften non ha un’app comune a cui basta dare il consenso. Vale per il nostro servizio come per un’installazione sul tuo server.
Tutto ciò che segue vale solo per gli account Google Workspace con un dominio proprio. Con un account personale @gmail.com non si può accedere a draften; un Gmail personale lo colleghi però tramite IMAP con una password per le app – vedi Provider supportati e limiti.
Che cosa vuoi e che cosa configurare
| Che cosa vuoi | Che cosa configurare |
|---|---|
| I membri accedono con l’account Google e ognuno ha la propria casella | il client dell’organizzazione – basta questo |
| In più caselle a cui nessuno accede (per esempio info@), o l’accesso alle caselle impostato centralmente, senza i loro proprietari | in più la registrazione dell’organizzazione (account di servizio) |
| Non vuoi l’accesso con l’account Google | le persone accedono con la password dall’invito, la posta la collega la registrazione dell’organizzazione (oppure IMAP) |
Due cose diverse in Google
Il client dell’organizzazione e la registrazione dell’organizzazione sono due cose separate in Google Cloud. Ognuna fa una cosa diversa e nessuna delle due sostituisce l’altra:
| Client dell’organizzazione | Registrazione dell’organizzazione | |
|---|---|---|
| Che cos’è | un client OAuth con una schermata di consenso di tipo Internal | un account di servizio con una chiave e la domain-wide delegation |
| Che cosa fa | l’accesso dei membri con il pulsante Accedi con Google e il pulsante Collega Gmail accanto alla propria casella | l’accesso dell’assistente alle caselle senza che i loro proprietari accedano |
| Dove in draften | Organizzazione → Login e accesso alla posta → riquadro Accesso con account e collegamento delle caselle | Organizzazione → Login e accesso alla posta → riquadro Registrazioni per caselle condivise e gestione centrale |
| Chi se ne occupa in draften | il proprietario dell’organizzazione | il proprietario o un gestore dell’organizzazione |
| Chi lo crea in Google | un amministratore di Google Cloud | un amministratore di Google Cloud e un super amministratore di Google Admin |
| Chi deve accedere alla casella | il proprietario di ogni casella, una volta | nessuno |
| Quali caselle raggiunge | solo quelle che le persone collegano da sé | tutte le caselle del dominio |
Sono due cose di proposito. Il consenso al client dà diritti solo sulle caselle che le persone collegano da sé – mai sulla posta di tutto il dominio. L’account di servizio invece raggiunge ogni casella del dominio, e per questo draften lo riceve solo per l’accesso alle caselle, non per l’accesso dei membri. Non unirli.
Ogni casella usa uno dei due modi; puoi averli entrambi insieme. draften chiede solo l’ambito gmail.modify – lettura e creazione di bozze, non invia nulla.
Client dell’organizzazione: accesso e Collega Gmail
Il proprietario della casella accede con il suo account Google e concede l’accesso solo alla propria posta. Lo stesso client serve anche per l’accesso a draften con l’account Google.
In Google Cloud
Lavori in https://console.cloud.google.com, con l’account di amministratore del tuo dominio Workspace. Tutto avviene in un solo progetto – il progetto selezionato si vede in alto a sinistra accanto al logo di Google Cloud; lì puoi anche cambiarlo o crearne uno nuovo. Il menu principale lo apri con l’icona ☰ in alto a sinistra.
- In draften apri prima Organizzazione → Login e accesso alla posta, il riquadro Accesso con account e collegamento delle caselle. Mostra due Redirect URI esatti per il tuo indirizzo di draften – terminano con
/auth/google/callbacke/mailboxes/connect/google/callback. Copiali da lì; devono corrispondere carattere per carattere. - Scegli un progetto, o creane uno nuovo (per esempio
draften), e attiva lì la Gmail API: ☰ → APIs & Services → Library, cerca Gmail API, aprila e fai clic su Enable. Direttamente: https://console.cloud.google.com/apis/library/gmail.googleapis.com - Imposta come l’app si presenta agli utenti (consent screen): ☰ → APIs & Services → OAuth consent screen. Si apre la pagina Google Auth Platform; direttamente: https://console.cloud.google.com/auth/overview (controlla che in alto sia selezionato il progetto giusto). Fai clic su Get started e segui la procedura guidata:
- App Information – App name
draftene User support email (la tua email o un gruppo di amministratori). Next. - Audience – scegli Internal. Potrà accedere solo un account del tuo dominio Workspace e l’app non deve essere verificata da Google. Next.
- Contact Information – l’email a cui Google ti invierà gli avvisi sull’app. Next.
- Finish – seleziona la casella di consenso alle norme di Google (I agree to the Google API Services: User Data Policy), fai clic su Continue e poi su Create.
- App Information – App name
- Consenti gli ambiti all’app. In Google Auth Platform, nel menu a sinistra, apri Data Access (direttamente: https://console.cloud.google.com/auth/scopes) → Add or remove scopes. Nell’elenco seleziona
openid,.../auth/userinfo.emaile.../auth/userinfo.profile. L’ambito per Gmail inseriscilo nel campo Manually add scopes:https://www.googleapis.com/auth/gmail.modify→ Add to table. Fai clic su Update e in basso su Save. - Crea il client. In Google Auth Platform, nel menu a sinistra, apri Clients (direttamente: https://console.cloud.google.com/auth/clients) → Create client. Application type: Web application, il nome per esempio
draften. In Authorized redirect URIs fai clic su Add URI e inserisci il primo indirizzo del riquadro, poi di nuovo Add URI e il secondo. Fai clic su Create. - Compaiono il Client ID e il Client secret – copiali subito entrambi. Il Client secret Google non lo mostrerà più; se lo perdi, ne crei uno nuovo nel client.
In draften
- Il proprietario dell’organizzazione apre Organizzazione → Login e accesso alla posta e nel riquadro Accesso con account e collegamento delle caselle compila in Client OAuth di Google i valori Client ID e Client secret del passo 6 e fa clic su Salva.
- L’accesso con l’account Google lo attiva nella stessa pagina, nel riquadro Come accedono i membri: in Domini email dell’organizzazione scrive il dominio Workspace – quello principale, non un alias (quello Google non lo invia all’accesso). Appena l’organizzazione ha sia il client sia il dominio, i membri accedono con l’account Google e le loro password smettono di funzionare – vedi Come accedono i membri.
- Il proprietario della casella apre la pagina della casella e nel riquadro Accesso alla posta, nella riga Collega con l’account della casella:, fa clic su Collega Gmail. Accede con l’account di quella casella – draften rifiuta un altro account – e concede l’accesso. Il pulsante lo vede solo il proprietario della casella, e solo se l’organizzazione ha il client; senza, il riquadro al posto del pulsante scrive che il collegamento con l’account sarà possibile quando il proprietario dell’organizzazione avrà aggiunto il client.
- Poi Testa la connessione.
Quando la casella si scollega
- L’account è stato eliminato o bloccato, o l’accesso è stato revocato – Google smette di rilasciare token e draften scollega la casella. Collegala di nuovo (Ricollega Gmail), oppure con la registrazione dell’organizzazione (qui sotto).
- “Il fornitore non ha rilasciato un refresh token” – il proprietario della casella rimuove l’app nelle impostazioni del suo account Google (Sicurezza → App e servizi di terze parti) e collega di nuovo la casella.
- “Ha effettuato l’accesso un account diverso dall’indirizzo della casella” – durante il collegamento scegli l’account proprio di quella casella.
Registrazione dell’organizzazione: accesso alla posta senza login
Un account di servizio con la domain-wide delegation dà all’assistente l’accesso alle caselle del dominio senza che nessuno debba accedere. È adatto alle caselle a cui nessuno accede (per esempio info@) e alle organizzazioni che vogliono gestire l’accesso centralmente. Con l’accesso a draften non ha nulla a che fare.
In Google Cloud
Lavori in https://console.cloud.google.com, nello stesso progetto in cui è attivata la Gmail API (passo 2 del client dell’organizzazione; senza il client attivala comunque). Controlla il progetto in alto a sinistra accanto al logo di Google Cloud.
- Apri l’elenco degli account di servizio: ☰ → IAM & Admin → Service accounts. Direttamente: https://console.cloud.google.com/iam-admin/serviceaccounts
- In alto fai clic su + Create service account e segui i tre passaggi:
- Service account details – Service account name per esempio
draften-posta(l’ID si compila da solo). Fai clic su Create and continue. - Permissions (optional) – non scegliere nulla; non gli servono ruoli nel progetto, l’accesso alla posta glielo dà solo la delega in Google Admin. Fai clic su Continue.
- Principals with access (optional) – non compilare nulla, fai clic su Done.
- Service account details – Service account name per esempio
- Nell’elenco fai clic sul nuovo account di servizio. Nella scheda Details copia l’Unique ID – un numero lungo; è il Client ID per Google Admin.
- Scheda Keys → Add key → Create new key → Key type: JSON → Create. Il browser scarica un file con la chiave (
….json).
Se Google rifiuta di creare la chiave, la tua organizzazione ha attiva la policy Disable service account key creation (iam.disableServiceAccountKeyCreation; le nuove organizzazioni la hanno per impostazione predefinita). Un amministratore dell’organizzazione la disattiva per questo progetto: ☰ → IAM & Admin → Organization policies (https://console.cloud.google.com/iam-admin/orgpolicies), cerca iam.disableServiceAccountKeyCreation → Manage policy → Override parent's policy → Enforcement: Off → Set policy. Poi ripeti il passo 4.
In Google Admin
Ti serve un account di super amministratore di Google Workspace.
- Apri https://admin.google.com → nel menu a sinistra Security → Access and data control → API controls → in basso Domain wide delegation → Manage domain wide delegation. Direttamente: https://admin.google.com/ac/owl/domainwidedelegation
- Fai clic su Add new e compila:
- Client ID – l’Unique ID numerico del passo 3,
- OAuth scopes (comma-delimited) –
https://www.googleapis.com/auth/gmail.modify.
Fai clic su Authorize. La delega compare nell’elenco. Di solito entra in vigore in pochi minuti, in rari casi dopo diverse ore.
In draften
- Apri Organizzazione → Login e accesso alla posta, il riquadro Registrazioni per caselle condivise e gestione centrale. Le registrazioni le gestiscono il proprietario o un gestore dell’organizzazione.
- Sistema: Google Workspace. Compila Nome, in Chiave dell’account di servizio (JSON) scegli il file scaricato e fai clic su Aggiungi registrazione. La chiave viene salvata cifrata; nel riquadro si vedono poi solo l’email dell’account di servizio e il suo Client ID.
- Nella pagina di ogni casella, nel riquadro Accesso alla posta, scegli in Registrazione dell’organizzazione questa registrazione, fai clic su Applica e poi su Testa la connessione. La procedura con le schermate la mostra la guida Aggiungere e collegare una casella.
Poi elimina il file della chiave scaricato. Chi lo ha entra in ogni casella del dominio. Una nuova chiave dello stesso account di servizio (passo 4 qui sopra) la carichi nella registrazione con nuova chiave (JSON); la chiave di un altro account di servizio aggiungila come nuova registrazione. Poi elimina la vecchia chiave in Google Cloud: account di servizio → scheda Keys → l’icona del cestino accanto alla vecchia chiave.
Con la casella automatica attiva (Come accedono i membri) una nuova casella si lega da sola alla registrazione, quando per Google Workspace ce n’è esattamente una attiva.
Errori del test della connessione
Il test verifica tre passaggi: Accesso, Token e autorizzazione e Lettura della Posta in arrivo.
| Nel messaggio | Che cosa significa | Che cosa fare |
|---|---|---|
la delega per l’ambito non è consentita (unauthorized_client) | in Google Admin manca la domain-wide delegation, o ha un altro Client ID o ambito | controllare la delega in Google Admin: l’ID numerico e l’ambito esatto gmail.modify |
invalid_grant con l’account di servizio | questa casella non esiste nel dominio Workspace | controllare l’indirizzo della casella |
| “Gmail API has not been used…” | nel progetto la Gmail API non è attivata | attivare la Gmail API |
token senza gmail.modify | la delega o la schermata di consenso non ha l’ambito gmail.modify | aggiungere l’ambito |
invalid_grant, deleted_client con un account collegato | il collegamento è stato revocato o il client OAuth eliminato | Ricollega Gmail |
Altri errori li descrive Risoluzione dei problemi.