Mon édition
Suite, toutes les versions Team, Growth, Professional, Enterprise ou Enterprise Plus
Support Team, Professional ou Enterprise

Résumé IA vérifié ◀▼

Utilisez OAuth 2 pour authentifier les demandes API de façon sécurisée, sans stocker les mots de passe des utilisateurs. Enregistrez votre application pour générer des identifiants OAuth et implémenter le workflow de code d’autorisation afin d’obtenir des tokens d’accès. Gérez l’expiration des tokens en les actualisant avec le token d’actualisation.

Lieu : Centre d’administration > Applications et intégrations > API > Clients OAuth

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 ajouter certaines fonctionnalités à votre application pour qu’elle prenne en charge le workflow de code d’autorisation OAuth et l’actualisation des tokens d’accès expirés.

Zendesk prend aussi en charge le workflow de type d’octroi d’identifiants client, qui vous permet de créer un token d’accès en utilisant uniquement le secret d’un client OAuth. Ce type d’autorisation est destiné uniquement aux clients confidentiels et n’est pas couvert dans cet article. Pour en savoir plus, consultez l’article sur le type d’autorisation d’identifiants client dans la documentation de référence de l’API.

Sujets abordés dans cet article :

  • Enregistrement de votre application auprès de Zendesk
  • Mise en œuvre d’un workflow d’autorisation OAuth dans votre application
  • Remplacement des tokens d’accès expirés

Articles connexes :

  • Pour un didacticiel expliquant la création d’une application Web mettant en œuvre le workflow d’autorisation OAuth, consultez l’article sur l’utilisation d’OAuth pour authentifier les demandes API Zendesk dans une application Web.
  • Pour savoir comment mettre en œuvre un workflow 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 Création et utilisation de tokens d’accès OAuth avec l’API.

Enregistrement de votre application auprès de Zendesk

Vous devez enregistrer votre application pour générer des identifiants OAuth que votre application utilisera pour authentifier les appels API vers Zendesk.

Remarque – Cette section explique comment configurer un client OAuth pour les utilisateurs d’un seul client Zendesk. Si votre application communique non seulement avec un compte Zendesk, mais également avec une multitude d’autres comptes, vous pouvez demander un client OAuthglobal. Un client OAuth global est une méthode plus sûre et plus propre d’effectuer l’authentification API avec plusieurs instances Zendesk. Pour en savoir plus, consultez l’article portant sur la configuration d’un client OAuth global.

Pour enregistrer votre application

  1. Dans le Centre d’administration, cliquez sur Applications et intégrations () dans la barre latérale, puis sélectionnez API > Clients OAuth.
  2. Cliquez sur Ajouter un client OAuth sur la droite de la liste des clients OAuth.
  3. Remplissez les champs suivants pour créer un client :
    • Nom - 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 : 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.
    • Genre 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 client.
    • 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.
  4. 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 OAuth 2.0.

  5. 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.
  6. Cliquez sur Enregistrer.

Utilisez l’identifiant unique et la valeur secrète dans votre application, comme décrit dans le sujet suivant.

Types de client

Les clients OAuth ont une propriété kind qui peut avoir l’une des valeurs suivantes :

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

Les clients confidentiels incluent par exemple les applications Web côté serveur. Une fois que le serveur d’autorisation fournit les tokens ou les identifiants à l’application Web, ces identifiants ne sont pas exposés à l’extérieur.

Les clients publics incluent par exemple les applications mobiles et les applications JavaScript qui s’exécutent sur des clients agent utilisateur, comme les navigateurs Web. Dans ces clients, les identifiants sont facilement accessibles (et souvent visibles).

Ces types de clients sont équivalents dans les spécifications OAuth. Pour en savoir plus, consultez la section Types de client dans les spécifications OAuth 2.0.

Cette propriété s’applique uniquement au système de gestion des tickets Zendesk Support. Elle n’est pas prise 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 ait la valeur 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.

Remarque – Si vous utilisez un client OAuth Zendesk existant et projetez de mettre à jour la propriété 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 obligatoire pour les clients OAuth créé avec le point de terminaison api/v2/oauth/clients endpoint, mais Zendesk recommande de l’inclure.

Mise en œuvre d’un workflow d’autorisation OAuth dans votre application

Zendesk prend en charge le workflow d’octroi de code d’autorisation pour l’obtention des tokens d’accès. Ce workflow est appelé workflow 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 obtenir un nouveau token d’accès quand il expire en utilisant le token d’actualisation fourni.

Pour mettre en œuvre le workflow 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 workflow de code d’autorisation OAuth, consultez l’article sur l’utilisation d’OAuth pour authentifier les demandes API Zendesk dans une application Web.

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/new

où {subdomain} est votre sous-domaine Zendesk principal, pas un sous-domaine avec mappage d’hôte.

Vous pouvez utiliser une demande 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 code comme 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 state et 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 demande GET 

https://{subdomain}.zendesk.com/oauth/authorizations/new?response_type=code&redirect_uri={your_redirect_url}&client_id={your_unique_identifier}&scope=read%20write

