Single Sign-On (SSO)

Configurazione e utilizzo dell’SSO

---

Pericolo

Questa guida è destinata agli amministratori di sistema. Se non disponi delle competenze tecniche necessarie, contatta il tuo reparto IT per assistenza.

La Prevu3D Cloud Platform supporta un Single Sign-On (SSO) sicuro tramite protocolli standard di settore:

• SAML 2.0 – per l’autenticazione e l’accesso degli utenti.

• SCIM 2.0 – per il provisioning automatico di utenti e gruppi.

Provider di identità supportati

Qualsiasi provider di identità che supporti pienamente i protocolli SAML 2.0 e/o SCIM 2.0 dovrebbe essere compatibile con Prevu3D, inclusi Okta, Google Workspace, OneLogin, Ping Identity e altri. L’implementazione di Prevu3D segue le specifiche ufficiali SAML 2.0 e SCIM 2.0, garantendo un’ampia compatibilità con i moderni sistemi di identità.

Abbiamo testato a fondo l’integrazione con:

• Microsoft Entra ID (precedentemente Azure Active Directory)

• JumpCloud (English)

Nota

• Ogni organizzazione Prevu3D supporta una sola connessione a un solo provider di identità alla volta.

• La funzionalità SSO è inclusa nell’abbonamento Enterprise. Contatta sales@prevu3d.com per abilitarla per la tua organizzazione.

SAML 2.0 – Configurazione dell’autenticazione

Prerequisiti

Per configurare l’SSO basato su SAML con Prevu3D, avrai bisogno di:

• Accesso amministratore alla tua organizzazione Prevu3D.

• Accesso al tuo IdP con il permesso di configurare le applicazioni.

Passaggi

1. Accedi al tuo account Prevu3D (usando il tuo indirizzo email e la password)

2. Vai alla scheda Impostazioni

3. Seleziona la scheda SSO dal menu a sinistra

Non riesci ad accedere alla scheda “SSO”?

1. Se è mancante, non sei un amministratore dell’organizzazione.

2. Se è disattivata, la tua organizzazione non ha sottoscritto la funzionalità SSO.

4. Copia i seguenti valori dalla scheda SSO e incollali nella configurazione del tuo IdP:

   • Endpoint del Service Provider – l’URL a cui il tuo IdP invia l’asserzione SAML. Il tuo IdP potrebbe chiamarlo ACS URL, Reply URL o Assertion Consumer Service URL.

   • Entity ID del Service Provider – l’identificatore univoco di Prevu3D nello scambio SAML. Il tuo IdP potrebbe chiamarlo Audience, Identifier o SP Entity ID.

Attenzione

