Uso dell’autenticazione OAuth con la tua applicazione

Quale piano sto usando?

Anteprima: Centro amministrativo > App e integrazioni > API > API Zendesk

Puoi usare OAuth 2 per autenticare tutte le richieste API della tua applicazione a Zendesk. OAuth fornisce alla tua applicazione un modo sicuro per accedere ai dati Zendesk senza dover memorizzare e usare le password degli utenti Zendesk, che sono informazioni sensibili.

Per usare l’autenticazione OAuth, devi registrare la tua applicazione in Zendesk. Devi inoltre aggiungere alcune funzionalità all’applicazione per supportare il flusso di autorizzazione OAuth.

Argomenti trattati in questo articolo:

• Registrazione della tua applicazione in Zendesk
• Implementazione di un flusso di autorizzazione OAuth nella tua applicazione

Argomenti correlati:

• Per un tutorial sulla creazione di un’applicazione web che implementa un flusso di autorizzazione OAuth, consulta Creazione di un’app web OAuth.
• Per implementare un flusso di autorizzazione OAuth nelle app Zendesk, consulta Aggiunta di OAuth di terzi all’app Support.
• Se non è necessario che gli utenti concedano alla tua applicazione l’accesso ai loro account, puoi comunque usare i token OAuth per autenticare le richieste API. Consulta Creazione e uso di token OAuth con l’API.

Registrazione della tua applicazione in Zendesk

Devi registrare la tua applicazione per generare credenziali OAuth che l’applicazione può usare per autenticare le chiamate API a Zendesk.

Nota: questa sezione descrive come configurare un client OAuth per gli utenti di un account Zendesk. Se la tua applicazione non interagirà solo con un account Zendesk, ma con molti altri account, puoi richiedere un client OAuth globale. Un client OAuth globale è un modo più sicuro e appropriato di eseguire l’autenticazione API con più istanze Zendesk. Per maggiori informazioni, consulta Configurazione di un client OAuth globale.

Per registrare la tua applicazione

1. Nel Centro amministrativo, fai clic su App e integrazioni nella barra laterale, quindi seleziona API > API Zendesk.
2. Fai clic sulla scheda Client OAuth nella pagina API Zendesk, quindi fai clic su Aggiungi client OAuth a destra dell’elenco di client OAuth.
3. Compila i campi seguenti per creare un client:
   • Nome client: immetti un nome per l’app. Questo è il nome che gli utenti vedranno quando viene chiesto loro di concedere l’accesso alla tua applicazione e quando controllano l’elenco di app di terzi che hanno accesso al loro Zendesk.
   • Descrizione: facoltativo. Una breve descrizione dell’app che gli utenti vedranno quando verrà chiesto loro di concedere l’accesso a tale app.
   • Azienda: facoltativo. Il nome dell’azienda che gli utenti vedranno quando verrà chiesto loro di concedere l’accesso alla tua applicazione. Le informazioni possono aiutarli a capire a chi stanno concedendo l’accesso.
   • Logo: facoltativo. Il logo che gli utenti vedranno quando verrà chiesto loro di concedere l’accesso alla tua applicazione. L’immagine può essere in formato JPG, GIF o PNG. Per un risultato ottimale, carica un’immagine quadrata. Verrà ridimensionata per la pagina di autorizzazione.
   • Identificatore univoco: il campo viene compilato automaticamente con una versione formattata del nome inserito per l’app, che puoi tuttavia modificare.
   • Tipo di client: pubblico o privato. I client OAuth pubblici sono applicazioni eseguite in ambienti in cui le credenziali non possono essere archiviate in modo sicuro, come app per dispositivi mobili e web. Questi client sono necessari per usare PKCE. I client OAuth privati vengono eseguiti su server sicuri in cui le relative credenziali possono essere mantenute al sicuro. Questi client possono usare PKCE, client secret o entrambi. Consulta i Tipi di client OAuth.
   • URL di reindirizzamento: inserisci l’URL o gli URL che Zendesk deve usare per inviare la decisione dell’utente di concedere l’accesso alla tua applicazione. Gli URL devono essere assoluti e non relativi, https (salvo se localhost o 127.0.0.1) e separati con un a capo.
