Authentification JWT

Identifiez les utilisateurs dans votre widget d’aide sans qu’ils aient besoin de se connecter séparément. Lorsque les utilisateurs sont connectés à votre application, vous pouvez transmettre leur identité à Ferndesk à l’aide d’un jeton JWT signé par votre backend.

Fonctionnement

Processus 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 depuis votre tableau de bord Ferndesk :

1. Accédez à Help Center > Access Control.

2. Dans la section User identification, développez la ligne JWT identify.

3. Cliquez sur Generate Secret.

La génération d’un secret active automatiquement l’authentification JWT pour votre centre d’aide. Le secret n’est affiché qu’une seule fois. 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 consulter ensuite.

Si vous devez faire tourner le secret, cliquez sur Regenerate. Cela remplace le secret existant et invalide tous les jetons signés avec l’ancien. Mettez à jour votre backend avec le nouveau secret avant que les utilisateurs ne soient impactés.

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

Créez un endpoint qui renvoie un jeton signé. Ferndesk n’exige pas les revendications iss (issuer) ni aud (audience).

Revendi­cations requises :

• sub (string, required): Identifiant unique dans votre système qui permet d’identifier cet utilisateur. Il s’agit de la clé d’identité principale.

• email (string, required): Adresse e-mail de l’utilisateur

• exp (number, required): Horodatage d’expiration du jeton

• iat (number, required): Horodatage d’émission du jeton

Revendi­cations facultatives :

• name (string, optional): Nom affiché

• customAttributes (object, optional): Attributs utilisateur supplémentaires. Vous pouvez aussi utiliser metadata; les deux clés sont acceptées.

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 now = Math.floor(Date.now() / 1000);
  const token = jwt.sign({
    sub: req.user.id,
    email: req.user.email,
    name: req.user.name,
    iat: now,
    exp: now + 3600, // 1 hour
    customAttributes: { plan: req.user.plan }
  }, 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

    now = int(time.time())
    token = jwt.encode({
        'sub': current_user.id,
        'email': current_user.email,
        'name': current_user.name,
        'iat': now,
        'exp': now + 3600,
        'customAttributes': {'plan': current_user.plan}
    }, 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 sont préremplis

• Analytics : 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

La vérification de la signature ou la validation des revendications a échoué. Vérifiez :

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

• Le jeton n’a pas expiré

• L’algorithme est HS256

• Les revendications requises sont présentes : sub, email, exp et iat

Le subject JWT ne correspond pas à l’utilisateur existant du centre d’aide

Cette erreur se produit lorsque l’e-mail d’un utilisateur existe déjà dans votre centre d’aide, mais avec un ID de subject différent. Cela signifie que quelqu’un s’est déjà connecté avec cet e-mail à l’aide d’un autre système d’identité ou d’une autre valeur sub.

Pour résoudre le 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

doit être appelé depuis le même domaine ou un sous-domaine de niveau 1

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 courante)

• 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

• Conservez des valeurs sub stables. Ferndesk conserve l’identité par subject.