Connessione a un Identity Provider (IdP)

Questa sezione spiega come collegare un Identity Provider (IdP) esterno a un Tenant di DS3 Composer, in modo che gli utenti possano accedere alla DS3 Console tramite single sign-on (SSO). La piattaforma reindirizza gli utenti all'IdP, convalida il risultato dell'autenticazione restituito dall'IdP e crea o associa l'account corrispondente nel Tenant.

Le impostazioni per l'integrazione SAML 2.0 e la procedura passo passo per PingOne sono descritte di seguito.

Come funziona il flusso di sign-in

L'integrazione supporta solo il sign-in avviato dalla DS3 Console. Il flusso è il seguente:

1. L'utente apre la pagina di sign-in della DS3 Console del Tenant. La console mostra un pulsante per ogni provider configurato nelle impostazioni del Tenant.
2. L'utente seleziona il pulsante del provider. La piattaforma avvia il sign-in con l'IdP e reindirizza il browser verso di esso.
3. L'utente si autentica con l'IdP.
4. L'IdP restituisce il risultato dell'autenticazione alla piattaforma.
5. La piattaforma convalida il risultato e legge le informazioni dell'utente. Al primo sign-in riuscito, l'account viene creato automaticamente nel Tenant (provisioning just-in-time).
6. La piattaforma reindirizza il browser alla DS3 Console e l'utente ha effettuato l'accesso.

attenzione

Gli utenti devono sempre avviare il flusso dalla pagina di sign-in della DS3 Console. Il sign-in avviato dall'IdP (IdP-initiated), in cui il flusso parte dal portale dell'IdP, non è supportato.

Troubleshooting

Sintomo	Causa probabile	Risoluzione
403 Forbidden dopo il ritorno dall'IdP	Non è stato possibile associare o creare l'account. Cause comuni: la registrazione è disattivata per il Tenant, il dominio email non è consentito, l'account è bannato oppure l'email appartiene già a un account creato con un metodo di sign-in diverso.	Controlla le impostazioni di registrazione e i dati dell'account utente.

Gli errori specifici del protocollo, come le risposte 400, 401 e 502 o valori di Entity ID e ACS URL non corrispondenti, sono trattati nelle sezioni Troubleshooting SAML e Troubleshooting PingOne di seguito.

Integrazione SAML 2.0

Le impostazioni SAML 2.0 sono condivise da ogni Identity Provider (IdP) SAML che puoi collegare a un Tenant di DS3 Composer: i valori di connessione, gli attributi dell'asserzione e le impostazioni IdP consigliate. I passaggi specifici dei provider sono descritti nella sezione PingOne di seguito.

info

Il SAML SSO deve essere abilitato sul Coordinator da un amministratore di piattaforma prima di poter essere configurato su un Tenant. Per i prerequisiti di piattaforma, i campi delle impostazioni del Tenant e l'endpoint dei metadati SAML, consulta la sezione Sign in with SAML 2.0 nella pagina di configurazione del Tenant (in inglese). Se la sezione SAML SSO non è visibile nelle impostazioni del tuo Tenant, contatta il tuo amministratore di piattaforma.

Valori di connessione

La maggior parte dei problemi di integrazione deriva da una mancata corrispondenza tra l'applicazione IdP e le impostazioni del Tenant. L'Entity ID e l'ACS URL devono essere identici su entrambi i lati, mentre l'IdP metadata URL si inserisce solo nelle impostazioni del Tenant:

Valore	Dove si configura	Descrizione
Entity ID	Applicazione IdP e impostazioni del Tenant	Un identificatore univoco per il Service Provider, scelto da te. La stessa identica stringa deve essere configurata su entrambi i lati. Alcuni IdP etichettano questo campo come Audience o SP Entity ID.
IdP metadata URL	Impostazioni del Tenant	L'URL HTTPS in cui l'IdP pubblica i propri metadati SAML. La piattaforma recupera questo URL per individuare l'endpoint SSO e i certificati di firma dell'IdP.
ACS URL	Applicazione IdP e impostazioni del Tenant	https://{console-domain}/api/iam/v1/auth/saml/acs. Deve usare il dominio della console, non il dominio API.