La 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=7xqwtlf3rrdj8uyeb1yf

Le 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+request

Utilisez ces valeurs pour contrôler le workflow 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 et un token d’actualisation. Pour obtenir les tokens, effectuez une demande POST au point de terminaison Créer un token pour le type d’octroi : 

https://{subdomain}.zendesk.com/oauth/tokens
Remarque – Ne confondez pas ce point de terminaison avec le point de terminaison Create token dans l’API Tokens OAuth. Même si ces deux points de terminaison renvoient des tokens d’accès OAuth valides, ils ne partagent pas le même chemin, le même format JSON ni les mêmes paramètres de demande.

Incluez les paramètres suivants exigés dans la demande :

  • 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 Zendesk (Applications et intégrations > API > Clients OAuth). Consultez Enregistrement de votre application auprès de Zendesk.
  • client_secret : utilisez le secret spécifié dans un client OAuth dans l’interface d’administration Zendesk (Applications et intégrations > API > Clients OAuth). Consultez Enregistrement de votre application auprès de Zendesk.

    Si vous utilisez les paramètres PKCE code_challenge et code_verifier, client_secret n’est pas exigé. Vous pouvez utiliser cette caractéristique pour effectuer la migration à partir du workflow 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 workflow d’octroi implicite dans la documentation pour les développeurs.

  • redirect_uri : 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 : nombre de secondes pendant lesquelles le token d’accès est valide. Spécifiez une valeur comprise entre 300 secondes (5 minutes) et 172 800 secondes (2 jours).
  • refresh_token_expires_in : nombre de secondes pendant lesquelles le token d’actualisation est valide. Spécifiez une valeur comprise entre 604 800 secondes (7 jours) et 7 776 000 secondes (90 jours).

Consultez la section sur le point de terminaison Créer un token pour le type d’autorisation dans la documentation de référence de l’API pour en savoir plus.

La demande 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 la bibliothèque de demandes 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
    }
)

Exemple de réponse 

Status: 201 OK

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

Enregistrez le token d’accès et le token d’actualisation dans un entrepôt de données sécurisé pour pouvoir les réutiliser plus tard.

É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 demande curl pour répertorier des tickets ressemblerait à ce qui suit : 

curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
  -H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"

Remplacement des tokens d’accès expirés

Les token d’accès expirent après un délai défini. Utilisez le token d’actualisation que vous avez reçu pour demander un nouveau token d’accès. Vous n’avez pas besoin d’utiliser le workflow de code d’autorisation pour obtenir le nouveau token.

Votre application doit 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 est survenue, utilisez un gestionnaire pour l’actualiser. Si le processus d’actualisation échoue ou s’il n’y a pas de token d’actualisation associé au token d’accès, redirigez l’utilisateur vers https://{subdomain}.zendesk.com/oauth/authorizations/new afin de réautoriser votre application.

Comment savoir si un token d’accès a expiré

Instrumentez votre code pour rechercher une réponse 401 après avoir effectué une demande API avec le token. La réponse inclura la chaîne JSON suivante : 

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

Si vous recevez une réponse 401, appelez un gestionnaire pour actualiser le token d’accès en utilisant le token d’actualisation que vous avez reçu avec le token d’accès.

Voici un exemple en utilisant la bibliothèque de demandes 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)

Actualisation d’un token d’accès

Pour actualiser un token d’accès, effectuez une demande POST au point de terminaison Créer un token pour le type d’octroi : 

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

Incluez les propriétés suivantes dans le corps de la demande :

  • grant_type : spécifiez la chaîne « refresh token » comme valeur.
  • refresh_token : spécifiez la valeur du token d’actualisation que vous avez reçu avec le token d’accès.
  • client_id : utilisez l’identifiant spécifié dans le client OAuth dans l’interface d’administration Zendesk (Applications et intégrations > API > Clients OAuth). Consultez Enregistrement de votre application auprès de Zendesk.
  • client_secret : utilisez le secret spécifié dans le client OAuth dans l’interface d’administration Zendesk (Applications et intégrations > API > Clients OAuth). Consultez Enregistrement de votre application auprès de Zendesk.
  • scope : consultez Définition de la portée.
  • expires_in : nombre de secondes pendant lesquelles le token d’accès est valide. Spécifiez une valeur comprise entre 300 secondes (5 minutes) et 172 800 secondes (2 jours).
  • refresh_token_expires_in : nombre de secondes pendant lesquelles le token d’actualisation est valide. Spécifiez une valeur comprise entre 604 800 secondes (7 jours) et 7 776 000 secondes (90 jours).

Consultez la section sur le point de terminaison Créer un token pour le type d’autorisation dans la documentation de référence de l’API pour en savoir plus.

Voici un exemple de demande en utilisant la bibliothèque de demandes 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 demande crée de nouveaux token d’accès et d’actualisation, tout en invalidant les précédents. Voici un exemple de réponse : 

Status: 201 OK

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

Enregistrez les deux tokens dans un entrepôt de données sécurisé pour pouvoir les utiliser plus tard.

Réalisé par Zendesk