1. A chi serve questa guida
La piattaforma Cyber Guru si integra con qualsiasi Identity Provider che supporti SAML 2.0. Per Microsoft Entra ID e Google Workspace esistono guide dedicate con gli screenshot delle rispettive console:
- Guida alla configurazione di SSO con Microsoft Entra
- Guida alla configurazione dell'SSO di Google Workspace
Questa guida è per tutti gli altri casi: Okta, Microsoft ADFS, Shibboleth, Oracle, ForgeRock, IBM, AWS, WSO2, PingFederate, o una soluzione sviluppata internamente.
Non troverai screenshot: ogni console ha una sua interfaccia, e le voci cambiano di versione in versione. Troverai invece tutto ciò che il tuo Identity Provider deve fare e i valori esatti da scambiare, così che chi conosce il tuo sistema possa configurarlo senza esitazioni.
| 💡 | La configurazione del tuo Identity Provider è a carico della tua organizzazione, con le risorse interne o con il supporto del fornitore della piattaforma di identità. Cyber Guru configura il proprio lato e fornisce tutti i valori necessari. |
2. Come funziona l'integrazione
Cyber Guru agisce da Service Provider (SP), il tuo sistema da Identity Provider (IdP). Perché il protocollo funzioni, entrambi devono avere le componenti SAML 2.0 e configurare la reciproca fiducia (il cosiddetto circle of trust) attraverso lo scambio dei metadati.
Il flusso previsto è SP-initiated: l'utente parte dall'indirizzo della piattaforma, viene reindirizzato al tuo Identity Provider per autenticarsi, e torna sulla piattaforma con un'asserzione SAML. (L'accesso avviato dal portale dell'IdP — IdP-initiated — è possibile ma richiede una configurazione aggiuntiva: vedi Scenari SSO avanzati.)
3. Prerequisiti e decisioni da prendere prima di iniziare
| Elemento | Chi lo fornisce | Note |
|---|---|---|
| Identity Provider con supporto SAML 2.0 | Cliente | Non sono supportati altri protocolli. |
| Privilegi amministrativi sull'IdP | Cliente | Serve poter creare una nuova applicazione/relying party e definire gli attributi rilasciati. |
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. In Active Directory tipicamente l'ObjectGUID; in altri sistemi un identificativo equivalente (per esempio una matricola). Evita email e UPN se possono cambiare nel tempo. |
| Attributi obbligatori valorizzati sui profili | Cliente | Sono quattro: username, email, firstName, lastName. |
| Organizzazioni da inviare | Cliente + Cyber Guru | Facoltative, nella forma org_{NOME_ORG}. Servono se la company opera senza precaricamento o se una di esse deve essere usata come Team per statistiche e gamification. |
| Metadati IdP | Cliente | URL pubblico raggiungibile da internet, oppure file XML. |
| Policy di accesso all'applicazione | Cliente | Usa un gruppo dedicato: solo gli utenti autorizzati all'applicazione potranno accedere. |
| Modalità di popolamento utenti | Cliente + Cyber Guru | Con precaricamento (consigliata) o senza: vedi Procedura Generale SSO. |
| Utenze di test | Cliente | 2-3 utenze per il collaudo, autorizzate all'applicazione. |
| Sottodominio della piattaforma e metadati SP | Cyber Guru | Forniti a valle dello scambio. |
4. Configurazione passo a passo
Passo 1 — Crea l'applicazione SAML sul tuo Identity Provider
Crea una nuova applicazione (a seconda del sistema si chiama application, relying party trust, service provider, client) di tipo SAML 2.0. Non usare template di catalogo per altri prodotti: serve un'integrazione generica.
Passo 2 — Trasmetti i metadati IdP a Cyber Guru
Invia a Cyber Guru l'URL pubblico dei metadati del tuo Identity Provider (preferibile) oppure il file XML dei metadati.
I metadati devono contenere: l'entityID dell'IdP, l'endpoint di Single Sign-On Service e il certificato pubblico di firma.
| ⚠️ | Se il tuo Identity Provider è raggiungibile solo dalla rete interna, i metadati vanno comunque esposti su un URL pubblico oppure trasmessi come file. Un endpoint non raggiungibile da internet non può essere usato per l'autenticazione degli utenti dall'esterno. |
Passo 3 — Ricevi i metadati SP di Cyber Guru e configura l'applicazione
Cyber Guru completa la configurazione sul proprio lato e ti invia l'URL dei metadati SP. Se il tuo sistema supporta l'import automatico dei metadati, usalo: è la via meno soggetta a errori. Altrimenti, apri l'URL in un browser e ricava i valori dal file XML:
| Valore da configurare | Dove si trova nel file XML dei metadati SP |
|---|---|
| Entity ID (audience / SP identifier) | attributo entityID dell'elemento radice <md:EntityDescriptor>
|
| ACS URL (Assertion Consumer Service, reply URL, destination) | attributo Location dell'elemento <md:AssertionConsumerService> con binding HTTP-POST |
| ⚠️ | 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. |
Passo 4 — Requisiti tecnici dell'asserzione
| Parametro | Valore richiesto |
|---|---|
| Versione del protocollo | SAML 2.0 |
| Binding della risposta | HTTP-POST verso l'ACS URL |
| Firma | L'asserzione (o la risposta) deve essere firmata con la chiave privata dell'IdP; il certificato pubblico corrispondente deve essere nei metadati trasmessi |
| Cifratura dell'asserzione | Non richiesta. Se il tuo IdP la impone, segnalalo prima della configurazione |
| Formato del Name ID | Da impostare secondo l'indicazione che ricevi da Cyber Guru insieme ai metadati SP |
| Single Logout | Facoltativo. Se il tuo IdP effettua il logout con binding HTTP-POST, segnalalo: richiede una configurazione aggiuntiva lato Cyber Guru |
Passo 5 — Configura gli attributi rilasciati
L'asserzione deve contenere quattro attributi obbligatori, con questi nomi esatti:
| Nome attributo | Contenuto |
|---|---|
username |
L'identificativo immutabile scelto nei prerequisiti |
email |
Indirizzo email dell'utente |
firstName |
Nome |
lastName |
Cognome |
Facoltativi: locale (codice lingua ISO a due lettere minuscole), country (codice paese ISO a due lettere maiuscole) e le organizzazioni nella forma org_{NOME_ORG}.
| 🛑 |
Due regole che valgono su qualsiasi Identity Provider: 1. I nomi degli attributi sono sensibili alle maiuscole. firstName e lastName vanno scritti esattamente così, in camelCase.2. I nomi non devono avere prefissi namespace. Molti Identity Provider — ADFS e Microsoft Entra ID in particolare — rilasciano gli attributi con un prefisso tipo http://schemas.xmlsoap.org/ws/2005/05/identity/claims: quel prefisso va rimosso, altrimenti l'attributo non viene riconosciuto. |
Il riferimento completo sugli attributi è Attributi Identity Provider SSO. Attributi non presenti in quell'elenco vanno concordati preventivamente con Cyber Guru.
Un esempio di come deve arrivare la parte attributi dell'asserzione:
<saml2:AttributeStatement>
<saml2:Attribute Name="username">
<saml2:AttributeValue>a1b2c3d4-0000-1111-2222-33445566778</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>Passo 6 — Autorizza gli utenti
Assegna all'applicazione il gruppo che contiene gli utenti autorizzati. Chi non è autorizzato all'applicazione riceverà un errore al momento dell'accesso, anche se tutto il resto è configurato correttamente. Per il collaudo autorizza solo le utenze di test.
Passo 7 — Documenta la configurazione
Conserva i valori inseriti (Entity ID, ACS URL, nomi degli attributi, gruppo autorizzato) e il file dei metadati: ti serviranno al rinnovo del certificato.
5. Test e conferma
- Verifica che l'utenza di test sia autorizzata all'applicazione sull'Identity Provider.
- Se la company è configurata con precaricamento, verifica che la stessa utenza sia già presente in piattaforma con username identico al valore inviato nell'attributo
username. Se non è precaricata, l'accesso verrà rifiutato. - Apri una finestra del browser in modalità incognito.
- Vai su
https://<sottodominio>.platform.cyberguru.eue clicca sul pulsante di accesso SSO. - Autenticati sul tuo Identity Provider: se tutto funziona arrivi alla pagina di benvenuto Cyber Guru senza inserire altre credenziali.
- Verifica in piattaforma che nome, cognome ed email siano corretti: se sono vuoti o errati, il problema è negli attributi rilasciati.
6. Se qualcosa non funziona
Il primo strumento è un SAML tracer nel browser: cattura la risposta SAML e verifica i nomi esatti degli attributi (maiuscole comprese), l'assenza di prefissi namespace, il valore di username e la presenza di tutti e quattro gli attributi obbligatori.
Controlla poi che Entity ID e ACS URL configurati corrispondano carattere per carattere a quelli dei metadati SP, e che l'utente sia autorizzato all'applicazione.
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, sottodominio della company e, se possibile, i file SamlRequest.xml e SamlResponse.xml.
7. Dopo il go-live: manutenzione
Dopo la configurazione i metadati vanno considerati fissi. Se cambiano — rinnovo del certificato di firma, nuovi endpoint, nuova applicazione, sostituzione dell'Identity Provider — non modificarli in autonomia: apri una richiesta al supporto Cyber Guru, che coordina l'aggiornamento su entrambi i lati. Lo stesso vale per i cambi di email, UPN o dominio degli utenti, che possono interrompere l'associazione con le utenze in piattaforma.
Le procedure sono in Manutenzione SSO: rinnovo del certificato e cambio di username/email.