Mon édition
Suite Toutes les éditions
Accès rapide : Centre d’administration > Applications et intégrations > Connexions > Connexions
Une connexion vous permet de stocker en toute sécurité vos identifiants d’API pour un service ou un système, comme Slack ou Shopify. Vous pouvez utiliser une connexion pour authentifier les appels API REST dans les actions d’assistance automatique. Vous devez être administrateur pour créer des connexions.
Remarque – Les instructions de cet article s’appliquent également aux comptes qui utilisent l’étape Effectuer un appel API de l’ancien créateur de bots.
Cet article aborde les sujets suivants :
  • À propos des connexions
  • Création d’une connexion
  • Domaine autorisé
  • En-têtes HTTP pour les clés API

À propos des connexions

Une connexion prend en charge l’une des méthodes d’authentification d’API suivantes :

  • Clé API
  • Authentification de base
  • Token du porteur
  • OAuth 2.0

Cette méthode d’authentification détermine le type d’identifiants que stocke la connexion. Par exemple, une connexion d’authentification de base stocke un nom d’utilisateur et un mot de passe. Une fois une connexion créée, vous ne pouvez pas changer son type d’authentification.

Les différentes API prennent en charge différentes méthodes d’authentification. Pour déterminer la méthode d’authentification appropriée pour un appel API, consultez la documentation de l’API.

En-têtes HTTP pour les types d’authentification

Quand vous utilisez une connexion pour authentifier un appel API dans l’action d’assistance automatique, Zendesk transfère les identifiants de la connexion dans un en-tête HTTP. Zendesk détermine cet en-tête en fonction du type d’authentification de la connexion.
Type d’authentification En-tête HTTP
Clé API Définie quand vous créez la connexion. Consultez En-têtes HTTP pour les clés API.
Authentification de base Authorization: Basic
Token du porteur Authorization: Bearer
OAuth 2.0 Le token d’accès est envoyé au service dans Authorization: Bearer

Pour en savoir plus sur l’utilisation d’une connexion dans une action, consultez Création et gestion des actions pour l’assistance automatique.

Création d’un client OAuth

Une connexion OAuth stocke un token d’accès OAuth 2.0 pour un service ou un système, comme Slack, Shopify ou Zendesk.

Avant de créer une connexion avec le type d’authentification OAuth 2.0, vous devez configurer un client OAuth. Pour configurer le client OAuth, vous avez besoin de l’ID client, du secret client, de l’URL d’autorisation, de l’URL du token et des portées du portail d’administration ou de l’interface de configuration OAuth du système externe. Ces identifiants sont générés quand vous enregistrez votre application client (comme Zendesk) auprès du système externe. Les étapes précises varient selon le système externe. Si nécessaire, définissez l’URL de rappel (callback) du client comme « https://zis.zendesk.com/api/services/zis/connections/oauth/callback ».

Remarque – Nous prenons uniquement en charge les connexions avec des systèmes externes conformes au cadre d’autorisation OAuth 2.0.
Vous pouvez créer des clients OAuth avec les types d’octroi OAuth 2.0 suivants :
  • Code d’autorisation
  • Identifiants du client

Le type d’octroi Token d’actualisation est pris en charge pour les clients OAuth 2.0 créés à l’aide d’un type d’octroi Code d’autorisation. Si la réponse du token d’accès inclut des valeurs expires_in et refresh_token non vides, le token d’accès est automatiquement actualisé via le token d’actualisation.

Les connexions OAuth 2.0 créées avec un client avec le type d’octroi Identifiants du client peuvent inclure une valeur d’expiration du token. Dans ce cas, quand le token arrive à expiration, un nouveau token d’accès est obtenu en utilisant le même client OAuth.

Remarque – Dans certains cas, il est possible que nous actualisions le token d’accès plusieurs fois avec un seul token d’actualisation. Comme certains systèmes implémentent des mécanismes conçus pour empêcher la réutilisation d’un token d’actualisation, nous vous conseillons d’implémenter, dans la mesure du possible, une période de grâce ou de plutôt utiliser le type d’octroi Identifiants du client.

Pour créer un client OAuth

  1. Dans le Centre d’administration, cliquez sur Applications et intégrations dans la barre latérale, puis sélectionnez Connexions > Connexions.
  2. Saisissez un nom pour le client. Une fois le client créé, vous ne pouvez plus changer ce nom.
  3. Saisissez l’ID client. Il s’agit d’un identifiant unique affecté à votre client OAuth, un peu comme le nom d’utilisateur de votre client.
  4. Saisissez le secret client. Il sert de mot de passe pour votre application client et établit la relation de confiance entre Zendesk et le système externe.
  5. (type d’octroi Code d’autorisation uniquement) Saisissez l’URL d’autorisation. C’est l’URL du serveur qui sert à recevoir un code d’utilisation.
  6. Saisissez l’URL de token. C’est l’URL qui sert à recevoir un token d’accès.
  7. Saisissez une liste de portées ou d’étendues d’autorisation par défaut séparées par des espaces. Ces étendues d’autorisation sont des permissions qui représentent ce à quoi une application client a accès pour le compte de l’utilisateur.
  8. Cliquez sur Enregistrer pour créer le client.