4. Fai clic su Salva.

   Dopo l’aggiornamento della pagina, nella parte inferiore viene visualizzato un nuovo campo Segreto precompilato. Si tratta del valore "client_secret" specificato nella specifica OAuth2.

5. Copia il valore di Segreto negli appunti e conservalo in un luogo sicuro. Nota: i caratteri possono estendersi oltre la larghezza della casella di testo, quindi assicurati di selezionare tutto prima di copiare.
   Importante: per motivi di sicurezza, il segreto verrà mostrato completamente solo una volta. Dopo aver fatto clic su Salva, potrai accedere solo ai primi nove caratteri.
6. Fai clic su Salva.

Usa l’identificatore univoco e il valore segreto nella tua applicazione come descritto di seguito.

Tipi di client OAuth

I client OAuth Zendesk includono una proprietà kind che viene passata durante la creazione del client OAuth e possono avere uno dei valori seguenti:

• Pubblico: I client OAuth pubblici sono applicazioni eseguite in ambienti in cui le credenziali non possono essere archiviate in modo sicuro, come app per dispositivi mobili e web. Questi client devono usare PKCE.
• Privato: I client OAuth privati vengono eseguiti su server sicuri in cui le relative credenziali possono essere mantenute al sicuro. Questi client possono usare PKCE, client segreti o entrambi.

Per maggiori informazioni, consulta i Tipi di client.

Il tipo di client OAuth Zendesk si applica solo al sistema di ticketing Zendesk Support. Non è supportato in Chat, Conversazioni o Sell.

I client Zendesk OAuth esistenti hanno attualmente la proprietà kind impostata su unknown. Questi client rimangono inalterati finché la proprietà kind viene aggiornata a public o confidential. I nuovi client OAuth creati nel Centro amministrativo devono impostare la proprietà kind durante la creazione.

Nota: Se stai usando un client OAuth Zendesk esistente e prevedi di cambiare la proprietà kind in public, devi prima implementare PKCE. In caso contrario, il client non funzionerà, poiché PKCE sarà immediatamente richiesto.

L’impostazione della proprietà kind è obbligatoria per tutti i nuovi client OAuth creati nel Centro amministrativo. Sebbene la proprietà kind non sia obbligatoria per i client OAuth creati con api/v2/oauth/clients endpoint, Zendesk consiglia di includerla.

Implementazione di un flusso di autorizzazione OAuth nella tua applicazione

Zendesk supporta il flusso di concessione del codice di autorizzazione per ottenere i token di accesso. Questo flusso è denominato flusso di concessione del codice di autorizzazione in quanto è necessario ottenere un codice di autorizzazione prima di poter richiedere un token di accesso. Altri flussi di concessioni sono stati ritirati.

Il flusso non usa token di aggiornamento. Il token di accesso non ha scadenza.

Per implementare il flusso di concessione del codice di autorizzazione, devi aggiungere la seguente funzionalità alla tua applicazione:

• Passaggio 1: indirizzare l’utente alla pagina di autorizzazione Zendesk
• Passaggio 2: gestire la decisione di autorizzazione dell’utente
• Passaggio 3: ottenere un token di accesso da Zendesk
• Passaggio 4: usare il token di accesso nelle chiamate API

Per un tutorial sulla creazione di un’applicazione web che implementa un flusso di autorizzazione OAuth, consulta Creazione di un’app web OAuth.

Il metodo di concessione del codice di autorizzazione supporta la chiave di prova per lo scambio di codice (PKCE), che aggiunge un ulteriore livello di sicurezza. Per ulteriori informazioni, consulta Uso di PKCE per rendere più sicuri i token di accesso OAuth Zendesk nella documentazione per sviluppatori.

Passaggio 1: indirizzare l’utente alla pagina di autorizzazione Zendesk

Innanzitutto, l’applicazione deve indirizzare l’utente alla pagina di autorizzazione Zendesk. La pagina chiede all’utente di autorizzare la tua applicazione ad accedere a Zendesk per suo conto. Dopo che l’utente effettua la scelta, Zendesk la invia all’applicazione insieme ad altre informazioni.

