Single Sign-On
Federa l'accesso alla Console con OIDC o SAML 2.0 — Entra ID, Google Workspace, Okta e Keycloak, con mapping dei gruppi sui ruoli.
Il Single Sign-On consente ai tuoi utenti di accedere alla Console con le credenziali aziendali già in uso, senza password dedicate. Sono supportati OpenID Connect (OIDC) e SAML 2.0.
Prima di iniziare
- Ruolo Amministratore tenant oppure permesso identity:sso:write
- Diritti di amministrazione sul tuo identity provider per registrare una applicazione
- Un dominio email verificato nel tenant, es. acme.it
- Un account di emergenza con password, escluso dal login federato
Prepara l'account di emergenza prima di iniziare
Se attivi l'enforcement del login federato e l'identity provider diventa irraggiungibile, nessuno può più entrare. Crea prima un account di emergenza con password e MFA, escluso dal SSO, con credenziali custodite in cassaforte. Vedi la sezione dedicata più avanti.
OIDC o SAML: quale scegliere
| Aspetto | OIDC | SAML 2.0 |
|---|---|---|
| Configurazione | Più semplice, discovery automatica | Scambio di metadati e certificati |
| Provider consigliati | Entra ID, Google Workspace, Okta, Keycloak, Auth0 | ADFS, provider legacy, alcune configurazioni PA |
| Trasporto | JSON su HTTPS | XML firmato |
| Rotazione dei certificati | Automatica via JWKS | Manuale, con scadenza da presidiare |
| Consiglio | Preferito dove disponibile | Usalo se il tuo provider non offre OIDC |
Configurazione OIDC
Valori da comunicare al tuo identity provider
Redirect URI (callback)
https://console.blupantheon.com/auth/callbackDeve corrispondere esattamente, incluso lo schema https e senza barra finale.
URL di disconnessione (post logout)
https://console.blupantheon.com/auth/logoutFacoltativo, abilita la disconnessione propagata (single logout).
Identificativo dell'applicazione (audience)
https://console.blupantheon.comDa usare come audience se il provider lo richiede esplicitamente.
Valori da inserire in Blu Pantheon
Configurazione OIDC
| Parametro | Tipo | Obblig. | Default | Descrizione |
|---|---|---|---|---|
discoveryUrl | string | Sì | — | URL del documento di discovery, tipicamente termina con /.well-known/openid-configuration. Da qui vengono ricavati automaticamente endpoint di autorizzazione, token, userinfo e JWKS. |
clientId | string | Sì | — | Identificativo dell’applicazione registrata sul tuo identity provider. |
clientSecret | string | Sì | — | Segreto dell’applicazione. Viene cifrato e non è più visibile dopo il salvataggio. |
scopes | string | Sì | openid profile email | Ambiti richiesti. Aggiungi groups oppure l’ambito equivalente del tuo provider per il mapping dei ruoli. |
emailDomains | array | Sì | — | Domini email autorizzati ad accedere via SSO, es. acme.it e acme-group.com. |
jitProvisioning | boolean | No | true | Crea automaticamente l’utenza al primo accesso riuscito. |
defaultRole | string | No | operator | Ruolo assegnato agli utenti creati automaticamente quando nessuna regola di gruppo corrisponde. |
enforceSso | boolean | No | false | Disabilita il login con password per tutti gli utenti del dominio, esclusi gli account di emergenza. |
Mapping dei claim
Claim del token di identità
| Parametro | Tipo | Obblig. | Default | Descrizione |
|---|---|---|---|---|
sub | string | Sì | — | Identificativo stabile e univoco dell’utente presso il provider. È la chiave di correlazione: non deve mai cambiare per la stessa persona. |
email | string | Sì | — | Indirizzo email. Il dominio deve essere fra quelli autorizzati. |
email_verified | boolean | No | — | Se presente e valorizzato a false, l’accesso viene rifiutato. |
given_name | string | No | — | Nome. Popola il campo nome dell’utenza. |
family_name | string | No | — | Cognome. Popola il campo cognome dell’utenza. |
name | string | No | — | Nome completo, usato come ripiego se given_name e family_name mancano. |
groups | array | No | — | Elenco dei gruppi di appartenenza, usato per il mapping automatico sui ruoli. |
preferred_username | string | No | — | Nome utente mostrato nell’interfaccia, se diverso dall’email. |
Non usare l'email come chiave di identità
La correlazione avviene su sub, non su email. Se un utente cambia indirizzo email
mantiene la propria utenza; se invece cambia sub (per esempio perché ricreato nel provider)
viene trattato come persona nuova e perde ruoli e assegnazioni.
Configurazione SAML 2.0
Valori da comunicare al tuo identity provider
Entity ID (Audience URI)
https://console.blupantheon.com/saml/metadataIdentificativo del service provider.
ACS URL (Assertion Consumer Service)
https://console.blupantheon.com/saml/acsEndpoint che riceve l'asserzione. Binding HTTP-POST.
Single Logout URL
https://console.blupantheon.com/saml/sloFacoltativo, per la disconnessione propagata.
URL dei metadati del service provider
https://console.blupantheon.com/saml/metadataMolti provider permettono di importarli automaticamente da questo URL.
| Parametro | Valore richiesto |
|---|---|
| NameID format | urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress |
| Binding di richiesta | HTTP-Redirect |
| Binding di risposta | HTTP-POST |
| Asserzione firmata | Obbligatoria |
| Risposta firmata | Consigliata |
| Asserzione cifrata | Supportata, facoltativa |
| Algoritmo di firma | RSA-SHA256 |
| Digest | SHA-256 |
Mapping degli attributi
Attributi SAML attesi
| Parametro | Tipo | Obblig. | Default | Descrizione |
|---|---|---|---|---|
NameID | string | Sì | — | Indirizzo email dell’utente, in formato emailAddress. |
email | string | Sì | — | Indirizzo email. Su Entra ID corrisponde a http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress. |
givenName | string | No | — | Nome dell’utente. |
surname | string | No | — | Cognome dell’utente. |
groups | array | No | — | Gruppi di appartenenza, per il mapping automatico sui ruoli. |
employeeId | string | No | — | Identificativo interno, utile per la correlazione con i sistemi HR. |
Presidia la scadenza del certificato di firma
Il certificato dell'identity provider ha una scadenza, tipicamente da 1 a 3 anni. Alla scadenza il SSO smette di funzionare senza preavviso. La Console mostra un avviso a 60, 30 e 7 giorni dalla scadenza e invia una notifica ai contatti di sicurezza: non ignorarla.
Configurazione per provider
Registra l'applicazione
Nel portale Azure apri Microsoft Entra ID › Registrazioni app › Nuova registrazione.
Nome: Blu Pantheon Console. Tipi di account supportati: solo la tua directory organizzativa.
Imposta il redirect URI
Piattaforma Web, URI di reindirizzamento
https://console.blupantheon.com/auth/callback.
Crea il segreto client
In Certificati e segreti › Nuovo segreto client genera il segreto e copialo subito: non sarà più visibile. Imposta una scadenza di 24 mesi e annotala in calendario.
Configura i claim dei gruppi
In Configurazione token › Aggiungi claim gruppi scegli Gruppi assegnati all'applicazione per evitare token di dimensioni eccessive. Seleziona sAMAccountName o Group ID come formato: annota quale, perché è il valore da usare nelle regole di mapping.
Concedi i permessi
In Autorizzazioni API verifica la presenza di openid, profile, email e User.Read,
poi concedi il consenso amministratore.
Raccogli i valori per Blu Pantheon
Nella panoramica della registrazione trovi ID applicazione (client) e ID directory (tenant).
L'URL di discovery è
https://login.microsoftonline.com/ID-DIRECTORY/v2.0/.well-known/openid-configuration.
Completa la configurazione in Console
Inserisci discovery URL, client ID e client secret, imposta gli ambiti a
openid profile email e aggiungi il dominio acme.it fra quelli autorizzati.
Assegna gli utenti all'applicazione
In Applicazioni aziendali › Blu Pantheon Console › Utenti e gruppi assegna i gruppi che devono poter accedere. Senza assegnazione l'accesso viene rifiutato.
Provisioning al primo accesso (JIT)
Con il provisioning just-in-time attivo, al primo accesso riuscito l'utenza viene creata automaticamente con i dati provenienti dal token.
L'utente avvia l'accesso
Nella pagina di login inserisce l'email aziendale: riconosciuto il dominio, viene reindirizzato all'identity provider.
Autenticazione presso il provider
L'utente si autentica con le credenziali aziendali e l'eventuale MFA gestito dal provider.
Creazione dell'utenza
Blu Pantheon crea l'utenza con nome, cognome ed email dai claim, e assegna il ruolo derivante dal mapping dei gruppi oppure il ruolo predefinito.
Accessi successivi
A ogni accesso i dati anagrafici e i ruoli derivati dai gruppi vengono riallineati al contenuto del token.
Il JIT non revoca le utenze
Se disattivi una persona sul provider, non potrà più accedere, ma l'utenza resta presente in Blu Pantheon. Per una rimozione completa disattiva l'utenza anche in Console o programma una revisione periodica.
Mapping dei gruppi sui ruoli
| Gruppo nel provider | Ruolo in Blu Pantheon | Effetto |
|---|---|---|
bp-amministratori | Amministratore tenant | Accesso completo, inclusa la gestione utenti |
bp-supervisori | Supervisore | Gestione delle code, statistiche, riassegnazione |
bp-operatori | Operatore | Gestione delle conversazioni assegnate |
bp-configuratori | Configuratore | Progetti, knowledge base, strumenti |
bp-privacy | Referente privacy | Audit log e richieste degli interessati, sola lettura sui dati |
bp-amministrazione | Amministrazione | Fatturazione e consumi |
Regole di valutazione:
- le regole sono valutate nell'ordine in cui compaiono nell'elenco;
- se un utente appartiene a più gruppi mappati, i ruoli si sommano;
- se nessuna regola corrisponde, viene assegnato il ruolo predefinito;
- se il ruolo predefinito è vuoto, l'accesso viene rifiutato: è la configurazione più restrittiva e consigliata per gli ambienti sensibili;
- i ruoli assegnati manualmente in Console vengono sovrascritti a ogni accesso se il mapping dei gruppi è attivo.
Provalo con un utente di test
Prima di attivare il mapping su tutta la popolazione, verifica con un utente appartenente a un solo gruppo e controlla i ruoli risultanti nella sua scheda in Amministrazione › Utenti.
Enforcement del login federato
Attivando l'enforcement:
- il login con password viene disabilitato per tutti gli utenti dei domini configurati;
- le sessioni attive con autenticazione a password vengono invalidate;
- il recupero password viene disattivato: la gestione delle credenziali passa al provider;
- gli account di emergenza esplicitamente esclusi continuano ad accedere con password e MFA;
- le chiavi API non sono influenzate: le integrazioni continuano a funzionare.
Verifica il SSO prima di attivare l'enforcement
Attiva l'enforcement solo dopo aver verificato che almeno tre utenti reali, con ruoli diversi, accedano correttamente via SSO. Un enforcement attivato su una configurazione incompleta blocca l'intero tenant.
Account di emergenza
Crea un'utenza dedicata
Usa un indirizzo su un dominio diverso da quello federato, per esempio
emergenza@acme-ops.it. Nome: “Accesso di emergenza”.
Assegna il ruolo di Amministratore tenant
Deve poter disattivare l'enforcement del SSO in caso di indisponibilità del provider.
Escludilo dal SSO
Nella scheda dell'utenza attiva Escludi dal login federato.
Proteggi le credenziali
Password lunga e casuale, MFA attivo, credenziali e codici di recupero custoditi in cassaforte o in un gestore di segreti aziendale con accesso a doppio controllo.
Verifica trimestralmente
Prova l'accesso ogni tre mesi e documenta l'esito. Un account di emergenza mai testato è un account che non funziona quando serve.
Monitora l'uso dell'account di emergenza
Configura un alert su
auth.login.succeeded per questa utenza: ogni utilizzo deve essere giustificato e tracciato.
Risoluzione dei problemi
L'URI registrato sul provider deve coincidere carattere per carattere con
https://console.blupantheon.com/auth/callback. Cause tipiche: barra finale in eccesso,
http invece di https, differenze di maiuscole nel percorso, presenza di un parametro
di query. Correggi sul provider e riprova: non è necessario ricreare la configurazione.
L'indirizzo dell'utente appartiene a un dominio non incluso in emailDomains. Aggiungi il
dominio nella configurazione SSO. Attenzione ai domini secondari e agli alias: acme-group.com
va aggiunto esplicitamente anche se punta alla stessa organizzazione.
Il mapping dei gruppi non ha prodotto corrispondenze e il ruolo predefinito è vuoto.
Verifica che il claim groups sia effettivamente presente nel token: nel dettaglio del
tentativo di accesso, in Single Sign-On › Registro, sono elencati i claim ricevuti
(senza valori sensibili). Se il claim manca, il provider non lo sta inviando: rivedi la
configurazione del mapper e degli ambiti richiesti.
Tipico di Entra ID con utenti appartenenti a centinaia di gruppi. Configura il claim gruppi su Gruppi assegnati all'applicazione invece che su tutti i gruppi, oppure applica un filtro per prefisso. In alternativa disattiva il mapping automatico e gestisci i ruoli in Console.
Cause più frequenti: certificato scaduto o ruotato sul provider senza aggiornarlo in Console; algoritmo di firma diverso da RSA-SHA256; asserzione non firmata quando la firma è obbligatoria; disallineamento dell'orologio fra i sistemi superiore a 5 minuti. Scarica i metadati aggiornati dal provider e reimportali nella configurazione.
Usa l'account di emergenza per entrare e disattivare l'enforcement. Se non l'hai creato, l'unica via è aprire una richiesta di supporto in priorità P1 a support@blupantheon.com dall'indirizzo di un referente amministrativo registrato: la disattivazione richiede una verifica di identità rafforzata e può richiedere diverse ore. È esattamente lo scenario che l'account di emergenza serve a evitare.
Molto probabilmente il suo identificativo sub è cambiato lato provider, tipicamente perché
l'account è stato eliminato e ricreato. Blu Pantheon lo tratta come una persona nuova.
Riassegna manualmente i ruoli e, se necessario, unisci le due utenze contattando il supporto.