Lorsqu'un utilisateur non connecté ouvre votre centre d'aide, Notiondesk le redirige vers une page de votre application, votre URL d'authentification unique (SSO). Cette page le connecte via Messenger ou par redirection depuis votre serveur, et il revient sur la page demandée, sans avoir à se reconnecter.
Avant de commencer
- Votre centre d'aide utilise le mode d'accès aux comptes invités .
- Vous disposez d'un secret d'application. Créez-en un dans Paramètres > Accès , dans la fiche Secret d'application . Il n'est affiché qu'une seule fois ; stockez-le donc sur votre serveur, par exemple dans
NOTIONDESK_APP_SECRET.
- Votre serveur peut signer un jeton utilisateur. Identifiez les utilisateurs connectés dans Notiondesk. Messenger explique le jeton. Dans Paramètres > Widget , la fiche « Synchroniser les informations utilisateur » fournit le code de signature pour Node.js, Python, PHP et Ruby, avec votre
site_uuidrenseigné. Stockez également cesite_uuidsur votre serveur, par exemple dansNOTIONDESK_SITE_UUID.
Étape 1 : Ajoutez votre URL SSO
- Accédez à Paramètres > Accès .
- Dans la section Contrôle d'accès , sélectionnez « Comptes invités » comme mode d'accès . Le paramètre est enregistré automatiquement.
- Dans l'URL SSO , entrez l'adresse de la page de votre application qui connecte les lecteurs, par exemple
https://app.example.com/help-sso.
- Cliquez sur Enregistrer les modifications .
L'URL SSO doit commencer par https://, utiliser un nom de domaine (et non localhost) et correspondre à une page de votre application, et non de votre centre d'aide. Si votre centre d'aide se trouve sur votre propre domaine, utilisez un autre hôte, ou le même hôte en dehors du chemin d'accès du centre d'aide : si votre centre d'aide est situé à l'adresse example.com/help, example.com/login convient.
Lorsque Notiondesk redirige un lecteur vers votre URL SSO, il conserve votre chaîne de requête et ajoute return_to, l'adresse complète de la page du centre d'aide demandée par le lecteur. Il ajoute également deux paramètres utilisés par Messenger. Laissez-les dans l'URL.
Étape 2 : Connectez les lecteurs à votre page SSO
Choisissez l'option qui convient à votre application. Les deux utilisent le même jeton utilisateur.
Option A : avec Messenger
Utilisez cette option si votre application exécute déjà Messenger. Sur votre page d'authentification unique (SSO), chargez Messenger avec un jeton d'utilisateur pour l'utilisateur connecté. Messenger connecte le lecteur à votre centre d'aide et le redirige vers la page demandée. Aucune autre action n'est requise.
Assurez-vous que votre page SSO :
- L'utilisateur est d'abord connecté à votre application. Un visiteur sans jeton d'utilisateur n'est pas connecté au centre d'aide.
- Charge le Messenger du centre d'aide d'où provient le lecteur, avec un jeton signé avec le secret d'application de ce centre d'aide.
- Le jeton est signé au chargement de la page et expire au maximum une heure après sa validation. Toute expiration ultérieure est refusée.
- S'ouvre comme une page normale, sans cadre, et ne définit pas l'option
apiUrldu Messenger.
- Conserve l'adresse complète utilisée lors de l'ouverture. Si votre formulaire de connexion redirige l'utilisateur vers un autre site ou onglet, ramenez-le à cette adresse initiale, avec tous ses paramètres, avant le chargement de Messenger.
La documentation du SDK Messenger aborde l'installation de React, Vue et des balises script dans sa section de connexion au centre d'aide .
Option B : avec une redirection depuis votre serveur
Utilisez cette option si votre application n'exécute pas Messenger, ou si vous préférez connecter les lecteurs sur votre serveur.
- Sur votre page SSO, lisez
return_todans l'adresse et conservez-la lors de votre connexion.
- Sur votre serveur, signez un jeton d'utilisateur pour l'utilisateur connecté avec votre secret d'application.
- Redirigez le navigateur vers
https://help.example.com/private/sso/jwt?jwt=TOKEN&return_to=RETURN_TO, en utilisant le domaine de votre centre d'assistance, le jeton etreturn_to, ces deux valeurs étant encodées en URL. Si votre centre d'assistance se trouve à l'adresseexample.com/help, l'adresse commence parhttps://example.com/help/private/sso/jwt.
Voici un exemple en Node.js avec Express. requireLogin correspond à votre propre vérification de connexion : elle redirige un utilisateur déconnecté vers votre page de connexion, puis vers cette adresse avec sa chaîne de requête.
Gardez ces règles à l'esprit :
const jwt = require('jsonwebtoken');
const HELP_CENTER_URL = 'https://help.example.com';
app.get('/help-sso', requireLogin, (req, res) => {
const now = Math.floor(Date.now() / 1000);
const token = jwt.sign(
{
type: 'site_contact_app',
iat: now,
exp: now + 300,
user_id: String(req.user.id),
site_uuid: process.env.NOTIONDESK_SITE_UUID,
email: req.user.email,
name: req.user.name,
},
process.env.NOTIONDESK_APP_SECRET,
{ algorithm: 'HS256' },
);
const target = new URL(`${HELP_CENTER_URL}/private/sso/jwt`);
target.searchParams.set('jwt', token);
if (req.query.return_to) {
target.searchParams.set('return_to', req.query.return_to);
}
res.redirect(target.toString());
});- Un nouveau jeton est généré pour chaque redirection. Un jeton permet d'authentifier un lecteur une seule fois.
- Définissez une courte durée de validité. Cinq minutes suffisent ; une durée supérieure à une heure est refusée. Assurez-vous que l’horloge de votre serveur est synchronisée : un décalage de 60 secondes maximum est toléré.
- Gardez le jeton inférieur à 8 Ko, donc gardez tout
custom_attributespetit.
- Transmettez
return_tosans modification. Sans cela, ou avec une adresse extérieure à votre centre d'aide, le lecteur arrive sur la page d'accueil du centre d'aide.
- Redirection depuis votre serveur. Ne jamais inclure ce lien dans un e-mail, car le jeton se trouve dans l'adresse.
Vous pouvez également rediriger les utilisateurs directement vers cette adresse depuis votre application sans URL SSO, par exemple depuis un lien « Aide » du menu. Attribuez la valeur return_to à la page du centre d'aide que vous souhaitez qu'ils ouvrent.
Étape 3 : Testez-le
- Ouvrez une fenêtre de navigation privée et accédez à une page de votre centre d'aide nécessitant une connexion.
- Vérifiez que vous accédez bien à votre URL SSO, que vous vous connectez à votre application et que vous revenez sur la même page du centre d'aide, une fois connecté.
Si cela ne fonctionne pas, vérifiez un jeton signé par votre application :
- Dans Paramètres > Accès , sous URL SSO , cliquez sur Vérifier un jeton de connexion . Cette option apparaît une fois l'URL SSO enregistrée.
- Collez le jeton, puis cliquez sur « Vérifier le jeton » . Vous verrez si votre centre d'aide l'accepte et pourquoi il est refusé. Le jeton est vérifié, mais n'est jamais enregistré.