Per indirizzare l’utente alla pagina di autorizzazione Zendesk

Aggiungi un link o un pulsante nella tua applicazione per indirizzare l’utente al seguente URL:

https://{subdomain}.zendesk.com/oauth/authorizations/new

dove {subdomain} è il tuo sottodominio Zendesk. Puoi usare una richiesta POST o GET. Includi i seguenti parametri:

• response_type: obbligatorio. Zendesk restituisce un codice di autorizzazione nella risposta, quindi specifica code come tipo di risposta. Esempio: response_type=code.
• redirect_uri: obbligatorio. L’URL che Zendesk deve usare per inviare la decisione dell’utente di concedere l’accesso alla tua applicazione. L’URL deve essere assoluto e non relativo. Inoltre, deve essere sicuro (https), a meno che non usi localhost o 127.0.0.1.
• client_id: obbligatorio. L’identificatore univoco che hai ottenuto al momento della registrazione della tua applicazione in Zendesk. Consulta la sezione qui sopra.
• scope: obbligatorio. Un elenco di ambiti separati da spazi che controllano l’accesso alle risorse Zendesk. Puoi richiedere un accesso di tipo read, write o impersonate per tutte le risorse o per specifiche risorse. Consulta Impostazione dell’ambito.
• state: una stringa arbitraria inclusa nella risposta di Zendesk dopo che l’utente ha deciso se concedere o meno l’accesso. Puoi usare il parametro per proteggerti da attacchi CSRF(Cross-Site Request Forgery, richiesta intersito falsa). In un attacco CSRF, l’utente finale viene indotto a fare clic su un link che esegue un’azione in un’applicazione web dove l’utente finale è ancora autenticato. Per proteggerti da questo tipo di attacco, aggiungi un valore al parametro state e convalidalo quando ritorna.
• code_challenge: obbligatorio se si usa PKCE. Una stringa che rappresenta una verifica del codice ricavata da un verificatore di codice. Consulta Generazione del valore code_challenge nella documentazione per sviluppatori.
• code_challenge_method: obbligatorio se si usa PKCE. Il metodo usato per ricavare la verifica del codice. Specifica "S256" come valore.

Assicurati di codificare i parametri nell’URL.

Esempio di richiesta GET

https://{subdomain}.zendesk.com/oauth/authorizations/new?response_type=code&redirect_uri={your_redirect_url}&client_id={your_unique_identifier}&scope=read%20write

Nel browser dell’utente finale si apre la pagina di autorizzazione Zendesk. Dopo che l’utente ha preso una decisione, Zendesk la invia all’URL di reindirizzamento specificato nella richiesta.

Impostazione dell’ambito

Devi specificare un ambito per controllare l’accesso dell’app alle risorse Zendesk. L’ambito read consente a un’app di accedere agli endpoint GET. Include l’autorizzazione di trasferire localmente le risorse correlate. L’ambito write consente a un’app di accedere agli endpoint POST, PUT e DELETE per la creazione, l’aggiornamento e l’eliminazione di risorse.

Per ulteriori informazioni sull’ambito, consulta Token OAuth per tipi di concessione.

L’ambito impersonate consente a un amministratore Zendesk di effettuare richieste per conto degli utenti finali. Consulta Esecuzione di richieste API per conto di utenti finali.

Ad esempio, il parametro seguente concede a un’app l’accesso in lettura a tutte le risorse:

"scope": "read"

Il parametro seguente consente l’accesso in lettura e scrittura a tutte le risorse:

"scope": "read write"

Puoi ottimizzare l’ambito per le risorse seguenti:

• ticket
• utenti
• registri di controllo (sola lettura)
• organizzazioni
• centri assistenza
• app
• trigger
• automazioni
• obiettivi
• webhook
• zis

La sintassi è la seguente:

"scope": "resource:scope"

Ad esempio, il parametro seguente limita un’app alla sola lettura dei ticket:

"scope": "tickets:read"

Per concedere a un’app l’accesso in lettura e scrittura a una risorsa, specifica entrambi gli ambiti:

"scope": "users:read users:write"

Per concedere a un’app l’accesso in scrittura a una sola risorsa, ad esempio le organizzazioni, e l’accesso in lettura a tutte le altre risorse:

