1. Introduzione

Cyber Guru offre la possibilità di sincronizzare automaticamente gli utenti della vostra organizzazione direttamente da Google Workspace. Questa integrazione consente di mantenere aggiornata la lista degli utenti nella piattaforma Cyber Guru senza interventi manuali, riflettendo in tempo reale le modifiche effettuate nel vostro dominio Google.

Questa guida descrive, passo per passo, le operazioni da eseguire sul vostro account Google Workspace e i dati da comunicare al team Cyber Guru per completare la configurazione.

I servizi offerti dalla sincronizzazione sono Create, Update, Suspend (Delete).

I campi sincronizzati automaticamente sono :

1.1 Panoramica del processo

L’integrazione si basa su un Service Account Google autorizzato a leggere in sola lettura gli utenti del vostro dominio. Di seguito le fasi principali:

2. Prerequisiti

Prima di procedere, verificare di soddisfare i seguenti requisiti:

• Accesso come Super Admin (o Admin delegato con permessi su Account di servizio) alla Google Admin Console (admin.google.com)
• Accesso alla Google Cloud Console (console.cloud.google.com) con ruolo Proprietario o Editor sul progetto Google Cloud dell’organizzazione
• Un progetto Google Cloud già esistente associato al dominio Google Workspace (o la possibilità di crearne uno)
• Credenziali di accesso alla piattaforma Cyber Guru con ruolo amministratore

3. Configurazione su Google Cloud Console

3.1 Accesso alla Google Cloud Console

1. Aprire il browser e navigare su https://console.cloud.google.com
2. Effettuare il login con l’account amministratore dell’organizzazione
3. Dal menu in alto a sinistra, verificare di essere nel progetto Google Cloud corretto (es. il progetto associato al dominio aziendale)

3.2 Creazione del Service Account

Il Service Account è un’identità applicativa che Cyber Guru utilizza per autenticarsi verso le API di Google Workspace. Procedere come segue:

1. Dal menu laterale, selezionare IAM e amministrazione > Account di servizio
2. Fare clic su + CREA ACCOUNT DI SERVIZIO
3. Compilare il modulo con i seguenti valori:
   • Nome account di servizio: cyberguru-sync (o un nome a scelta)
   • ID account di servizio: verrà generato automaticamente in base al nome
   • Descrizione: Account di servizio per sincronizzazione utenti con Cyber Guru
4. Fare clic su CREA e CONTINUA
5. Nella sezione Concedi a questo account di servizio l’accesso al progetto, assegnare il ruolo Visualizzatore (Viewer) e fare clic su CONTINUA
6. Nella sezione Concedi agli utenti l’accesso a questo account di servizio, lasciare vuoto e fare clic su FINE

3.3 Abilitazione della Domain-Wide Delegation

Per consentire al Service Account di leggere gli utenti di tutto il dominio Google Workspace, è necessario abilitare la Domain-Wide Delegation (delega a livello di dominio).

1. Nella lista degli Account di servizio, fare clic sul Service Account appena creato
2. Selezionare la scheda Dettagli avanzati
3. Nella sezione Delega a livello di dominio, fare clic su Modifica e copia l’ID Cliente

3.4 Generazione della chiave JSON (google_private_key)

La chiave JSON contiene le credenziali crittografiche che Cyber Guru utilizza per autenticarsi. È l’elemento più sensibile dell’intera configurazione.

1. Aprire il Service Account creato
2. Selezionare la scheda CHIAVI
3. Fare clic su AGGIUNGI CHIAVE > Crea nuova chiave
4. Selezionare il formato JSON
5. Fare clic su CREA: il file JSON verrà scaricato automaticamente nel computer

4. Configurazione su Google Admin Console

4.1 Autorizzazione del Service Account (OAuth Scopes)

Nella Google Admin Console è necessario autorizzare il Service Account ad accedere alle API di Google Workspace tramite gli OAuth Scope appropriati.

1. Navigare su https://admin.google.com e accedere come Super Admin
2. Dal menu, selezionare Sicurezza > Accesso e controllo dei dati > Controlli API
3. Fare clic su Gestisci la delega a livello di dominio
4. Fare clic su Aggiungi nuovo
5. Nel campo Client ID, inserire il Client ID numerico del Service Account annotato in precedenza
6. Nel campo OAuth Scope, inserire i seguenti scope separati da virgola:

1. Fare clic su AUTORIZZA

4.2 Recupero del Customer ID (google_customer_id)

Il Customer ID identifica univocamente il vostro account Google Workspace.

