Se connecter avec votre produit

Se connecter avec votre produit est une authentification unique basée sur une redirection : les lecteurs cliquent sur un bouton de la page de connexion de votre centre d’aide, se connectent sur la propre page de connexion de votre produit, puis reviennent avec un JWT à courte durée de validité qui établit leur session dans le centre d’aide. Cette fonctionnalité est disponible avec tous les forfaits et fonctionne avec les centres d’aide publics comme privés.

Ce dont vous avez besoin

• Une page de connexion sur votre produit. Vous saisissez son URL dans Ferndesk, qui doit être une URL complète commençant par http:// ou https://.

• Signature JWT côté serveur avec HS256. Votre backend signe le jeton une fois que les lecteurs se sont connectés de votre côté.

• Un rôle de propriétaire ou d’administrateur dans votre espace de travail Ferndesk. Seuls les propriétaires et administrateurs actifs de l’espace de travail peuvent générer, afficher et renouveler le secret de signature.

Configurer la connexion avec votre produit

Tout se configure au même endroit : dans le tableau de bord, sous Centre d’aide, puis Contrôle d’accès, dans l’onglet Accès.

1

Ouvrir les paramètres de l’authentification unique

Dans le tableau de bord, accédez à Centre d’aide, puis à Contrôle d’accès, et ouvrez l’onglet Accès. Développez Se connecter avec votre produit, puis Authentification unique.

2

Saisir votre URL de connexion

L’URL de connexion est la page de connexion de votre produit vers laquelle les lecteurs sont redirigés. Elle doit commencer par http:// ou https://.

3

Nommer le bouton de connexion

Le Nom du bouton est affiché aux lecteurs sous la forme Continue with <product name>. Par défaut, il correspond au nom de votre centre d’aide.

4

Copier l’URL de rappel

Une URL de rappel en lecture seule est affichée dans cette section. Copiez-la : votre produit redirige les lecteurs vers cette URL après leur connexion.

5

Générer le secret de signature

Dans la section Secret de signature, générez le secret que votre backend utilise pour signer les JWT.

6

Définir les options facultatives

Sous Plus d’options, vous pouvez ajouter une URL du logo du bouton et une URL de déconnexion. L’URL de déconnexion est l’adresse vers laquelle les lecteurs sont redirigés lorsqu’ils se déconnectent du centre d’aide via l’authentification unique de votre produit.

Ouvrez le Guide de configuration dans cette section pour consulter des exemples de code Node.js et Python prêts à l’emploi.

L’état de la méthode reflète sa configuration : Non configurée tant qu’aucun secret de signature n’existe, Identification uniquement lorsqu’un secret existe mais qu’aucune URL de connexion valide n’est configurée, et Activée dès que le secret et une URL de connexion valide sont configurés.

Fonctionnement du processus de connexion

La redirection passe par votre produit, et le jeton signé revient à Ferndesk dans le fragment de l’URL.

1. Un lecteur clique sur le bouton de connexion de votre centre d’aide. Ferndesk l’envoie vers votre URL de connexion avec un paramètre de requête return_to.

2. Votre produit connecte le lecteur, signe un JWT, puis redirige le navigateur vers la valeur de return_to, avec le jeton ajouté sous la forme #jwt=<token>.

3. Ferndesk valide le jeton et crée la session du lecteur dans le centre d’aide.

Envoyez le jeton dans le fragment de l’URL. Les fragments ne sont pas transmis aux journaux du serveur ni à l’en-tête Referer, ce qui empêche le jeton d’y apparaître. Le rappel accepte également le jeton via une requête POST de formulaire ou comme paramètre de requête ?jwt=.

Signer le JWT

Signez avec HS256. Revendications obligatoires :

Revendications facultatives :

• name : nom affiché du lecteur

• customAttributes ou metadata : attributs du groupe d’utilisateurs

Exemple Node.js :

const jwt = require('jsonwebtoken');

app.get('/sso/ferndesk', (req, res) => {
  if (!req.user) return res.redirect('/login');

  const returnTo = req.query.return_to;
  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)
  }, process.env.FERNDESK_JWT_SECRET, { algorithm: 'HS256' });

  res.redirect(returnTo + '#jwt=' + token);
});

Tester la connexion

Une fois que votre page de connexion a signé et redirigé le jeton, cliquez sur Tester la connexion dans la section Authentification unique pour exécuter le processus avant que les lecteurs ne l’utilisent.

Connecter les lecteurs silencieusement (facultatif)

Vous pouvez entièrement ignorer la redirection pour les lecteurs qui sont déjà connectés à votre produit. Envoyez un JWT signé avec le même secret de signature au point de terminaison d’identification, /api/auth/identify, ou utilisez le processus d’identification du widget. Consultez Authentification JWT pour en savoir plus sur l’identification silencieuse.

Renouveler le secret de signature

Le renouvellement est limité aux propriétaires et administrateurs actifs de l’espace de travail, les mêmes rôles que ceux qui peuvent générer et afficher le secret. Le renouvellement remplace immédiatement le secret, et les jetons signés avec l’ancien secret cessent de fonctionner. Remplacez l’ancien secret par le nouveau dans les variables d’environnement de votre backend.

Autres façons pour les lecteurs de se connecter

• Se connecter avec des liens magiques : liens de connexion par e-mail à usage unique

• Se connecter avec l’authentification unique OIDC : connexion via un fournisseur d’identité externe

• Mot de passe partagé : un mot de passe unique pour l’ensemble du centre d’aide