| Suite | Team, Growth, Professional, Enterprise ou Enterprise Plus |
| Support | Team, Professional ou Enterprise |
Vous pouvez utiliser OAuth 2 pour authentifier toutes les demandes API de votre application vers Zendesk. OAuth permet à votre application d’accéder aux données Zendesk de façon sécurisée sans avoir à stocker ni à utiliser les mots de passe des utilisateurs Zendesk, qui sont des informations sensibles.
Pour utiliser l’authentification OAuth, vous devez enregistrer votre application auprès de Zendesk. Vous devez aussi d’ajouter certaines fonctionnalités à votre application pour qu’elle prenne en charge le flux d’autorisation OAuth.
Sujets abordés dans cet article :
- Enregistrement de votre application auprès de Zendesk
- Types de clients OAuth
- Type d’octroi de valeurs de connexion client OAuth
- Mise en œuvre d’un flux d’autorisation OAuth dans votre application
Articles connexes :
- Pour un didacticiel expliquant la création d’une application Web mettant en œuvre le flux d’autorisation OAuth, consultez Building an OAuth web app.
- Pour savoir comment mettre en œuvre un flux d’authentification OAuth dans les applications Zendesk, consultez l’article portant sur l’ajout d’une authentification OAuth tierce à une application Support.
- Si vous n’avez pas besoin que les utilisateurs accordent à votre application l’accès à leurs comptes, vous pouvez malgré tout utiliser les tokens OAuth pour authentifier les demandes API. Consultez Creating and using OAuth tokens with the API.
Enregistrement de votre application auprès de Zendesk
Vous devez enregistrer votre application pour générer des valeurs de connexion OAuth que votre application utilisera pour authentifier les appels API vers Zendesk.
Pour enregistrer votre application
- Dans le Centre d’administration, cliquez sur Applications et intégrations (
) dans la barre latérale, puis sélectionnez API > API Zendesk. - Activez l’onglet Clients OAuth à la page API Zendesk, puis cliquez sur Ajouter un client OAuth sur la droite de la liste des clients OAuth.
- Remplissez les champs suivants pour créer un client :
- Nom du client : saisissez un nom pour votre application. Il s’agit du nom que verront les utilisateurs lorsqu’il leur sera demandé d’accorder l’accès à votre application, et lorsqu’ils consulteront la liste des applications tierces qui ont accès à leur Zendesk.
- Description : facultatif. Il s’agit d’une brève description de votre application que verront les utilisateurs lorsqu’il leur sera demandé d’y accorder l’accès.
- Société : facultatif. Il s’agit du nom de la société que verront les utilisateurs lorsqu’il leur sera demandé d’accorder l’accès à votre application. Le nom les aidera à comprendre à qui ils accordent l’accès.
- Logo : facultatif. Il s’agit du logo que verront les utilisateurs lorsqu’il leur sera demandé d’accorder l’accès à votre application. L’image peut-être aux formats JPG, GIF ou PNG. Pour un résultat optimal, téléchargez une image carrée. Elle sera redimensionnée pour la page d’autorisation.
- Identifiant unique : le champ est rempli automatiquement avec une version reformatée du nom que vous avez saisi pour votre application. Vous pouvez le modifier si vous le souhaitez.
- Type de client : public ou confidentiel. Les clients OAuth publics sont des applications qui s’exécutent dans des environnements dans lesquels leurs identifiants ne peuvent pas être stockés de façon sécurisée, comme les applications Web ou mobiles. Ces clients doivent utiliser PKCE. Les clients OAuth confidentiels s’exécutent sur des serveurs sécurisés où les identifiants peuvent être conservés de façon sécurisée. Ces clients peuvent utiliser PKCE, le secret client ou les deux. Consultez Types de clients OAuth.
- URL de redirection : saisissez l’URL ou les URL que Zendesk doit utiliser pour envoyer la décision de l’utilisateur d’accorder l’accès à votre application. Les URL doivent être absolues et non relatives, sécurisées (https, sauf si hôte local ou 127.0.0.1), et séparées par de nouvelles lignes.
- Cliquez sur Enregistrer.
Une fois la page actualisée, un nouveau champ Secret prérempli apparaît en bas de l’écran. Il s’agit de la valeur « client_secret » spécifiée dans la spécification OAuth2.
- Copiez la valeur Secret dans votre presse-papier et conservez-la en lieu sûr. Remarque – Les caractères peuvent dépasser la largeur du champ de texte, veillez donc à tout sélectionner avant de copier.
Important : pour des raisons de sécurité, votre valeur secrète n’est affichée intégralement qu’une seule fois. Après avoir cliqué sur Enregistrer, vous ne verrez que les neuf premiers caractères.
- Cliquez sur Enregistrer.
Utilisez l’identifiant unique et la valeur secrète dans votre application, comme décrit dans le sujet suivant.
Types de clients OAuth
Les clients OAuth Zendesk incluent une propriété kind qui est transférée lors de la création du client OAuth et peuvent avoir l’une des valeurs suivantes :
- Publics : les clients OAuth publics sont des applications qui s’exécutent dans des environnements dans lesquels leurs identifiants ne peuvent pas être stockés de façon sécurisée, comme les applications Web ou mobiles. Ces clients doivent utiliser PKCE.
- Confidentiel : les clients OAuth confidentiels s’exécutent sur des serveurs sécurisés où les identifiants peuvent être conservés de façon sécurisée. Ces clients peuvent utiliser PKCE, le secret client ou les deux.
Pour en savoir plus, consultez Types de clients.
Le type de client OAuth Zendesk s’applique uniquement au système de gestion des tickets Zendesk Support. Il n’est pas pris en charge dans Chat, les conversations ou Sell.
Pour les clients OAuth Zendesk existants, la propriété kind est définie sur unknown. Ces clients ne changent pas jusqu’à ce que la propriété kind soit mise à jour sur public ou confidential. Pour les nouveaux clients OAuth créés dans le Centre d’administration, la propriété kind doit être définie pendant la création.
kind sur public, vous devez implémenter PKCE. Sinon, le client ne fonctionnera pas, car PKCE sera immédiatement requis.Pour les nouveaux clients OAuth créés dans le Centre d’administration, la propriété kind doit être définie. La propriété kind n’est pas exigé pour les clients OAuth créé avec le point de terminaison api/v2/oauth/clients endpoint, mais Zendesk recommande de l’inclure.
Type d’octroi de valeurs de connexion client OAuth
Actuellement, les tokens créés par le type d’octroi de valeurs de connexion client ne peuvent être utilisés que par les points de terminaison qui autorisent les utilisateurs anonymes. Tout point de terminaison qui nécessite un rôle, comme administrateur ou agent, ne fonctionnera pas avec ces tokens. À l’avenir, ces tokens pourront être utilisés pour les points de terminaison qui nécessitent un rôle.
Le type d’octroi de valeurs de connexion client OAuth est réservé aux clients confidentiels et vous permet de créer un token OAuth en utilisant le secret d’un client spécifique. Pour utiliser ce workflow, transférez un paramètre client_secret valide au point de terminaison /oauth/tokens en utilisant grant_type: client_credentials pour générer un nouveau token d’accès OAuth. Contrairement aux autres workflows d’autorisation, ce type d’octroi ne renvoie pas de token d’actualisation et ne nécessite pas l’autorisation de l’utilisateur. Pour des raisons de sécurité, les clients publics n’ont pas le droit d’utiliser ce type d’octroi. Pour en savoir plus, consultez Clients OAuth.
Type d’octroi du token d’actualisation OAuth
Le type d’octroi du token d’actualisation OAuth permet d’actualiser un token d’accès qui a expiré ou est sur le point d’expirer. Pour générer un nouveau token d’accès OAuth, transférez un paramètre refresh_token au point de terminaison https://{subdomain}.zendesk.com/oauth/tokens en utilisant grant_type: refresh_token, qui renvoie un nouveau token d’accès et un nouveau token d’actualisation tout en invalidant les précédents.
Votre client OAuth devrait mettre en œuvre un mécanisme de repli pour traiter les tokens d’accès et d’actualisation expirés. Par exemple, si le token d’accès a expiré ou si une erreur survient, vous pouvez l’actualiser. Cependant, si le processus d’actualisation échoue ou s’il n’y a pas de token d’actualisation associé au token d’accès, vous devez rediriger l’utilisateur vers https://{subdomain}.zendesk.com/oauth/authorizations/new afin de réautoriser votre application. Pour en savoir plus, consultez OAuth Tokens for Grant Type et Creating and using OAuth access tokens with the API.
Mise en œuvre d’un flux d’autorisation OAuth dans votre application
Zendesk prend en charge le flux d’octroi de code d’autorisation pour l’obtention des tokens d’accès. Ce flux est appelé flux d’octroi de code d’autorisation, car vous avez besoin d’un code d’autorisation pour pouvoir demander un token d’accès.
Le workflow utilise des tokens d’actualisation, qui vous permettent de générer de nouveaux tokens d’accès sans devoir réautoriser l’utilisateur. Le token d’accès peut expirer si l’API fournit un paramètre expires_in valide, qui indique une durée de vie spécifique pour le token. Dans ce cas, mettez en œuvre un mécanisme pour actualiser le token d’accès en utilisant le token d’actualisation fourni avant qu’il n’expire.
Pour mettre en œuvre le flux d’octroi de code d’autorisation, vous devez ajouter la fonctionnalité suivante à votre application :
- Étape 1 - Dirigez l’utilisateur vers la page d’autorisation de Zendesk
- Étape 2 - Traitez la décision d’autorisation de l’utilisateur
- Étape 3 - Obtenez un token d’accès auprès de Zendesk
- Étape 4 - Utilisez le token d’accès dans les appels API
Pour un didacticiel expliquant la création d’une application Web mettant en œuvre le flux d’autorisation OAuth, consultez Building an OAuth web app.
La méthode d’octroi d’un code d’autorisation prend en charge Proof Key for Code Exchange (PKCE), qui ajoute une couche de sécurité supplémentaire. Pour en savoir plus, consultez la section sur l’utilisation de PKCE pour rendre les tokens d’accès OAuth Zendesk encore plus sûrs dans la documentation pour les développeurs.
Étape 1 - Dirigez l’utilisateur vers la page d’autorisation de Zendesk
L’application doit d’abord diriger l’utilisateur vers la page d’autorisation de Zendesk. La page demande à l’utilisateur d’autoriser votre application à accéder à Zendesk en votre nom. Lorsque l’utilisateur a pris sa décision, Zendesk renvoie le choix et d’autres éléments d’information à votre application.
Pour diriger l’utilisateur vers la page d’autorisation de Zendesk
Ajoutez un lien ou un bouton dans votre application pour diriger l’utilisateur vers l’URL suivante :
https://{subdomain}.zendesk.com/oauth/authorizations/newoù {subdomain} est votre sous-domaine Zendesk principal, pas un sous-domaine avec mappage d’hôte.
Vous pouvez utiliser une requête POST ou GET. Incluez les paramètres suivants :
-
response_type : exigé. Zendesk renvoie un code d’autorisation dans la réponse ; vous devez donc spécifier
codecomme type de réponse. Exemple :response_type=code. - redirect_uri : exigé. L’URL que Zendesk doit utiliser pour envoyer la décision de l’utilisation pour accorder l’accès à votre application. L’URL doit être absolue (pas relative). Elle doit en outre être sécurisée (https), sauf si vous utilisez localhost ou 127.0.0.1.
- client_id : exigé. L’identifiant unique que vous avez obtenu lorsque vous avez enregistré votre application auprès de Zendesk. Voir la section ci-dessus.
- scope : exigé. Liste séparée par des espaces des valeurs qui contrôlent l’accès aux ressources Zendesk. Vous pouvez demander un accès de type read, write ou impersonate à toutes les ressources ou à des ressources spécifiques. Consultez Définition de la portée.
-
state : chaîne arbitraire incluse dans la réponse de Zendesk une fois que l’utilisateur a décidé ou non d’octroyer l’accès. Vous pouvez utiliser le paramètre pour vous protéger contre les attaques intersite (CSRF). Lors d’une attaque de type CSRF, l’utilisateur final est incité à cliquer sur un lien qui lance une action dans une application Web où l’utilisateur est toujours authentifié. Pour se protéger contre ce type d’attaque, ajoutez une valeur au paramètre
stateet validez-la lorsqu’elle revient. - code_challenge : exigé si vous utilisez PKCE. Une chaîne représentant un défi de code dérivé d’un vérificateur de code. Consultez la section sur la génération de la valeur code_challenge dans la documentation pour les développeurs.
- code_challenge_method : exigé si vous utilisez PKCE. La méthode utilisée pour dériver le défi de code. Spécifiez "S256" comme valeur.
Veillez à coder les paramètres dans l’URL.
Exemple de requête GET
https://{subdomain}.zendesk.com/oauth/authorizations/new?response_type=code&redirect_uri={your_redirect_url}&client_id={your_unique_identifier}&scope=read%20writeLa page d’autorisation de Zendesk s’ouvre dans le navigateur de l’utilisateur final. Une fois que l’utilisateur a pris sa décision, Zendesk envoie la décision à l’URL de redirection que vous avez spécifiée dans la demande.
Définition de la portée
Vous devez spécifier une portée pour contrôler l’accès de l’application aux ressources Zendesk. La valeur read permet à l’application d’accéder aux points finaux GET. Cela inclut la permission de transférer les ressources connexes. La valeur write permet à l’application d’accéder aux points finaux POST, PUT et DELETE pour créer, mettre à jour et supprimer des ressources.
Pour en savoir plus au sujet de la portée, consultez l’article sur les tokens OAuth pour les types d’octroi.
La valeur impersonate permet à un administrateur Zendesk de faire des demandes pour le compte des utilisateurs finaux. Consultez Faire des demandes d’API pour le compte des utilisateurs finaux.
Par exemple, le paramètre suivant accorde à une application l’accès en lecture à toutes les ressources :
"scope": "read"Le paramètre suivant accorde l’accès en lecture et écriture à toutes les ressources :
"scope": "read write"Vous pouvez affiner la portée aux ressources suivantes :
- tickets
- utilisateurs
- journaux d’audit (lecture seule)
- organisations
- centre d’aide
- applications
- déclencheurs
- automatismes
- cibles
- webhooks
- zis
La syntaxe est la suivante :
"scope": "resource:scope"Par exemple, le paramètre suivant limite une application à la lecture des tickets :
"scope": "tickets:read"Pour accorder l’accès en lecture et écriture à une ressource, spécifiez les deux valeurs :
"scope": "users:read users:write"Pour accorder l’accès en écriture à une seule ressource, par exemple les organisations, et l’accès en lecture à tout le reste :
"scope": "organizations:write read"Étape 2 - Traitez la décision d’autorisation de l’utilisateur
Votre application doit traiter la réponse de Zendesk, qui lui indique ce qu’a décidé l’utilisateur. Les informations se trouvent dans les paramètres d’URL de l’URL de redirection.
Si l’utilisateur a décidé d’accorder l’accès à l’application, l’URL de redirection contient un code d’autorisation. Exemple :
{redirect_url}?code=7xqwtlf3rrdj8uyeb1yfLe code d’autorisation n’est valable que 120 secondes.
Si l’utilisateur a décidé de ne pas accorder l’accès à l’application, l’URL de redirection contient les paramètres error et error_description qui informent l’application que l’utilisateur a refusé l’accès :
{redirect_url}?error=access_denied&error_description=The+end-user+or+authorization+server+denied+the+requestUtilisez ces valeurs pour contrôler le flux de votre application. Si l’URL contient le paramètre code, obtenez un token d’accès auprès de Zendesk, comme décrit dans la section suivante. Il s’agit du token à inclure dans les appels API à Zendesk.
Étape 3 - Obtenez un token d’accès auprès de Zendesk
Si votre application a reçu un code d’autorisation de Zendesk en réponse à l’utilisateur octroyant l’accès, votre application peut l’échanger contre un token d’accès. Pour obtenir le token d’accès, lancez une requête POST au point final suivant :
https://{subdomain}.zendesk.com/oauth/tokensIncluez les paramètres suivants exigés dans la requête :
- grant_type : spécifiez « authorization_code » comme valeur.
- code : utilisez le code d’autorisation que vous avez reçu de Zendesk après octroi de l’accès par l’utilisateur.
- client_id : utilisez l’identifiant unique spécifié dans un client OAuth dans l’interface d’administration Support (Admin > Canaux > API > Clients OAuth). Consultez Enregistrement de votre application auprès de Zendesk.
-
secret : utilisez le secret spécifié dans un client OAuth dans l’interface d’administration Support (Admin > Canaux > API > Clients OAuth). Consultez Enregistrement de votre application auprès de Zendesk.
Si vous utilisez les paramètres PKCE
code_challengeetcode_verifier,client_secretn’est pas exigé. Vous pouvez utiliser cette caractéristique pour effectuer la migration à partir du flux d’octroi implicite, qui n’est plus conseillé à cause d’inquiétudes portant sur la sécurité. Consultez la section portant sur l’utilisation de PKCE pour effectuer la migration à partir du flux d’octroi implicite dans la documentation pour les développeurs. - redirect_uri - La même URL de redirection que celle de l’étape 1. À des fins d’identification uniquement.
- scope - Consultez Définition de la portée.
-
code_verifier - exigé si vous utilisez PKCE. La chaîne utilisée pour générer la valeur
code_challenge. Consultez la section sur la génération de la valeur code_challenge dans la documentation pour les développeurs. - expires_in - Facultatif. Nombre de secondes pendant lesquelles le token d’accès est valide. Consultez OAuth Tokens for Grant Types.
- refresh_token_expires_in - Facultatif. Nombre de secondes pendant lesquelles le token d’actualisation est valide. Consultez OAuth Tokens for Grant Types.
La requête doit être dirigée sur un site https et les propriétés doivent être au format JSON. Si vous utilisez une application personnalisée ou tierce pour effectuer la demande API, consultez sa documentation pour connaître le format approprié pour les valeurs des propriétés.
Utilisation de 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 POSTExemple de réponse
Status: 200 OK
{
"access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
"token_type": "bearer",
"scope":"read"
}Étape 4 - Utilisez le token d’accès dans les appels API
L’application peut utiliser le token d’accès pour effectuer des appels d’API. Incluez le token dans un en-tête d’autorisation HTTP avec la demande, comme suit :
Authorization: Bearer {a_valid_access_token}
Par exemple, une requête curl pour répertorier des tickets ressemblerait à ce qui suit :
curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
-H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"
0 commentaire
Se connecter pour laisser un commentaire.