Activation de la connexion unique JWT

toutes les éditions Suite tous les produits

Accès rapide : Centre d’administration > Compte > Sécurité > Connexion unique

La connexion unique est un mécanisme qui vous permet d’authentifier les utilisateurs dans vos systèmes pour ensuite indiquer à Zendesk qu’ils ont été authentifiés. Si vous utilisez la connexion unique avec JWT (token Web JSON), les utilisateurs sont automatiquement vérifiés auprès du fournisseur d’identité quand ils se connectent. Les utilisateurs sont alors autorisés à accéder à Zendesk sans avoir à saisir d’identifiants de connexion supplémentaires.

En tant qu’administrateur Zendesk, votre rôle est d’activer les options de connexion unique. Cet article décrit comment activer plusieurs configurations de connexion unique JWT qui peuvent servir à authentifier les membres de l’équipe (administrateurs et agents, y compris les agents light et les contributeurs), les utilisateurs finaux ou les deux.

Au centre de la connexion unique se trouve un mécanisme de sécurité qui permet à Zendesk de faire confiance aux demandes de connexion reçues depuis vos systèmes. Zendesk accorde l’accès uniquement aux utilisateurs que vous avez authentifiés. La connexion unique Zendesk utilise JWT pour sécuriser l’échange des données d’authentification des utilisateurs.

Cet article contient les sections suivantes :

L’équipe informatique d’une entreprise est généralement chargée de la configuration et de la gestion du système d’authentification JWT de l’entreprise. Son rôle est d’implémenter la connexion unique pour Zendesk dans le système. L’équipe peut consulter le sujet suivant dans cet article :

Fiche pour l’implémentation technique

Fonctionnement de la connexion unique avec JWT pour Zendesk

Une fois la connexion unique activée, les demandes de connexion sont envoyées à une page de connexion à l’extérieur de Zendesk Support.

兵站du突起d 'authentification connexi不相上下on unique avec JWT :

Un utilisateur non authentifié navigue jusqu’à votre URL Zendesk Support. Exemple :https://votre_sousdomaine．zendesk.com/．
Le mécanisme de connexion unique Zendesk détecte que la connexion unique est activée et que l’utilisateur n’est pas authentifié.
Zendesk essaie de déterminer si l’utilisateur non authentifié est un utilisateur final ou un membre de l’équipe et le redirige vers la page de connexion à distance appropriée de votre organisation. Exemple :https://mon_entreprise．com/zendesk/sso．
Un script sur le serveur à distance authentifie l’utilisateur en utilisant le processus de connexion de votre organisation.
Le système d’authentification crée une demande JWT contenant les données utilisateur appropriées.
Le système d’authentification redirige l’utilisateur vers le point de terminaison Zendesk suivant avec la charge JWT :
https://votre_sousdomaine．zendesk.com/access/jwt
Zendesk analyse les détails de l’utilisateur de la charge JWT, puis lui accorde une session.

Comme vous le voyez, ce processus s’appuie sur des redirections du navigateur et la transmission de messages signés avec JWT. Les redirections ont lieu entièrement dans le navigateur et il n’y a pas de connexion directe entre Zendesk et vos systèmes, ce qui vous permet de placer vos scripts d’authentification en sécurité derrière le pare-feu de votre entreprise.

Configuration requise pour l’activation de la connexion unique avec JWT

Rencontrez l’équipe responsable du système d’authentification JWT de votre entreprise (en général l’équipe informatique) pour vous assurer que le trafic Zendesk utilise HTTPS et non HTTP.

Vous aurez besoin des informations suivantes pour configurer une méthode de connexion unique JWT dans Zendesk. Votre équipe informatique devrait pouvoir vous les fournir.

L’URL de connexion à distance vers laquelle rediriger les utilisateurs Zendesk quand ils essaient d’accéder à Zendesk.
(facultatif) L’URL de déconnexion à distance vers laquelle Zendesk peut rediriger les utilisateurs quand ils se déconnectent de Zendesk.
(facultatif) Une liste de plages IP pour rediriger les utilisateurs vers l’option de connexion appropriée. Les utilisateurs faisant des demandes à partir des plages IP spécifiées sont dirigés vers le formulaire d’authentification JWT à distance. Les utilisateurs faisant des demandes provenant d’adresses IP hors de ces plages sont dirigés vers le formulaire de connexion Zendesk normal. Si vous ne spécifiez pas de plage, tous les utilisateurs sont redirigés vers le formulaire d’authentification à distance.

