Single Sign-On (SSO) SAML2 in KanbanBOX

Questa guida spiega come abilitare il Single Sign-On (SSO) SAML 2.0 in KanbanBOX.

L'attivazione dell'SSO viene gestita dal Supporto KanbanBOX e deve essere richiesta tramite ticket di supporto.

Ambito

Usa questo documento quando la tua azienda vuole autenticare gli utenti KanbanBOX tramite un Identity Provider (IdP) SAML 2.0, come Microsoft Entra ID, Okta, ADFS o simili.

Funzionalità supportate

The KanbanBOX SAML SSO implementation supports the following features:

• SP-initiated SSO: gli utenti accedono a KanbanBOX e vengono reindirizzati all'IdP per l'autenticazione.
• IdP-initiated SSO: gli utenti accedono all'IdP e vengono reindirizzati a KanbanBOX con un RelayState predefinito.
• SP-initiated SLO (Single Logout): gli utenti possono disconnettersi da KanbanBOX e dall'IdP in un unico flusso.

Ruoli e responsabilità

Prerequisiti

Prima di aprire il ticket, assicurati di avere:

• Un IdP compatibile con SAML 2.0
• Accesso amministrativo al tuo IdP
• L'elenco dei Plant KanbanBOX dove l'SSO deve essere abilitato
• Un nome dominio SSO univoco da associare al Tenant/Plant
• Almeno un utente di test gia presente in KanbanBOX con un'email valida

1. Configura il Service Provider (SP) KanbanBOX nel tuo Identity Provider (IdP)

Quando non sono richieste configurazioni personalizzate, usa queste configurazioni standard del SP KanbanBOX:

• KanbanBOX-testing.sp per l'ambiente di Test KanbanBOX
• KanbanBOX-production.sp per l'ambiente di Produzione KanbanBOX

Puoi trovare i file XML dei metadata SP, insieme ai dettagli per la configurazione SAML, all'interno dell'applicazione KanbanBOX all'indirizzo https://app.kanbanbox.com/help/sso_configuration_details.

Consigliamo di configurare due SP separati per abilitare l'SSO sia in Produzione sia in Test.

2. Apri un ticket di supporto per richiedere l'attivazione SSO

L'SSO viene attivato solo dopo una richiesta al Supporto KanbanBOX.

Includi nel ticket le seguenti informazioni obbligatorie:

• Nome Tenant
• Ambiente target: Test, Produzione, o entrambi
• Elenco Plant o licenza Corporate dove l'SSO deve essere abilitato
• Metadata IdP (file XML allegato, o URL metadata HTTPS)
• Conferma che l'attributo SAML email sia mappato e inviato nell'asserzione
• Dati del contatto tecnico per la validazione (nome ed email)
• Dati del contatto tecnico per eventuali comunicazioni future sull'SSO (nome ed email)

3. Il Supporto KanbanBOX configura l'SSO per ogni Plant

Quando le informazioni del ticket sono complete, il Supporto KanbanBOX:

• Registra la configurazione dell'IdP in KanbanBOX
• Associa la configurazione ai Plant richiesti
• Abilita l'SSO in base all'ambiente richiesto (Test/Produzione)
• Conferma quando si può iniziare la validazione

4. Checklist di validazione dopo l'attivazione

Esegui questi controlli con almeno un utente per ogni Plant abilitato:

1. Login SP-initiated: dalla pagina di login KanbanBOX, inserisci l'email e prosegui con SSO.
2. Login IdP-initiated (se usato): verifica il reindirizzamento a KanbanBOX con il RelayState previsto.
3. Verifica che l'accesso avvenga solo quando email corrisponde a un utente KanbanBOX esistente.
4. Verifica il comportamento sia in Test sia in Produzione, se sono stati richiesti entrambi.

Risoluzione dei problemi

• Utente non riconosciuto dopo il login: verifica che email nell'asserzione SAML corrisponda esattamente all'email utente in KanbanBOX.
• Errore generico di validazione SAML: verifica che i valori ACS URL, Recipient e Audience siano esattamente quelli documentati.
• Il flusso IdP-initiated non arriva a KanbanBOX: verifica il valore RelayState.
• Solo alcuni utenti riescono ad accedere: verifica che l'SSO sia abilitato sui Plant e sugli account utente corretti.

Se il problema persiste, aggiorna lo stesso ticket di supporto con:

• Timestamp del tentativo fallito
• Email dell'utente coinvolto
• Ambiente (Test/Produzione)
• Dettagli diagnostici della risposta SAML dall'IdP (quando disponibili)

Rotazione del certificato

Prima della scadenza del certificato attuale, è necessario seguire questa procedura per il rinnovo:

1. Il team IT del cliente genera un nuovo certificato nell'IdP, senza abilitarlo.
2. Il team IT del cliente apre un ticket al Supporto KanbanBOX e condivide il nuovo certificato (o i metadata aggiornati che lo contengono).
3. Il Supporto KanbanBOX aggiunge il nuovo certificato come certificato secondario nella configurazione SSO.
4. Dopo la conferma del Supporto KanbanBOX, il team IT del cliente puo abilitare il nuovo certificato nell'IdP.

Seguendo questa sequenza, è possibile garantire una transizione fluida senza downtime per gli utenti.

Note su change management e sicurezza

• Mantieni validi i certificati di firma dell'IdP e monitora le date di scadenza.
• Se cambiano metadata, certificati, IdP o dominio email, avvisa il Supporto KanbanBOX prima delle modifiche in produzione.
• Mantieni almeno un percorso di accesso admin non-SSO per il ripristino di emergenza, se consentito dalla policy aziendale.