SAML¶

Introduzione¶

Connetti il tuo identity provider SAML (Security Assertion Markup Language) come metodo di single sign-on (SSO). SAML è uno standard aperto per l’autenticazione SSO (tra le altre cose). Gli accessi sono condivisi tra più service provider e gestiti da un identity provider (IdP) centrale.

In questo caso, il service provider è Zammad, e l’IdP è un servizio software che ospiti o a cui ti abboni (ad es. Keycloak, Redhat SSO Server, ADFS, o Okta).

Questa guida presuppone che tu stia già utilizzando SAML all’interno della tua organizzazione (cioè che il tuo IdP sia completamente configurato).

Configurazione di base¶

Questa sezione descrive la configurazione di un IdP in modo generale. Vedi Guide di configurazione per le guide di configurazione per Keycloak e SAML di Microsoft.

Configura il tuo IdP¶

Aggiungi Zammad come Client/App¶

Importa Zammad nel tuo IdP utilizzando la configurazione XML trovata su https://your.zammad.domain/auth/saml/metadata.

Se il tuo IdP non supporta l’importazione XML, dovrai configurare Zammad come un nuovo client/app manualmente utilizzando il file di metadati XML sopra come riferimento.

Ad esempio, quando vedi questo tag:

<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="http://your.zammad.domain/auth/saml/callback" index="0" isDefault="true"/>

Imposta l”URL di Binding del Service Consumer di Asserzione (a volte indicato anche come URI di reindirizzamento validi) su http://your.zammad.domain/auth/saml/callback.

Configura il mapping degli attributi utente¶

Zammad richiede i seguenti attributi utente (o “proprietà”) dall’IdP:

Indirizzo email (email)
Nome completo (name)
Nome proprio (first_name)
Cognome (last_name)

Potrebbe essere necessario impostare dei “mapper” (o “mapping”) per indicare al tuo IdP come gli attributi utente in SAML corrispondono a quelli in Zammad. Per una ripartizione più dettagliata, fai riferimento al file di metadati XML citato nella sezione precedente.

Guide di configurazione¶

Puoi trovare guide di configurazione specifiche per:

Se stai utilizzando un altro IdP, adattalo alle tue esigenze. Per una descrizione dei campi in Zammad, continua a leggere qui sotto.

Configurazione generale di Zammad¶

Abilita SAML e inserisci i dettagli del tuo IdP nel Pannello di Amministrazione sotto Impostazioni > Sicurezza > Applicazioni di terze parti > Autenticazione tramite SAML:

Nome visualizzato

Ti permette di definire un nome personalizzato per il pulsante SAML. Questo aiuta i tuoi utenti a capire meglio cosa fa il pulsante sulla pagina di login.

Il default è SAML.

URL di destinazione SSO IdP

Questo è l’URL di destinazione a cui Zammad deve reindirizzare quando l’utente preme il pulsante SAML.

URL di destinazione logout singolo IdP

Questo è l’URL a cui la richiesta e la risposta di logout singolo devono essere inviate.

Certificato IdP

Il certificato pubblico del tuo IdP affinché Zammad possa verificarlo durante la fase di callback.

Impronta digitale del certificato IdP

L’impronta digitale del certificato pubblico del tuo IdP da verificare durante la fase di callback.

Nota

🔏 Per il certificato IdP / impronta digitale del certificato:

Fornisci solo uno dei due—non fornire entrambi! (Tra i due, raccomandiamo il certificato di firma stesso: le impronte digitali usano SHA-1, che è stato compromesso da un po” di tempo.)

Utenti Keycloak: Trova il tuo certificato nel pannello di amministrazione Keycloak sotto Impostazioni Realm > Chiavi > Algoritmo: RS256 > Certificato.

Formato identificatore nome

Questo è il tipo di campo per gli identificatori univoci. Di solito dovrebbe essere urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.

Zammad si aspetta un indirizzo email come identificatore univoco!

Nome attributo UID

Qui puoi definire un attributo che identifica univocamente l’utente. Se non impostato, viene utilizzato l’identificatore nome restituito dall’IdP.

Verifica SSL

Decidi se il certificato per la connessione al servizio IdP debba essere verificato o meno (default: sì).

Pericolo

Si prega di essere consapevoli che disattivare la verifica SSL è un rischio per la sicurezza. Dovrebbe essere usato solo temporaneamente o a scopo di test. Se disattivato, non c’è verifica del certificato, il che significa che qualsiasi certificato presentato verrà accettato.

Firma e Crittografia

Definisci se vuoi firmare, crittografare, fare entrambe le cose o nulla per le richieste.

Certificato (PEM)

Incolla il certificato pubblico del tuo client SAML Zammad, se desideri crittografare le richieste.

Assicurati che il certificato sia:

già valido e non ancora scaduto
non un certificato CA
valido per firmare e crittografare

Chiave privata (PEM)

Incolla qui la chiave privata del tuo client SAML Zammad, se desideri firmare le richieste.

Assicurati che la chiave sia una chiave RSA con una lunghezza di almeno 2048 bit.

Segreto chiave privata

Se la tua chiave privata è protetta da un segreto, puoi fornirlo qui.

Il tuo URL di callback

Questo URL è necessario per la configurazione del tuo IdP in modo che sappia dove reindirizzare dopo l’autenticazione riuscita.

Suggerimento

Dopo aver salvato il tuo input facendo clic sul pulsante «Invia», Zammad verifica le chiavi/certificati forniti (ad es. se sono validi per la firma/crittografia e se non sono scaduti).

Vedi collegamento automatico account per dettagli su come collegare account Zammad esistenti ad account IdP.

Risoluzione problemi¶

Il collegamento automatico account non funziona: Hai ricontrollato la configurazione del mapping degli attributi utente del tuo IdP?
Il logout non funziona: Nel caso in cui il tuo processo di logout non funzioni, puoi provare https://<tuo-url-zammad>/auth/saml/slo come alternativa. Tuttavia, in tal caso non viene inviato alcun logout al tuo IdP.