Authentification JWT

Identifiez les utilisateurs dans votre widget d'aide sans exiger 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.

Fonctionnement

Flux en trois étapes :

1. Votre frontend détecte un utilisateur connecté

2. Votre backend génère un JWT signé avec les informations 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 à Centre d'aide > Contrôle d'accès.

2. Dans la section Identification de l'utilisateur, développez la ligne JWT identify.

3. Cliquez sur Générer le 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.

Si vous devez faire pivoter le secret, cliquez sur Régénérer. 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 affectés.

Connexion via le navigateur pour les clients MCP et IA

L'identification JWT fonctionne en arrière-plan dans votre produit. Les clients IA connectent les utilisateurs via un navigateur à la place.

Dans JWT identify sous Connexion via le navigateur (clients MCP et IA) :

1. Saisissez l'URL de votre page de connexion SSO. Ferndesk redirige les utilisateurs ici avec un paramètre return_to. Après la connexion, redirigez vers return_to avec un paramètre de requête jwt.

2. Activez éventuellement Autoriser la connexion par e-mail pour les clients IA afin que les utilisateurs existants puissent prouver qu'ils possèdent l'adresse e-mail lors de la connexion d'un client IA. Laissez cette option désactivée si les attributs utilisateur protègent du contenu sensible.

3. Cliquez sur Enregistrer les modifications.

Utilisez une URL valide commençant par http: ou https:. Les valeurs non valides affichent Saisissez une URL de page de connexion valide, y compris https://.

Connexe : Utiliser Ferndesk avec des outils d'IA · Permettre aux lecteurs d'utiliser votre centre d'aide dans des outils d'IA

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

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

Claims requis :

• sub (string, required): ID unique dans votre système qui identifie 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

Claims facultatifs :

• name (string, optional): Nom affiché

• customAttributes (object, optional): Attributs utilisateur supplémentaires. Vous pouvez également 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 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

La vérification de la signature ou la validation du claim a échoué. Vérifiez :

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

• Le jeton n'a pas expiré

• L'algorithme est HS256

• Les claims requis sont présents : sub, email, exp et iat

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

Cette erreur se produit lorsqu'un e-mail d'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 cette adresse 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 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

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