"scope": "organizations:write read"

Passaggio 2: gestire la decisione di autorizzazione dell’utente

L’applicazione deve gestire la risposta di Zendesk indicando la decisione dell’utente. Le informazioni sono contenute nei parametri URL dell’URL di reindirizzamento.

Se l’utente decide di concedere l’accesso all’applicazione, l’URL di reindirizzamento contiene un codice di autorizzazione. Esempio:

{redirect_url}?code=7xqwtlf3rrdj8uyeb1yf

Il codice di autorizzazione è valido solo per 120 secondi.

Se l’utente decide di non concedere l’accesso all’applicazione, l’URL di reindirizzamento contiene i parametri error e error_description che informano l’app che l’utente ha negato l’accesso:

{redirect_url}?error=access_denied&error_description=The+end-user+or+authorization+server+denied+the+request

Usa questi valori per controllare il flusso della tua applicazione. Se l’URL contiene un parametro code, ottieni un token di accesso da Zendesk come descritto nella sezione seguente. Si tratta del token da includere nelle chiamate API a Zendesk.

Passaggio 3: ottenere un token di accesso da Zendesk

Se l’applicazione ha ricevuto un codice di autorizzazione da Zendesk in risposta all’utente che concede l’accesso, l’applicazione può scambiarlo con un token di accesso. Per ottenere il token di accesso, invia una richiesta POST al seguente endpoint:

https://{subdomain}.zendesk.com/oauth/tokens

Nota: non confondere questo endpoint con l’endpoint Create Token nell’API Token OAuth. Sebbene entrambi gli endpoint restituiscano token di accesso OAuth validi, non condividono lo stesso percorso, lo stesso formato JSON o gli stessi parametri di richiesta.

Includi nella richiesta i seguenti parametri obbligatori:

• grant_type: specifica "authorization_code" come valore.
• code: usa il codice di autorizzazione ricevuto da Zendesk dopo che l’utente ha concesso l’accesso.
• client_id: usa l’identificatore univoco specificato in un client OAuth nell’interfaccia di amministrazione di Support (Amministratore > Canali > API > Client OAuth). Consulta Registrazione della tua applicazione in Zendesk.
• client_secret: usa il segreto specificato in un client OAuth nell’interfaccia di amministrazione di Support (Amministratore > Canali > API > Client OAuth). Consulta Registrazione della tua applicazione in Zendesk.

  Se usi PKCE code_challenge e i parametri code_verifier, il valore client_secret non è obbligatorio. Puoi usare questa caratteristica per eseguire la migrazione dal flusso di concessione implicito, che non è più consigliato a causa di problemi di sicurezza. Consulta Uso di PKCE per la migrazione dal flusso di concessione implicito nella documentazione per sviluppatori.

• redirect_uri: lo stesso URL di reindirizzamento del passaggio 1. Solo per scopi di identificazione.
• scope: consulta Impostazione dell’ambito.
• code_verifier : obbligatorio se si usa PKCE. La stringa usata per generare il valore code_challenge. Consulta Generazione del valore code_challenge nella documentazione per sviluppatori.

La richiesta deve avvenire via https e le proprietà devono essere in formato JSON. Se usi un'applicazione personalizzata o di terzi per effettuare la richiesta API, consulta la relativa documentazione per sapere qual è il formato corretto per i valori delle proprietà.

Uso di curl

curl https://{subdomain}.zendesk.com/oauth/tokens \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "authorization_code", "code": "{your_code}",
    "client_id": "{your_client_id}", "client_secret": "{your_client_secret}", 
    "redirect_uri": "{your_redirect_url}", "scope": "read" }' \
  -X POST

Esempio di risposta

Status: 200 OK

{
  "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
  "token_type": "bearer",
  "scope":"read"
}

Passaggio 4: usare il token di accesso nelle chiamate API

L’app può usare il token di accesso per effettuare chiamate API. Includi il token in un’intestazione di autorizzazione HTTP con la richiesta, come segue:

Authorization: Bearer {a_valid_access_token}

Ad esempio, una richiesta curl per elencare i ticket apparirà come segue:

curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
  -H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"