1. Dalla Google Admin Console, navigare su Account > Impostazioni account
2. Nella sezione Informazioni sul profilo, trovare il campo ID cliente
3. Il valore ha il formato Cxxxxxxxx (es. C03abc1de)
4. Annotare questo valore: corrisponde al parametro google_customer_id

4.3 Recupero del Dominio (google_domain)

Il dominio primario del vostro Google Workspace è visibile nella Google Admin Console:

1. Dalla Google Admin Console, navigare su Account > Domini > Gestisci domini
2. Il dominio primario (contrassegnato come Principale) è il valore da comunicare
3. Es.: azienda.com. Corrisponde al parametro google_domain

4.4 Identificazione dell’Admin Email (google_admin_email)

Il Service Account deve impersonare un account amministratore per leggere gli utenti del dominio. Identificare un account con i seguenti requisiti:

• Deve essere un utente reale del dominio Google Workspace (non un alias)
• Deve avere il ruolo di Super Admin o Admin con permessi di sola lettura sulla directory
• Deve essere un account stabile, non soggetto a disattivazione o cambio email

Questo valore corrisponde al parametro google_admin_email da comunicare a Cyber Guru.

5. Parametri Avanzati

I seguenti tre parametri sono opzionali e riguardano funzionalità avanzate di personalizzazione. Configurarli solo se necessario, in accordo con il team Cyber Guru.

5.1 google_custom_schemas

Google Workspace consente agli amministratori di aggiungere attributi personalizzati agli utenti tramite Custom Schemas. Questi attributi non fanno parte del profilo utente standard e vengono definiti dall’amministratore per esigenze specifiche dell’organizzazione (es. reparto, sede, livello di rischio, etc.).

Il parametro google_custom_schemas indica a Cyber Guru quali schemi personalizzati leggere per ogni utente. Se la vostra organizzazione utilizza custom schemas e desiderate che Cyber Guru li acquisisca, procedere come segue:

1. Dalla Google Admin Console, navigare su Directory > Impostazioni personalizzate
2. Verificare quali schemi personalizzati sono definiti (es. HR_Data, Security_Attributes)
3. Per ogni schema di interesse, annotare il nome dello schema e i nomi dei campi da includere

Il valore da comunicare è un elenco di nomi di schema, ad esempio:

5.2 google_org_mapping

Il parametro google_org_mapping definisce come rinominare i campi dei Custom Schema di Google Workspace quando vengono sincronizzati come org in Cyber Guru.

Questa mappatura consente di standardizzare i nomi degli attributi personalizzati provenienti da Google, rendendoli coerenti con la nomenclatura utilizzata in Cyber Guru (es. reparto, sede, manager).

Formato

Esempio

Ogni riga contiene la coppia NomeCampoSchema; nome_destinazione:

I campi non inclusi nel mapping vengono comunque sincronizzati, mantenendo la struttura originale.

5.3 google_groups

Il parametro google_groups consente di limitare la sincronizzazione ai soli utenti appartenenti a uno o più gruppi Google Workspace specifici. Se non configurato, vengono sincronizzati tutti gli utenti del dominio.

Se la vostra organizzazione desidera sincronizzare solo un sottoinsieme di utenti basato sull'appartenenza a gruppi, procedere come segue:

1. Dalla Google Admin Console, navigare su Directory > Gruppi
2. Identificare i gruppi di interesse e annotare l’ID di ciascun gruppo

Come funziona: verranno sincronizzati solo gli utenti che risultano membri diretti di almeno uno dei gruppi indicati. Se un gruppo configurato non viene trovato in Google Workspace, la sincronizzazione per la company viene interrotta (comportamento fail-safe).

ℹ️ Quando configurare questo parametro Questo parametro è opzionale. Se desiderate sincronizzare tutti gli utenti del dominio, lasciare vuoto. È combinabile con google_domain: in tal caso verranno sincronizzati solo gli utenti dei gruppi indicati che appartengono al dominio specificato.

6. Riepilogo dei Parametri da Comunicare

Una volta completate le operazioni descritte nelle sezioni precedenti, raccogliere tutti i valori nella tabella seguente e trasmetterli al team Cyber Guru tramite ticket o email cifrata (vedi Sezione 7).

7. Come Inviare i Dati a Cyber Guru

Una volta raccolti tutti i parametri, comunicarli al team Cyber Guru seguendo le istruzioni di seguito.

7.1 Canali accettati

• Ticket di supporto sulla piattaforma Cyber Guru (metodo preferito): allegare i dati in un file di testo cifrato
• Email al proprio referente Cyber Guru: utilizzare solo indirizzi email aziendali verificati