Il est possible que l’équipe informatique ait besoin de plus d’informations de la part de Zendesk pour configurer l’implémentation JWT. Dites-lui de consulter laFiche pour l’implémentation techniquede cet article.

Une fois que vous avez vérifié que vous remplissez toutes les exigences et disposez de toutes les informations nécessaires, vous êtes prêt àactiver la connexion unique JWT．

Activation de la connexion unique avec JWT

Les administrateurs peuvent activer la connexion unique JWT pour les utilisateurs finaux uniquement, pour les membres de l’équipe (y compris les agents light et les contributeurs) uniquement ou pour les deux groupes. Vous pouvez créer plusieurs configurations de connexion unique JWT. Avant de commencer, procurez-vous les informations obligatoires auprès de l’équipe informatique de votre entreprise. ConsultezConfiguration requise pour l’activation de la connexion unique avec JWT．

Pour activer la connexion unique JWT

Dans leCentre d’administration, cliquez sur l’icôneCompte() dans la barre latérale, puis sélectionnezSécurité > Connexion unique．
Cliquez surCréer une configuration de connexion unique, puis sélectionnezToken Web JSON．
Entrez unnom de configurationunique.
PourURL de connexion à distancesaisissez l 'URL更小的那个rediriger vos跑龙套isateurs quand ils essaient d’accéder à votre URL Zendesk.
Zendesk ajoute automatiquement un paramètrebrand_idà l’URL. Il s’agit de la marque Zendesk Support que consultait l’utilisateur quand il a essayé de se connecter.
(facultatif) PourURL de déconnexion à distance, saisissez une URL de déconnexion vers laquelle les utilisateurs doivent être redirigés quand ils se déconnectent de Zendesk.
Zendesk ajoute automatiquement les paramètresemail,external_idetbrand_idà l’URL de déconnexion. Si vous préférez que l’URL n’inclue pas les informations d’e-mail et d’ID externe, spécifiez des paramètres vides dans l’URL de déconnexion. Exemple :
https://www.xyz.com/user/signout/?email=&external_id=

Remarque –Si vous utilisez une application Ember.js, vous devez modifier l’URL pour utiliser des paramètres vides avant l’adressage. Par exemple,https://somedomain.com/?brand_id=&return_to=&email=#/zendesk-login/．
(facultatif) Pour lesplages IP, saisissez une liste de plages pour rediriger les utilisateurs vers l’option de connexion appropriée.
Les utilisateurs faisant des demandes à partir des plages IP spécifiées sont dirigés vers le formulaire d’authentification JWT. Les utilisateurs faisant des demandes provenant d’adresses IP hors de ces plages sont dirigés vers le formulaire de connexion Zendesk normal. Ne spécifiez pas de plage si vous voulez que tous les utilisateurs soient redirigés vers le formulaire d’authentification JWT.
Si vous utilisez des ID externes pour vos utilisateurs, vous pouvez les mettre à jour dans Zendesk Support en sélectionnantOnpourAutoriser la mise à jour des ID externes ?
Fournissez lesecret partagéà votre équipe informatique. Elle en aura besoin pour son implémentation JWT.
Important :conservez votre secret partagé en sécurité. S’il est compromis, toutes les données de votre compte Support sont en danger.
SélectionnezAfficher le bouton lorsque les utilisateurs se connectent倒ajouter联合国boutonContinuer avec la connexion uniqueà la page de connexion Zendesk.
Vous pouvez personnaliser le libellé du bouton en saisissant une valeur dans le champNom du bouton．Les libellés de bouton personnalisés sont utiles si vous ajoutez plusieurs boutons de connexion unique à la page de connexion. ConsultezAjout de boutons Continuer avec la connexion unique à la page de connexion Zendeskpour en savoir plus.
Cliquez surEnregistrer．

Par défaut, les configurations de connexion unique d’entreprise sont inactives. Vous devezaffecter la configuration de connexion unique aux utilisateurspour l’activer.

Affectation de la connexion unique avec JWT aux utilisateurs

