Authentification JWT

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

Vous aurez besoin de votre secret JWT disponible dans Help Center > Customize > Access Control et du SDK Ferndesk installé.

Comment ça fonctionne

Flux en trois étapes :

Votre frontend détecte un utilisateur connecté
Votre backend génère un JWT signé avec les détails de l'utilisateur
Votre frontend appelle Ferndesk('identify', { token })

Le centre d'aide et le widget connaissent désormais l'identité de l'utilisateur pour l'authentification, la personnalisation et l'analyse.

La méthode identify ne fonctionne qu'à partir du même domaine que votre centre d'aide ou d'un sous-domaine de niveau 1. Si votre centre d'aide est sur help.example.com, vous pouvez identifier à partir de app.example.com mais pas depuis autredomaine.com.

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

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

userId (string) : Identifiant unique dans votre système
email (string) : Email de l'utilisateur
name (string, optionnel) : Nom d'affichage
customAttributes (object, optionnel) : Métadonnées supplémentaires
exp (number, 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({
    userId: 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({
        'userId': 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

N'exposez jamais votre secret JWT dans le code côté client. Stockez-le uniquement dans des variables d'environnement côté serveur.

Appeler Identify depuis votre Frontend

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

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

fetch('/api/ferndesk-token')
  .then(r => r.text())
  .then(token => Ferndesk('identify', { token }))
  .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(token => window.Ferndesk('identify', { token }));
  }
}, [currentUser]);

Appelez identify après init mais avant d'ouvrir le widget. Pour vous déconnecter, réinitialisez sans appeler identify.

Vérifier le fonctionnement

Vérifiez ces indicateurs :

Console du navigateur : Aucune erreur. Les jetons invalides affichent Ferndesk: identify failed - invalid token
Formulaire de contact : L’email et le nom seront pré-remplis
Analytique : Les sessions utilisateur apparaissent dans votre tableau de bord

Erreurs courantes

identify requires a token

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

invalid token

La vérification de la signature a échoué. Vérifiez :

Le secret JWT correct
Le jeton n'a pas expiré
L'algorithme est HS256

must be called from same domain or 1-level subdomain

Incohérence 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 commettez jamais de secrets dans le contrôle de version

Cela vous a-t-il été utile ?