Attributi dell'asserzione

La piattaforma legge le informazioni dell'utente dagli attributi dell'asserzione SAML. I nomi degli attributi distinguono maiuscole e minuscole e devono corrispondere esattamente. Sono accettati i seguenti nomi per i campi di identità usati nel sign-in:

Scopo	Nomi degli attributi SAML accettati	Obbligatorio
Email	email, mail, urn:oid:0.9.2342.19200300.100.1.3	Sì. Il sign-in fallisce se manca l'attributo email.
Nome	given_name, givenName, firstName, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname	No
Cognome	family_name, sn, lastName, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname	No

Quando un attributo contiene più di un valore, la piattaforma utilizza il primo valore.

Impostazioni IdP consigliate

• Firma le asserzioni. La piattaforma verifica la firma utilizzando i certificati pubblicati nei metadati dell'IdP.
• Usa l'algoritmo di firma RSA-SHA256. La piattaforma firma le proprie richieste di autenticazione con RSA-SHA256.
• Usa il binding HTTP-Redirect per la richiesta di autenticazione e il binding HTTP-POST per la risposta.
• Imposta il formato Subject NameID su emailAddress (consigliato).

Troubleshooting SAML

Sintomo	Causa probabile	Risoluzione
400 Bad Request su /api/iam/v1/auth/saml/acs	Il tentativo di sign-in è stato interrotto o ripetuto, quindi la richiesta non è più valida. Ogni tentativo può essere completato una sola volta.	Riavvia il flusso dalla pagina di sign-in della DS3 Console.
401 Unauthorized sull'ACS URL	L'asserzione SAML è stata rifiutata dalla piattaforma.	Controlla la mappatura degli attributi. La causa più comune è un attributo email mancante o un attributo email con un nome non incluso nell'elenco accettato (vedi la tabella sopra).
502 Bad Gateway subito dopo aver selezionato il pulsante del provider	La piattaforma non è riuscita a recuperare o analizzare i metadati dell'IdP.	Verifica che l'URL dei metadati dell'IdP sia raggiungibile, utilizzi HTTPS e restituisca l'XML dei metadati dell'IdP.
Errore sul lato IdP relativo all'applicazione o all'ACS URL	L'Entity ID o l'ACS URL configurati nell'IdP non corrispondono alle impostazioni del Tenant.	Verifica che entrambi i valori siano identici sul lato IdP e nelle impostazioni del Tenant.
Errore di salvataggio nelle impostazioni del Tenant: "SAML provider URL is malformed"	Il campo URL contiene un valore non valido.	Inserisci un URL assoluto completo https:// senza spazi circostanti.

PingOne

Questa sezione illustra come collegare PingOne come Identity Provider (IdP) SAML 2.0 per un Tenant di DS3 Composer, dalla configurazione dell'applicazione PingOne alle impostazioni del Tenant e a un sign-in di prova.

Prima di iniziare, consulta il flusso di sign-in qui sopra, i valori di connessione e gli attributi dell'asserzione dell'integrazione SAML 2.0. Verifica con il tuo amministratore di piattaforma che il SAML SSO sia abilitato sul Coordinator; vedi la sezione Sign in with SAML 2.0 (in inglese).

In questa sezione vengono utilizzati i seguenti segnaposto:

Segnaposto	Significato
{console-domain}	Il dominio della DS3 Console del Tenant (ad esempio console.example.com).
{environment-id}	L'ID del tuo ambiente PingOne.
{application-id}	L'ID dell'applicazione PingOne creata in questa sezione.

info

Le console di amministrazione PingOne sono specifiche per regione. Questa sezione utilizza come esempio la regione europea (console.pingone.eu, auth.pingone.eu); sostituisci il dominio con quello della tua regione, ad esempio console.pingone.com e auth.pingone.com in Nord America. L'URL di sign-in della console di amministrazione include l'ID del tuo ambiente, ad esempio https://console.pingone.eu/?env=<environment-id>. Mantieni la stessa regione per la console di amministrazione e per l'URL dei metadati.

