Una connessione ti consente di memorizzare in modo sicuro le credenziali API per un servizio o un sistema, come Slack o Shopify. Puoi usare una connessione per autenticare le chiamate API REST nel passaggio Effettua chiamata API di Creazione bot o per le azioni di assistenza automatica. Per creare le connessioni, devi essere un amministratore.
Informazioni sulle connessioni
Una connessione supporta uno dei seguenti metodi di autenticazione API:
- Chiave API
- Autenticazione base
- Token portatore
- OAuth 2.0
Questo metodo di autenticazione determina il tipo di credenziali memorizzate nella connessione. Ad esempio, una connessione di autenticazione di base memorizza un nome utente e una password. Una volta creata una connessione, non è possibile modificare il tipo di autenticazione.
API diverse supportano metodi di autenticazione diversi. Per determinare il metodo di autenticazione appropriato per una chiamata API, consulta la documentazione API.
Intestazioni HTTP per i tipi di autenticazione
| Tipo di autenticazione | Intestazione HTTP |
|---|---|
| Chiave API | Viene impostata quando crei la connessione. Consulta Intestazioni HTTP per le chiavi API |
| Autenticazione base |
Authorization: Basic
|
| Token portatore |
Authorization: Bearer
|
| OAuth 2.0 |
Il token di accesso viene inviato al servizio in Authorization:
Bearer
|
Per ulteriori informazioni sull’uso di una connessione in un bot, consulta Uso del passaggio Effettua chiamata API in Creazione bot. Per ulteriori informazioni sull’uso di una connessione in un’azione, consulta Creazione e gestione di azioni per l’assistenza automatica.
Creazione di un client OAuth
Una connessione OAuth memorizza un token di accesso OAuth 2.0 per un servizio o un sistema, come Slack, Shopify o Zendesk.
Prima di creare una connessione con il tipo di autenticazione OAuth 2.0, devi configurare un client OAuth. Per la configurazione del client OAuth sono necessari l’ID del client, il segreto del client, l’URL di autorizzazione, l’URL token e gli ambiti indicati nell’interfaccia di configurazione OAuth del sistema esterno o nel portale di amministrazione. Queste credenziali vengono generate durante la registrazione dell’applicazione client (come Zendesk) nel sistema esterno. I passaggi esatti variano in base al servizio esterno. Se necessario, imposta l’URL del servizio di richiamata del client come “https://zis.zendesk.com/api/services/zis/connections/oauth/callback”.
- Codice autorizzazione
- Credenziali del client
Il tipo di concessione del token di aggiornamento è supportato per i client OAuth 2.0 creati usando un tipo di concessione del codice di autorizzazione. Se la risposta del token di accesso del sistema include valori expires_in e refresh_token non vuoti, il token di accesso viene aggiornato automaticamente usando il token di aggiornamento.
Le connessioni OAuth 2.0 create con un client usando il tipo di concessione Credenziali client possono includere un valore di scadenza del token. In questi casi, quando il token scade, viene recuperato un nuovo token di accesso usando lo stesso client OAuth.
Per creare un client OAuth
- Nel Centro amministrativo, fai clic su
App e integrazioni nella barra laterale, quindi seleziona Connessioni > Connessioni. - Inserisci un nome per il client. Una volta creato il client, il nome non potrà essere modificato.
- Inserisci l’ID del client. Si tratta di un identificatore univoco assegnato al client OAuth, simile al nome utente del client.
- Inserisci il segreto del client. Quest’ultimo funge da password per l’applicazione client e stabilisce una connessione attendibile tra Zendesk e il sistema esterno.
- (Solo tipo di concessione del codice di autorizzazione) Inserisci l’URL di autorizzazione. Si tratta dell’URL del server usato per ricevere un codice di autorizzazione.
- Inserisci l’URL del token. Si tratta dell’URL usato per ricevere un token di accesso.
- Inserisci un elenco di ambiti predefiniti separati da spazi. Gli ambiti sono autorizzazioni che definiscono ciò a cui un’applicazione client può accedere per conto dell’utente.
- Fai clic su Salva per creare il client.
Creazione di una connessione
È possibile creare una connessione nel Centro amministrativo dalla pagina Connessioni.
Per creare una connessione
- Nel Centro amministrativo, fai clic su App e integrazioni nella barra laterale e seleziona Connessioni > Client OAuth.
- Fai clic su Crea connessione.
- Seleziona un tipo di autenticazione.
- Inserisci un nome per la connessione. Una volta creata la connessione, il nome non potrà essere modificato.
- Esegui una delle operazioni descritte di seguito:
- (Chiave API, Autenticazione di base, Token portatore) Configura le credenziali di autenticazione della connessione. La connessione usa questi dettagli per autenticare le chiamate API REST al servizio o al sistema.
- (OAuth 2.0) Seleziona il client da usare e, facoltativamente, inserisci un elenco di ambiti separati da spazi. Se non inserisci alcun ambito, vengono usati quelli predefiniti specificati nel client OAuth.
- Inserisci un dominio consentito per la connessione. Una volta creata la connessione, il dominio consentito non potrà essere modificato. Per maggiori informazioni, consulta Dominio consentito.
- Fai clic su Salva per creare la connessione.
Una volta creata la connessione, è possibile visualizzarne i dettagli nella pagina Connessioni nel Centro amministrativo. Consulta Gestione delle connessioni.
Dominio consentito
Ciascuna connessione richiede un nome host URL come dominio consentito. Zendesk trasmette a questo nome host solo le credenziali della connessione nelle chiamate API. I tentativi di usare la connessione con altri nomi host non avranno esito positivo. Questo consente di prevenire la fuga accidentale delle credenziali della connessione. Una volta creata la connessione, il dominio consentito non potrà essere modificato.
Ad esempio, puoi usare solo una connessione con dominio consentito “api.example.com” per effettuare chiamate API al nome host “https://api.example.com”.
Requisiti del dominio consentito
Il dominio consentito per una connessione non può superare i 128 caratteri. Un sottodominio o un dominio in questo valore non può superare i 63 caratteri. Il valore deve contenere un nome di dominio valido.
Una connessione usa sempre uno schema https. Altri schemi, quali ftps, non sono supportati.
Caratteri jolly per il dominio consentito
Il dominio consentito di una connessione supporta un sottodominio jolly (*) facoltativo. Questo consente di usare la connessione con il dominio semplice e qualsiasi sottodominio. Ad esempio, puoi usare una connessione con dominio consentito *.example.com per autenticare le chiamate API a “example.com” o a qualsiasi sottodominio di “example.com”.
Per usare un sottodominio con caratteri jolly. I primi due caratteri del dominio consentito devono essere *.. Non puoi usare un carattere jolly in altre parti del nome host. Ad esempio, non puoi usare un carattere jolly in un nome host, come exam*.com o my-*.example.com.
Non puoi usare un carattere jolly con solo un suffisso di dominio pubblico, come *.com, *.com.au oppure *.myshopify.com. Per un elenco dei suffissi pubblici, consulta l’elenco dei suffissi pubblici su publicsuffix.org.
Intestazioni HTTP per chiavi API
Quando crei una connessione con chiave API, devi specificare un nome di intestazione HTTP. Quando la connessione viene usata per effettuare una chiamata API, Zendesk trasmette la chiave API come valore per questa intestazione.
Molte API usano un'intestazione personalizzata per accettare le chiavi API. Per ottenere il nome di intestazione appropriato per una chiamata API, consulta la documentazione API.
Requisiti per il nome dell’intestazione
Il nome dell’intestazione di una connessione chiave API non può superare i 128 caratteri. Il nome dell’intestazione può contenere solo lettere, trattini (-) e trattini bassi (_).
acceptaccept-charsetaccept-encodingaccept-languagecache-controlconnectioncontent-md5cookiedateexpectfromhostif-matchif-modified-sinceif-none-matchif-rangeif-unmodified-sincemax-forwardspragmaproxy-authenticateproxy-authorizationrangeserverreferertetrailertransfer-encodingupgradeuser-agentviawarningwww-authenticate- Nomi di intestazioni che iniziano con:
x-amz-
x-amzn-x-forwarded-x-zis-