Questa pagina risponde alle domande che si presentano più spesso quando si configura o si gestisce l'accesso Single Sign-On (SSO) alla piattaforma Cyber Guru. Vale per tutti gli Identity Provider: Microsoft Entra ID, Google Workspace, Okta, ADFS, Shibboleth e altri.
Prima di configurare
Quale campo devo usare come username?
Un campo immutabile, cioè che non cambierà per tutta la durata del progetto. È la scelta più importante di tutta la configurazione: l'username è la chiave con cui la piattaforma riconosce l'utente e non può essere modificato a progetto avviato.
Su Microsoft Entra ID la scelta consigliata è l'Object ID (user.objectid). Su Google Workspace, un identificativo stabile come l'ID dipendente. Sono ammessi altri campi purché immutabili.
Posso usare l'email o l'UPN come username?
Tecnicamente sì, ma è sconsigliato. Se l'email o l'UPN cambiano — cambio cognome, migrazione di dominio, riorganizzazione — l'associazione tra l'identità e l'utenza in piattaforma si interrompe e l'utente non riesce più ad accedere. Il ripristino richiede un intervento di Cyber Guru.
Quali attributi devo inviare?
Quattro attributi sono obbligatori: username, email, firstName, lastName. Facoltativi: locale, country e le organizzazioni nella forma org_{NOME_ORG}. Il riferimento completo, con le regole di scrittura e la frequenza di aggiornamento, è Attributi Identity Provider SSO. Attributi non presenti in quell'elenco vanno concordati preventivamente con Cyber Guru.
Come si gestiscono i team?
Il Team non è un attributo a sé: è una delle organizzazioni (org_{NOME_ORG}), quella che viene designata come Team ai fini delle statistiche e della gamification. La designazione avviene nella configurazione della company, non nell'asserzione SAML. Se le organizzazioni sono precaricate in piattaforma non serve inviarle via SSO.
Che differenza c'è tra SSO con e senza precaricamento utenti?
Con precaricamento (modalità consigliata) gli utenti vengono caricati in piattaforma prima dell'attivazione e l'SSO si occupa solo dell'autenticazione: chi non è precaricato non può accedere. Senza precaricamento, ogni utente viene creato automaticamente al primo login con gli attributi presenti nell'asserzione. Dettagli in Procedura Generale SSO.
Si può cambiare modalità dopo l'attivazione?
Sì. Il passaggio tra le due modalità si ottiene abilitando o disabilitando il flag di precaricamento sulla configurazione della company: non comporta di rifare la configurazione SSO. Richiedilo al tuo referente Cyber Guru.
Alcuni utenti devono continuare ad accedere con username e password. È possibile?
Sì, è l'autenticazione ibrida: si può stabilire per singolo utente se accede in SSO o con credenziali applicative. Va attivata dopo la configurazione dell'SSO standard. Vedi Autenticazione Ibrida (SSO + Credenziali Applicative).
È supportato LDAP?
No. L'integrazione dell'autenticazione avviene tramite SAML 2.0.
L'MFA della nostra organizzazione continua a funzionare?
Sì, e resta interamente sotto il tuo controllo. L'autenticazione avviene sul tuo Identity Provider: MFA, Conditional Access e qualsiasi altra policy che applichi prima di emettere l'asserzione dipendono da te. Alla piattaforma Cyber Guru arriva la risposta SAML, e quello che è avvenuto prima lo decide l'Identity Provider.
Durante la configurazione
Cosa devo inviare a Cyber Guru, e cosa riceverò?
Su Microsoft Entra ID invii l'URL dei metadati di federazione dell'applicazione (non il certificato, non il file XML scaricato). Su Google Workspace invii il file GoogleIDPMetadata.xml, perché Google non espone un URL pubblico.
In risposta ricevi l'URL dei metadati SP di Cyber Guru, da cui ricavi i valori da inserire nella configurazione dell'applicazione.
Posso ricostruire da solo l'ACS URL e l'Entity ID?
No. Usa sempre i valori presi dal file di metadati che ti viene fornito: l'indirizzo dipende dall'ambiente su cui è ospitata la tua company e non coincide necessariamente con quello di altre organizzazioni o di altri esempi.
Quanto tempo richiede l'attivazione?
La configurazione lato Cyber Guru richiede circa 30 minuti dal momento in cui riceve i metadati. I tempi complessivi dipendono dalle attività lato cliente: creazione dell'applicazione, mappatura degli attributi, autorizzazione degli utenti e collaudo.
I nomi degli attributi sono sensibili alle maiuscole?
Sì. firstName e lastName vanno scritti esattamente così, in camelCase. Scritti FirstName o firstname non vengono riconosciuti.
Su Microsoft Entra ID devo compilare il campo Namespace?
No: il campo Namespace deve restare vuoto. Entra ID lo precompila con un valore tipo http://schemas.xmlsoap.org/ws/2005/05/identity/claims: se lo lasci, l'attributo arriva a Cyber Guru con quel prefisso e non viene riconosciuto. È l'errore più frequente in assoluto su Entra ID: cancellalo per tutti e quattro gli attributi obbligatori.
Come verifico cosa sto effettivamente inviando?
Installa nel browser un'estensione SAML tracer, ripeti il tentativo di accesso e osserva la risposta SAML. Controlla 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. È il modo più rapido per diagnosticare la quasi totalità dei problemi.
Errori al momento dell'accesso
"User … authenticated with identity provider saml does not exist"
Il valore di username che l'Identity Provider sta inviando non corrisponde a nessun username presente in piattaforma. Le cause tipiche:
- l'utente non è stato precaricato (in modalità con precaricamento non può accedere);
- l'attributo mappato su
usernamenon è quello concordato; - l'email o l'UPN dell'utente sono cambiati dopo l'attivazione.
Confronta con un SAML tracer il valore inviato con l'username in piattaforma. Nel terzo caso serve un intervento di Cyber Guru: vedi Manutenzione SSO.
"Errore imprevisto durante l'autenticazione con identity provider"
L'identità dell'Identity Provider risulta già associata a un'altra utenza in piattaforma. Non è risolvibile in autonomia: contatta il supporto Cyber Guru indicando gli utenti coinvolti e il sottodominio della company.
Un errore che segnala un campo nullo (es. Column 'firstname' cannot be null)
L'attributo è arrivato con un nome che la piattaforma non riconosce, quindi il campo risulta vuoto. Due cause possibili, spesso presenti insieme: maiuscole errate nel nome dell'attributo, oppure campo Namespace non svuotato. Correggi entrambi e ripeti il test.
"Errore di registrazione" al primo accesso di un nuovo utente
Manca uno degli attributi obbligatori nell'asserzione, oppure l'attributo è presente ma vuoto sul profilo dell'utente nell'Identity Provider. Verifica entrambe le cose: un campo non popolato sull'IdP produce un attributo vuoto.
Nota: questo errore riguarda le company senza precaricamento, dove l'utente viene creato al primo accesso. Con precaricamento un attributo vuoto non blocca l'ingresso: il dato resta semplicemente non aggiornato.
Errore 403 o "servizio non abilitato" subito dopo il click sul pulsante SSO
L'utente non è autorizzato all'applicazione lato Identity Provider. Su Entra ID: assegna l'utente o il suo gruppo all'applicazione in Users and groups. Su Google Workspace: verifica che l'utente appartenga a un gruppo con Service status = ON nel pannello User access. Dopo la modifica attendi qualche minuto per la propagazione.
L'accesso funziona, ma in piattaforma nome e cognome sono vuoti o errati
Il problema è nel mapping degli attributi, oppure il campo è vuoto sul profilo dell'IdP. Nome e cognome vengono riallineati ad ogni accesso, quindi una volta corretto il mapping il dato si sistema al login successivo.
L'accesso funziona, ma l'utente non vede corsi o risulta senza licenza
Verifica la disponibilità di licenze nella company. Se la company opera senza precaricamento utenti, l'assegnazione automatica della licenza al primo accesso deve essere attiva: chiedi conferma al tuo referente Cyber Guru.
Gli utenti esistenti accedono, i nuovi no
È il comportamento previsto in modalità con precaricamento: possono accedere solo gli utenti già presenti in piattaforma. Carica i nuovi utenti tramite user list, oppure chiedi il passaggio alla modalità senza precaricamento (è un flag, non una riconfigurazione).
Viene richiesta una password anche dopo l'accesso SSO
Può dipendere da una password applicativa ancora presente sull'utenza, oppure dal fatto che la company è in autenticazione ibrida e quell'utente è impostato per accedere con credenziali. Verifica la modalità dell'utente: vedi Autenticazione Ibrida.
Il pulsante SSO non appare nella pagina di login
Il pulsante compare quando la configurazione è completata su entrambi i lati. Se non lo vedi, verifica con il tuo referente Cyber Guru lo stato dell'attivazione.
Il logout non funziona correttamente
Alcuni Identity Provider gestiscono il logout con modalità che richiedono una configurazione aggiuntiva lato Cyber Guru. Se dopo il logout riscontri errori o sessioni che restano aperte, segnalalo: non è una modifica da fare sul tuo Identity Provider.
Dopo il go-live
Gli utenti in SSO ricevono un'email di benvenuto?
No. L'email di benvenuto è legata all'associazione delle licenze — viene inviata quando è previsto l'evento di associazione e le licenze vengono effettivamente assegnate — ed è un meccanismo indipendente dall'SSO. Gli utenti che accedono in SSO non ricevono credenziali via email, perché non ne hanno bisogno: raggiungono la piattaforma dal proprio indirizzo dedicato e si autenticano con le credenziali aziendali.
Quanto dura la sessione?
La sessione in piattaforma ha una durata di 30 minuti; alla scadenza è necessario autenticarsi di nuovo. Se sul tuo Identity Provider è ancora attiva una sessione valida, la riautenticazione è trasparente per l'utente.
I metadati possono cambiare nel tempo?
Non devono. Dopo la configurazione i metadati vanno considerati fissi. Se sul tuo Identity Provider cambia qualcosa — nuovo certificato, nuova applicazione, endpoint diversi — non modificare né ricreare la configurazione in autonomia: apri una richiesta al supporto Cyber Guru, che coordina l'aggiornamento su entrambi i lati.
Il certificato di firma SAML sta scadendo. Cosa devo fare?
Comunicare a Cyber Guru il nuovo certificato prima di attivarlo, e concordare la finestra di switch. La procedura completa è in Manutenzione SSO.
Stiamo cambiando il dominio email aziendale. Ha impatto sull'SSO?
Sì, se l'email o l'UPN sono usati come username: il cambio interrompe l'associazione con le utenze in piattaforma. Segnalalo a Cyber Guru prima della migrazione: pianificato in anticipo, l'allineamento si esegue in una finestra concordata.
Cosa accade se disabilitiamo un utente sul nostro Identity Provider?
L'utente non riesce più ad autenticarsi, quindi non accede alla piattaforma. La sua utenza e la licenza associata, però, restano in piattaforma: l'SSO gestisce l'autenticazione, non il ciclo di vita degli account. Per allineare automaticamente disattivazioni e cancellazioni serve il provisioning SCIM 2.0; in assenza di SCIM, le modalità di deprovisioning vanno concordate con Cyber Guru.
Abbiamo due tenant o due Identity Provider. È supportato?
Sì. Sono supportati anche l'accesso avviato dal portale dell'Identity Provider e la gestione di più company sullo stesso tenant. Vedi Scenari SSO avanzati: la sequenza dei passaggi cambia, quindi segnalalo prima di iniziare la configurazione.
Possiamo sincronizzare automaticamente utenti e attributi?
L'SSO trasporta le informazioni solo al momento del login. Per sincronizzare il ciclo di vita degli utenti o portare in piattaforma molti attributi si valutano il provisioning SCIM 2.0 o le API. Parlane con il tuo referente Cyber Guru prima del go-live.
Serve aiuto?
Se dopo queste verifiche il problema persiste, contatta il supporto Cyber Guru fornendo:
- il messaggio d'errore completo e l'orario del tentativo;
- l'username dell'utente coinvolto e il sottodominio della company;
- se disponibili, i file
SamlRequest.xmleSamlResponse.xmlesportati dal SAML tracer.
Queste informazioni riducono sensibilmente i tempi di diagnosi.