Impersonare gli utenti di Workspace all’interno di Apps Script può sembrare un’esigenza bizzarra. Apps Script è uno strumento molto potente, che permette di interagire con i servizi di Google Workspace programmando funzionalità aggiuntive o personalizzate rispetto a quanto già presente di default nella piattaforma. Spesso abbiamo utilizzato linee di codice per coadiuvare il lavoro di admin, automatizzando procedure meccaniche, o implementando funzionalità che agevolano gli utenti finali, specie se meno esperti.
Le operazioni eseguibili da script si basano sulle API di Google: interfacce che permettono di intervenire sui servizi di Google da codice, anziché da interfaccia grafica. Per alcune operazioni è sufficiente utilizzare un account di superadmin, e si potrà intervenire sui dati degli utenti della piattaforma. È il caso ad esempio dei fogli di lavoro per la creazione e gestione degli utenti (caricamento collettivo degli utenti, ricerca ed eliminazione di alias, elenco di utenti che non hanno eseguito l’accesso, per nominarne solo alcuni).
Per altri tipi di operazioni, invece, anche agendo da account superadmin non sarà permesso modificare alcuni dati degli utenti: è il caso ad esempio dell’aggiunta di un calendario condiviso tra i calendari visualizzati dall’utente. In questo tipo di operazioni (e sono molte più di quanto si possa pensare) nemmeno l’admin può intervenire direttamente. Solo l’utente interessato ha il permesso di eseguire tali operazioni. Non è quindi possibile intervenire da script nel modo tradizionale.
Questa guida non riveste particolare importanza presa per sé. Diventa utile come supporto a tutte quelle procedure in cui è necessario creare un account di servizio e concedergli la delega a livello di dominio, come illustrato di seguito. Fai riferimento a questa guida quando, all’interno di una procedura descritta nel blog, vengono richiesti questi due passaggi come operazioni preliminari per il funzionamento di uno script.
Impersonare utenti in Apps Script
Per poter agire in questi contesti, è necessario che lo script ‘impersoni’ l’utente finale, cioè agisca per suo conto. Solo a questa condizione potranno essere eseguite le operazioni accennate sopra. Workspace mette a disposizione uno strumento per raggiungere questo scopo, che si compone di due passaggi complementari.
Prima di tutto è necessario creare un account di servizio (service account nella nomenclatura delle guide). Questo non è un account solito, creato da console di amministrazione come gli utenti ordinari. Viene creato con una procedura particolare, illustrata sotto. Nessuno usa mai direttamente questo tipo di account. Solo gli script (o le app esterne, ma non è il nostro caso) utilizzano un account di servizio come se fosse un account utente. L’admin concede a questo account permessi e limitazioni funzionali agli scopi dello script. Deve poter eseguire tutto quanto richiesto dall’app. E al tempo stesso non deve avere permessi eccessivi, per non esporre l’app a potenziali problemi di sicurezza.
In secondo luogo, l’admin deve concedere all’account di servizio una delega di autorità a livello di dominio (domain-wide authority delegation). Questa seconda caratteristica permetterà all’account di servizio di impersonare tutti gli utenti di Workspace. E di poter quindi eseguire quelle operazioni altrimenti precluse anche all’admin negli script. Chiaramente non sempre questo secondo passaggio è necessario: ci sono script che usano account di servizio senza dover impersonare gli utenti finali. Per gli scopi di questa guida è invece una condizione necessaria.
Tutte le indicazioni riguardanti questi due passaggi si trovano nella guida di Google Workspace: https://developers.google.com/admin-sdk/directory/v1/guides/delegation. Non esiste ancora versione italiana della guida; consiglio di non utilizzare un servizio di traduzione per consultarla, su alcuni termini tecnici rischierebbe di creare maggiore confusione.
Sicurezza e protezione della piattaforma
Prima di procedere, è bene comprendere la posta in gioco a livello di sicurezza della piattaforma. L’account di servizio di cui parliamo viene utilizzato con credenziali speciali – non la solita accoppiata di username e password. Chi utilizza questo account, infatti, ha accesso ad aree molto delicate della piattaforma – potenzialmente tutte, anche se di fatto gli ambiti di lavoro saranno limitati dall’admin, come detto sopra. Se un estraneo dovesse venire in possesso delle credenziali, potrebbe produrre danni enormi.
Le credenziali dell’account di servizio sono molto più articolate del consueto. Ma questo non basta a renderle sicure. La cura dell’utente – noi admin – nella conservazione di queste credenziali deve essere massima. Questo significa certo conservarle in un luogo sicuro (no computer condivisi, no cartelle facilmente accessibili, ecc.). Oltre a questo, va fatta particolare attenzione agli script in cui queste credenziali vengono utilizzate. Come vedremo, dovremo inserire queste credenziali in ogni script che dovrà utilizzare l’account di servizio. Diventa quindi indispensabile proteggere anche l’accesso a tali script, dai quali le credenziali sarebbero facilmente ricavabili.
Al netto di queste considerazioni, l’utilizzo dell’account di servizio è un’operazione non solo molto utile, ma che se correttamente implementata aumenta la sicurezza del sistema. Lo stesso potenziale di intervento affidato ad una semplice coppia username-password sarebbe molto più vulnerabile. Come per le nostre password, però, dobbiamo avere la massima cura per proteggere adeguatamente l’accesso a questi dati più che sensibili.
Creare l’account di servizio
Vediamo nel dettaglio il primo passaggio: la creazione dell’account di servizio, e la generazione (e conservazione) delle sue credenziali. Quanto descritto qui traduce ed articola con maggiore dettaglio quanto indicato nella prima parte della guida di Google citata sopra.
- Apri la pagina degli account di servizio e scegli Crea progetto (se creato in precedenza, puoi selezionare un progetto esistente). Nella schermata successiva dai un nome al progetto, scegli come organizzazione il dominio principale, e lascia invariata la località, quindi scegli Crea. Verifica poi che risulti selezionato in alto a sinistra il progetto appena creato, altrimenti sceglilo dal menu a tendina:
- Clicca in alto su Crea account di servizio. Nella schermata successiva:
- assegna un nome all’account e scegli Crea e continua
- alla sezione Concedi a questo account di servizio l’accesso al progetto non inserire nessun ruolo e continua
- alla sezione Concedi agli utenti l’accesso a questo account di servizio inserisci in entrambi i campi l’indirizzo email di admin (è l’account che creerà ed eseguirà gli script che utilizzeranno l’account di servizio), quindi clicca su Fine
- Scegli ora l’account di servizio cliccando sul suo nome in elenco:
- Clicca in alto sulla scheda Chiavi, quindi scegli Aggiungi chiave, poi Crea una nuova chiave. Seleziona poi il formato JSON.
Viene quindi scaricato un file in formato JSON contenente le chiavi che serviranno per utilizzare l’account. Scegli Chiudi, quindi salva il file in modo sicuro. Nessuno deve accedere a quel file tranne te. Non perdere le credenziali, perché non sarà possibile scaricarle nuovamente. Se smarrite, dovrai eliminare le credenziali precedenti, rigenerarne di nuove e modificarle in tutti gli script dove le avrai utilizzate.
Ora l’account di servizio è creato, e le credenziali pronte per essere utilizzate. Per il nostro scopo, manca però ancora un passaggio fondamentale: concedere la delega di autorità a livello di dominio.
Delega di autorità a livello di dominio
Per poter impersonare gli utenti di Workspace in Apps Script, l’account di servizio deve ottenere la domain-wide authority delegation. Maggiori informazioni su questa caratteristica si trovano a questa pagina della guida per admin: https://support.google.com/a/answer/162106.
Per concedere la delega di autorità procedi così:
- Da console di amministrazione vai in Sicurezza > Controlli API
- Nella sezione Delega a livello di dominio scegli Gestisci delega a livello di dominio, quindi clicca su Aggiungi nuovo
- Si apre una nuova scheda: inserisci l’ID client. Lo trovi nel file JSON ottenuto al termine della creazione dell’account di servizio: è il valore della variabile client_id
- Inserisci quindi gli ambiti OAuth richiesti dalla tua applicazione/script; questo valore non è fisso, dipende dallo script che utilizzerai (se si trova su questo blog, nelle istruzioni vengono indicati gli ambiti da inserire qui). Se occorre specificare più di un ambito OAuth, puoi inserirli tutti insieme, separati da virgola. A titolo esemplificativo, puoi inserire questi due valori, che permettono all’account di agire su utenti e gruppi:
https://www.googleapis.com/auth/admin.directory.user, https://www.googleapis.com/auth/admin.directory.group
quindi clicca su Autorizza - Potrai tornare su questi valori ed aggiungere/rimuovere gli ambiti in base alle esigenze dello script che utilizzerai; è sufficiente tornare in questa schermata, e passando il mouse sulla riga dell’account scegli in fondo Modifica
Utilizzare l’account di servizio
Hai scaricato e conservato le credenziali in luogo sicuro. Hai concesso la delega di autorità a livello di dominio. Ora l’account è pronto per essere utilizzato negli script che lo richiedono.
A seconda del tipo di script che lo impiega, serviranno dati leggermente diversi, ma sostanzialmente dovrai compiere a due operazioni:
- apri lo script e copia, nelle variabili opportune, alcuni dati estratti dal file JSON: tipicamente si tratta di client_email e private_key
- ricava dallo script – o dalle istruzioni che lo illustrano – gli ambiti OAuth necessari al funzionamento di quello script; quindi da console di amministrazione in Sicurezza > Controllo API > Gestisci delega a livello di dominio, apri l’account di servizio e controlla gli ambiti OAuth: aggiungi quelli richiesti dallo script, se non già presenti, e salva
L’effettivo funzionamento di tutto il meccanismo potrebbe richiedere – dall’ultima autorizzazione dei nuovi ambiti OAuth – da qualche minuto a qualche ora. Se si presentano problemi nell’esecuzione dello script, attendi qualche ora – fino a 24 – e riprova. Se i problemi persistono, occorrerà cercare una diagnosi e soluzione adeguata.
