# Google Workspace: collegare le caselle

Perché l’assistente possa leggere la posta in Google Workspace e creare lì le
bozze, gli serve l’accesso tramite la Gmail API. Ci sono due strade ed entrambe
si basano su ciò che l’organizzazione crea 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.

Supportiamo **Google Workspace**. Gli account personali `@gmail.com` non sono
supportati: non si può accedere a draften con essi e collegarli richiederebbe
che l’app venisse verificata da Google.

## Quale strada scegliere

| | Per tutta l’organizzazione | Con l’account della casella |
|---|---|---|
| In draften | una registrazione (account di servizio) in Organizzazione → **Integrazioni** | il pulsante **Collega Gmail** accanto alla casella |
| In Google | un account di servizio con una chiave e la domain-wide delegation | un client OAuth e una schermata di consenso di tipo Internal |
| Chi lo crea | un amministratore di Google Cloud e un super amministratore di Google Admin | un amministratore di Google Cloud |
| Chi deve accedere | nessuno | il proprietario di ogni casella, una volta |
| Quali caselle raggiunge | tutte le caselle del dominio | solo la casella con il cui account si è effettuato l’accesso |
| Accesso a draften con l’account Google | no, è una cosa separata | lo stesso client OAuth serve anche per l’accesso |

Per un’organizzazione con più caselle la strada più semplice è quella **per tutta
l’organizzazione**. **Con l’account della casella** conviene quando non vuoi
dare a una sola chiave l’accesso a tutte le caselle del dominio, o quando
introduci comunque l’accesso con l’account Google.

Puoi avere entrambe le strade insieme; ogni casella ne usa una. draften chiede
solo l’ambito `gmail.modify` – lettura e creazione di bozze, non invia nulla.

## Strada A: per tutta l’organizzazione

### In Google Cloud

Lavori in https://console.cloud.google.com, nell’organizzazione del tuo dominio
Workspace.

1. Scegli un progetto, o creane uno nuovo (per esempio `draften`).
2. **APIs & Services** → **Library** → **Gmail API** → **Enable**.
3. **IAM & Admin** → **Service accounts** → **Create service account**. Un nome,
   per esempio `draften-posta`. Non gli servono ruoli nel progetto – l’accesso
   alla posta glielo dà solo la delega in Google Admin. Fai clic su **Done**.
4. Apri l’account di servizio e annota il suo **Unique ID** – il Client ID
   numerico.
5. Scheda **Keys** → **Add key** → **Create new key** → **JSON** →
   **Create**. Viene scaricato un file con la chiave.

!> Se Google rifiuta di creare la chiave, la tua organizzazione ha attiva la
policy `iam.disableServiceAccountKeyCreation` (le nuove organizzazioni la hanno
per impostazione predefinita). Per questo progetto la disattiva un amministratore
dell’organizzazione in **IAM & Admin** → **Organization policies**.

### In Google Admin

Ti serve un super amministratore. In https://admin.google.com apri
**Security** → **Access and data control** → **API controls** → **Manage
Domain Wide Delegation** → **Add new**. **Client ID**: l’ID numerico del passo 4.
**OAuth scopes**: `https://www.googleapis.com/auth/gmail.modify`. Fai clic su
**Authorize**. Di solito la delega entra in vigore in pochi minuti, in rari casi
dopo diverse ore.

### In draften

1. Apri Organizzazione → **Integrazioni**, il riquadro **Accesso alla posta per
   tutta l’organizzazione**. Le registrazioni le gestiscono il proprietario o un
   gestore dell’organizzazione.
2. **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.
3. Nella pagina di ogni casella, nel riquadro **Accesso alla posta**, scegli in
   **Usa** 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](/it/admin/adding-a-mailbox).

**Poi elimina il file della chiave scaricato.** Chi lo ha entra in ogni casella
del dominio. Una nuova chiave dello stesso account di servizio la carichi nella
registrazione con **nuova chiave (JSON)**; la chiave di un altro account di
servizio aggiungila come nuova registrazione. Elimina la vecchia chiave in Google
Cloud.

Con la **casella automatica** attiva ([Come accedono i
membri](/it/admin/member-sign-in)) una nuova casella si lega da sola alla
registrazione, quando per Google Workspace ce n’è esattamente una attiva.

## Strada B: con l’account della casella (Collega Gmail)

Qui il proprietario della casella accede con il suo account Google e concede
l’accesso solo alla propria posta. Lo stesso client OAuth serve anche per
l’**accesso a draften con l’account Google**.

### In Google Cloud

1. In draften apri prima Organizzazione → **Come accedono i membri**, il riquadro
   **Accesso con account e collegamento delle caselle**. Mostra due **Redirect
   URI** esatti per il tuo indirizzo di draften – terminano con
   `/auth/google/callback` e `/mailboxes/connect/google/callback`. Copiali da lì;
   devono corrispondere carattere per carattere.
2. Nel progetto con la **Gmail API** attivata (passo 2 della strada A) apri **APIs
   & Services** → **OAuth consent screen**. **User type**: **Internal** –
   potrà accedere solo un account del tuo dominio e l’app non deve essere
   verificata da Google. Compila il nome dell’app (per esempio `draften`) e
   un’email di contatto.
3. Nella parte degli ambiti (**Scopes** / **Data access**) aggiungi `openid`,
   `email`, `profile` e `https://www.googleapis.com/auth/gmail.modify`.
4. **APIs & Services** → **Credentials** → **Create credentials** → **OAuth
   client ID**. **Application type**: **Web application**. In **Authorized
   redirect URIs** inserisci entrambi gli indirizzi del riquadro e fai clic su
   **Create**.
5. Copia il **Client ID** e il **Client secret**.

### In draften

1. Il **proprietario dell’organizzazione**, nel riquadro **Accesso con account
   e collegamento delle caselle**, compila in **Client OAuth di Google** i valori
   **Client ID** e **Client secret** e fa clic su **Salva**.
2. Il **proprietario della casella** apre la pagina della casella e nel riquadro
   **Accesso alla posta** 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 OAuth.
3. Poi **Testa la connessione**.

L’**accesso con l’account Google** lo attivi nella stessa pagina: in **Domini
email dell’organizzazione** scrivi il tuo dominio Workspace – quello principale,
non un alias (quello Google non lo invia all’accesso). Appena l’organizzazione ha
sia il client OAuth sia il dominio, i membri accedono con l’account Google e le
loro password smettono di funzionare – vedi
[Come accedono i membri](/it/admin/member-sign-in).

### 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 strada A.
- **“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.

## 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 (passo 2) |
| 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](/it/admin/troubleshooting).