1. A chi serve questa guida
Questa guida ti accompagna nella configurazione del Single Sign-On (SSO) tra Microsoft Entra ID (già Azure Active Directory) e la piattaforma Cyber Guru, usando il protocollo SAML 2.0.
Per completarla ti serve un ruolo con privilegi amministrativi su Microsoft Entra ID (tipicamente Cloud Application Administrator o Application Administrator). Se non sei sicuro di averli, coinvolgi il team IT della tua organizzazione prima di iniziare.
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 Microsoft in lingua inglese. Se la tua console è in italiano, trovi le voci corrispondenti indicate nel testo tra parentesi. Le etichette dell'interfaccia Microsoft cambiano frequentemente: se non trovi una voce con il nome esatto, usa la barra di ricerca del portale. |
2. Indice
- Termini chiave
- Prerequisiti e decisioni da prendere prima di iniziare
- Configurazione passo a passo (passi 1-8)
- Test e conferma
- Se qualcosa non funziona
- Dopo il go-live: manutenzione
- Risorse aggiuntive
3. Termini chiave
- IdP (Identity Provider): il sistema che autentica gli utenti. In questo scenario è Microsoft Entra ID.
- SP (Service Provider): il servizio a cui l'utente accede, cioè la piattaforma Cyber Guru.
- Metadati: file (o URL) XML con cui IdP e SP si scambiano endpoint e certificati per stabilire la reciproca fiducia (circle of trust).
- Claim (attestazione): un'informazione sull'utente che l'IdP inserisce nella risposta SAML — ad esempio nome, cognome, email.
- Enterprise Application: l'oggetto in Entra ID che rappresenta l'applicazione da integrare.
4. Prerequisiti e decisioni da prendere prima di iniziare
Queste voci vanno chiarite prima di aprire la console: la gran parte dei problemi di configurazione nasce da una di queste decisioni presa male.
| Elemento | Chi lo fornisce | Note |
|---|---|---|
| Accesso amministrativo a Microsoft Entra ID | Cliente | Ruolo Application Administrator o superiore. |
| 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. Su Entra ID la scelta consigliata è l'Object ID (user.objectid). Sono ammesse alternative (es. matricola) purché immutabili. Evita email e UPN se possono cambiare: vedi §8. |
| Attributi obbligatori valorizzati sul profilo utente | Cliente | Sono quattro: username, email, firstName, lastName. Verifica che nome, cognome ed email siano effettivamente popolati sui profili Entra. |
| Organizzazioni da inviare | Cliente + Cyber Guru | Facoltative, nella forma org_{NOME_ORG} (sede, dipartimento, unità organizzativa…). Servono se la company opera senza precaricamento o se una di esse deve essere usata come Team per statistiche e gamification. Dettagli in Attributi Identity Provider SSO. |
| Policy di accesso all'applicazione | Cliente | Usa un gruppo dedicato anziché assegnare utenti singoli: è la modalità più semplice da gestire nel tempo. Solo gli utenti assegnati all'app potranno accedere. |
| Modalità di popolamento utenti | Cliente + Cyber Guru | Con precaricamento (consigliata) o senza. Le due modalità hanno conseguenze diverse su licenze e attributi: leggi Procedura Generale SSO prima di scegliere. |
| Utente di test | Cliente | Fornisci un'utenza di test su Entra ID, utile per le verifiche in fase di collaudo. |
| Sottodominio della piattaforma | Cyber Guru | Nella forma https://<sottodominio>.platform.cyberguru.eu. |
5. Configurazione passo a passo
Passo 1 — Accedi a Microsoft Entra ID
Vai su https://entra.microsoft.com con un'utenza che abbia i privilegi amministrativi indicati nei prerequisiti.
Passo 2 — Apri "Enterprise applications" (Applicazioni aziendali)
Nel pannello di navigazione a sinistra seleziona Enterprise applications (Applicazioni aziendali).
Passo 3 — Crea una nuova applicazione non-gallery
In alto nella pagina clicca su New application (Nuova applicazione).
Poi clicca su Create your own application (Crea la tua applicazione).
Nel pannello che si apre: inserisci un nome per l'applicazione (es. Cyber Guru), assicurati che sia selezionata l'opzione "Integrate any other application you don't find in the gallery (Non-gallery)" e clicca su Create.
Passo 4 — Avvia la configurazione SAML
Dalla pagina di panoramica dell'applicazione appena creata, apri Single sign-on nel menu di sinistra (oppure il riquadro Set up single sign on).
Tra i metodi proposti seleziona SAML.
Passo 5 — Invia i metadati IdP a Cyber Guru
Nel riquadro 3 — SAML Certificates trovi il campo App Federation Metadata Url.
Copia quell'URL e invialo a Cyber Guru. Ha questa forma:
https://login.microsoftonline.com/<tenant-id>/federationmetadata/2007-06/federationmetadata.xml?appid=<app-id>
| ⚠️ | Invia l'URL, non il certificato scaricato né il file XML. Dopo la configurazione i metadati devono rimanere invariati. Se in futuro cambiano — nuovo certificato, nuova applicazione, endpoint diversi — non modificarli e non ricrearli in autonomia: apri una richiesta al supporto Cyber Guru, che coordina l'aggiornamento. Vedi §8. |
Passo 6 — Ricevi e carica i metadati SP di Cyber Guru
Cyber Guru completa la configurazione sul proprio lato e ti invia l'URL dei metadati SP, nella forma:
https://<host-login-cyberguru>/realms/<sottodominio>/broker/saml/endpoint/descriptor
| ⚠️ | Usa esattamente l'URL che ricevi da Cyber Guru: non ricostruirlo a mano e non copiarlo da altre guide o da configurazioni di altre organizzazioni. L'indirizzo dipende dall'ambiente su cui è ospitata la tua company. |
Apri l'URL in un browser e salva la pagina come file XML. Poi, nella pagina SAML dell'applicazione, clicca su Upload metadata file (Aggiorna file metadati) in alto e carica il file salvato.
Entra ID compila automaticamente Identifier (Entity ID) e Reply URL (ACS URL). Verifica i valori nella pagina di revisione e clicca su Save.
Passo 7 — Configura le claim (Attributes & Claims)
Apri il riquadro 2 — Attributes & Claims e clicca su Edit. Alla creazione dell'app trovi un set di claim predefinite:
Puoi modificare le claim aggiuntive esistenti oppure rimuoverle tutte e crearne di nuove. Cyber Guru richiede esattamente queste quattro claim:
| Nome claim (Name) | Namespace | Source attribute consigliato |
|---|---|---|
username |
(vuoto) | user.objectid |
email |
(vuoto) | user.mail |
firstName |
(vuoto) | user.givenname |
lastName |
(vuoto) | user.surname |
Per ciascuna claim, in Manage claim imposta Source = Attribute e scegli il Source attribute:
| 🛑 |
I due errori più frequenti in assoluto, entrambi in questo passo: 1. 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, la claim arriva a Cyber Guru con il prefisso e non viene riconosciuta. Cancellalo per tutte e quattro le claim.2. I nomi delle claim sono sensibili alle maiuscole. firstName e lastName vanno scritti esattamente così (camelCase). |
Se servono anche le organizzazioni (org_{NOME_ORG}) o gli attributi facoltativi locale e country, aggiungili con le stesse regole. Le regole complete sono in Attributi Identity Provider SSO, che è il riferimento da seguire.
A configurazione completata dovresti vedere una situazione come questa. Rileggi con attenzione il mapping riga per riga:
Passo 8 — Autorizza gli utenti e documenta la configurazione
Vai su Users and groups (Utenti e gruppi) e assegna all'applicazione il gruppo che contiene gli utenti autorizzati. Chi non è assegnato all'app riceverà un errore 403 al momento dell'accesso, anche se tutto il resto è configurato correttamente.
Per il collaudo assegna solo 2-3 utenti di test; estenderai al gruppo completo al go-live.
Conserva una copia digitale della configurazione (URL metadati, nomi delle claim, gruppo assegnato): tornerà utile al rinnovo del certificato.
6. Test e conferma
- Verifica che l'utente di test sia assegnato all'applicazione su Entra ID.
- Se la company è configurata con precaricamento, verifica che lo stesso utente sia già presente in piattaforma e che il suo username in piattaforma corrisponda esattamente al valore inviato nella claim
username. Se non è precaricato, l'accesso verrà rifiutato. - Apri una finestra del browser in modalità incognito (per non riusare sessioni Microsoft già attive).
- Vai su
https://<sottodominio>.platform.cyberguru.eu - Clicca sul pulsante di accesso SSO.
- Autenticati su Microsoft. Se tutto funziona, arrivi direttamente alla pagina di benvenuto Cyber Guru senza inserire altre credenziali.
- Verifica in piattaforma che nome, cognome ed email dell'utente siano corretti: se sono vuoti o errati, il problema è nel mapping delle claim.
7. Se qualcosa non funziona
Prova questi tre controlli, che risolvono la maggior parte dei casi:
-
Cattura la risposta SAML con un SAML tracer (estensione browser) e verifica i nomi esatti delle claim ricevute: maiuscole corrette? namespace assente? valore di
usernameuguale a quello in piattaforma? - Verifica l'assegnazione dell'utente all'applicazione su Entra ID.
- Leggi il messaggio d'errore: è quasi sempre diagnostico.
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: il messaggio d'errore completo, l'orario del tentativo, l'username dell'utente coinvolto e, se possibile, i file SamlRequest.xml e SamlResponse.xml catturati dal tracer.
8. Dopo il go-live: manutenzione
Tre eventi richiedono un intervento coordinato con Cyber Guru. Pianificali in anticipo:
- Scadenza del certificato di firma SAML sull'applicazione Entra (Microsoft invia una notifica prima della scadenza).
- Qualsiasi variazione dei metadati dell'applicazione: devono rimanere invariati, e ogni modifica va gestita dal supporto.
- Cambi di email, UPN o dominio degli utenti: possono rompere l'associazione tra l'identità Entra e l'utenza in piattaforma, con conseguente blocco dell'accesso.
Le procedure sono descritte in Manutenzione SSO: rinnovo del certificato e cambio di username/email. Avvisa Cyber Guru prima di migrazioni di dominio o cambi massivi di UPN.
9. Risorse aggiuntive
- Procedura Generale SSO — le due modalità di SSO e i requisiti di base.
- Attributi Identity Provider SSO — riferimento completo sugli attributi.
- Autenticazione Ibrida (SSO + Credenziali Applicative)
- Domande frequenti sull'SSO (FAQ) · Manutenzione SSO · Scenari SSO avanzati
- Documentazione Microsoft Entra ID sull'SSO SAML