Création d’une connexion

Vous pouvez créer une connexion dans le Centre d’administration, à la page Connexions.

Pour créer une connexion

  1. Dans le Centre d’administration, cliquez sur l’icône Applications et intégrations dans la barre latérale, puis sélectionnez Connexions > Clients OAuth.
  2. Cliquez sur Créer une connexion.
  3. Sélectionnez un type d’authentification.
  4. Saisissez un nom pour la connexion. Une fois la connexion créée, vous ne pouvez plus changer ce nom.
  5. Suivez l’une de ces méthodes :
    • (clé API Key, authentification de base, token du porteur) configurez les identifiants d’authentification de la connexion. La connexion utilise ces détails pour authentifier les appels API REST au service ou au système.
    • (OAuth 2.0) Sélectionnez le client à utiliser et facultativement, saisissez une liste de portées ou d’étendues d’autorisations séparées par des espaces. Si vous ne saisissez pas d’étendues d’autorisations, les étendues par défaut spécifiées dans le client OAuth sont utilisées.
  6. Saisissez un domaine autorisé pour la connexion. Une fois la connexion créée, vous ne pouvez plus changer le domaine autorisé. Pour en savoir plus, consultez Domaine autorisé.
  7. Cliquez sur Enregistrer pour créer la connexion.

Une fois la connexion créée, vous pouvez en voir les détails à la page Connexions du Centre d’administration. Consultez Gestion des connexions.

Remarque – Quand vous créez une connexion avec un type d’authentification OAuth 2.0, les étendues d’autorisation incluses à la réponse du token d’accès du système externe sont stockées, pas les étendues d’autorisation définies lors de la création de la connexion. Cette valeur ne peut pas excéder 255 caractères.

Domaine autorisé

Chaque connexion nécessite un nom d’hôte d’URL comme domaine autorisé. Zendesk ne transfère les identifiants de la connexion que dans les appels API à ce nom d’hôte. Toute tentative d’utilisation de la connexion avec d’autres noms d’hôte échouera. Cela aide à éviter une fuite accidentelle des identifiants de la connexion. Une fois une connexion créée, vous ne pouvez pas changer son domaine autorisé.

Par exemple, vous pouvez uniquement utiliser une connexion avec le domaine autorisé « api.example.com » pour effectuer des appels API au nom d’hôte « https://api.example.com ».

Exigences pour le domaine autorisé

Le domaine autorisé d’une connexion ne doit pas dépasser 128 caractères. Un sous-domaine ou un domaine au sein de la valeur ne peut pas dépasser 63 caractères. La valeur doit contenir un nom de domaine valide.

Une connexion utilise toujours un schéma https. Les autres schémas, comme ftps, ne sont pas pris en charge.

Caractères génériques pour le domaine autorisé

Le domaine autorisé d’une connexion prend en charge un sous-domaine générique (*) facultatif. Cela vous permet d’utiliser la connexion avec le domaine brut et n’importe quel sous-domaine. Par exemple, vous pouvez utiliser une connexion avec le domaine autorisé *.example.com pour authentifier les appels API à « example.com » ou n’importe quel sous-domaine de « example.com ».

Pour utiliser un sous-domaine générique, les deux premiers caractères du domaine autorisé doivent être *.. Vous ne pouvez pas utiliser de caractère générique dans les autres parties du nom d’hôte. Par exemple, vous ne pouvez pas utiliser de caractère générique au sein d’un nom d’hôte, comme exam*.com ou my-*.example.com.

Vous ne pouvez pas utiliser de caractère générique uniquement avec un suffixe de domaine public, comme *.com, *.com.au ou *.myshopify.com. Pour consulter la liste des suffixes publics, rendez-vous sur publicsuffix.org.

En-têtes HTTP pour les clés API

Quand vous créez une connexion de clé API, vous devez spécifier un nom d’en-tête HTTP. Quand la connexion est utilisée pour effectuer un appel API, Zendesk transfère la clé API comme valeur pour cet en-tête.

De nombreuses API utilisent un en-tête personnalisé pour accepter les clés API. Pour obtenir le nom d’en-tête approprié pour un appel API, consultez la documentation de l’API.

Exigences pour les noms d’en-tête

Le nom d’en-tête d’une connexion de clé API ne peut pas dépasser 128 caractères. Le nom d’en-tête peut uniquement contenir des lettres, des tirets (-) et des traits de soulignement (_).

Vous ne pouvez pas utiliser les noms d’en-tête HTTP suivants :
  • accept
  • accept-charset
  • accept-encoding
  • accept-language
  • cache-control
  • connection
  • content-md5
  • cookie
  • date
  • expect
  • from
  • host
  • if-match
  • if-modified-since
  • if-none-match
  • if-range
  • if-unmodified-since
  • max-forwards
  • pragma
  • proxy-authenticate
  • proxy-authorization
  • range
  • server
  • referer
  • te
  • trailer
  • transfer-encoding
  • upgrade
  • user-agent
  • via
  • warning
  • www-authenticate
  • Noms d’en-tête commençant par :
    • x-amz-
    • x-amzn-
    • x-forwarded-
    • x-zis-
Réalisé par Zendesk