Choisissez à quel moment les lecteurs accèdent à votre URL SSO
L'option « Connexion requise » , située au-dessus de l'URL SSO , est activée par défaut. Lorsqu'elle est activée, tout lecteur non connecté est redirigé vers votre URL SSO en ouvrant votre centre d'aide.
Si cette option est désactivée, n'importe qui peut consulter votre centre d'aide, et seuls ces lecteurs sont redirigés vers votre URL SSO :
- Lecteurs qui ouvrent un article nécessitant une connexion.
- Les lecteurs qui suivent un lien du centre d'aide se terminant par
nd_sign_in=1, tel quehttps://help.example.com/en/articles/billing?nd_sign_in=1, seront concernés. Ajoutez-le aux liens du centre d'aide dans votre application.
- Les lecteurs qui cliquent sur « Continuer avec votre compte » sur la page de connexion du centre d'aide.
Les invités que vous avez conviés peuvent toujours choisir « Utiliser l'adresse e-mail et le mot de passe » sur la page de connexion.
Partagez avec vos lecteurs les comptes invités que vous avez conviés.
Un jeton permet à un utilisateur que vous n'avez jamais invité de se connecter en tant que nouveau lecteur. Pour accorder à un utilisateur l'accès et le rôle d'un compte invité que vous avez créé par e-mail :
- Incluez l'identifiant
emailde l'utilisateur dans le jeton dès sa première identification. Un utilisateur initialement identifié sans cet identifiant dispose d'un lecteur distinct, sans accès au compte invité, même si vous ajoutez l'adresse e-mail ultérieurement.
- Si votre application n'a pas vérifié l'adresse e-mail d'un utilisateur, envoyez
email_verified: false. Cet utilisateur n'est pas associé au compte invité. Si vous omettez cette information, l'adresse e-mail sera considérée comme vérifiée. Envoyez-la sous la formetrueoufalse, et non en texte brut : une valeur comme"true"sera comptabilisée commefalse.
- Un compte invité est lié à un compte
user_id. Un deuxième utilisateur qui se connecte avec la même adresse e-mail dispose d'un lecteur séparé.
Si l'invitation de l'invité était encore en attente, elle est acceptée automatiquement.
Dépannage
| Problème | Cause | Réparer |
|---|---|---|
| Le lecteur arrive sur la page de connexion avec le message suivant : « Nous n’avons pas pu vous connecter automatiquement. Veuillez réessayer ou vous connecter ci-dessous. » | Le jeton a été refusé : il a expiré, a déjà été utilisé, expire dans plus d’une heure ou a été signé avec un autre secret d’application. | Exécutez la vérification du jeton de connexion et signez un nouveau jeton pour chaque redirection. |
| Le lecteur reste sur votre page SSO | Le Messenger n'a pas de jeton d'utilisateur ou celui-ci est invalide, l'adresse a perdu ses paramètres lors de votre connexion, la page est dans une frame ou apiUrl est défini. | Exécutez « Vérifier un jeton de connexion » et consultez la liste de l'option A. |
| Le lecteur est connecté mais arrive sur la page d'accueil | La page return_to est manquante ou ne figure pas dans votre centre d'aide. | Transmettez return_to sans modification |
| Les lecteurs ne sont jamais redirigés vers votre URL SSO. | Aucune URL SSO n'est enregistrée ou l'authentification requise est désactivée. | Enregistrez une URL SSO, puis ajoutez nd_sign_in=1 à vos liens du centre d'aide ou activez l'option « Connexion requise ». |
| « Saisissez une URL commençant par https:// » lors de l’enregistrement | L'URL SSO n'est pas une adresse https:// | Utilisez l'adresse https:// d'une page de votre application |
| « Saisissez une page de votre application, et non de votre centre d'aide. » lorsque vous enregistrez | L'URL SSO se trouve à l'adresse de votre centre d'aide. | Utilisez un autre hôte ou un chemin d'accès en dehors du centre d'aide. |
| La vérification du jeton de connexion indique « Ce jeton n'est pas encore valide. » | iat est exprimé en millisecondes, ou l'horloge de votre serveur est en avance. | Utilisez les secondes et synchronisez l'horloge de votre serveur. |
| Un lecteur n'a pas accès au compte invité que vous avez créé. | Le jeton ne comportait pas de email la première fois, ou bien email_verified n'existe pas. __PRÉSERVÉ_2__ | Voir « Associer les lecteurs aux comptes invités que vous avez conviés » ci-dessus |
Questions fréquentes
Les lecteurs doivent-ils se connecter deux fois ?
Non. Les lecteurs connectés à votre application passent par votre URL SSO et reviennent connectés, sans avoir besoin de se connecter via Notiondesk.
Quelle option dois-je choisir ?
Option A si votre application exécute déjà Messenger sur une page que vous contrôlez. Option B sinon, ou si votre connexion s'effectue sur votre serveur.
Les lecteurs peuvent-ils encore se connecter avec un e-mail et un mot de passe ?
Oui. Les invités que vous avez conviés peuvent choisir « Utiliser l'adresse e-mail et le mot de passe » sur la page de connexion du centre d'aide.
Combien de temps un lecteur reste-t-il connecté ?
Jusqu'à 12 heures. Se déconnecter de votre application ne les déconnecte pas du centre d'aide ; tenez-en compte sur les ordinateurs partagés.
Qui peut modifier l'URL SSO ?
Propriétaires d'espaces de travail, administrateurs et éditeurs.
Comment désactiver l'authentification unique (SSO) ?
Effacez le champ URL SSO et cliquez sur Enregistrer les modifications . Les lecteurs se connectent ensuite avec leur adresse e-mail et leur mot de passe.