Uso dell’autenticazione OAuth con la tua applicazione

Qual è il mio piano?

Tutte le suite

Team, Growth, Professional, Enterprise o Enterprise Plus

Support

Team, Professional o Enterprise

Riepilogo AI verificato ◀▼

Usa OAuth 2 per autenticare in modo sicuro le richieste API senza memorizzare le password degli utenti. Registra la tua app per generare le credenziali OAuth e implementa il flusso del codice di autorizzazione per ottenere i token di accesso. Gestisci la scadenza dei token aggiornando i token con il token di aggiornamento.

Posizione: Centro amministrativo > App e integrazioni > API > Client Oauth

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 del codice di autorizzazione OAuth e il rinnovo dei codici di accesso scaduti.

Zendesk supporta anche il flusso del tipo di concessione Credenziali client, che permette di creare un token di accesso utilizzando soltanto il secret di un client OAuth. Questo tipo di concessione è pensato solo per client confidenziali e non viene approfondito in questo articolo. Per maggiori informazioni, consulta Tipo di concessione Credenziali client nelle informazioni di riferimento sulle API.

Argomenti inclusi in questo articolo:

• Registrazione della tua applicazione in Zendesk
• Implementazione di un flusso di autorizzazione OAuth nella tua applicazione
• Sostituzione dei token di accesso scaduti

Argomenti correlati:

• Per un tutorial sulla creazione di un’applicazione web che implementa un flusso di autorizzazione OAuth, consulta Utilizzo di OAuth per autenticare le richieste API Zendesk in un’app web.
• 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 di accesso 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 > Client OAuth.
2. Fai clic su Aggiungi client OAuth a destra dell'elenco dei client OAuth.
3. Compila i campi seguenti per creare un client:
   • Nome: inserisci 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: 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 Informazioni sui tipi di client.
   • 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. Corrisponde al valore “client_secret” indicato nella specifica OAuth 2.0.

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 del segreto nella tua applicazione come descritto nell’argomento seguente.

Informazioni sui tipi di client

I client OAuth hanno una proprietà kind che può avere uno dei seguenti valori:

• 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.
• 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.

Esempi di client confidenziali includono le applicazioni web lato server. Quando il server di autorizzazione invia i token o le credenziali all’applicazione web, queste non vengono mai rese accessibili all’esterno.

Esempi di client pubblici includono le applicazioni per dispositivi mobili e le applicazioni JavaScript eseguite su client user agent, come i browser web. Le credenziali sono facilmente accessibili (e spesso visibili) in questi client.

Nella specifica OAuth, i client possono essere indicati anche come tipi di client. Per maggiori informazioni, consulta Tipi di client nella specifica OAuth 2.0.

