Ferndesk
Authentification

Authentification JWT

Identifiez les utilisateurs dans votre widget d'aide sans nécessiter une 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.

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

Comment ça marche

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', { 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 d'identification ne fonctionne qu'à partir du même domaine que votre centre d'aide ou un sous-domaine de niveau 1. Si votre centre d'aide est sur help.example.com, vous pouvez identifier l'utilisateur depuis 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 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 l'identification 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 l'initialisation 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 non valides affichent Ferndesk: identify failed - invalid token

  • Formulaire de contact : l'e-mail 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

Échec de la vérification de la signature. 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

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

Cela vous a-t-il ete utile ?