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

Guida alla configurazione di SSO con Microsoft Entra ID

  • Aggiornato

 

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 "CyberGuru" è CyberGuru o il partner che gestisce la tua piattaforma.

Questa guida, inoltre, copre il caso di autenticazione SSO via SAML 2.0 con meccanismo SP-Initiated ( ovvero partendo dalla URL ); nel caso in cui ci sia la necessità di configurare l'accesso in SSO via applicazione ( IDP-Initiated ) si prega di contattare il supporto.

💡 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).

Menu di navigazione con la voce Enterprise applications

Passo 3 — Crea una nuova applicazione non-gallery

In alto nella pagina clicca su New application (Nuova applicazione).

Pulsante New application

Poi clicca su Create your own application (Crea la tua applicazione).

Pulsante Create your own application

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.

Pannello di creazione applicazione non-gallery

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).

Pagina di panoramica dell'applicazione

Tra i metodi proposti seleziona SAML.

Selezione del metodo SSO SAML

Passo 5 — Invia i metadati IdP a Cyber Guru

Nel riquadro 3 — SAML Certificates trovi il campo App Federation Metadata Url.

Riquadro SAML Certificates con 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 CyberGuru, 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.

Pulsante Upload metadata file

Entra ID compila automaticamente Identifier (Entity ID) e Reply URL (ACS URL). Verifica i valori nella pagina di revisione e clicca su Save.

Pagina di revisione dei metadati importati

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:

Claim predefinite dell'applicazione

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 o user.userprincipalname
email (vuoto) user.mail
firstName (vuoto) user.givenname
lastName (vuoto) user.surname
Unique User Identifier   allineato ad username

Per ciascuna claim, in Manage claim imposta Source = Attribute e scegli il Source attribute:

Pannello Manage claim con 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,  nel caso ci sia la creazione dell'utenza contestualmente al login via SSO, aggiungili con le stesse regole. Le regole complete sugli attributi — obbligatori, facoltativi, organizzazioni e Team, frequenza di aggiornamento — 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:

Mapping finale delle claim

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 o errore di non autorizzazzione sul proprio IDP, 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

  1. Verifica che l'utente di test sia assegnato all'applicazione su Entra ID.
  2. 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.
  3. Apri una finestra del browser in modalità incognito (per non riusare sessioni Microsoft già attive).
  4. Vai su https://<sottodominio>.platform.cyberguru.eu
  5. Clicca sul pulsante di accesso SSO.
  6. Autenticati su Microsoft. Se tutto funziona, arrivi direttamente alla pagina di benvenuto Cyber Guru senza inserire altre credenziali.
  7. 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:

  1. Cattura la risposta SAML con un SAML tracer (estensione browser) e verifica i nomi esatti delle claim ricevute: maiuscole corrette? namespace assente? valore di username uguale a quello in piattaforma?
  2. Verifica l'assegnazione dell'utente all'applicazione su Entra ID.
  3. 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

Articoli correlati