7.2 Formato consigliato per il ticket / email

Includere nel corpo del messaggio o in allegato le seguenti informazioni:

7.3 Cosa aspettarsi dopo l’invio

1. Il team Cyber Guru riceverà i dati e li caricherà nella configurazione della vostra istanza entro 1-2 giorni lavorativi
2. Verrà effettuato un test di connettività e un primo import degli utenti
3. Riceverete una conferma via ticket con il numero di utenti sincronizzati e l’esito dell’operazione
4. In caso di errori, il team Cyber Guru vi contatterà per richiedere le informazioni mancanti o corrette

8. Domande Frequenti (FAQ)

D: Il Service Account ha accesso a dati sensibili degli utenti?

R: No. Il Service Account viene configurato con scope di sola lettura (readonly) limitati alla directory utenti. Non ha accesso a email, documenti, calendario o altri dati personali degli utenti.

D: Cosa succede se un utente viene disattivato in Google Workspace?

R: Ad ogni sincronizzazione, Cyber Guru aggiorna lo stato degli utenti. Gli utenti disattivati o eliminati da Google Workspace vengono automaticamente disattivati anche sulla piattaforma Cyber Guru.

D: Con quale frequenza avviene la sincronizzazione?

R: La frequenza di sincronizzazione è configurabile dal team Cyber Guru in base alle esigenze. Di default viene eseguita ogni 24 ore. Per esigenze specifiche, contattare il supporto.

D: Cosa succede se cambio la password dell’admin email indicata in google_admin_email?

R: La password dell’admin email non influisce sull’integrazione: il Service Account utilizza la chiave privata JSON per autenticarsi, non la password dell’utente. Tuttavia, se l’account viene disattivato o rimosso il ruolo di admin, la sincronizzazione cesserà di funzionare. In quel caso, comunicare il nuovo account admin a Cyber Guru.

D: Devo rinnovare la chiave JSON periodicamente?

R: Le chiavi JSON di Google non scadono automaticamente, ma è buona prassi di sicurezza ruotarle ogni 12 mesi. In tal caso, generare una nuova chiave (sezione 3.4), eliminarla vecchia dal progetto Google Cloud, e comunicare la nuova chiave al team Cyber Guru.

D: Posso usare un Service Account già esistente nella mia organizzazione?

R: Sì, è possibile utilizzare un Service Account esistente purché non abbia permessi eccessivi. Verificare che abbia la Domain-Wide Delegation abilitata e gli OAuth Scope corretti come indicato nella sezione 4.1.

D: google_custom_schemas e google_org_mapping sono obbligatori?

R: No, entrambi i parametri sono opzionali. Se non utilizzate custom schemas o non è richiesta una mappatura organizzativa, comunicatelo al team Cyber Guru che configurerà l’integrazione con i valori di default.

D: La sincronizzazione include gli utenti di tutti i domini dell’organizzazione?

R: Di default viene sincronizzato il dominio indicato in google_domain. Se la vostra organizzazione ha più domini Google Workspace (domini alias o domini aggiuntivi), contattare il team Cyber Guru.

D: Posso sincronizzare solo alcuni Custom Schema?

R: Sì, usa il campo google_custom_schemas per specificare quali schema sincronizzare.

D: Posso rinominare i campi dei Custom Schema?

R: Sì, usa il campo google_org_mapping per mappare SchemaName.FieldName → tags.custom_name.

D: Perché il paese non viene sincronizzato?

R: Il campo countryCode è disponibile solo se l'indirizzo è inserito via API con campi strutturati. Da Google Admin Console, il campo indirizzo è testo libero e non fornisce countryCode.

D: Posso modificare utenti da CyberGuru verso Google?

R: No, la sincronizzazione è unidirezionale. Google Workspace è sempre la fonte di verità.

D: Gli utenti vengono eliminati ?

R: No, se un utente non esiste più in Google viene solo sospeso in CyberGuru, non eliminato.

D: Posso sincronizzare solo gli utenti di specifici gruppi Google?

R: Sì, comunicare al team Cyber Guru gli ID dei gruppi Google da includere. Verranno sincronizzati solo gli utenti membri di almeno uno dei gruppi indicati.

D: Cosa succede se un gruppo configurato non esiste più?

R: La sincronizzazione per la company viene interrotta per sicurezza. Contattare il team Cyber Guru per aggiornare la configurazione.

9. Supporto e Contatti

Per qualsiasi dubbio durante la configurazione, il team Cyber Guru è a disposizione attraverso i seguenti canali: