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.

La creazione di utenti just-in-time non è attualmente supportata. Gli utenti devono avere un account preesistente in KanbanBOX. La gestione delle identità può essere automatizzata tramite l'API di KanbanBOX, ma questo è fuori dallo scopo di questo documento.

Ruoli e responsabilità

Ruolo	Responsabilità
Team IT del cliente	Configurare l'applicazione IdP, fornire i metadata, eseguire i test di validazione
Supporto KanbanBOX	Configurare l'SSO in KanbanBOX per ogni Plant richiesto e confermare l'attivazione

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

Procedura di configurazione

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

Nella maggior parte dei casi, puoi usare le configurazioni standard del SP KanbanBOX:

• KanbanBOX-production.sp per l'ambiente di Produzione KanbanBOX
• KanbanBOX-testing.sp per l'ambiente di Test 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.

Raccomandiamo di configurare due SP separati nell'ambiente di produzione del tuo Identity Provider, per abilitare gli utenti ad accedere con SSO a entrambi gli ambienti di KanbanBOX (Produzione e Test).

1.1 Solo per utenti Okta

Se stai usando Okta come tuo Identity Provider, troverai KanbanBOX nel catalogo delle app. L'applicazione preconfigurata è valida solo per l'ambiente di produzione di KanbanBOX.

Per completare la configurazione, segui questi passaggi in Okta:

1. Aggiungi l'applicazione KanbanBOX dal catalogo delle app.
2. Dalla scheda "Sign On" all'interno dell'applicazione, fai clic su "Edit" e carica il certificato che trovi nei metadata SP all'indirizzo https://app.kanbanbox.com/help/sso_configuration_details.
3. Da Sign On > Sign on methods > SAML 2.0, annota il Metadata URL: ti servirà nei passaggi successivi.

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 dell'Identity Provider (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.

SP-initiated SSO

Per informazioni sul flusso di login SP-initiated, consulta Come effettuare il login con SSO.

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.