Après avoir créé votre configuration de connexion unique JWT, vous devez l’activer en l’affectant aux utilisateurs finaux, aux membres de l’équipe ou aux deux.

Pour affecter une configuration de connexion unique aux membres de l’équipe ou aux utilisateurs finaux

Ouvrez les paramètres de sécurité pour les membres de l’équipe et les utilisateurs finaux.
- Dans leCentre d’administration, cliquez surCompte() dans la barre latérale, puis sélectionnezSécurité > Authentification des membres de l’équipe．
- Dans leCentre d’administration, cliquez surCompte() dans la barre latérale, puis sélectionnezSécurité > Authentification des utilisateurs finaux．
Si vous affectez une configuration de connexion unique aux membres de l’équipe, sélectionnezAuthentification externepour afficher les options d’authentification.
Ces options sont déjà affichées pour les utilisateurs finaux.
Cliquez sur l’optionConnexion uniquedans la sectionAuthentification externe, puis sélectionnez le ou les noms de la ou des configurations de connexion unique que vous voulez utiliser.
La connexion unique peut ne pas couvrir toutes les utilisations, et l’authentification Zendesk reste donc active par défaut.
Choisissez la façon dont vous voulez que les utilisateurs se connectent.
Laissez-les choisirpermet aux utilisateurs de se connecter en utilisant n’importe quelle méthode d’authentification active. ConsultezPermettre aux utilisateurs de se connecter à Zendesk de différentes façons．
Redirection vers la connexion uniqueautorise uniquement les utilisateurs à s’authentifier en utilisant laconfiguration de connexion unique principale．Ils ne voient pas d’autres options de connexion, même si ces options d’authentification sont actives. Quand vous sélectionnezRedirection vers la connexion unique, le champConnexion unique principales’affiche pour que vous puissiez sélectionner la configuration de connexion unique principale.
Cliquez surEnregistrer．

Gestion des utilisateurs dans Zendesk après l’activation de la connexion unique JWT

Après l’activation de la connexion unique JWT dans Zendesk, les modifications apportées aux utilisateurs à l’extérieur de Zendesk sont synchronisées avec votre compte Zendesk. Par exemple, si un utilisateur est ajouté à votre système interne, l’utilisateur est automatiquement ajouté à votre compte Zendesk. Si vous supprimez un utilisateur de votre système interne, l’utilisateur ne pourra plus se connecter à votre Zendesk (mais son compte existera toujours dans Zendesk).

Par défaut, les seules données utilisateur stockées dans Zendesk quand la connexion unique est activée sont le nom et l’adresse e-mail de l’utilisateur. Zendesk ne stocke pas les mots de passe. Par conséquent, vous devez désactiver toutes les notifications par e-mail automatisées envoyées par Zendesk au sujet des mots de passe. ConsultezDésactivation des notifications par e-mail au sujet des mots de passe de Zendesk.．

Pour fournir une meilleure expérience client, vous devriez envisager de stocker plus que le nom et l’adresse e-mail de l’utilisateur dans Zendesk. Pour ce faire, vous pouvez utiliser desattributs JWT supplémentaires．

Désactivation des notifications par e-mail au sujet des mots de passe de Zendesk

Quand un utilisateur est ajouté à un compte Zendesk, une notification par e-mail automatique peut lui être envoyée pour lui demander de vérifier son adresse e-mail et de créer un nom d’utilisateur et un mot de passe.

Un profil utilisateur Zendesk est créé pour chaque nouvel utilisateur qui accède à votre compte Zendesk par le biais de SAML ou JWT. Comme il est authentifié par un mot de passe qui ne dépend pas de Zendesk, le profil est créé sans mot de passe car l’utilisateur n’a pas besoin de se connecter à Zendesk. Cependant, par défaut, chaque nouvel utilisateur recevra un e-mail lui demandant de confirmer son adresse e-mail et de créer un nom d’utilisateur et un mot de passe.

Pour éviter cela, désélectionnez les options suivantes.

Dans leCentre d’administration, cliquez surUtilisateurs() dans la barre latérale, puis sélectionnezConfiguration > Utilisateurs finaux．
Dans la sectionE-mails du compte, désélectionnez l’optionAussi envoyer un e-mail de vérification lors de la création d’un nouvel utilisateur par un agent ou un administrateur．
DansPermettre aux utilisateurs de changer de mot de passe, désélectionnez cette option.

