1. A chi serve questa guida
Questa guida ti accompagna nella configurazione del Single Sign-On (SSO) tra Google Workspace e la piattaforma Cyber Guru, usando il protocollo SAML 2.0. Al termine, i tuoi utenti accederanno a Cyber Guru con le credenziali Google Workspace, senza una password dedicata.
Ti serve un account con ruolo Super Admin di Google Workspace, con accesso alla Console di amministrazione (https://admin.google.com).
Nel testo, l'interlocutore indicato come "Cyber Guru" è Cyber Guru o il partner che gestisce la tua piattaforma.
| 💡 | Gli screenshot di questa guida mostrano la Console di amministrazione Google in lingua inglese. Se la tua console è in italiano, trovi le voci corrispondenti indicate nel testo tra parentesi. |
2. Prerequisiti e decisioni da prendere prima di iniziare
| Elemento | Chi lo fornisce | Note |
|---|---|---|
| Account Super Admin di Google Workspace | Cliente | Accesso a admin.google.com. |
| Protocollo | — | SAML 2.0. Non sono supportati altri protocolli. |
Campo da usare come username
|
Cliente | Decisione più importante della configurazione. Deve essere un attributo immutabile: è la chiave con cui la piattaforma riconosce l'utente e non può essere modificata a progetto avviato. Se c'è la possibilità che l'Email principale cambi (cambio cognome, migrazione di dominio), non usarla: scegli un campo stabile come ID dipendente. Vedi §6. |
| Attributi obbligatori valorizzati sui profili | Cliente | Sono quattro: username, email, firstName, lastName. Se un campo è vuoto sul profilo Google, l'attributo arriva vuoto. |
| Organizzazioni da inviare | Cliente + Cyber Guru | Facoltative, nella forma org_{NOME_ORG} (sede, dipartimento, unità organizzativa…). Dettagli in Attributi Identity Provider SSO. |
| Gruppo degli utenti autorizzati | Cliente | Usa un gruppo dedicato anziché abilitare l'app a tutta l'organizzazione. |
| Modalità di popolamento utenti | Cliente + Cyber Guru | Con precaricamento (consigliata) o senza: vedi Procedura Generale SSO. |
| Utente di test | Cliente | Utile fornire un'utenza di test per le verifiche. |
| Sottodominio della piattaforma | Cyber Guru | Nella forma https://<sottodominio>.platform.cyberguru.eu. |
3. Configurazione passo a passo
Passo 1 — Accedi alla Console di amministrazione Google
Apri https://admin.google.com e accedi con l'account amministratore.
Passo 2 — Scarica i metadati IdP di Google e inviali a Cyber Guru
Nel menu di sinistra seleziona Apps (App) → Web and mobile apps (App web e per dispositivi mobili).
Apri Settings (Impostazioni) → SAML certificates (Certificati SAML).
Si apre la pagina con i dettagli del Google Identity Provider.
Scorri fino in fondo alla pagina e clicca su DOWNLOAD METADATA (SCARICA METADATI).
Invia il file GoogleIDPMetadata.xml a Cyber Guru. Cyber Guru configura il proprio lato e ti risponde con l'URL dei metadati SP (vedi Passo 3.3).
| ⚠️ | A differenza di Microsoft Entra, Google non espone un URL pubblico dei metadati IdP: qui il file XML scaricato è il modo corretto di trasmettere i metadati. Dopo la configurazione i metadati devono rimanere invariati. Se in futuro cambiano — nuovo certificato, nuova app SAML — non modificarli in autonomia: apri una richiesta al supporto Cyber Guru, che coordina l'aggiornamento. Vedi §6. |
Passo 3 — Crea l'app SAML personalizzata
Torna in Apps → Web and mobile apps.
Clicca su Add app (Aggiungi app) → Add custom SAML app (Aggiungi app SAML personalizzata).
3.1 — Dettagli dell'app. Compila App name (es. Cyber Guru) e Description, poi clicca CONTINUE.
3.2 — Dettagli IdP di Google. Questa schermata mostra gli stessi metadati che hai già inviato al Passo 2: non serve fare nulla, clicca CONTINUE.
3.3 — Dettagli del Service Provider. Qui inserisci i valori presi dai metadati SP che hai ricevuto da Cyber Guru.
L'URL dei metadati SP che ricevi ha questa forma:
https://<host-login-cyberguru>/realms/<sottodominio>/broker/saml/endpoint/descriptor
Aprilo in un browser: i due valori da riportare nel form si trovano nel file XML.
| Campo Google | Dove si trova nel file XML dei metadati SP |
|---|---|
| ACS URL | attributo Location dell'elemento <md:AssertionConsumerService> con binding HTTP-POST |
| Entity ID | attributo entityID dell'elemento radice <md:EntityDescriptor>
|
| ⚠️ | Copia i valori dal tuo file di metadati, carattere per carattere. Non ricostruirli a mano e non copiarli da altre guide o da configurazioni di altre organizzazioni: l'indirizzo dipende dall'ambiente su cui è ospitata la tua company. |
Compila ACS URL ed Entity ID, imposta il Name ID format secondo l'indicazione che ricevi da Cyber Guru insieme ai metadati SP, lascia Name ID al valore predefinito e clicca CONTINUE.
3.4 — Mappatura degli attributi. Clicca su ADD MAPPING (AGGIUNGI MAPPATURA) e configura le quattro claim richieste da Cyber Guru.
| Attributo Google Directory | Nome dell'attributo dell'app | Note |
|---|---|---|
| Campo immutabile scelto nei prerequisiti (es. Employee ID; Primary email solo se non cambierà mai) | username |
Chiave di associazione dell'utente. |
| Primary email | email |
|
| First name | firstName |
camelCase obbligatorio. |
| Last name | lastName |
camelCase obbligatorio. |
| 🛑 |
I nomi delle claim sono sensibili alle maiuscole. firstName e lastName vanno scritti esattamente così (camelCase). Scriverli FirstName o firstname impedisce alla piattaforma di riconoscerli. |
Mappatura di username:
Mappatura di firstName:
Mappatura di lastName:
Mappatura di email:
Se servono anche le organizzazioni (org_{NOME_ORG}) o gli attributi facoltativi locale e country, aggiungili con le stesse regole. Il riferimento completo è Attributi Identity Provider SSO.
Clicca FINISH in fondo alla pagina. L'app è creata:
Passo 4 — Abilita l'app per i tuoi utenti
Nella panoramica dell'app individua il pannello User access (Accesso utente).
Clicca su OFF for everyone (OFF per tutti).
Seleziona Groups (Gruppi) e scegli il gruppo che contiene gli utenti autorizzati.
Imposta lo Service status (Stato del servizio) su ON per quel gruppo e clicca SAVE.
| ⚠️ | Per il collaudo abilita un gruppo ristretto con 2-3 utenti di test. Se un utente non è coperto da un gruppo con servizio ON, al login riceverà un errore di servizio non abilitato anche se tutto il resto è configurato correttamente. Le modifiche di stato del servizio possono richiedere qualche minuto per propagarsi. |
Passo 5 — Documenta la configurazione
Conserva in un posto sicuro il file dei metadati e i valori inseriti (ACS URL, Entity ID, mappatura delle claim, gruppo abilitato): ti serviranno al rinnovo del certificato.
4. Test e conferma
- Verifica che l'utente di test appartenga a un gruppo con Service status = ON.
- Se la company è configurata con precaricamento, verifica che lo stesso utente sia già presente in piattaforma con username identico al valore inviato nella claim
username. Se non è precaricato, l'accesso verrà rifiutato. - Apri una finestra del browser in modalità incognito.
- Vai su
https://<sottodominio>.platform.cyberguru.eu - Clicca sul pulsante di accesso SSO.
- Autenticati con le credenziali Google Workspace: se tutto funziona arrivi alla pagina di benvenuto Cyber Guru.
Verifica infine che nome, cognome ed email dell'utente siano corretti in piattaforma: se sono vuoti o errati, il problema è nel mapping delle claim.
5. Se qualcosa non funziona
- Cattura la risposta SAML con un SAML tracer e verifica i nomi esatti delle claim ricevute. Un esempio di risposta corretta:
<saml2:AttributeStatement>
<saml2:Attribute Name="username">
<saml2:AttributeValue>mario.rossi@esempio.it</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="email">
<saml2:AttributeValue>mario.rossi@esempio.it</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="firstName">
<saml2:AttributeValue>Mario</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="lastName">
<saml2:AttributeValue>Rossi</saml2:AttributeValue>
</saml2:Attribute>
</saml2:AttributeStatement>- Verifica ACS URL ed Entity ID: devono corrispondere carattere per carattere a quelli del file di metadati SP.
- Verifica lo stato del servizio per il gruppo dell'utente.
- Ricorda che le modifiche su Google possono richiedere alcuni minuti a propagarsi.
I messaggi d'errore più comuni, con causa e soluzione, sono raccolti in Domande frequenti sull'SSO (FAQ).
Se il problema persiste, contatta il supporto Cyber Guru fornendo: messaggio d'errore completo, orario del tentativo, username dell'utente coinvolto e, se possibile, i file SamlRequest.xml e SamlResponse.xml.
6. Dopo il go-live: manutenzione
- Rotazione del certificato SAML di Google: se generi un nuovo certificato nella sezione SAML certificates, va comunicato a Cyber Guru prima di attivarlo.
- Variazioni dei metadati: devono rimanere invariati; ogni modifica va gestita dal supporto Cyber Guru.
-
Cambi di email principale o di dominio: se l'email è usata come
username, un cambio rompe l'associazione con l'utenza in piattaforma e blocca l'accesso.
Le procedure sono in Manutenzione SSO: rinnovo del certificato e cambio di username/email. Avvisa Cyber Guru prima di migrazioni di dominio o cambi massivi.
7. Risorse aggiuntive
- Procedura Generale SSO
- Attributi Identity Provider SSO
- Autenticazione Ibrida (SSO + Credenziali Applicative)
- Domande frequenti sull'SSO (FAQ) · Manutenzione SSO · Scenari SSO avanzati
- Centro assistenza Google: configurare l'SSO per app SAML personalizzate