Inserisci l’Entity ID nel tuo IdP esattamente come appare nella scheda SSO, incluso il suffisso completo (ad esempio xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx-production-############-Prevu3DCloudPlatform). Copialo e incollalo anziché digitarlo nuovamente.

Se il tuo IdP invia un valore di audience abbreviato o un nome descrittivo (ad esempio Prevu3D), l’autenticazione viene rifiutata per una mancata corrispondenza dell’audience, anche se il resto della configurazione è corretto. È l’errore di configurazione più frequente — vedi Risoluzione dei problemi.

5. Recupera i seguenti valori dal tuo IdP e inseriscili nella scheda SSO:

   • Certificato SAML (formato PEM)

   • URL dell’endpoint SAML

6. Se SCIM non è abilitato, definisci le mappature degli attributi SAML – vedi Mappature degli attributi SAML qui sotto.

   

Attenzione

Questi attributi sono opzionali quando il provisioning SCIM è abilitato e configurato. SCIM gestisce automaticamente i dettagli degli utenti.

7. Fai clic su Salva in fondo alla pagina.

8. Verifica la configurazione prima di distribuirla – vedi Convalida della configurazione qui sotto.

Mappature degli attributi SAML

Ogni campo indica a Prevu3D quale attributo (claim) leggere dall’asserzione SAML inviata dal tuo provider di identità. Il valore inserito deve corrispondere esattamente al nome dell’attributo configurato nel tuo IdP, incluse le maiuscole e le minuscole.

Campo	Cosa inserire	Valori di esempio
First Name SAML Attribute Key	Il nome dell’attributo IdP che contiene il nome dell’utente	givenName, firstName, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
Last Name SAML Attribute Key	Il nome dell’attributo IdP che contiene il cognome dell’utente	familyName, surname, lastName

Non sai quali nomi di attributi invia il tuo IdP? Acquisisci una traccia SAML tramite un’estensione del browser come SAML-tracer e controlla i nomi elencati nell’AttributeStatement, oppure consulta la configurazione dell’applicazione nel tuo IdP.

Assegnazione dei ruoli tramite SSO

Questa sezione conteneva in precedenza un campo Role SAML Attribute Key e un selettore Default Organization Role, che assegnavano un unico ruolo a livello di organizzazione a partire da un attributo SAML. Entrambi sono stati rimossi: un unico ruolo per tutta l’organizzazione non è abbastanza granulare e i ruoli offerti non corrispondevano più ai ruoli personalizzabili della tua organizzazione.

Assegna i ruoli tramite la Mappatura dei gruppi: mappa i gruppi del tuo IdP sui gruppi Prevu3D e concedi a ciascun gruppo l’accesso necessario. Se SCIM è abilitato, gestisci l’assegnazione dei ruoli tramite SCIM.

Distribuzione dell’SSO agli utenti

Una volta salvata e convalidata la configurazione, due elementi determinano se i tuoi utenti possono effettivamente accedere.

Configurazione del dominio e nuovi utenti

Il tuo dominio email deve essere associato alla tua organizzazione Prevu3D. La configurazione del dominio abilita:

• Il reindirizzamento dalla pagina di accesso – gli utenti che cliccano su Accedi tramite SSO e inseriscono un’email del tuo dominio vengono reindirizzati al tuo IdP.

• La creazione dell’account just-in-time – quando un utente del tuo dominio che non ha mai usato Prevu3D si autentica correttamente tramite il tuo IdP, viene creato automaticamente un account Prevu3D, con i nomi compilati a partire dalle mappature degli attributi SAML. Non è necessario alcun invito né la creazione manuale dell’account. Il nuovo account parte senza accesso ai progetti finché non glielo concedi, tramite la Mappatura dei gruppi oppure aggiungendo l’utente direttamente ai progetti.

Nota

La configurazione del dominio viene eseguita da Prevu3D nell’ambito dell’onboarding Enterprise SSO. Contatta support@prevu3d.com per rivendicare i tuoi domini email.

Finché il dominio non è configurato, gli utenti del tuo dominio non vengono reindirizzati al tuo IdP e possono ricevere un errore invalid_user_email_domain durante l’autenticazione.

Attenzione

Gli utenti creati tramite SSO partono senza accesso ai progetti. Concedi l’accesso ai progetti tramite i Gruppi (con la mappatura dei gruppi) oppure aggiungendo gli utenti direttamente ai progetti.

Gli utenti di un dominio configurato per l’SSO dovrebbero accedere tramite SSO anziché creare un account con password dal link di un invito via email.

Utenti esistenti e collegamento degli account

Gli account creati prima dell’abilitazione dell’SSO devono essere collegati una sola volta al tuo provider di identità prima di poter essere usati con l’SSO. Gli utenti vengono guidati in questa procedura la prima volta che accedono tramite SSO, e i loro progetti e dati vengono conservati. I passaggi che vedono sono descritti in Registrazione e accesso.

Attenzione

Il collegamento richiede la password Prevu3D esistente di ciascun utente, quindi chiunque l’abbia dimenticata deve reimpostarla prima di poter effettuare il collegamento.

Per evitare del tutto questo passaggio, contatta support@prevu3d.com per collegare tutti gli account del tuo dominio email in un’unica operazione. In questo modo gli utenti non vedranno mai la procedura di collegamento.

Convalida della configurazione

Prima di distribuire l’SSO su larga scala, esegui un test con un piccolo gruppo di utenti e verifica che:

• L’accesso avvenga correttamente sia dalla pagina di accesso Prevu3D (Accedi tramite SSO) sia dalla dashboard del tuo IdP.

• Il nome e il cognome siano compilati correttamente sui nuovi account.

• Nessun utente riceva permessi più ampi del previsto.

• Le appartenenze ai gruppi vengano applicate come previsto, se utilizzi la mappatura dei gruppi.

Nota

Una traccia SAML acquisita con un’estensione del browser come SAML-tracer è il modo più rapido per verificare esattamente quali attributi e quale valore di audience invia il tuo IdP.

Mappatura dei gruppi (opzionale)

È anche possibile mappare i gruppi dal tuo sistema IdP ai gruppi Prevu3D per semplificare la gestione dell’accesso per le persone della tua organizzazione. I seguenti passaggi ti guidano nella mappatura dei tuoi gruppi.

• Configura il tuo IdP per trasmettere le appartenenze ai gruppi tramite un attributo SAML.

• Inserisci questo attributo nella scheda SSO di Prevu3D.

• Nella sezione “Gruppi” di Prevu3D, fai clic su “Modifica gruppo” e specifica il valore del gruppo SAML previsto dal tuo IdP.

• Questa mappatura viene applicata agli utenti quando accedono a Prevu3D Cloud. Se l’utente è già connesso, dovrà disconnettersi e riconnettersi affinché le modifiche all’accesso abbiano effetto.

Nota

• La mappatura dei gruppi viene applicata all’accesso. Gli utenti devono disconnettersi e riconnettersi per applicare l’accesso aggiornato.

• Assicurati che al gruppo sia concesso qualche accesso; per maggiori informazioni, consulta la sezione gruppi.

Attenzione

• Se SCIM è abilitato, la creazione dei gruppi e l’assegnazione delle appartenenze dovrebbero invece essere gestite tramite SCIM.

SCIM 2.0 – Configurazione del provisioning

Prevu3D supporta il provisioning di utenti e gruppi tramite il protocollo SCIM 2.0 (System for Cross-Domain Identity Management).

Prerequisiti

• La tua organizzazione deve avere il piano Enterprise.

• Il tuo IdP deve supportare SCIM (ad es. Azure AD/Entra, Okta, JumpCloud).

Cosa abilita SCIM

• Provisioning degli utenti – I nuovi utenti vengono creati automaticamente in Prevu3D

• Deprovisioning degli utenti – Gli utenti vengono disabilitati o rimossi quando vengono disabilitati nel tuo IdP

• Assegnazione dei gruppi – Gruppi e ruoli possono essere gestiti centralmente dal tuo IdP

Guida alla configurazione

1. Accedi al tuo account Prevu3D come amministratore dell’organizzazione.

2. Vai alla scheda Impostazioni

3. Seleziona la scheda SSO dal menu a sinistra

4. Scorri fino alla sezione Provisioning SCIM e abilitala.

   

5. Troverai:

   • URL di base SCIM (utenti di Entra ID, consultate l’avviso qui sotto)

   • Bearer Token

Nota

Puoi anche ruotare il bearer token quando necessario per motivi di sicurezza o rotazione delle credenziali.

Attenzione

Quando configuri SCIM con Entra ID (Azure AD), devi aggiungere ?aadOptscim062020 alla fine dell’URL di base SCIM fornito da Prevu3D.

6. Nel tuo provider di identità (ad es. Microsoft Entra ID):

   • Apri l’applicazione enterprise Prevu3D.

   • Abilita il provisioning SCIM.

   • Inserisci l’URL di base SCIM e il Bearer Token ottenuti dalla scheda SSO.

7. Configura le mappature degli attributi per:

   • userName, givenName, familyName, email

   • Opzionali: groups, roles, active

8. Salva la configurazione

   Il tuo IdP sincronizzerà ora automaticamente utenti e gruppi con Prevu3D in base alla pianificazione del provisioning.

Risoluzione dei problemi

Sintomo	Causa probabile	Cosa fare
L’accesso non si completa dopo che l’IdP reindirizza nuovamente a Prevu3D	Il valore di audience nell’asserzione SAML non corrisponde esattamente all’Entity ID del Service Provider. Il tuo IdP potrebbe inviare un valore abbreviato o un nome descrittivo.	Nel tuo IdP, imposta il campo Audience / Identifier / Entity ID sul valore esatto mostrato nella scheda SSO, incluso il suffisso completo.
L’utente inserisce email e password nella pagina di accesso e non viene mai indirizzato all’IdP	Il modulo di accesso principale è riservato agli account con password.	Chiedi all’utente di cliccare su Accedi tramite SSO sotto il pulsante Login, quindi di inserire la propria email aziendale.
Nessun reindirizzamento dopo l’inserimento di un’email aziendale nella schermata Accedi tramite SSO	Il dominio email non è associato alla tua organizzazione Prevu3D.	Contatta support@prevu3d.com per configurare il tuo dominio email.
{"statusCode":401,"message":"invalid_user_email_domain"} dopo l’autenticazione presso l’IdP	Stessa causa: il dominio email dell’utente non è associato alla tua organizzazione.	Contatta support@prevu3d.com per configurare il tuo dominio email.
L’utente vede “sessione scaduta” e gli viene chiesto di reinserire la propria email	Fa parte del normale processo una tantum di collegamento degli account creati prima dell’abilitazione dell’SSO.	Chiedi all’utente di proseguire; non si tratta di un errore. Vedi Utenti esistenti e collegamento degli account.
Un utente esistente non riesce a completare il collegamento dell’account	Il collegamento richiede la password Prevu3D esistente dell’utente, che potrebbe non ricordare.	Chiedigli di reimpostarla con Password dimenticata?, oppure richiedi il collegamento in blocco per il tuo dominio a support@prevu3d.com.
I nomi risultano vuoti o errati sui nuovi account	Le SAML Attribute Key inserite nella scheda SSO non corrispondono ai nomi degli attributi inviati dal tuo IdP. Questi valori distinguono maiuscole e minuscole.	Acquisisci una traccia SAML, controlla i nomi degli attributi nell’AttributeStatement e aggiorna le mappature in modo che corrispondano esattamente.
Le modifiche all’accesso tramite gruppi non hanno effetto	La mappatura dei gruppi viene applicata solo all’accesso.	Chiedi all’utente di disconnettersi e riconnettersi.
L’apertura diretta nel browser dell’URL dell’endpoint del Service Provider restituisce {"statusCode":500,"message":"Internal server error"}	È il comportamento previsto. Questo endpoint accetta solo richieste SAML POST e non può essere aperto direttamente in un browser.	Non indica un problema di configurazione. Esegui il test accedendo dalla pagina di accesso o dal tuo IdP.

Nota

Se il problema persiste, acquisisci una traccia SAML di un tentativo di accesso non riuscito, oscura i valori sensibili e inviala a support@prevu3d.com. Includi il valore di audience e i nomi degli attributi mostrati nell’asserzione — questo consente al nostro team di diagnosticare la maggior parte dei casi in un solo passaggio.

Risoluzione degli errori di accesso

Quando qualcuno non riesce ad accedere tramite SSO a causa di un problema di configurazione, Prevu3D mostra una pagina di errore con un breve codice di errore. In qualità di amministratore, individua il codice corrispondente qui sotto e segui la relativa soluzione — ciascuna si risolve nell’applicazione SAML del tuo IdP oppure nella scheda SSO di Prevu3D.

Nota

Alcuni errori vengono mostrati all’utente per un problema di idoneità, non di configurazione — ad esempio un dominio email non associato alla tua organizzazione, un account che non è membro, oppure un account che deve ancora essere collegato (vedi Utenti esistenti e collegamento degli account). Questi casi non richiedono alcuna modifica al tuo IdP o alla scheda SSO.

Configurazione non trovata

Codice: ConfigNotFound

Non esiste alcuna configurazione SAML per la tua organizzazione — l’SSO non è mai stato configurato, oppure la configurazione è stata rimossa.

Come risolvere: Configura l’SSO nella scheda SSO (Impostazioni → SSO) con i metadati del tuo IdP — vedi Passaggi sopra — e verifica che l’applicazione del tuo IdP sia indirizzata all’organizzazione Prevu3D corretta.

Asserzione email mancante

Codice: MissingEmailAssertion

La risposta SAML del tuo IdP non includeva un indirizzo email (né un NameID).

Come risolvere: Nell’applicazione SAML del tuo IdP, mappa l’attributo email (o NameID) in modo che venga incluso nell’asserzione.

Firma della risposta non valida

Codice: InvalidResponseSignature

La firma della risposta SAML non ha superato la convalida. Questo di solito significa che il certificato memorizzato nella scheda SSO non corrisponde più al certificato di firma attuale del tuo IdP, oppure che la risposta non è firmata affatto.

Come risolvere: Copia il certificato di firma x509 attuale del tuo IdP nella scheda SSO, e assicurati che il tuo IdP sia configurato per firmare la risposta SAML.

Errore del certificato

Codice: CertificateError

Il certificato memorizzato nella scheda SSO non è ben formato, è scaduto, oppure non è stato possibile analizzarlo.

Come risolvere: Incolla un certificato x509 valido in formato PEM dal tuo IdP. Se quello attuale è scaduto, ruotalo.

Mancata corrispondenza dell’audience

Codice: AudienceMismatch

L’audience configurata nel tuo IdP non corrisponde all’Entity ID del Service Provider che Prevu3D si aspetta per la tua organizzazione.

Come risolvere: Imposta il campo Audience / Identifier / Entity ID nel tuo IdP sull’esatto Entity ID del Service Provider mostrato nella scheda SSO, incluso il suffisso completo.

Mappatura del ruolo non valida

Codice: InvalidRoleMapping

Un valore di ruolo inviato dal tuo IdP non corrisponde a nessun ruolo valido dell’organizzazione Prevu3D.

Come risolvere: L’assegnazione dei ruoli da un attributo SAML è stata rimossa, quindi questo codice riguarda solo le organizzazioni che conservano ancora un attributo di ruolo da una configurazione precedente. Assegna i ruoli tramite la Mappatura dei gruppi e contatta support@prevu3d.com se l’errore persiste.

Definizioni

• IdP, Identity Provider: si riferisce al sistema che registra tutti gli utenti e abilita la connessione a vari altri servizi. È la tua fonte di verità per organizzazione, utenti e gruppi. Ad es.: Azure AD, JumpCloud…

• SP, Service Provider: si riferisce all’applicazione di servizio che consuma le informazioni SSO, in questo caso Prevu3D Cloud.

• SSO, Single Sign-On: si riferisce a un meccanismo che consente agli utenti di ottenere le proprie credenziali da un unico portale e distribuire la configurazione della gestione degli utenti su più applicazioni.

• SAML, Security Assertion Markup Language: un protocollo diffuso a livello di settore che consente l’uso dell’SSO su più piattaforme cloud.

• SCIM, System for Cross-Domain Identity Management: protocollo per il provisioning di utenti e gruppi.