Single Sign-On è un meccanismo che ti consente di autenticare gli utenti nei tuoi sistemi e di comunicare a Zendesk che gli utenti sono stati autenticati. Se usi Single Sign-On con JSON Web Token (JWT), un utente viene verificato automaticamente con il provider di identità quando effettua l'accesso. All'utente viene quindi consentito di accedere a Zendesk senza che gli venga chiesto di inserire credenziali di accesso separate.
In qualità di amministratore Zendesk, il tuo ruolo consiste nell’abilitare le opzioni SSO. Il presente articolo spiega come abilitare più configurazioni Single Sign-On JWT che possono essere utilizzate per l’autenticazione dei membri del team (amministratori e agenti, inclusi agenti interni e collaboratori), degli utenti finali o di entrambi.
La parte centrale di Single Sign-On è un meccanismo di sicurezza che consente a Zendesk di fidarsi delle richieste di accesso ricevute dai sistemi. Zendesk concede l'accesso solo agli utenti che hai autenticato. SSO Zendesk si affida a JWT per proteggere lo scambio dei dati di autenticazione degli utenti.
- Funzionamento di SSO JWT per Zendesk
- Requisiti per l'abilitazione di SSO JWT
- Abilitazione di SSO JWT
- Assegnazione di SSO JWT agli utenti
- Gestione di utenti in Zendesk dopo l'abilitazione di SSO JWT
- Generazione di un nuovo segreto condiviso
- Cambiamento del metodo di autenticazione
- Ulteriori informazioni su JWT
In genere, il team IT di un'azienda è responsabile dell'impostazione e della gestione del sistema di autenticazione JWT dell'azienda. Il suo ruolo è implementare SSO per Zendesk nel sistema. Invita il team a leggere il seguente argomento in questo articolo:
Articoli correlati:
Funzionamento di SSO JWT per Zendesk
Una volta abilitato il servizio SSO, le richieste di accesso vengono indirizzate a una pagina di accesso esterna a Zendesk Support.
Passaggi del processo di autenticazione SSO JWT:
- Un utente non autenticato accede all'URL del tuo Zendesk Support. Esempio: https://yoursubdomain.zendesk.com/.
- Il meccanismo SSO di Zendesk riconosce che l'autenticazione SSO è abilitata e che l'utente non è autenticato.
- Zendesk tenta di determinare se l’utente non autenticato è un utente finale o un membro del team e lo reindirizza alla pagina di accesso remoto appropriata dell’organizzazione. Esempio: https://mycompany.com/zendesk/sso.
- Uno script sul server remoto autentica l'utente usando la procedura di accesso proprietaria dell'organizzazione.
- Il sistema di autenticazione crea una richiesta JWT contenente i dati utente pertinenti.
- Il sistema di autenticazione reindirizza l'utente al seguente endpoint Zendesk con il payload JWT:
https://yoursubdomain.zendesk.com/access/jwt
- Zendesk verifica il token, quindi analizza i dettagli dell'utente dal payload JWT e concede all'utente una sessione.
Come puoi vedere, questo processo si basa sul reindirizzamento del browser e sul passaggio di messaggi firmati con JWT. I reindirizzamenti avvengono interamente nel browser e non esiste una connessione diretta tra Zendesk e i tuoi sistemi, quindi puoi tenere gli script di autenticazione al sicuro dietro il firewall aziendale.
Requisiti per l'abilitazione di SSO JWT
Incontra il team responsabile del sistema di autenticazione JWT (di solito il team IT) per assicurarti che il traffico diretto a Zendesk sia su HTTPS e non su HTTP.
- L'URL di accesso remoto al quale gli utenti Zendesk devono essere reindirizzati quando tentano di accedere a Zendesk
- (Facoltativo) L'URL di disconnessione remota a cui Zendesk può reindirizzare gli utenti dopo che si sono disconnessi da Zendesk
- (Facoltativo) Un elenco di intervalli IP per reindirizzare gli utenti all'opzione di accesso appropriata. Gli utenti che effettuano richieste dagli intervalli IP specificati vengono indirizzati al modulo di accesso con autenticazione JWT remota. Gli utenti che effettuano richieste da indirizzi IP al di fuori degli intervalli vengono indirizzati al modulo di accesso Zendesk normale. Se non specifichi un intervallo, tutti gli utenti vengono reindirizzati al modulo di accesso con autenticazione remota.
Il team IT potrebbe avere bisogno di ulteriori informazioni da Zendesk per configurare l’implementazione JWT. Invita il team a consultare Foglio di lavoro per l’implementazione tecnica in questo articolo.
Dopo essersi assicurati di soddisfare tutti i requisiti e di disporre di tutte le informazioni necessarie, è possibile abilitare SSO JWT.
Abilitazione di SSO JWT
Gli amministratori possono abilitare Single Sign-On JWT solo per gli utenti finali, solo per i membri del team (inclusi agenti interni e collaboratori) o per entrambi i gruppi. Puoi creare molteplici configurazioni SSO JWT. Prima di iniziare, richiedi le informazioni necessarie al team IT della tua azienda. Consulta Requisiti per l'abilitazione di SSO JWT.
Per abilitare Single Sign-On JWT
- Nel Centro amministrativo, fai clic su
Account nella barra laterale, quindi seleziona Sicurezza > Single Sign-On. - Fai clic su Crea configurazione SSO, quindi seleziona JSON Web Token.
- Inserisci un Nome configurazione univoco.
- In URL di accesso remoto, inserisci l'URL al quale gli utenti devono essere reindirizzati quando tentano di accedere all'URL del tuo Zendesk.
Zendesk aggiunge automaticamente un parametro brand_id all'URL. Questo è il brand Zendesk Support usato dall'utente quando ha tentato di accedere.
- (Facoltativo) In URL di uscita remota, inserisci l’URL di uscita a cui gli utenti devono essere reindirizzati quando si disconnettono da Zendesk.
Zendesk aggiunge automaticamente i parametri email, external_id e brand_id all'URL di uscita. Se preferisci non includere l'indirizzo email e l'ID esterno nell'URL, specifica parametri vuoti nell'URL di uscita. Esempio:
https://www.xyz.com/user/signout/?email=&external_id=
Nota: se stai usando un’applicazione Ember.js, devi modificare l’URL di uscita per usare parametri vuoti prima dell’hash. Ad esempio,https://somedomain.com/?brand_id=&return_to=&email=#/zendesk-login/. - (Facoltativo) Per Intervalli IP, inserisci un elenco di intervalli IP per reindirizzare gli utenti all'opzione di accesso appropriata.
Gli utenti che effettuano richieste dagli intervalli IP specificati vengono indirizzati al modulo di accesso con autenticazione JWT. Gli utenti che effettuano richieste da indirizzi IP al di fuori degli intervalli vengono indirizzati al modulo di accesso Zendesk normale. Non specificare un intervallo se vuoi che tutti gli utenti vengano reindirizzati al modulo di accesso con autenticazione JWT.
- Se usi ID esterni per gli utenti, puoi aggiornarli in Zendesk Support selezionando Attivato per Aggiornamento di ID esterni?.
- Fornisci il segreto condiviso al team IT. Ne avranno bisogno per l’implementazione JWT. Importante: conserva il segreto condiviso in un luogo sicuro. Se viene compromesso, tutti i dati nel tuo account Support saranno a rischio.
- Seleziona Mostra pulsante all’accesso degli utenti per aggiungere il pulsante Continua con SSO alla pagina di accesso a Zendesk.
Puoi personalizzare l’etichetta del pulsante inserendo un valore nel campo Nome pulsante. Le etichette dei pulsanti personalizzate sono utili se aggiungi più pulsanti SSO alla pagina di accesso. Per maggiori informazioni, consulta Aggiunta di pulsanti “Continua con SSO” alla pagina di accesso Zendesk.
- Fai clic su Salva.
Per impostazione predefinita, le configurazioni SSO aziendali sono disattivate. Assegna la configurazione SSO agli utenti per attivarla.
Assegnazione di SSO JWT agli utenti
Una volta creata una configurazione SSO JWT, devi attivarla assegnandola agli utenti finali, ai membri del team o a entrambi.
Per assegnare una configurazione SSO ai membri del team o agli utenti finali
- Apri le impostazioni di sicurezza per i membri del team o gli utenti finali.
- Nel Centro amministrativo, fai clic su Account nella barra laterale, quindi seleziona Sicurezza > Autenticazione membri del team.
- Nel Centro amministrativo, fai clic su Account nella barra laterale, quindi seleziona Sicurezza > Autenticazione utenti finali.
- Nel Centro amministrativo, fai clic su
- Seleziona Autenticazione esterna per mostrare le opzioni di autenticazione.
- Seleziona i nomi delle configurazioni SSO da usare.
Single Sign-On potrebbe non coprire tutti i casi d'uso, pertanto l'autenticazione Zendesk rimane attiva per impostazione predefinita.
- Scegli come consentire agli utenti di accedere.
L’opzione Consenti loro di scegliere abilita gli utenti ad accedere usando qualsiasi metodo di autenticazione attivo. Consulta Accesso a Zendesk per gli utenti in diverse modalità.
Il reindirizzamento a SSO consente agli utenti di autenticarsi solo usando la configurazione SSO principale. Gli utenti non vedono ulteriori opzioni di accesso, anche se sono attive. Quando selezioni Reindirizza a SSO, viene visualizzato il campo SSO principale per selezionare la configurazione SSO principale.
- Fai clic su Salva.
Gestione di utenti in Zendesk dopo l'abilitazione di SSO JWT
Dopo aver abilitato il Single Sign-On JWT in Zendesk, le modifiche apportate agli utenti esterni a Zendesk non vengono sincronizzate automaticamente con il tuo account Zendesk. Gli utenti vengono aggiornati in Zendesk al momento dell’autenticazione. Ad esempio, se un utente viene aggiunto al tuo sistema interno, quando accede a Zendesk viene aggiunto al tuo account Zendesk. Se un utente viene eliminato dal sistema interno, non sarà più in grado di accedere a Zendesk. Tuttavia, il suo account continuerà a esistere in Zendesk.
Per impostazione predefinita, quando il Single Sign-On è abilitato, gli unici dati utente memorizzati in Zendesk sono il nome e l'indirizzo email dell'utente. Zendesk non memorizza le password. Di conseguenza, dovresti disattivare le notifiche email automatizzate di Zendesk sulle password.
Per migliorare l’esperienza clienti, in Zendesk potresti memorizzare non solo il nome e l’indirizzo email dell’utente, ma anche altri dati. Puoi farlo usando attributi JWT aggiuntivi.
Disabilitazione delle email di notifica sulle password di Zendesk
Per ogni nuovo utente che accede al tuo account Zendesk usando SAML, JWT o OpenID Connect (OIDC) come opzione di Single Sign-On viene creato un profilo utente Zendesk. Poiché gli utenti vengono autenticati tramite un IdP con una password non Zendesk, il profilo viene creato senza password in quanto non è necessario accedere a Zendesk.
Poiché i nuovi utenti che accedono a Zendesk tramite SSO vengono verificati tramite un IdP, non ricevono notifiche email per la verifica del proprio account. Tuttavia, è comunque consigliabile disattivare le notifiche email automatiche per impedire che vengano inviate nel caso in cui la verifica dell’utente tramite IdP non andasse a buon fine. Nel caso dell’SSO, la verifica degli utenti deve sempre avvenire tramite IdP.
Per disattivare le email di notifica sulle password
- In Centro amministrativo, fai clic sull’icona Persone
nella barra laterale, quindi seleziona Configurazione > Utenti finali. - Nella sezione Email relative all’account, deseleziona Invia un’email di benvenuto anche quando un nuovo utente viene creato da un agente o un amministratore.
- In Consenti agli utenti di cambiare la propria password, deseleziona questa opzione.
Generazione di un nuovo segreto condiviso
In alcuni casi, ad esempio se il segreto è compromesso, potrebbe essere necessario emettere un nuovo segreto condiviso JWT e fornirlo al team IT o al provider di identità esterno. Puoi generare un nuovo segreto condiviso JWT dal Centro amministrativo Zendesk. Questa azione creerà un nuovo segreto e annullerà quello vecchio. Per mantenere attiva l'autenticazione dell'account SSO Zendesk, devi comunicare al tuo provider di identità esterno il nuovo segreto condiviso.
Per generare un nuovo segreto condiviso
- Nel Centro amministrativo, fai clic su Account nella barra laterale, quindi seleziona Sicurezza > Single Sign-On.
- Posiziona il cursore del mouse sulla configurazione JWT per la quale vuoi creare un nuovo segreto condiviso, quindi fai clic sull’icona del menu delle opzioni (
) e seleziona Modifica. - Scorri fino a Segreto condiviso in fondo alla pagina di configurazione e fai clic su Reimposta segreto.
Viene visualizzato un messaggio di conferma.
- Fai clic su Reimposta segreto per confermare il ripristino.
Dovresti vedere un nuovo segreto condiviso in testo normale.
- Fai clic su Copia per creare una copia del nuovo segreto condiviso e trasmetterla al team IT o al provider di identità esterno.
- Salva le modifiche.
Modifica del metodo di autenticazione
Se usi un metodo SSO di terzi per creare e autenticare gli utenti in Zendesk e poi passi all’autenticazione Zendesk, questi utenti non avranno una password per l’accesso. Per ottenere l’accesso, chiedi a questi utenti di reimpostare la loro password dalla pagina di accesso a Zendesk.
Ulteriori informazioni su JWT
JWT è uno standard aperto, gestito dall'ente di standardizzazione internazionale IETF, che ha sostenitori di alto livello nel settore tecnologico (ad esempio Microsoft, Facebook e Google).
Gli elementi fondamentali di JWT sono componenti ben compresi e il risultato è una specifica relativamente semplice, disponibile sul sito http://tools.ietf.org/html/draft-jones-json-web-token-10. Esistono molte implementazioni open source della specifica JWT che coprono la maggior parte delle tecnologie moderne. Ciò significa che puoi configurare Single Sign-On JWT senza troppe difficoltà.
Una cosa da tenere presente è che il payload JWT è semplicemente codificato e firmato, non crittografato, quindi non inserire dati sensibili nella tabella hash. JWT funziona serializzando il JSON che viene trasmesso a una stringa. La stringa è codificata in Base64 e quindi JWT la converte in HMAC, facendola dipendere dal segreto condiviso. Ciò produce una firma che il destinatario può usare per convalidare l'utente.
Foglio di lavoro per l'implementazione tecnica
Questa sezione è destinata al team responsabile del sistema di autenticazione JWT dell'azienda. Fornisce dettagli sull'implementazione SSO JWT di Zendesk.
Argomenti trattati:
Algoritmo JWT
Specifica HS256 come algoritmo JWT nell'intestazione del tuo payload JWT:
{
"typ":"JWT",
"alg":"HS256"
}HS256 è l’acronimo di HMAC SHA 256, un algoritmo di crittografia a 256 bit ideato dalla NSA (National Security Agency, Agenzia per la Sicurezza Nazionale degli Stati Uniti)
Endpoint JWT Zendesk
Dopo aver autenticato l’utente, crea il payload JWT e invia una richiesta POST contenente il payload JWT al seguente endpoint Zendesk:
https://yoursubdomain.zendesk.com/access/jwt
Il payload deve essere codificato in base64 e inoltrato tramite invio di un modulo da un client. L’invio del payload con una richiesta AJAX, fetch o axios lato client non funzionerà perché la richiesta sarà bloccata dalla policy della stessa originedel client . Anche l’invio di una richiesta POST dal server non funzionerà perché non imposterà correttamente i cookie usati per l’autenticazione nel browser dell’utente.
Il payload JWT deve essere inviato al tuo sottodominio Zendesk Support usando il protocollo https. Esempio:
https://yoursubdomain.zendesk.com/access/jwtI sottodomini mappati all'host non sono supportati.
Attributi JWT
Invia attributi JWT usando un hash (Ruby) o un dizionario (Python). Il JWT deve essere codificato come base64. Esempio d'uso di Ruby:
payload = JWT.encode({
:email => "bob@example.com", :name => "Bob", :iat => Time.now.to_i, :jti => rand(2<<64).to_s
}, "Our shared secret")Zendesk richiede un indirizzo email per identificare l'utente in modo univoco. Oltre agli attributi obbligatori elencati nella tabella seguente, puoi facoltativamente inviare ulteriori dati del profilo utente. Questi dati vengono sincronizzati tra il sistema di gestione degli utenti e Zendesk Support.
| Attributo | Tipo di dati | Descrizione |
|---|---|---|
| iat | Data numerica | Generato alle. Il momento in cui il token è stato generato. Viene usato per garantire l'uso di un dato token poco dopo essere stato generato. Il valore deve essere il numero di secondi trascorsi dall'epoch UNIX. Zendesk consente fino a tre minuti di sfasamento dell'orologio, quindi assicurati di configurare NTP o simili sui tuoi server. |
| jti | stringa | ID JSON Web Token. Un ID univoco per il token, usato da Zendesk per prevenire attacchi di ripetizione dei token. |
| stringa | Indirizzo email dell'utente che sta effettuando l'accesso, usato per identificare in modo univoco il record utente in Zendesk Support. | |
| name | stringa | Il nome dell'utente. L'utente in Zendesk Support verrà creato o aggiornato in base a questo attributo. |
| Attributo | Tipo di dati | Descrizione |
|---|---|---|
| external_id | stringa | Se gli utenti sono identificati in modo univoco mediante qualcosa di diverso da un indirizzo email e i loro indirizzi email sono soggetti a modifiche, invia l'ID univoco dal tuo sistema. Specifica l'ID come stringa. |
| locale (per utenti finali) locale_id (per agenti) |
numero intero | Le impostazioni locali in Zendesk Support, specificate come numero. |
| organization | stringa | Il nome di un'organizzazione a cui aggiungere l'utente. Se l'opzione Gli utenti finali possono appartenere a più organizzazioni è abilitata, le organizzazioni aggiuntive aggiungono l'organizzazione originale e sono considerate organizzazioni secondarie. Questa operazione non elimina le appartenenze esistenti. Se vuoi passare più organizzazioni contemporaneamente, usa l'attributo organizations. I nomi delle organizzazioni devono essere inseriti in una stringa, separati da virgole. |
| organization_id | numero intero | L'ID esterno dell'organizzazione nell'API Zendesk. Se vengono specificati sia organization che organization_id, l'organizzazione viene ignorata. Se l'opzione Gli utenti finali possono appartenere a più organizzazioni è abilitata, le organizzazioni aggiuntive aggiungono l'organizzazione originale e sono considerate organizzazioni secondarie. Questa operazione non elimina le appartenenze esistenti. Se vuoi trasmettere più ID di organizzazioni contemporaneamente, usa l’attributo organization_ids. Gli ID delle organizzazioni devono essere inseriti in una stringa, separati da virgole. |
| phone | stringa | Un numero di telefono, specificato come stringa. Il numero di telefono deve essere conforme al piano di numerazione telefonica internazionale E.164. Esempio: +15551234567. I numeri E164 sono numeri internazionali con il prefisso di selezione del Paese, in genere il prefisso e il numero di un abbonato. Un numero di telefono E.164 valido deve includere il prefisso del paese. |
| tag | array | È un array JSON di tag da impostare per l'utente. Questi tag sostituiscono qualsiasi altro tag esistente nel profilo dell'utente. |
| remote_photo_url | stringa | L’URL di una foto da impostare nel profilo utente. |
| role | stringa | Il ruolo dell’utente. Questo valore può essere impostato su end_user, agent o admin. Il valore predefinito è end_user. Se il ruolo dell’utente è diverso da quello in Zendesk Support, il ruolo viene cambiato in Zendesk Support. |
| custom_role_id | numero intero | Applicabile solo se il ruolo dell'utente è agente. |
| user_fields | oggetto |
Un hash JSON della chiave del campo utente personalizzato e dei valori da impostare per l'utente. Il campo utente personalizzato deve esistere per poter impostare il valore del campo. Ogni campo utente personalizzato è identificato dalla relativa chiave del campo che si trova nelle impostazioni di amministrazione dei campi utente. Il formato dei valori della data è aaaa-mm-gg. Se un valore o una chiave del campo utente personalizzato non è valido, l'aggiornamento del campo non riuscirà senza messaggio di errore e l'utente potrà comunque accedere. Per ulteriori informazioni sui campi utente personalizzati, consulta Aggiunta di campi personalizzati agli utenti.
Nota: l'invio di valori null nell'attributo user_fields rimuoverà qualsiasi valore esistente nei campi corrispondenti.
|
Parametro URL di accesso remoto (return_to)
Il passaggio del parametro return_to è facoltativo, ma lo consigliamo per una migliore esperienza utente. Quando Zendesk reindirizza un utente alla tua pagina di accesso remoto, può passare un parametro URL return_to. Il parametro contiene la pagina che Zendesk restituisce all'utente dopo che il sistema ha autenticato l'utente. Aggiungi il parametro (nome e valore) all'endpoint JWT Zendesk.
Ad esempio, supponi che un agente disconnesso faccia clic sul link seguente per aprire un ticket in Support: https://mycompany.zendesk.com/tickets/1232. Il flusso è il seguente:
- Quando l'utente fa clic, Zendesk reindirizza l'utente all'URL di accesso remoto e aggiunge il seguente parametro
return_toall'URL:https://mycompany.com/zendesk/sso?return_to=https://mycompany.zendesk.com/tickets/123 - Il tuo sistema di autenticazione estrae il parametro
return_todall’URL e, dopo aver autenticato l’utente, lo aggiunge all’endpoint JWT Zendesk o lo aggiunge al corpo della richiesta. Esempio:https://mycompany.zendesk.com/access/jwt?&return_to=https://mycompany.zendesk.com/tickets/123 - Zendesk usa questo parametro per aprire la pagina dei ticket per l'agente.
Il parametro return_to è un URL assoluto per l'interfaccia agente e un URL relativo per il centro assistenza.
return_to contiene i propri parametri URL, assicurati che lo script codifichi l'intero valore return_to in URI quando invii il token JWT. Gestione degli errori
Se Zendesk riscontra un errore durante l'elaborazione di una richiesta di accesso JWT, invia un messaggio che spiega il problema. Se hai specificato un URL di uscita remota durante la configurazione dell'integrazione JWT, viene reindirizzato a quell'URL e trasmette un messaggio e un parametro kind. In caso di errore, il parametro kind ha sempre il valore "error". Zendesk consiglia di specificare un URL di uscita remota e di inserire nella registrazione i messaggi provenienti da Zendesk oltre al tipo. Molti degli errori che possono verificarsi devono essere corretti. Esempi: derive dell’orologio, raggiungimento dei limiti e token non validi.
Esempi di invio di moduli
Il payload JWT deve essere inviato tramite un invio di un modulo da un browser al seguente endpoint Zendesk:
https://yoursubdomain.zendesk.com/access/jwtZendesk fornisce una serie di esempi per vari stack tecnologici nel repository SSO JWT Zendesk su GitHub. Devi inviare il payload JWT usando l’invio di un modulo da un browser per garantire che i cookie possano essere impostati correttamente nel browser e che la richiesta non sia bloccata da CORS.
Risposta
La risposta deve essere HTML con uno stato 200 OK. Il formato della risposta è il seguente:
<html><body>You are being <a href="">redirected</a>.</body></html>Se href corrisponde al valore return_to, l’autenticazione dell’utente è riuscita ed è necessario impostare i cookie. Se href inizia con https://SUBDOMAIN.zendesk.com/access/unauthenticated, Zendesk non ha potuto autenticare l’utente.
Esempi di generazione JWT
La codifica JWT effettiva è semplice e la maggior parte dei linguaggi moderni dispone di librerie che la supportano. Zendesk fornisce una serie di esempi per vari stack nel repository GitHub JWT SSO:
Il codice di generazione JWT è per l’implementazione del server. Puoi ritrasferire il JWT generato alla tua pagina di accesso e quindi avviare l’invio del modulo dal browser.
Se implementi JWT in qualsiasi altro stack, saremmo lieti di esporti un esempio. Aggiungi un commento a questo articolo per condividere ciò che hai implementato.
Se esegui IIS/AD e non intendi creare una tua soluzione .NET, forniamo un'implementazione completa in ASP classico, per la quale ti verrà richiesto di modificare soltanto un paio di variabili. Scarica lo script di autenticazione ASP da Github.