Single Sign On#

Un database Konga può essere configurato in modo che gli utenti vi accedano con le credenziali di un provider di identità esterno, anziché con nome utente e password di Konga. Sono supportati Microsoft Entra ID (già Azure Active Directory) e qualsiasi server compatibile con lo standard OpenID Connect.

L’accesso in questa modalità detta Single Sign On (SSO) funziona in Konga, in Konga Client e nel client web. Tutto il dialogo con il provider (richiesta di autorizzazione e scambio del codice con il token di accesso) è svolto da Konga Server; al client spetta solo di aprire la pagina di accesso del provider e di raccoglierne l’esito. Konga Server usa il flusso authorization code con PKCE e non conserva alcun segreto dell’applicazione: sul provider l’applicazione va quindi registrata come client pubblico.

Indirizzi di ritorno#

Al termine dell’accesso il provider rimanda il browser dell’utente a un indirizzo di ritorno (redirect URI), che deve essere registrato sul provider esattamente come Konga lo richiede. Gli indirizzi da registrare dipendono dalle modalità di accesso usate:

  • Browser di sistema (Konga e Konga Client): http://localhost/auth

    La pagina di accesso del provider viene aperta nel browser predefinito del computer, e Konga ne raccoglie l’esito su una porta locale scelta di volta in volta; i provider ignorano la porta degli indirizzi localhost, per cui va registrato l’indirizzo senza porta. È la modalità predefinita per le nuove configurazioni SSO.

  • Finestra integrata (Konga e Konga Client): konga://auth/oidc

    La pagina di accesso del provider viene aperta in una finestra di Konga. È la modalità delle configurazioni SSO create con versioni di Konga precedenti alla 2.2.0, che la mantengono finché non si attiva il browser di sistema.

  • Client web: https://<indirizzo del sito>/client/auth

    La pagina di ritorno del client web, così come la vede il browser dell’utente; va registrato un indirizzo per ogni nome con cui gli utenti raggiungono il client web (ad esempio https://konga.esempio.it/client/auth, ma anche l’eventuale indirizzo in rete locale o quello pubblicato da un proxy). Ad eccezione di localhost, il sito deve essere raggiungibile in https; non occorre invece che sia raggiungibile dal provider, perché all’indirizzo di ritorno arriva solo il browser dell’utente.

Nota

La finestra integrata non può usare le passkey né le chiavi di sicurezza, che Microsoft Entra ID propone sempre più spesso come primo metodo di accesso: in quel caso occorre scegliere un altro metodo nella pagina del provider, oppure passare al browser di sistema. Quando la pagina del provider chiede una passkey, Konga lo segnala e permette di annullare l’accesso; l’accesso può essere annullato anche in qualsiasi momento premendo Esc.

Registrazione dell’applicazione sul provider#

Microsoft Entra ID#

Dal portale di Microsoft Entra ID (Registrazioni app) creare una nuova registrazione per Konga, quindi:

  • annotare l”ID applicazione (client) e l”ID della directory (tenant), da riportare nella configurazione del database;

  • nella sezione Autenticazione, aggiungere la piattaforma Applicazioni per dispositivi mobili e desktop e registrarvi gli indirizzi di ritorno delle modalità di accesso usate (si veda sopra), compresi quelli del client web;

  • non occorre creare alcun segreto client.

Avvertimento

Gli indirizzi di ritorno non vanno registrati sotto la piattaforma Applicazione a pagina singola (SPA): Microsoft Entra ID consentirebbe lo scambio del codice solo dal browser, mentre in Konga lo effettua il server, e l’accesso fallirebbe con l’errore AADSTS9002327. Vale anche per l’indirizzo del client web.

Per assegnare automaticamente gli utenti ai gruppi di Konga (si veda Utenti e gruppi), nella sezione Configurazione token aggiungere l’attestazione dei gruppi (groups) al token ID.

Server OpenID Connect personalizzato#

Il server deve pubblicare il documento di discovery all’indirizzo <indirizzo del server>/.well-known/openid-configuration, e consentire a Konga di registrarsi come client pubblico con PKCE, senza segreto, con gli indirizzi di ritorno delle modalità di accesso usate. Per il browser di sistema il server deve accettare l’indirizzo http://localhost/auth su qualsiasi porta, come previsto dallo standard per le applicazioni native (RFC 8252). Konga richiede gli scope openid profile email offline_access.

Configurazione del database#

La configurazione SSO si imposta per ogni database da Configura database…, nella pagina Sicurezza (visibile solo agli utenti che hanno il permesso di modificare le impostazioni di sicurezza). Selezionando SSO (Single Sign On) come Metodo di autenticazione sono disponibili le seguenti impostazioni:

  • Provider: Microsoft Entra ID oppure Server personalizzato.

  • ID Applicazione (client): l’identificativo dell’applicazione registrata sul provider.

  • ID Tenant (solo Microsoft Entra ID): l’identificativo della directory in cui è registrata l’applicazione.

  • Indirizzo del server (solo server personalizzato): l’indirizzo del server OpenID Connect, a cui Konga aggiunge /.well-known/openid-configuration; il pulsante Test verifica che il server risponda.

  • Rinnova automaticamente l’autenticazione con il provider: quando l’autenticazione di un utente scade, Konga Server la rinnova presso il provider senza chiedere un nuovo accesso, finché il provider lo consente.

  • Usa il browser di sistema per l’accesso SSO: l’accesso avviene nel browser predefinito del computer anziché nella finestra integrata; attivo per le nuove configurazioni. Non si applica al client web, che usa sempre il browser.

  • Indirizzi di ritorno web: gli indirizzi di ritorno del client web consentiti per questo database, che devono corrispondere a quelli registrati sul provider. Si può inserire anche solo l’indirizzo del sito (ad esempio https://konga.esempio.it): Konga lo completa con /client/auth. In grigio sono elencati gli indirizzi del client web aperto sul computer stesso del server (localhost e 127.0.0.1), sempre consentiti e non modificabili; anche questi, se usati, vanno registrati sul provider.

Sotto le impostazioni è riportato l’indirizzo di ritorno del browser di sistema da registrare sul provider, con un pulsante per copiarlo.

Nota

Konga Server accetta solo gli indirizzi di ritorno previsti dalla configurazione del database: konga://auth/oidc sempre, http://localhost/auth solo se è attivo il browser di sistema, e quelli del client web solo se elencati (o se sono quelli del computer del server). In questo modo un client non può far recapitare il codice di accesso a un indirizzo arbitrario.

Utenti e gruppi#

Gli utenti SSO non vanno creati in anticipo: al primo accesso Konga crea automaticamente l’utente corrispondente, di tipo SSO. Il nome utente è preso, nell’ordine, dalle informazioni preferred_username o email fornite dal provider (in mancanza di entrambe, dall’identificativo sub), e il nome completo dall’informazione name.

A ogni accesso l’utente viene associato a un gruppo di Konga, da cui eredita i permessi:

  • se il token del provider contiene l’informazione konga_user_group, o l’elenco dei gruppi groups, viene usato il primo gruppo di Konga che ha lo stesso nome (senza distinzione fra maiuscole e minuscole);

  • altrimenti l’utente viene associato al gruppo di Konga chiamato default, se esiste;

  • in mancanza anche di questo, l’utente non è associato ad alcun gruppo.

Per sfruttare l’associazione automatica occorre quindi creare in Konga dei gruppi con lo stesso nome dei gruppi indicati dal provider. Microsoft Entra ID, per i gruppi creati nel cloud, indica nell’attestazione groups l”ID oggetto del gruppo anziché il suo nome: in questo caso il gruppo di Konga va chiamato con l’ID oggetto del gruppo Entra.

Un utente SSO disabilitato o eliminato in Konga non può più accedere, anche se il provider lo autentica correttamente.

Accesso al database#

All’apertura di un database configurato per l’SSO, Konga avvia l’accesso presso il provider anziché chiedere nome utente e password. L’autenticazione ottenuta viene conservata in forma cifrata sul computer dell’utente, per cui alle aperture successive l’accesso avviene senza passare dal provider finché l’autenticazione è valida (o finché può essere rinnovata, se è attivo il rinnovo automatico).

Se il provider, nello scambiare il codice di accesso, richiede all’utente un’ulteriore verifica (ad esempio un secondo fattore richiesto dai criteri di accesso condizionale di Microsoft Entra ID), Konga ripropone automaticamente la pagina di accesso del provider.

Nel client web l’accesso apre la pagina del provider in una finestra a comparsa. Poiché i browser aprono le finestre a comparsa solo in seguito a un clic dell’utente, quando questo non è più possibile all’apertura del database è la pagina stessa del client web a passare dal provider, per poi tornare al client web e completare l’apertura; se invece ci sono già finestre aperte, che andrebbero perse, Konga mostra un pulsante Accedi da premere per aprire la pagina del provider.

Nota

Tenendo premuto il tasto Alt all’apertura del database, Konga chiede nome utente e password invece di avviare l’accesso SSO. Questo permette di accedere con un utente Konga non SSO, ad esempio un amministratore, anche quando il provider non è raggiungibile o la configurazione SSO è errata.