| Suite | Team, Growth, Professional, Enterprise, or Enterprise Plus |
| Support | Team, Professional, or Enterprise |
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
- Tipi di client OAuth
- Tipo di concessione Credenziali client OAuth
- 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.
Per registrare la tua applicazione
- Nel Centro amministrativo, fai clic su App e integrazioni
nella barra laterale, quindi seleziona API > API Zendesk. - Fai clic sulla scheda Client OAuth nella pagina API Zendesk, quindi fai clic su Aggiungi client OAuth a destra dell’elenco di client OAuth.
- 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.
- 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.
- 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.
- 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.
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.
Tipo di concessione Credenziali client OAuth
Il tipo di concessione Credenziali client OAuth è pensato esclusivamente per i client riservati e consente di creare un token OAuth usando solo il segreto di un client specifico. Per usare questo flusso, invia un parametro client_secret valido all'endpoint /oauth/tokens usando grant_type: client_credentials per generare un nuovo token di accesso OAuth. A differenza di altri flussi di autorizzazione, questo tipo di concessione non restituisce un token di aggiornamento e non richiede l'autorizzazione dell'utente. L’utente associato al token sarà lo stesso utente collegato al client usato. Se lo desideri, puoi includere un expires_in valore per impostare il tempo di scadenza del token in millisecondi. Per motivi di sicurezza, i client pubblici non possono usare questo tipo di concessione. Per maggiori informazioni, consulta Client Oauth.
Tipo di concessione del token di aggiornamento OAuth
Il tipo di concessione del token di aggiornamento OAuth consente di aggiornare un token di accesso scaduto o in procinto di scadere. Per generare un nuovo token di accesso OAuth , passa un parametrorefresh_token all'endpoint https://{subdomain}.zendesk.com/oauth/tokens utilizzando grant_type: refresh_token, che restituisce un nuovo token di accesso e un nuovo token di aggiornamento, invalidando quelli precedenti.
Il client OAuth deve implementare un meccanismo di fallback per gestire i token di accesso scaduti e i token di aggiornamento scaduti. Ad esempio, se il token di accesso è scaduto o si verifica un errore, puoi aggiornarlo. Tuttavia, se il processo di aggiornamento non riesce o non esiste alcun token di aggiornamento collegato al token di accesso, devi reindirizzare l’utente a https://{subdomain}.zendesk.com/oauth/authorizations/new per riautorizzare l’applicazione. Per maggiori informazioni, consulta Token OAuth per il tipo di concessione e Creazione e uso di token di accesso OAuth con l’API.
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.
Il flusso usa i token di aggiornamento, che ti consentono di generare nuovi token di accesso senza richiedere la riautorizzazione da parte degli utenti. Il token di accesso potrebbe scadere se l’API fornisce un parametro expires_in valido, che indica una durata specifica per il token. In questi casi, implementa un meccanismo per aggiornare il token di accesso usando il token di aggiornamento fornito prima che scada.
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/newdove {subdomain} è il tuo sottodominio principale Zendesk, non un sottodominio mappato all’host.
Puoi usare una richiesta POST o GET. Includi i seguenti parametri:
-
response_type: obbligatorio. Zendesk restituisce un codice di autorizzazione nella risposta, quindi specifica
codecome 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
statee 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%20writeNel 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=7xqwtlf3rrdj8uyeb1yfIl 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+requestUsa 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/tokensIncludi 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_challengee i parametricode_verifier, il valoreclient_secretnon è 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. - expires_in - Facoltativo. Numero di secondi di validità del token di accesso. Consulta Token OAuth per tipi di concessioni.
- refresh_token_expires_in - Facoltativo. Numero di secondi di validità del token di aggiornamento. Consulta Token OAuth per tipi di concessioni.
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 POSTEsempio 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"
0 commenti
Accedi per lasciare un commento.