Identité vérifiée du widget

L’API REST (clients, réponses, etc.) est décrite dans la page Pour commencer.

​

Ce que l’option protège

• Une URL d’agent divulguée ne sert à rien sans un jeton signé par votre serveur. Copier le snippet ou l’UUID de l’agent sur un autre site ne permet pas de discuter avec lui.
• Chaque utilisateur ne voit que son propre historique. La session est liée à un utilisateur (sub) et à un agent : elle ne donne accès à aucune autre conversation.
• La révocation est immédiate : une rotation de la clé, ou la désactivation de l’option, coupe toutes les sessions en cours.

​

Ce qu’elle ne protège pas

• Elle ne masque pas l’URL ni l’UUID de l’agent, qui restent visibles dans le code source de vos pages.
• Un agent Public reste accessible anonymement, avec ou sans userToken, et l’historique d’un utilisateur n’y est pas confidentiel. Pour réserver l’agent à vos utilisateurs authentifiés, passez-le en Privé (voir Mise en place sans interruption).
• Les métadonnées d’un utilisateur sont partagées entre les agents de votre compte. Si vous gardez un autre agent Public et que vous enrichissez vos utilisateurs via l’API (/api/v1/customers), ces métadonnées restent lisibles par qui connaît l’identifiant de l’utilisateur. Dans ce cas, passez aussi cet agent en Privé, ou n’y placez pas de données sensibles.
• Elle vaut ce que vaut votre authentification : toute personne qui obtient un jeton valide peut ouvrir une session au nom de cet utilisateur tant que le jeton n’a pas expiré. Ne délivrez de jeton qu’à l’utilisateur connecté et gardez une durée de vie courte.
• Les utilisateurs de votre entreprise connectés à Moustache AI conservent l’accès aux agents Privés, comme aujourd’hui.

​

Prérequis

1. L’option est activée sur votre compte par l’équipe Moustache AI. Tant qu’elle ne l’est pas, la section « Identité vérifiée du widget » de la Console l’indique ; contactez-nous pour l’activer.
2. Une clé secrète est générée par un administrateur : Console > Administration > Identité vérifiée du widget > Générer la clé. La clé commence par mwsk_.
3. La clé est stockée côté serveur uniquement (variable d’environnement, coffre de secrets). Elle ne doit jamais apparaître dans du code exécuté par le navigateur, ni dans votre dépôt.

​

Le jeton utilisateur (JWT)

​

Côté page

window.initMoustacheAI({
  chatbot: 'UUID-DE-L-AGENT',
  userToken: <?= json_encode($moustacheUserToken) ?>,
})

window.initMoustacheAI({
  chatbot: 'UUID-DE-L-AGENT',
  userToken: async () => {
    const response = await fetch('/moustache/token', {
      credentials: 'same-origin',
    })
    if (!response.ok) {
      throw new Error('Jeton Moustache AI indisponible')
    }
    const { token } = await response.json()
    return token
  },
})

​

Côté serveur

​

Node.js (jose)

// npm install jose
import { SignJWT } from 'jose'

const secret = new TextEncoder().encode(
  process.env.MOUSTACHE_WIDGET_IDENTITY_SECRET // la clé mwsk_… telle quelle
)

export async function createMoustacheUserToken(userId) {
  return await new SignJWT({})
    .setProtectedHeader({ alg: 'HS256' })
    .setSubject(String(userId)) // 100 caractères maximum
    .setIssuedAt()
    .setExpirationTime('10m')
    // .setAudience('UUID-DE-L-AGENT') // optionnel
    .sign(secret)
}

// Exemple Express
app.get('/moustache/token', requireLogin, async (req, res) => {
  res.set('Cache-Control', 'no-store')
  res.json({ token: await createMoustacheUserToken(req.user.id) })
})

​

PHP (firebase/php-jwt)

<?php
// composer require firebase/php-jwt
require __DIR__ . '/vendor/autoload.php';

use Firebase\JWT\JWT;

session_start();
if (!isset($_SESSION['user_id'])) {
    http_response_code(401);
    exit;
}

$secret = getenv('MOUSTACHE_WIDGET_IDENTITY_SECRET'); // la clé mwsk_… telle quelle
$now = time();

$token = JWT::encode([
    'sub' => (string) $_SESSION['user_id'], // 100 caractères maximum
    'iat' => $now,
    'exp' => $now + 600,                    // 10 minutes
    // 'aud' => 'UUID-DE-L-AGENT',          // optionnel
], $secret, 'HS256');

header('Content-Type: application/json');
header('Cache-Control: no-store');
echo json_encode(['token' => $token]);

​

Mise en place sans interruption

1. Laissez l’agent en Public et déployez userToken (serveur + page). Vérifiez que le widget s’ouvre, qu’aucune erreur n’apparaît dans la console du navigateur et que chaque utilisateur retrouve son historique.
2. Passez l’agent en Privé (réglages de l’agent, champ Accès). À partir de là, seuls les widgets munis d’un jeton valide fonctionnent.

​

Rotation de la clé

• L’ancienne clé cesse de fonctionner immédiatement : les jetons signés avec elle sont refusés et toutes les sessions de widget en cours sont révoquées.
• Il n’y a pas de période de recouvrement : mettez à jour la clé sur votre serveur juste après la rotation. En attendant, le widget ne s’affiche pas (erreur invalid_signature).
• Régénérez la clé dès que vous soupçonnez une fuite.

​

Durée de session et renouvellement

• Une session de widget dure 12 heures.
• Le widget la renouvelle automatiquement avant d’ouvrir la fenêtre de discussion lorsqu’il lui reste moins de 30 minutes, et lorsqu’elle est refusée en cours d’utilisation (expirée ou révoquée) ; la fenêtre se recharge alors avec la nouvelle session et l’historique est conservé.
• Chaque renouvellement demande un nouveau jeton à userToken. Avec une fonction, c’est transparent. Avec une chaîne, le widget réutilise le même jeton, qui aura expiré si vous suivez la recommandation de 10 minutes : il faudra recharger la page. Préférez la fonction pour les pages qui restent ouvertes longtemps (applications monopage, back-offices).

​

Erreurs

Moustache AI: the user identity could not be verified (<code>). The chatbot will not be loaded.

• user_token_unavailable : votre fonction userToken a levé une erreur ;
• missing_user_token : elle a renvoyé une valeur vide ;
• network_error : la requête a été bloquée, par exemple par une politique CSP (autorisez l’hôte Moustache AI dans connect-src).