Création d’un nouveau secret partagé

Dans certains cas, par exemple si votre secret est compromis, vous devrez peut-être créer un nouveau secret partagé JWT et le communiquer à votre équipe informatique ou un fournisseur d’identité tiers. Vous pouvez générer un nouveau secret partagé JWT à partir du Centre d’administration Zendesk. Cela crée un nouveau secret et annule l’ancien. Vous devez informer votre équipe informatique ou votre fournisseur d’identité externe de votre nouveau secret partagé pour que l’authentification par connexion unique du compte Zendesk fonctionne.

Important :les utilisateurs ne peuvent plus s’authentifier avec la connexion unique JWT jusqu’à ce que le nouveau secret soit mis en place. Assurez-vous que les utilisateurs disposent d’une autre méthode d’authentification.

Pour créer un nouveau secret partagé

Dans leCentre d’administration, cliquez sur l’icôneCompte() dans la barre latérale, puis sélectionnezSécurité > Connexion unique．
Placez votre curseur sur la configuration JWT pour laquelle vous voulez créer un nouveau secret partagé, puis cliquez sur l’icône du menu des options () et sélectionnezModifier．
Allez àSecret partagéen bas de la page de configuration et cliquez surRéinitialiser le secret．
Un message de confirmation s’affiche.
Cliquez surRéinitialiser le secretpour confirmer la réinitialisation.
Vous devriez voir un nouveausecret partagéen texte brut.
Cliquez surCopierpour faire une copie de votre nouveau secret partagé et la remettre à votre équipe informatique ou votre fournisseur d’identité externe.
Enregistrezvos modifications.

Changement de méthode d’authentification

Il est important de noter que si vous utilisez une méthode de connexion unique tierce pour créer et authentifier les utilisateurs dans Zendesk, puis passez à l’authentification Zendesk, ces utilisateurs n’auront pas de mot de passe pour se connecter. Pour obtenir l’accès, ces utilisateurs doivent réinitialiser leur mot de passe à la page de connexion Zendesk.

Informations supplémentaires au sujet de JWT

JWT est une norme ouverte, pilotée par un organisme de normes international (IETF)等soutenue par des重量lourds du secteur科技nologique (par exemple, Microsoft, Facebook et Google).

Les éléments fondamentaux de JWT sont des composants très bien compris, ce qui débouche sur une spécification relativement simple, disponible icihttp://tools.ietf.org/html/draft-jones-json-web-token-10．Il existe de nombreuses implémentations open source de la spécification JWT qui couvrent la plupart des technologies modernes. Cela signifie que vous pouvez configurer la connexion unique JWT sans grandes difficultés.

Attention cependant, la charge JWT est seulement codée et signée, pas chiffrée, ne placez donc pas de données sensibles dans le tableau d’adressage. JWT fonctionne en sérialisant le JSON qui est transmis à une chaîne. La chaîne est codée en base 64, puis JWT convertit cette chaîne base 64 en HMAC, qui dépend du secret partagé. Cela produit une signature que le côté du destinataire peut utiliser pour valider l’utilisateur.

Fiche pour l’implémentation technique

Cette section est destinée à l’équipe responsable du système d’authentification JWT de l’entreprise. Elle fournit des détails au sujet de l’implémentation de la connexion unique JWT pour Zendesk.

Remarque –如果你们将一个一个ancienne已经从水平rsion de la connexion unique Zendesk (appelée authentification à distance Zendesk) vers JWT, vous pouvez avoir plusieurs implémentations de connexion unique activées simultanément. Zendesk détecte si une demande est adressée à JWT ou un autre type de connexion unique et la traite donc en conséquence. Cela signifie que vous pouvez activer et tester JWT avant de désactiver votre implémentation de connexion unique précédente.

Sujets couverts :

Algorithme JWT

Spécifiez HS256 comme algorithme JWT dans l’en-tête de votre charge JWT :

{ "typ":"JWT", "alg":"HS256" }

HS256 signifie HMAC SHA 256, un algorithme de cryptage 256 bits conçu par la NSA (US National Security Agency).

