Comment le jeton sécurisé fonctionne-t-il ?

Tabata Vossen -

Avec la fonctionnalité du jeton sécurisé, Qualifio vous permet de transmettre des informations et d'identifier les participants de manière sécurisée. Découvrez comment l'utiliser.

Principe général

L'idée derrière le jeton sécurisé est de fournir un processus standard pour transmettre en tout sécurité des informations externes à une campagne Qualifio. D'un point de vue technique, ces informations sont partagées sous la forme d'un "JSON Web Token" signé, ou JWS, que vous générez en suivant une structure standard définie par Qualifio.

Vous pouvez ajouter le jeton à l'URL de votre campagne en tant que paramètre, ou l'intégrer au code JavaScript. Lorsque la campagne est chargée, le jeton et son contenu sont consommés par Qualifio.

Un jeton JWT (parfois prononcé "jot") n'est généralement pas crypté, mais simplement signé. En s'assurant que chaque demande est accompagnée d'un jeton signé, nous pouvons valider le jeton et seulement ensuite servir la campagne. Au sujet du cryptage, voyez la section dédiée ci-dessous.

Vous générez également des jetons sécurisés avec un délai d'expiration en fonction de vos propres exigences de sécurité. Le jeton sécurisé est donc la méthode recommandée pour envoyer des informations externes à une campagne Qualifio. 

Générer le jeton sécurisé

Tout d'abord, vous devez générer un jeton pour chaque participation et le partager avec Qualifio. Le jeton sera demandé lors du chargement de la campagne.

Important : Cette procédure est destinée aux développeurs. Nous proposons cette fonctionnalité et la structure attendue mais nous ne prenons pas en charge le développement du jeton sécurisé.

Un jeton JWT signé se compose de trois parties séparées par des points (.) :

HEADER.PAYLOAD.SIGNATURE

Ici, nous allons nous concentrer sur le payload (que nous pouvons traduire par "charge utile"). Ce dernier contient une série d'informations, qui sont en fait des paires clé/valeur, sur une entité (l'utilisateur).

Comment défini dans la RFC-7519, voici un exemple de "payload" de jeton JWT :

{
“sub”: “298776628”,
“iat”: 1619102989,
“exp”: 1619101489 ,
“iss”: “ABC Company”,
“campaignId”: 123456
}

Note : Vous avez la responsabilité de mettre à disposition toutes les informations nécessaires à l'utilisation du jeton. Besoin d'aide ? Nous vous expliquons cela ci-dessous.

Structure d'un jeton JWT

La partie "payload" est donc celle qui contient donc les informations ("déclarations") qui doivent être transmises à Qualifio. On utilise des noms de déclarations courts afin de limiter au maximum la longueur des jetons. Décomposons cela ensemble :

Déclarations réservées

sub (sujet)
Le jeton doit contenir une déclaration "sub" qui identifie l'utilisateur de votre côté, comme le numéro de sa carte de fidélité ou un ID utilisateur unique.

