Au centre de la connexion unique se trouve une technologie appelée token Web JSON (JWT) qui permet à Zendesk de faire confiance aux demandes de connexion reçues depuis vos systèmes. Consultez Configuration de la connexion unique avec JWT (token Web JSON) pour en savoir plus.
Pour les intégrations à connexion unique Zendesk, un mécanisme côté serveur devrait générer le JWT et rediriger le navigateur de l’utilisateur à une URL spécifique à Zendesk, en transférant le JWT comme paramètre dans la chaîne de requête et non dans l’en-tête HTTP.
En général, un JWT se compose de trois parties, séparées par des points. Chaque partie a un rôle différent au sein de la structure du JWT : l’en-tête, la charge et la signature.
Cet article contient les sections suivantes :
Partie 1 : en-tête JWT
La première partie est l’en-tête JWT. Elle indique qu’il s’agit d’une demande JWT, ainsi que le type d’algorithme d’adressage (nous en reparlerons plus tard).
eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
Ce qui est important ici (et pour le reste des données), c’est l’utilisation du codage base64. Ce n’est pas un chiffrement à proprement parler et des outils comme ceux qui suivent peuvent donc être utilisés pour le décodage :
- Outil Web : http://www.base64decode.org/
- Terminal : http://drewsymo.com/how-to/quick-and-simple-base64-encode-on-mac-osx-terminal/
Voici à quoi ressemblent les chaînes une fois décodées :
{"typ":"JWT",
"alg":"HS256"}
Vous voyez une structure JSON avec deux paires clé-valeur signifiant type: JWT et Algorithm: HMAC SHA 256. SHA 256 est un algorithme de chiffrement 256 bits conçu par la NSA (US National Security Agency). Il est utilisé pour générer la troisième partie (la signature), dont nous parlerons un peu plus tard.
Partie 2 : jeu de revendications/Charge utile JWT
La deuxième partie est beaucoup plus longue car elle contient la charge utile. On parle parfois de « jeu de revendications JWT ».
eyJpYXQiOjEzNzIxMTMzMDUsImp0aSI6ODg4MzM2MjUzMTE5Ni4zMjYsIm5hbWUiOiJUZXN0IFVzZXIiLCJlbWFpbCI6InR1c2VyQGV4YW1wbGUub3JnIiwiZXh0ZXJuYWxfaWQiOiI1Njc4Iiwib3JnYW5pemF0aW9uIjoiQXBwbGUiLCJ0YWdzIjoidmlwX3VzZXIiLCJyZW1vdGVfcGhvdG9fdXJsIjoiaHR0cDovL21pdC56ZW5mcy5jb20vMjA2LzIwMTEvMDUvQmFybmFieV9NYXR0X2Nyb3BwZWQuanBnIiwibG9jYWxlX2lkIjoiOCJ9
On y trouve un horodatage, une valeur aléatoire, un nom d’utilisateur, une adresse e-mail, un ID externe et des marqueurs. Il y a aussi d’autres options possibles. Il suffit d’effectuer un décodage base64 pour comprendre la charge utile. Nous allons regarder tout ça ligne par ligne pour que cela soit plus facile à comprendre.
{
"iat":1372113305,
"jti":8883362531196.326,
"name":"Test User",
"email":"tuser@example.org",
"external_id":"5678",
"organization":"Apple",
"tags":"vip_user",
"remote_photo_url":"http://mit.zenfs.com/206/2011/05/Barnaby_Matt_cropped.jpg",
"locale_id":"8"
}
Propriétés exigées
IAT
La première clé est iat, soit issued at (date d’émission). C’est l’horodatage formaté en secondes entières depuis le 1er janvier 1970, une représentation du temps UNIX standard. L’horodatage doit être un nombre entier (pas décimales) et UTC. Il doit aussi ne pas être distant de plus de 3 minutes de l’heure actuelle quand le serveur Zendesk le reçoit. Cela introduit un mécanisme d’auto-destruction dans chaque demande d’authentification à distance, ce qui empêche qu’une demande ne soit utilisée plus de 3 minutes après sa génération.
JTI
La deuxième clé est jti, soit JSON Token ID (ID du token JSON). Ce n’est qu’une chaîne aléatoire, suffisamment longue et aléatoire pour qu’il soit peu probable qu’elle ne soit jamais réutilisée pour ce compte. Si, par accident ou hasard, elle est réutilisée pour une autre demande d’authentification, l’authentification échoue. C’est en fait une clé jetable. En incluant une valeur aléatoire (obligatoire) comme celle-ci, nous nous assurons que chaque demande d’authentification est unique. Cela empêche la réutilisation d’une URL de demande valide. Par exemple, supposons que quelqu’un ait réussi à installer un logiciel malveillant sur votre ordinateur ou votre serveur et ait commencé à enregistrer le trafic. Cette personne peut voir chaque URL que vous consultez. Si elle voit et capture l’URL émise pour votre connexion à Zendesk, elle a 3 minutes pour l’utiliser et se connecter en se faisant passer pour vous sans cette clé unique.
Nom
Vient ensuite le nom complet de l’utilisateur, espaces inclus. Ce que Zendesk reçoit ici devient le nom d’utilisateur, même s’il y avait un autre nom d’utilisateur auparavant.
Vient ensuite l’adresse e-mail de l’utilisateur. L’adresse e-mail est toujours exigé. Elle sert d’identifiant unique pour l’utilisateur, sauf si un ID externe a été reçu*. Cela signifie que si nous recevons une adresse e-mail et un ID externe, nous commençons par essayer de trouver une correspondance pour l’ID externe. Si nous y parvenons, nous mettons l’utilisateur à jour avec l’adresse e-mail spécifiée.
*Remarque - Si l’option Autoriser la mise à jour des ID externes est activée dans Zendesk, nous continuerons à définir l’e-mail, même si nous recevons un ID externe. Si l’adresse e-mail et l’ID externe sont différents, nous changerons l’ID.
Propriétés facultatives
ID externe
L’ID externe est un identifiant facultatif que vous pouvez utiliser pour identifier les utilisateurs au lieu de leur adresse e-mail (voir ci-dessus).
Organisation
Vous pouvez aussi envoyer une valeur d’organisation pour ajouter un utilisateur à une organisation. L’organisation nommée doit déjà exister et le nom doit être identique. Sinon, il ne se passe rien.
Marqueurs
La valeur tags vous permet de définir des marqueurs pour l’utilisateur en cours de connexion. La clé remplace tous les marqueurs existants pour l’utilisateur par les marqueurs que vous spécifiez, alors soyez prudent. Si vous envoyez un paramètre de marqueurs vide, tous les marqueurs sont supprimés de l’utilisateur.
URL de photo à distance
Vous pouvez aussi envoyer une valeur pour remote_photo_url, qui accepte une URL publique contenant une photo et définit cette photo comme photo de profil de l’utilisateur.
Paramètres régionaux (langue)
Vous pouvez envoyer une valeur pour locale_id pour définir ou mettre à jour la langue de l’utilisateur authentifié dans Zendesk. La valeur doit être un nombre correspondant à une langue actuellement activée dans votre Zendesk. Vous pouvez trouver les paramètres régionaux en utilisant le point de terminaison locales.json de notre API: https://developer.zendesk.com/api-reference/ticketing/account-configuration/locales/#list-locales
Champs utilisateur (absents de l’exemple)
Il doit s’agir d’un objet JSON incluant des paires clé/valeur pour la clé et la valeur de chaque champ. Vous pouvez trouver ou définir la clé du champ dans l’interface Champs d’utilisateur. Notez que vous pouvez uniquement envoyer des champs d’utilisateur personnalisés.
Exemple :
"user_fields": {"checked": false,"date_joined": "2013-08-14T00:00:00+00:00","region": "EMEA","text_field": null}
Les cases à cocher utilisent des valeurs booléennes, les codes de date suivent l’exemple ci-dessus et les champs déroulants acceptent le nom de l’option. Les champs de texte acceptent les chaînes.
Numéro de téléphone (absent de l’exemple)
Il s’agit d’une chaîne identifiant un numéro de téléphone. Faites attention d’utiliser un format accepté. Pour en savoir plus, consultez Quels sont les formats de numéros de téléphone acceptés ?.
Partie 3 : signature JWS
La dernière partie de la demande est chiffrée. Vous n’avez pas vraiment à vous en soucier, mais en gros, elle génère une chaîne chiffrée à partir de toutes les informations ci-dessus (iat, jti, nom, e-mail, etc.) et d’un secret partagé. Ensuite, selon les normes JWT, une partie de cette chaîne chiffrée est prélevé (appelée somme de contrôle) : c’est la signature JWS.
Comment est-ce sécurisé ?
Pour générer une chaîne chiffrée valide, vous devez connaître le secret partagé.
Le chiffrement est conçu pour vous empêcher d’obtenir les données et la clé à partir de la chaîne chiffrée. Même si vous possédez les données, il est quasi impossible de déduire la clé.
Mais comme vous avez la clé et nous aussi, et que vous nous envoyez les mêmes données sans chiffrement que celles avec chiffrement, nous pouvons créer la signature et vérifier qu’elle correspond à ce que vous avez envoyé.
Cela garantit également que personne ne peut falsifier les données en transit.
Voici le pseudo-code correspondant :
URLBase64Encode(
HMAC-SHA256(
URLBase64Encode( header_json ).URLBase64Encode( payload_json )
)
)
Lors de la génération du HMAC-SHA256 de l’en-tête et de la charge utile codés, vous incluez le secret partagé.
Voici le résultat :
Zv9P7PNIcgHfxZaMwQtMpty3TZnmVHRWcsmAMM-mNHg