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 à l’étape Effectuer un appel API du créateur de bots ou pour les actions de l’assistance automatique. Vous devez être administrateur pour créer des connexions.
À 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
| 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 le créateur de bots, consultez Utilisation de l’étape Effectuer un appel API dans le créateur de bots. 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 ».
- 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.
Pour créer un client OAuth
- Dans le Centre d’administration, cliquez sur l’icône Applications et intégrations
dans la barre latérale, puis sélectionnez Connexions > Connexions. - Saisissez un nom pour le client. Une fois le client créé, vous ne pouvez plus changer ce nom.
- 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.
- 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.
- (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.
- Saisissez l’URL de token. C’est l’URL qui sert à recevoir un token d’accès.
- 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.
- 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
- 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.
- Cliquez sur Créer une connexion.
- Sélectionnez un type d’authentification.
- Saisissez un nom pour la connexion. Une fois la connexion créée, vous ne pouvez plus changer ce nom.
- 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.
- 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é.
- 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.
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 (_).
acceptaccept-charsetaccept-encodingaccept-languagecache-controlconnectioncontent-md5cookiedateexpectfromhostif-matchif-modified-sinceif-none-matchif-rangeif-unmodified-sincemax-forwardspragmaproxy-authenticateproxy-authorizationrangeserverreferertetrailertransfer-encodingupgradeuser-agentviawarningwww-authenticate- Noms d’en-tête commençant par :
x-amz-
x-amzn-x-forwarded-x-zis-