Anatomie d’une requête JWT

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.

Une demande d’authentification JWT ressemble à ceci :

https://joeandco.zendesk.com/access/jwt?jwt=eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpYXQiOjEzNzIxMTMzMDUsImp0aSI6ODg4MzM2MjUzMTE5Ni4zMjYsIm5hbWUiOiJUZXN0IFVzZXIiLCJlbWFpbCI6InR1c2VyQGV4YW1wbGUub3JnIiwiZXh0ZXJuYWxfaWQiOiI1Njc4Iiwib3JnYW5pemF0aW9uIjoiQXBwbGUiLCJ0YWdzIjoidmlwX3VzZXIiLCJyZW1vdGVfcGhvdG9fdXJsIjoiaHR0cDovL21pdC56ZW5mcy5jb20vMjA2LzIwMTEvMDUvQmFybmFieV9NYXR0X2Nyb3BwZWQuanBnIiwibG9jYWxlX2lkIjoiOCJ9.Zv9P7PNIcgHfxZaMwQtMpty3TZnmVHRWcsmAMM-mNHg

En copiant cette URL dans la barre d’adresse d’un navigateur, j’ai accédé à une instance Zendesk.

C’est aussi simple que ça. Il n’y a rien d’autre à faire. Pas de serveurs qui communiquent en arrière-plan. Tout se passe dans une URL.

Un script d’authentification doit simplement la créer (pour simplifier) et y diriger l’utilisateur.

Analysons le token.

https://joeandco.zendesk.com/access/jwt?jwt=

La première partie est un point de terminaison d’URL vers lequel les demandes d’authentification à distance doivent être dirigées. Vient ensuite un point d’interrogation (?), qui indique que vous ajoutez des paramètres. Les paramètres transmettent des informations au script au point de terminaison de destination (https://joeandco.zendesk.com/access/jwt). Le script a été conçu pour accepter ces paramètres, c’est pour cette raison que vous devez l’envoyer à /access/jwt et non à une adresse aléatoire.

Après le point d’interrogation, jwt est le nom du paramètre et = indique que la chaîne qui vient ensuite est la valeur du paramètre.

Le reste est composé de données. En regardant de plus près, vous verrez qu’elles sont séparées par des points. Nous allons nous pencher sur chaque partie individuellement.

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 ressemble 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 algorithme : 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"
}

Obligatoire

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.

E-mail

Vient ensuite l’adresse e-mail de l’utilisateur. 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.

Facultatif

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 profl 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 langues en utilisant le point de terminaison locales.json de notre API: http://developer.zendesk.com/documentation/rest_api/locales.html#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