iat (date d'émission)
Le jeton peut contenir une déclaration "iat" qui identifie la date et l'heure d'émission du jeton sous forme de "timestamp" (soit le nombre de secondes depuis Epoch).

exp (date d'expiration)
Le jeton peut contenir une déclaration "exp" qui identifie la date et l'heure d'expiration à partir desquelles le JWT ne doit pas être accepté. Elle est également représentée par un "timestamp". La déclaration "exp" estfortement recommandée pour des raisons de sécurité.

iss (émetteur)
Le jeton peut contenir une déclaration "iss" qui identifie l'émetteur du jeton.

campaignId (identifiant campagne)
Le jeton doit contenir une déclaration "campaignId" qui fournit l'identifiant (ID) unique de la campagne dans laquelle il est utilisé. Trouvez l'ID de votre campagne

Ces déclarations peuvent apparaître dans n'importe quel ordre. N'hésitez pas à nous contacter si vous rencontrez des problèmes.

Déclarations supplémentaires

En fonction de vos besoins, vous pouvez incorporer au jeton des déclarations supplémentaires. Lorsqu'elles sont utilisées par Qualifio, ces déclarations optionnelles peuvent servir différents objectifs. Pour plus d'informations, voir

Implémenter le jeton sécurisé dans Qualifio

Une fois le jeton sécurisé généré, vous pouvez l'utiliser dans Qualifio pour limiter les participations, par exemple.

Note : si c'est la première fois que vous utilisez cette intégration, vous devez l'activer dans votre compte et la configurer (ou contacter l'administrateur de votre compte pour qu'il le fasse). Vous n'aurez à le faire qu'une seule fois.

Étape 1 : Naviguez vers les Paramètres du compte → Intégrations puis activez l'option Jeton sécurisé.

Schermafbeelding_2021-11-25_om_17.15.14.png

Étape 2 : Cliquez sur Paramétrer.

Schermafbeelding_2021-11-25_om_17.16.06.png

Étape 3 : Dans la liste déroulante, sélectionnez un système de validation du jeton :

Schermafbeelding_2021-08-16_om_17.39.00.png

Les jetons peuvent être validés à l'aide des systèmes suivantes :

  • Avec le point de terminaison JWKS, vous publiez un point de terminaison en lecture seule qui nous permet de récupérer le secret utilisé pour signer le jeton (sur base du champ d'en-tête "kid" ou KeyID).
  • Clé publique utilisant RS256 ; RS384 ; RS512 ; ES256 ; ES384 ; ES512.
  • Enfin, il est possible de signer le jeton JWT grâce à une clé symétrique utilisant d'un HMAC (avec l'algorithme HS256, HS384 ou HS512).

Étape 4 : Entrez votre point de terminaison ou votre clé dans le champ correspondant.

Schermafbeelding_2021-11-04_om_15.56.37.png

Étape 5 : Lorsque vous avez fini, cliquez sur Sauvegarder.

Partager le jeton avec Qualifio

Vous devez être en mesure de partager le jeton avec Qualifio au chargement de la page. Ceci peut être fait en incluant le JWT dans l'URL ou le transmettant via JavaScript.

Ajoutez le jeton à l'URL de la WebView de cette façon :

https://interact.qualifioapp.com/20/.../v1.cfm?id=12345678&qual_token=yourToken

ou à l'URL du mini-site, de la manière suivante :

https://interact.qualifioapp.com/xmas?qual_token=yourToken

ou dans l'iframe JavaScript intégré dans votre site :

<div id="qualifio_insert_place_123456" class="qualifio_iframe_wrapper"></div>
<script type="text/javascript">
(function(b,o,n,u,s){var a,t;a=b.createElement(u);a.async=1;a.src=s;t=b.getElementsByTagName(u)[0];t.parentNode.insertBefore(a,t);o[n]=o[n]||[]}) (document,window,'_qual_async','script','//interact.qualifioapp.com/kit/qualp.2.min.js');
_qual_async.push(['createIframe', 'qualifio_insert_place_123456', 'interact.qualifioapp.com', '20', 'A1B23C45-6789-01DE-2F34-567890123G45', '100%', '1200', 'qual_token=yourToken', '', '', 'max-width:810px;margin:0 auto;']);
</script>

FAQ

🔐 Le jeton est-il vraiment sécurisé ? Doit-il être encrypté ?

Compte tenu de la sensibilité des données stockées dans Qualifio, la sécurité est une préoccupation constante pour nous.

Les JWT peuvent être soit signés (un JWS), soit encrypté (un JWE), soit les deux. Une signature permet de vérifier que l'émetteur du jeton est bien celui qu'il prétend être et de veiller à ce que le message ne soit pas modifié en cours de route. Le cryptage, quant à lui, permet de s'assurer que le contenu du JWS est confidentiel et uniquement lisible par Qualifio. Si un jeton est signé, mais non encrypté, tout le monde peut donc lire son contenu, mais ne peut pas le modifier.

Bien que les jetons signés soient généralement suffisants pour vérifier l'intégrité des champs, il est possible d'encrypter le JWS pour assurer le secret entre les parties (par exemple, pour cacher un lot potentiel transmis à Qualifio via le jeton).

Si le jeton est encrypté, vous devrez remplir ce champ :

Schermafbeelding_2021-11-25_om_17.18.10.png

Note : Pour accéder à notre Crypto API, veuillez contacter notre équipe d'assistance.