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

Processus 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 l'analyse.

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. Ouvrez l'onglet Accès.

3. Dans la section Se connecter avec votre produit, sous Authentification unique, recherchez la zone Secret de signature.

4. Cliquez sur Générer un secret.

La section affiche un statut : Non configuré signifie qu'aucun secret n'existe encore. Identification uniquement signifie que le secret fonctionne pour une identification silencieuse, mais que les lecteurs ne peuvent pas encore se connecter via votre produit, car aucune URL de connexion valide n'est configurée. Activé signifie que le secret et une URL de connexion valide sont tous deux configurés.

Le secret est masqué après sa génération. Copiez-le immédiatement et stockez-le en toute sécurité dans les variables d'environnement de votre backend. Vous pourrez l'afficher à nouveau ultérieurement depuis le tableau de bord.

L'identification silencieuse peut également être effectuée en envoyant au endpoint d'identification /api/auth/identify un JWT signé avec le même secret.

Seuls les propriétaires et administrateurs actifs de l'espace de travail peuvent générer, afficher, renouveler ou supprimer le secret. Les autres membres de l'espace de travail voient des instructions leur demandant de s'adresser à un propriétaire ou à un administrateur, au lieu des commandes de gestion du secret.

Si vous devez renouveler le secret, cliquez sur Régénérer et confirmez le renouvellement dans la boîte de dialogue Régénérer le secret de signature JWT ?. Le secret existant est remplacé et tous les jetons signés avec l'ancien cessent immédiatement de fonctionner. Déployez le nouveau secret sur votre backend avant que la connexion au centre d'aide puisse reprendre.

Se connecter avec votre produit

Les lecteurs se connectent via la propre page de connexion du centre d'aide, en utilisant les méthodes activées par celui-ci. L'une de ces méthodes consiste à se connecter via votre produit : le centre d'aide redirige le lecteur vers votre produit, votre backend signe un JWT de courte durée, puis le lecteur revient au centre d'aide avec sa session ouverte. Le même secret de signature permet également l'identification silencieuse depuis votre application.

Les clients IA qui consultent votre centre d'aide via MCP se connectent dans le navigateur en utilisant les propres méthodes de connexion du centre d'aide.

Les étapes de configuration sont disponibles dans Se connecter avec votre produit.

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

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

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

Revendications obligatoires :

• sub (chaîne, obligatoire) : ID unique dans votre système qui identifie cet utilisateur. Il s'agit de la clé d'identité principale.

• email (chaîne, obligatoire) : Adresse e-mail de l'utilisateur

• exp (nombre, obligatoire) : Horodatage d'expiration du jeton

• iat (nombre, obligatoire) : Horodatage d'émission du jeton

Revendications facultatives :

• name (chaîne, facultatif) : Nom affiché

• customAttributes (objet, facultatif) : Attributs supplémentaires de l'utilisateur. 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 + 900, // 15 minutes (maximum token age)
    customAttributes: { plan: req.user.plan }
  }, process.env.FERNDESK_JWT_SECRET, { algorithm: 'HS256' });

  res.send(token);
});

Exemple Python :

import jwt
import os\nimport 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 + 900,  # 15 minutes (maximum token age)
        '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 tout fonctionne

Vérifiez les indicateurs suivants :

• Console du navigateur : aucune erreur. Les JWT non valides affichent Ferndesk: identify failed (Invalid or expired token).

• Formulaire de contact : l'adresse e-mail et le nom sont 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

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

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

• Le jeton n'a pas expiré

• L'algorithme est HS256, HS384 ou HS512 (les exemples ci-dessus utilisent HS256)

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

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

Cette erreur se produit lorsque l'adresse e-mail d'un utilisateur existe déjà dans votre centre d'aide, mais avec un ID de sujet différent. Cela signifie qu'une personne s'est précédemment connectée avec cette adresse e-mail en utilisant un autre système d'identité ou 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 modifié les systèmes 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

Origine différente. Les requêtes ultérieures de session du widget doivent provenir de l'origine exacte ayant effectué l'identification, notamment avec le même schéma, hôte et port.

Notes de sécurité

• Définissez l'expiration du jeton à 15 minutes ou moins

• Générez uniquement des jetons pour les utilisateurs authentifiés

• Utilisez HTTPS partout

• N'enregistrez jamais de secrets dans le contrôle de version

• Conservez des valeurs sub stables. Ferndesk conserve l'identité en fonction du sujet.