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.

Vous aurez besoin de votre secret JWT provenant de Centre d'aide > Personnaliser > Contrôle d'accès et du SDK Ferndesk installé.

Fonctionnement

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', { jwt })

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

La méthode identify fonctionne uniquement depuis le même domaine que votre centre d'aide ou un sous-domaine de niveau 1. Si votre centre d'aide est à l'adresse help.example.com, vous pouvez identifier depuis app.example.com mais pas otherdomain.com.

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

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

userId (chaîne) : identifiant unique dans votre système
email (chaîne) : 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({
    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(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]);

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

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

Échec de la vérification de la signature. Vérifiez :

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

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 l'expiration du 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 ?