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 qu'un utilisateur est connecté

2. Votre backend génère un JWT signé contenant les informations de l'utilisateur

3. Votre frontend appelle Ferndesk('identify', { jwt })

Le centre d'aide et le widget connaissent désormais l'identité de l'utilisateur à des fins d'authentification, de personnalisation et d'analyse.

Secret JWT

Avant de pouvoir signer des JWT, vous devez obtenir 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 est masqué après sa génération. Copiez-le immédiatement et stockez-le de manière sécurisée dans les variables d'environnement de votre backend. Vous pourrez l'afficher à nouveau ultérieurement depuis le tableau de bord.

Si vous devez renouveler le secret, cliquez sur Regenerate. Le secret existant sera remplacé et tous les jetons signés avec l'ancien seront invalidés. Mettez votre backend à jour avec le nouveau secret avant que les utilisateurs ne soient affectés.

Connexion au navigateur pour MCP et les clients IA

L'identification JWT fonctionne silencieusement dans votre produit. Les clients IA connectent les utilisateurs via un navigateur à la place.

Dans JWT identify, sous Browser sign-in (MCP and AI clients) :

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

2. Activez éventuellement Allow email sign-in for AI clients afin que les utilisateurs existants puissent prouver qu'ils possèdent leur adresse e-mail lorsqu'ils connectent un client IA. Laissez cette option désactivée si les attributs utilisateur contrôlent l'accès à du contenu sensible.

3. Cliquez sur Save changes.

Utilisez une URL http: ou https: valide. Les valeurs incorrectes affichent Enter a valid login page URL, including https://.

Articles associés : Utiliser Ferndesk avec des outils IA · Permettre aux lecteurs d'utiliser votre centre d'aide dans des outils IA

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

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

Claims obligatoires :

• sub (string, obligatoire) : identifiant unique dans votre système permettant d'identifier cet utilisateur. Il s'agit de la clé d'identité principale.

• email (string, obligatoire) : adresse e-mail de l'utilisateur

• exp (number, obligatoire) : horodatage d'expiration du jeton

• iat (number, obligatoire) : horodatage d'émission du jeton

Claims facultatifs :

• name (string, facultatif) : nom d'affichage

• customAttributes (object, facultatif) : 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 + 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 le fonctionnement

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 seront 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 claims a échoué. Vérifiez les éléments suivants :

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

• Le jeton n'a pas expiré

• L'algorithme est HS256

• Les claims obligatoires sont présents : 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 autre identifiant de sujet. 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 ce problème :

• Vérifiez que votre backend envoie toujours le même sub pour chaque utilisateur

• Si vous avez modifié vos systèmes d'identifiants utilisateur, l'utilisateur concerné devra être reprovisionné dans Ferndesk

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

Les origines ne correspondent pas. Les requêtes ultérieures de session du widget doivent provenir exactement de l'origine ayant effectué l'identification, avec le même schéma, le même hôte et le même port.

Notes de sécurité

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

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

• Utilisez HTTPS partout

• N'intégrez jamais de secrets dans le contrôle de version

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