Avant de commencer

Avant d'activer la sécurité, vous devez créer une paire de clés publiques / privées RS256. Vous pouvez utiliser un outil tel que OpenSSL ou PuTTYgen.

Par exemple, pour créer la paire de clés à l'invite de commande à l'aide d' OpenSSL, utilisez la commande openssl genrsa -out key.pem 2048.

Sauvegardez la paire de clés générée dans un emplacement sécurisé.

Assurez-vous que ces clés sont accessibles uniquement par le code de votre serveur. Ne les transmettez jamais à un navigateur client via votre site Web.

Génération d'un jeton JWT

Pour utiliser la sécurité de la discussion Web, vous devez configurer la discussion Web sur votre site Web pour envoyer un jeton Web JSON (JWT) avec chaque message à l'assistant. Le jeton Web JSON (JWT) est utilisé pour vérifier l'origine des messages envoyés à partir de votre site Web et, en option, pour transmettre des données chiffrées supplémentaires. Votre site Web devra pouvoir générer un nouveau jeton Web JSON (JWT) au début de chaque session, ainsi qu'à chaque fois qu'un jeton Web JSON (JWT) existant arrive à expiration.

Ne codez pas un jeton Web JSON (JWT) dans le code de votre site Web ou ne partagez pas de jetons Web JSON (JWT) entre les utilisateurs.

Sur votre serveur, implémentez une fonction qui génère et renvoie un jeton Web JSON (JWT) signé avec votre clé privée. Vous utiliserez ce jeton pour vérifier l'origine des messages envoyés à partir de votre site Web et, le cas échéant, pour transmettre des données chiffrées supplémentaires.

La plupart des langages de programmation offrent des bibliothèques JWT que vous pouvez utiliser pour générer un jeton. Pour valider les jetons JWT signés, l'intégration de discussion Web utilise la bibliothèque jsonwebtoken avec l'algorithme RS256.

Le contenu du jeton Web JSON (JWT) doit spécifier les revendications suivantes:

• sub: ID utilisateur unique qui identifie le client qui interagit avec la discussion Web. Il peut s'agir d'un identificateur unique généré (pour les utilisateurs anonymes) ou d'un ID utilisateur authentifié. Pour plus d'informations sur l'utilisation de la valeur sub, voir Authentification des utilisateurs dans la discussion Web.

  Pour garantir la sécurité, le jeton Web JSON (JWT) doit être spécifique à chaque utilisateur. Utilisez les informations de connexion authentifiées de l'utilisateur ou un ID généré unique. Ne réutilisez pas le même jeton Web JSON (JWT) ou la même valeur sub pour plusieurs utilisateurs.

• exp: délai d'expiration après lequel le jeton Web JSON (JWT) n'est plus valide. De nombreuses bibliothèques JWT définissent automatiquement cette valeur pour vous. Définissez une réclamation exp de courte durée (par exemple, 1h).

  Ne créez pas de jeton JWT sans revendication exp. Bien que cette réclamation ne soit pas formellement requise, son omission représente un risque de sécurité car toute personne ayant accès au jeton Web JSON (JWT) peut la copier et l'utiliser ultérieurement pour accéder à votre assistant. La définition d'un délai d'expiration limite cette exposition.

L'exemple JavaScript suivant montre comment vous pouvez générer un jeton JWT à l'aide de la bibliothèque jsonwebtoken :

// Sample NodeJS code on your server.
const jwt = require('jsonwebtoken');

// Returns a signed JWT signed with the RS256 algorithm.
function createJWT() {
  const payload = {
    sub: 'some-user-id', // Identifies user for billing purposes
  };
  // The "expiresIn" option adds an "exp" claim to the payload.
  return jwt.sign(payload,
    process.env.YOUR_PRIVATE_RSA_KEY,
    { algorithm: 'RS256', expiresIn: '1h' });
}

Configuration de la discussion Web pour inclure les jetons JWT

Maintenant que vous avez implémenté une fonction pour générer un jeton JWT signé, vous devez mettre à jour votre instance de discussion Web pour inclure le jeton JWT signé à chaque message qu'il envoie. Une fois que vous avez activé la sécurité de la discussion Web, tous les messages qui ne sont pas signés avec la clé privée appropriée sont rejetés.

Dans le code HTML de votre site Web, mettez à jour le script d'imbrication de discussion Web pour spécifier un nouveau jeton JWT au début de chaque session, ainsi que chaque fois que le jeton JWT existant expire. La méthode la plus simple consiste à s'abonner à l'événement identityTokenExpired et à générer un nouveau jeton Web JSON (JWT) lorsque cet événement est reçu. L'événement identityTokenExpired est déclenché dans les deux situations suivantes:

• Au début d'une nouvelle session, si aucun jeton JWT n'a été fourni à l'aide de l'option de configuration identityToken.

• Lorsque le jeton Web JSON (JWT) spécifié précédemment arrive à expiration.

Dans votre gestionnaire d'événements onLoad, utilisez la méthode d'instance on() pour vous abonner à l'événement identityTokenExpired.

Dans le rappel, appelez la fonction sur votre serveur que vous avez implémentée pour générer un nouveau jeton JWT. Utilisez ensuite le paramètre identityToken de l'événement pour spécifier le nouveau jeton JWT, comme dans cet exemple:

instance.on({ type: 'identityTokenExpired',
              handler: async function(event) {
                const jwtFromServer = await fetch('http://example.com:3001/createJWT');
                event.identityToken = jwtFromServer;
}});

Le nouveau jeton JWT que vous spécifiez est automatiquement envoyé avec chaque message suivant de l'instance de discussion Web sur votre site Web (jusqu'à l'expiration du jeton).

Vous pouvez également spécifier le jeton Web JSON (JWT) au début de la session à l'aide de la propriété identityToken dans l'objet de configuration de discussion Web. Toutefois, vous devrez toujours créer un gestionnaire d'événements pour identityTokenExpired, sauf si vous êtes certain que vos jetons JWT n'expireront jamais au cours d'une session.

Mise à jour des paramètres de discussion Web

Maintenant que vous avez configuré la discussion Web pour envoyer des jetons JWT signés, vous pouvez activer la sécurité de la discussion Web dans les paramètres d'intégration de la discussion Web.

Une fois que vous avez activé la sécurité de la discussion Web, les messages provenant d'une autre origine que votre instance de discussion Web (que vous avez configurée pour envoyer des jetons JWT signés) sont rejetés. Cela signifie que l'activation de la sécurité de la discussion Web désactive le lien de prévisualisation partageable, qui n'envoie pas de JWT avec des messages. Pour plus d'informations sur le lien d'aperçu, voir Copie d'un lien à partager.

Pour activer la sécurité, procédez comme suit :

1. Dans l'onglet Sécurité des paramètres d'intégration de discussion Web, définissez le commutateur Sécuriser votre discussion Web sur On.

2. Dans la zone Votre clé publique, collez votre clé publique.

   watsonx Assistant utilise la clé publique pour vérifier que les messages entrants proviennent de votre site Web.

Le diagramme suivant illustre le flux de messages entre la discussion Web et l'assistant lorsque la sécurité de la discussion Web est activée: