Authentification JWT

Identifiez les utilisateurs dans votre widget d'aide sans nécessiter de connexion séparée. Lorsque les utilisateurs sont connectés à votre application, vous pouvez transmettre leur identité à Ferndesk à l'aide d'un jeton JWT signé par votre backend.

Comment ça fonctionne

Flux en trois étapes :

1. Votre frontend détecte un utilisateur connecté

2. Votre backend génère un JWT signé avec les détails de l'utilisateur

3. Votre frontend appelle Ferndesk('identify', { jwt })

Le centre d'aide et le widget savent désormais qui est l'utilisateur pour l'authentification, la personnalisation et les analyses.

Secret JWT

Avant de pouvoir signer des JWT, vous avez besoin d'un secret de signature provenant de votre tableau de bord Ferndesk :

1. Allez dans Centre d'aide, puis sous Gérer, cliquez sur Contrôle d'accès.

2. Développez la ligne Identification JWT

3. Cliquez sur Générer le secret

Le secret ne s'affiche qu'une seule fois lors de sa génération. Copiez-le immédiatement et stockez-le de manière sécurisée dans les variables d'environnement de votre backend. Vous ne pourrez plus le visualiser.

Si vous perdez votre secret, vous devrez le supprimer et en générer un nouveau. Cela invalidera tous les jetons JWT existants signés avec l'ancien secret jusqu'à ce que vous mettiez à jour votre backend pour utiliser le nouveau.

Générer le JWT côté serveur

Créez un point de terminaison qui renvoie un jeton signé. Revendications (claims) requises :

• sub (chaîne, requis) : identifiant unique dans votre système qui identifie cet utilisateur. Il s'agit de la clé d'identité principale.

• email (chaîne, requis) : adresse e-mail de l'utilisateur

• name (chaîne, facultatif) : nom d'affichage

• customAttributes (objet, facultatif) : métadonnées supplémentaires

• exp (nombre, recommandé) : horodatage d'expiration du jeton

Exemple Node.js :

const jwt = require('jsonwebtoken');

app.get('/api/ferndesk-token', async (req, res) => {if (!req.user) return res.status(401).json({ error: 'Not authenticated' });

  const token = jwt.sign({
    sub: req.user.id,
    email: req.user.email,
    name: req.user.name,
    exp: Math.floor(Date.now() / 1000) + 3600 // 1 hour
  }, process.env.FERNDESK_JWT_SECRET, { algorithm: 'HS256' });

  res.send(token);
});

Exemple Python :

import jwt
import time

@app.route('/api/ferndesk-token')
def ferndesk_token():
    if not current_user:
        return {'error': 'Not authenticated'}, 401

    token = jwt.encode({
        'sub': current_user.id,
        'email': current_user.email,
        'name': current_user.name,
        'exp': int(time.time()) + 3600
    }, os.environ['FERNDESK_JWT_SECRET'], algorithm='HS256')

    return token

Appeler Identify depuis votre frontend

Récupérez le jeton depuis votre backend et transmettez-le au SDK :

Ferndesk('init', { widgetId: 'your-widget-id' });

fetch('/api/ferndesk-token').then(r => r.text())
  .then(jwt => Ferndesk('identify', { jwt }))
  .catch(err => console.error('Identification failed:', err));

Exemple React :

useEffect(() => {
  window.Ferndesk('init', { widgetId: 'your-widget-id' });

  if (currentUser) {
    fetch('/api/ferndesk-token')
      .then(r => r.text())
      .then(jwt => window.Ferndesk('identify', { jwt }));
  }
}, [currentUser]);

Vérifier que cela fonctionne

Vérifiez ces indicateurs :

• Console du navigateur : aucune erreur. Les JWT invalides affichent Ferndesk: identify failed - invalid jwt.

• Formulaire de contact : l'e-mail et le nom seront pré-remplis.

• Analyses : les sessions utilisateur apparaissent dans votre tableau de bord.

Erreurs courantes

Ferndesk: identify requires a jwt

Paramètre jwt manquant. Vérifiez que votre backend renvoie une chaîne JWT.

invalid jwt

L'échec de la vérification de la signature a échoué. Vérifiez :

• Le secret JWT correct correspond à celui stocké dans Ferndesk.

• Le jeton n'a pas expiré.

• L'algorithme est HS256.

JWT subject does not match the existing help-center user

Cette erreur se produit lorsqu'un e-mail d'utilisateur existe déjà dans votre centre d'aide mais avec un identifiant de sujet différent. Cela signifie que quelqu'un s'est précédemment connecté avec cet e-mail à l'aide d'un système d'identité ou d'une valeur sub différente.

Pour résoudre :

• Assurez-vous que votre backend envoie toujours le même sub pour chaque utilisateur.

• Si vous avez changé de système d'ID utilisateur, l'utilisateur concerné devra être ré-approvisionné dans Ferndesk.

must be called from same domain or 1-level subdomain

Incompatibilité de domaine. Votre application et votre centre d'aide doivent partager un domaine racine.

Notes de sécurité

• Définissez une expiration de jeton (1 heure est courant).

• Générez des jetons uniquement pour les utilisateurs authentifiés.

• Utilisez HTTPS partout.

• Ne validez jamais de secrets dans le contrôle de version.

• Gardez vos valeurs sub stables — Ferndesk conserve l'identité par sujet.