Remarque –Zendesk ne prend pas en charge les algorithmes JWT RS256 et ES256.

Point de terminaison JWT

Une fois l’utilisateur authentifié, redirigez-le en utilisant une demande POST qui contient la charge JWT, vers le point de terminaison Zendesk suivant :

https://votre_sousdomaine．zendesk.com/access/jwt

La charge doit être chiffrée base64 et envoyée dans le corps de la demande sous la forme d’un paramètre chiffré URLjwt, équivalent à un formulaire HTML avecenctype=x-www-url-encoded．

La charge JWT doit être envoyée à votre sous-domaine Zendesk Support en utilisant le protocole https. Exemple :

https://yoursubdomain．zendesk.com/access/jwt

Les sous-domaines avec mappage d’hôte ne sont pas pris en charge.

Attributs JWT

Envoyez les attributs JWT en utilisant un hachage (Ruby) ou un dictionnaire (Python). Le JWT doit être chiffré base64. Exemple utilisant Ruby :

payload = JWT.encode({ :email => "bob@example.com", :name => "Bob", :iat => Time.now.to_i, :jti => rand(2<<64).to_s }, "Our shared secret")

Zendesk exige une adresse e-mail pour identifier l’utilisateur de façon unique. En plus des attributs obligatoires que vous pouvez voir dans le tableau ci-dessous, vous pouvez envoyer des données de profil utilisateur supplémentaires facultatives. Ces données sont synchronisées entre votre système de gestion des utilisateurs et Zendesk Support.

Attributs requis

Attribut	Description
iat	Émis à. L’heure à laquelle le token a été généré. Cela permet de s’assurer qu’un token donné est utilisé peu de temps après sa génération. La valeur doit être le nombre de secondes depuis l’epoch UNIX．亚博Zendesk autorise联合国倾角差d这里最大的de trois minutes, alors n’oubliez pas de configurer le protocole NTP ou similaire sur vos serveurs.
jti	ID du token Web JSON. Un identifiant unique pour le token, utilisé par Zendesk pour empêcher les attaques de réutilisation de token.
email	Adresse e-mail de l’utilisateur en cours de connexion, utilisée pour identifier de façon unique le dossier de l’utilisateur dans Zendesk Support.
name	Nom de l’utilisateur. L’utilisateur dans Zendesk Support sera créé ou mis à jour en fonction de cet attribut.

Attributs utilisateur facultatifs

Attribut	Description
external_id	Si vos utilisateurs sont identifiés de façon unique par autre chose qu’une adresse e-mail et si leur adresse e-mail risque de changer, envoyez l’ID unique depuis votre système. Spécifiez l’ID sous la forme d’une chaîne.
locale (pour utilisateurs finaux) locale_id (pour agents)	Langue dans Zendesk Support, spécifiée en tant que chiffre.
organization	Nom d’une organisation à laquelle ajouter l’utilisateur. Si l’optionAutoriser les utilisateurs à appartenir à plusieurs organisationsest activée, des organisations supplémentaires sont ajoutées à celle d’origine et sont considérées comme des organisations secondaires. Cela ne supprime pas les affiliations existantes. Si vous voulez transférez plusieurs noms d’organisation à la fois, utilisez plutôt l’attributorganizations．Les noms d’organisation doivent être transférés dans une chaîne, séparés par des virgules.
organization_id	ID externede l’organisation dans l’API Zendesk. Si organization et organization_id sont fournies, alors l’attribut organization est ignoré. Si l’optionAutoriser les utilisateurs à appartenir à plusieurs organisationsest activée, des organisations supplémentaires sont ajoutées à celle d’origine et sont considérées comme des organisations secondaires. Cela ne supprime pas les affiliations existantes. Si vous voulez transférer plusieurs ID d’organisation à la fois, utilisez plutôt l’attributorganization_ids．Les ID d’organisation doivent être transférés dans une chaîne, séparés par des virgules.
phone	Numéro de téléphone, spécifié sous forme de chaîne.
tags	Il s’agit d’un jeu de marqueurs JSON à configurer pour l’utilisateur. Ces marqueursremplacenttous les autres marqueurs qui existent dans le profil utilisateur.
remote_photo_url	URL d’une photo pour le profil utilisateur.
role	Rôle de l’utilisateur. Cette valeur peut être définie surend_user,agentouadmin．La valeur par défaut estend_user．Si le rôle de l’utilisateur est différent du rôle dans Zendesk Support, le rôle est modifié dans Zendesk Support.
custom_role_id	Applicable seulement si le rôle de l’utilisateur est « agent ».
user_fields	Adressage JSON de la clé de champ d’utilisateur personnalisé et des valeurs à définir pour l’utilisateur. Le champ d’utilisateur personnalisé doit exister pour définir la valeur du champ. Chaque champ d’utilisateur personnalisé est identifié par sa clé de champ, qui se trouve dans les paramètres d’administration des champs d’utilisateur. Le format des valeurs de date est : aaaa-mm-jj. Si une valeur ou une clé de champ d’utilisateur personnalisé n’est pas valide, la mise à jour du champ échouera sans message d’erreur et l’utilisateur pourra toujours se connecter. Pour en savoir plus au sujet des champs d’utilisateur personnalisés, consultezAjout de champs personnalisés aux utilisateurs． Remarque –L’envoi de valeurs null dans l’attribut user_fields supprimera toute valeur existante dans les champs correspondants.

