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 en utilisant un jeton JWT signé par votre backend.

Fonctionnement

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 > Personnaliser > Contrôle d'accès

2. Faites défiler jusqu'à la section Authentification 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 revoir.

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. C'est 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 passez-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 bien une chaîne JWT.

invalid jwt

Échec de la vérification de la signature. 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 lorsque l'e-mail d'un 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 en utilisant un système d'identité ou une valeur sub différente.

Pour résoudre ce problème :

• 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 reprovisionné 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 committez jamais de secrets dans le contrôle de version

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