Crea l'applicazione SAML in PingOne

1. Accedi alla console di amministrazione PingOne della tua regione, ad esempio https://console.pingone.eu/?env=<environment-id>.
2. Vai su Applications → Applications e fai clic su + Add Application.
3. Inserisci un nome, ad esempio Cubbit, e seleziona SAML Application come tipo di applicazione.

Configura l'applicazione PingOne

1. Nella scheda Configuration, imposta i valori del Service Provider:
   • ACS URLs: https://{console-domain}/api/iam/v1/auth/saml/acs
   • Entity ID: l'Entity ID che hai scelto per questa integrazione, identico al valore che inserirai nelle impostazioni del Tenant (vedi Valori di connessione).
2. Nella scheda Attribute Mappings, aggiungi una mappatura per ogni riga, utilizzando i nomi degli attributi esatti attesi dalla piattaforma, che distinguono maiuscole e minuscole:
   • Attributo SAML email → attributo PingOne user.email (obbligatorio)
   • Attributo SAML given_name → attributo PingOne user.name.given
   • Attributo SAML family_name → attributo PingOne user.name.family
3. Torna alla scheda Configuration, mantieni Sign Assertion abilitato (impostazione predefinita) con RSA-SHA256 come algoritmo di firma e imposta il formato Subject NameID su emailAddress (consigliato).
4. Abilita l'applicazione con l'interruttore Enabled.
5. Apri la scheda Overview e copia l'URL dei metadati IdP da Connection Details. L'URL ha la forma https://auth.pingone.eu/<environment-id>/saml20/metadata/<application-id>, dove <environment-id> e <application-id> identificano il tuo ambiente e la tua applicazione. Puoi anche usare Download Metadata per rivedere l'XML dei metadati.

Configura il Tenant in DS3 Composer

1. Accedi a DS3 Composer, apri Tenants e seleziona il Tenant.
2. Apri Settings e trova la sezione SAML SSO in General.
3. Abilita l'interruttore SAML e compila i campi:
   • Entity ID: lo stesso Entity ID configurato nell'applicazione PingOne.
   • Name: un nome per questo provider, ad esempio PingOne. La console usa questo nome per etichettare il pulsante di sign-in.
   • IdP Metadata URL: l'URL dei metadati PingOne copiato nella sezione precedente.
   • ACS URL: https://{console-domain}/api/iam/v1/auth/saml/acs, lo stesso URL configurato in PingOne.
4. Salva le impostazioni.

Testa il sign-in

1. Apri la pagina di sign-in della DS3 Console del Tenant (ad esempio https://{console-domain}/signin) e seleziona il pulsante PingOne.
2. Accedi a PingOne con lo username di un utente della directory, non con l'indirizzo email, e la password corrispondente.
3. Al primo sign-in riuscito, la piattaforma crea l'account nel Tenant e reindirizza il browser alla DS3 Console.

attenzione

Se PingOne richiede un cambio password al primo sign-in, completalo e poi avvia di nuovo il flusso dalla pagina di sign-in della DS3 Console. Un cambio password può superare la validità del tentativo di sign-in, quindi il primo tentativo potrebbe andare in timeout e richiedere un secondo tentativo di accesso dalla DS3 Console.

Troubleshooting PingOne

Per gli errori SAML generici (400, 401, 502, Entity ID o ACS URL non corrispondenti e messaggi relativi a URL malformati), consulta la sezione Troubleshooting SAML qui sopra.

Controlli specifici per PingOne:

• PingOne rifiuta l'indirizzo email nella sua pagina di sign-in: PingOne si aspetta lo username della directory, non l'indirizzo email, nel proprio modulo di sign-in.
• 401 Unauthorized dopo un sign-in riuscito su PingOne: verifica che l'utente della directory abbia un indirizzo email impostato in PingOne e che la mappatura dell'attributo email esista esattamente come mostrato sopra.
• PingOne rifiuta l'utente prima che DS3 riceva una risposta: se l'accesso all'applicazione è limitato a gruppi selezionati, assegna l'utente o il suo gruppo all'applicazione (scheda Access).