Paramètre de l’URL de connexion à distance (return_to)

Le transfert du paramètrereturn_toest facultatif, mais nous vous le conseillons pour une expérience utilisateur plus conviviale. Quand Zendesk redirige un utilisateur vers votre page de connexion à distance, il peut transférer un paramètre d’URLreturn_to．Le paramètre contient la page à laquelle Zendesk renverra l’utilisateur une fois que votre système l’a identifié. Ajoutez le nom et la valeur du paramètre au point de terminaison JWT Zendesk.

Par exemple, supposez qu’un agent qui est déconnecté clique sur le lien suivant pour ouvrir un ticket dans Support :https://mon_entreprise.zendesk.com/tickets/1232．Le flux est le suivant :

Quand l’utilisateur clique, Zendesk le redirige vers l’URL de connexion à distance et ajouter le paramètrereturn_to根据l 'URL:
```
https://mycompany.com/zendesk/sso?return_to=https://mycompany.zendesk.com/tickets/123
```
Votre système d’authentification extrait le paramètrereturn_tode l’URL et, une fois l’authentification de l’utilisateur effectuée, l’ajoute au point de terminaison JWT Zendesk. Exemple :
```
https://mycompany.zendesk.com/access/jwt?&return_to=https://mycompany.zendesk.com/tickets/123
```
Zendesk utilise le paramètre pour ouvrir la page du ticket pour l’agent.

Le paramètrereturn_toest une URL absolue pour l’interface d’agent et une URL relative pour le centre d’aide.

Remarque –Si l’adresse de votre paramètrereturn_tocontient ses propres valeurs d’URL, vérifiez que votre script code en URI toute la valeur return_to lors de l’envoi du token JWT.

Traitement des erreurs

Si Zendesk rencontre une erreur lors du traitement d’une demande de connexion JWT, un message expliquant le problème est envoyé. Si vous avez spécifié une URL de connexion à distance quand vous avez configuré l’intégration JWT. Zendesk vous redirige vers cette URL et transmet un paramètremessageet un paramètrekind．En cas d’erreur, le paramètrekindaura toujours la valeur « error ». Zendesk vous conseille de configurer une URL de connexion à distance et des messages de connexion, en plus du type. La plupart des erreurs qui peuvent survenir doivent être résolues (par exemple, décalage d’horloge, limites de taux atteintes, tokens non valides, etc.).

Exemples de code d’implémentation JWT

L’implémentation JWT est simple et de nombreux ouvrages sont disponibles dans la plupart des langues. Zendesk fournit une série d’exemples pour diverses piles dans le répertoire GitHub de connexion unique JWT :

https://github.com/zendesk/zendesk_jwt_sso_examples

Si vous implémentez JWT dans une autre pile, nous serions enchantés d’en inclure un exemple. Ajoutez un commentaire à cet article afin de partager votre implémentation.

Si vous exécutez IIS/AD et ne voulez pas créer votre propre solution .NET, nous fournissons une implémentation complète en ASP classique, qui ne vous demandera que l’ajustement de quelques variables.Téléchargez le script d’authentification ASPà partir de GitHub :