Questa proprietà 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.

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 ottenere un nuovo token di accesso alla scadenza usando il token di aggiornamento fornito.

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 del codice di autorizzazione OAuth, consulta Utilizzo di OAuth per autenticare le richieste API Zendesk in un’app web.

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 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 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 la tua applicazione ha ricevuto un codice di autorizzazione da Zendesk in seguito alla concessione dell’accesso da parte dell’utente, può scambiarlo con un token di accesso e un token di aggiornamento. Per ottenere i token, invia una richiesta POST all’endpoint Crea tipo di concessione token:

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 nel Centro amministrativo Zendesk (App e integrazioni > API > Client OAuth). Consulta Registrazione della tua applicazione in Zendesk.
• client_secret: usa il segreto specificato in un client OAuth nel Centro amministrativo Zendesk (App e integrazioni > 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.
• expires_in: numero di secondi di validità del token di accesso. Specifica un valore compreso tra 300 secondi (5 minuti) e 172.800 secondi (2 giorni).
• refresh_token_expires_in: numero di secondi di validità del token di aggiornamento. Specifica un valore compreso tra 604.800 secondi (7 giorni) e 7.776.000 secondi (90 giorni).

Per maggiori informazioni, consulta l’endpoint Crea tipo di concessione token nelle informazioni di riferimento sulle API.

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à.

Utilizzo della libreria di richieste Python

response = requests.post(
    f'https://{subdomain}.zendesk.com/oauth/tokens',
    data={
        'grant_type': 'authorization_code',
        'code': f'{your_code}',
        'client_id': f'{your_client_id}',
        'client_secret': f'{your_client_secret}',
        'redirect_uri': f'{your_redirect_url}',
        'scope': 'read',
        'expires in': 172800,
        'refresh_token_expires_in': 800000
    }
)

Esempio di risposta

Status: 201 OK

{
  "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
  "refresh_token": "31048ba4d7c601302f3173f243da835f",
  "token_type": "bearer",
  "scope":"read"
}

Salva token di accesso e token di aggiornamento in un datastore sicuro per riutilizzarli in un secondo momento.

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"

Sostituzione dei token di accesso scaduti

I token di accesso scadranno dopo un determinato periodo di tempo. Usa il token di aggiornamento che hai ricevuto con il token di accesso per richiedere un nuovo token di accesso. Non è necessario usare il flusso del codice di autorizzazione per ottenere il nuovo token.

L’applicazione 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 è verificato un errore, utilizza un gestore per aggiornarlo. Se il processo di aggiornamento non riesce o non esiste alcun token di aggiornamento collegato al token di accesso, reindirizza l’utente a https://{subdomain}.zendesk.com/oauth/authorizations/new per riautorizzare l’applicazione.

Verificare se un token di accesso è scaduto

Per verificare se un token di accesso è scaduto, configura il tuo codice in modo da rilevare una risposta 401 dopo avere effettuato una richiesta API con il token. La risposta includerà la seguente stringa JSON:

{"error":"invalid_token","error_description":"The access token provided is expired, revoked, 
 malformed or invalid for other reasons."}

Se ricevi una risposta 401, chiama un gestore per aggiornare il token di accesso usando il token di aggiornamento che hai ricevuto con il token di accesso.

Ecco un esempio di utilizzo della libreria di richieste Python:

url = f'https://{your_subdomain}.zendesk.com/{endpoint}'
headers = {'Authorization': f'Bearer {access_token}'}
response = requests.get(url, headers=headers)
if response.status_code == 401:     # if token has expired or is otherwise invalid
    access_token = refresh_access_token(refresh_token)
    headers['Authorization'] = f'Bearer {access_token}'
    response = requests.get(url, headers=headers)

Aggiornamento di un token di accesso

Per aggiornare un token di accesso, invia una richiesta POST all’endpoint Crea tipo di concessione token:

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

Includi le seguenti proprietà nel corpo della richiesta:

• grant_type: specifica la stringa "token di aggiornamento" come valore.
• refresh_token: specifica il valore del token di aggiornamento ricevuto con il token di accesso.
• client_id: usa l’identificatore specificato nel client OAuth nel Centro amministrativo Zendesk (App e integrazioni > API > Client OAuth). Consulta Registrazione della tua applicazione in Zendesk.
• client_secret: usa il segreto specificato nel client OAuth nel Centro amministrativo Zendesk (App e integrazioni > API > Client OAuth). Consulta Registrazione della tua applicazione in Zendesk.
• scope: consulta Impostazione dell’ambito.
• expires_in: numero di secondi di validità del token di accesso. Specifica un valore compreso tra 300 secondi (5 minuti) e 172.800 secondi (2 giorni).
• refresh_token_expires_in: numero di secondi di validità del token di aggiornamento. Specifica un valore compreso tra 604.800 secondi (7 giorni) e 7.776.000 secondi (90 giorni).

Per maggiori informazioni, consulta l’endpoint Crea tipo di concessione token nelle informazioni di riferimento sulle API.

Ecco un esempio di richiesta che usa la libreria di richieste Python:

response = requests.post(
    f'https://{your_subdomain}.zendesk.com/oauth/tokens',
    data={
        'grant_type': 'refresh_token',
        'refresh_token': refresh_token,
        'client_id': client_id,
        'client_secret': client_secret,
        'scope': 'read',
        'expires in': 172800,
        'refresh_token_expires_in': 800000
    }
)

La richiesta crea nuovi token di accesso e aggiornamento invalidando quelli precedenti. Ecco un esempio di risposta:

Status: 201 OK

{
  "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
  "refresh_token": "31048ba4d7c601302f3173f243da835f,
  "token_type": "bearer",
  "scope": "read"
}

Salva entrambi i token in un datastore sicuro per riutilizzarli in un secondo momento.