Vai al contenuto principale
Novità! Clicca qui
Accedi
Deutsch English (United States) Español Français

Guida alla configurazione dell'SSO con un Identity Provider generico (SAML 2.0)

  • Aggiornato

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:

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 — obbligatori, facoltativi, organizzazioni e Team, frequenza di aggiornamento — è 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

  1. Verifica che l'utenza di test sia autorizzata all'applicazione sull'Identity Provider.
  2. 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.
  3. Apri una finestra del browser in modalità incognito.
  4. Vai su https://<sottodominio>.platform.cyberguru.eu e clicca sul pulsante di accesso SSO.
  5. Autenticati sul tuo Identity Provider: se tutto funziona arrivi alla pagina di benvenuto Cyber Guru senza inserire altre credenziali.
  6. 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.

8. Articoli collegati

Articoli correlati