Guida per l'amministratore Google Workspace

1. Riassunto

La problematica. Altamira deve creare e gestire automaticamente riunioni Google Meet per conto dell'azienda: lezioni a distanza (aula virtuale), meeting collegati ad attività, con generazione del link Meet, configurazione della stanza e — a riunione conclusa — recupero del report delle presenze. Tutte queste operazioni, lato Google, non sono azioni "di sistema": sono azioni di un utente (un organizzatore con calendario e licenza Meet). Un'applicazione server come Altamira non possiede un'identità Google con calendario e Meet, quindi deve poter agire per conto di un utente reale.

Cosa richiede Altamira. Per la cosiddetta modalità applicativa Altamira richiede:

• un service account Google con domain-wide delegation (DWD) abilitata;
• l'autorizzazione, nella Admin Console, di 4 scope OAuth specifici;
• un utente organizzatore reale del Workspace, di cui il service account assume l'identità per creare gli eventi.

Perché lo fa così. Le alternative sono due: (a) far autorizzare ogni utente via OAuth interattivo (modalità delegata), oppure (b) usare un service account che impersona un organizzatore aziendale (modalità applicativa). La modalità applicativa è stata scelta perché è centralizzata e senza manutenzione del token: non richiede consensi interattivi né refresh token da custodire e rinnovare, ed è l'unica che consente di risolvere le email dei partecipanti dalla rubrica (necessario per un report presenze completo).

Come viene risolta. Il service account non agisce mai "come sé stesso" (un service account non ha calendario né Meet): tramite la DWD impersona un singolo utente organizzatore configurato in Altamira, e su quel contesto crea l'evento Calendar con link Meet, configura la stanza e legge le presenze.

2. Le due modalità a confronto

Altamira supporta entrambe; sceglie automaticamente quella configurata (con precedenza alla modalità applicativa).

3. Cosa va creato e configurato

3.1 Service account (Google Cloud Console)

1. In un progetto GCP (consigliato dedicato), abilita le API: Google Calendar API, Google Meet API, Admin SDK API.
2. Crea un service account dedicato a questa integrazione. Non servono ruoli IAM di progetto: i permessi arrivano dalla delega Workspace, non da IAM.
3. Genera una chiave JSON del service account: è il valore che andrà inserito in Altamira (che lo conserva cifrato).
4. Abilita sul service account "Enable Google Workspace Domain-wide Delegation" e annota il Client ID numerico.

3.2 Autorizzazione in Admin Console (Workspace)

In admin.google.com → Security → Access and data control → API controls → Domain-wide delegation → Add new:

• Client ID: quello numerico del punto 3.1.4;
• OAuth scopes: i quattro elencati nella tabella sotto.

3.3 Utente organizzatore

Serve l'email di un utente reale e attivo del Workspace (non alias, non gruppo), con licenza adeguata a Calendar/Meet. Sarà l'organizzatore di tutti gli eventi creati da Altamira.

3.4 Configurazione in Altamira

Vanno valorizzati il JSON del service account e l'email dell'organizer; inoltre deve essere attivo il relativo feature flag aziendale. Solo con tutti e tre gli elementi presenti, Altamira attiva la modalità applicativa.

4. API e scope richiesti (e a cosa servono)

Nota tecnica: Altamira usa due credenziali distinte (una per Calendar, una per Meet+Directory) perché Google non consente di combinare lo scope Calendar con quelli Meet sotto DWD. Vanno quindi autorizzati tutti e quattro gli scope.

Comportamento sulla stanza: ogni meeting viene impostato come aperto all'accesso esterno (accessType=OPEN, entryPointAccess=ALL) con moderazione attiva (moderation=ON). Questo permette la partecipazione di utenti esterni al dominio: va valutato se compatibile con le vostre policy.

5. Sicurezza: cosa si può limitare e cosa no

Questo è il punto più importante per la decisione dell'amministratore.

La DWD è, per definizione, a livello di dominio. Una volta autorizzato il Client ID per uno scope, il service account può tecnicamente impersonare qualunque utente del dominio entro quegli scope. Non esiste una funzione nativa per limitare la DWD a utenti specifici.

Il vincolo "agisce solo sull'organizer" è applicativo, non imposto da Google. Altamira impersona sempre e solo l'organizer configurato. Ma questo limite vive nel codice: chi entrasse in possesso della chiave JSON bypasserebbe Altamira e potrebbe impersonare chiunque, entro gli scope concessi.

Cosa puoi effettivamente fare per ridurre il rischio:

• Minimizzare gli scope — autorizza solo i quattro necessari. Se il report presenze con email non è indispensabile, valuta di omettere admin.directory.user.readonly (lo scope più sensibile): perderai la risoluzione delle email dei partecipanti, ma riduci molto l'esposizione.
• Service account dedicato — usato esclusivamente per questa integrazione, così il raggio d'azione è limitato a questi scope.
• Proteggere la chiave JSON — è l'anello debole. Rotazione periodica, nessun salvataggio in chiaro (Altamira la cifra), idealmente org-policy che limita la creazione di chiavi scaricabili.
• Organizer con privilegi minimi — un utente dedicato con la sola licenza Meet/Calendar necessaria, mai un super admin.
• Audit — negli audit log di Workspace il soggetto impersonato è tracciato: monitora che corrisponda sempre all'organizer atteso.

Se la restrizione per-utente è un requisito non negoziabile: l'unica via che la garantisce lato Google è non usare la DWD e adottare la modalità delegata (consenso OAuth del singolo account). In quel caso il token è legato a quell'unico utente; lo svantaggio è la gestione del token e la perdita della lettura rubrica (quindi report presenze incompleto).

6. Come decidere

7. Checklist di attivazione

• [ ] Progetto GCP con Calendar API, Meet API, Admin SDK API abilitate
• [ ] Service account dedicato creato, con DWD abilitata e Client ID annotato
• [ ] Chiave JSON generata e gestita in modo sicuro
• [ ] Scope autorizzati in Admin Console (4, o 3 senza Directory se si rinuncia alle email nelle presenze)
• [ ] Utente organizzatore reale, attivo, con licenza Meet/Calendar e privilegi minimi
• [ ] Policy verificate: partecipanti esterni alla stanza, lettura rubrica
• [ ] Valori inseriti in Altamira (JSON + email organizer) e feature flag attivo
• [ ] Test end-to-end: creazione meeting → link Meet → accesso → report presenze
• [ ] Piano di rotazione chiave e monitoraggio audit log