Le jeton de redirection a été envoyé deux fois, souvent par une page qui se recharge. Signez un nouveau jeton pour chaque redirection.
Connecter les lecteurs avec JWT ou OIDC
Les lecteurs peuvent se connecter à votre centre d’aide avec un compte qu’ils possèdent déjà. Un centre d’aide privé leur permet ensuite d’y accéder, et les règles de groupe déterminent ce qu’ils peuvent consulter. Deux méthodes sont possibles : un JWT provenant de votre propre application ou OIDC via un fournisseur d’identité tel qu’Okta, Auth0 ou Azure AD. Pour savoir ce que cela peut apporter à votre équipe, consultez Rendre votre centre d’aide privé.
Les propriétaires et les administrateurs configurent les deux méthodes dans Centre d’aide > Contrôle d’accès. La connexion par JWT est disponible avec tous les forfaits. OIDC, les centres d’aide privés et les règles de groupe dépendent de votre forfait ; consultez Tarifs et forfaits.
JWT : se connecter avec votre produit
Le lecteur choisit Continuer avec votre produit sur la page de connexion du centre d’aide. Si JWT est la seule méthode de connexion, le centre d’aide ignore cette page et passe directement à l’étape suivante.
Le centre d’aide redirige le lecteur vers votre URL de connexion avec un paramètre
return_to. Toute chaîne de requête déjà présente dans votre URL de connexion est conservée.Votre application connecte le lecteur si nécessaire, signe un JWT avec le secret de signature du centre d’aide, puis le redirige vers
return_toavec le jeton dans le fragment :#jwt=TOKEN.Le centre d’aide vérifie le jeton, démarre une session de 180 jours et renvoie le lecteur vers la page souhaitée.
import { SignJWT } from 'jose';
const secret = new TextEncoder().encode(process.env.FERNDESK_SIGNING_SECRET);
// Your login URL: the reader is signed in to your app here
app.get('/help-center/sso', requireLogin, async (req, res) => {
const now = Math.floor(Date.now() / 1000);
const token = await new SignJWT({
email: req.user.email,
name: req.user.name,
metadata: { plan: req.user.plan, roles: req.user.roles }
})
.setProtectedHeader({ alg: 'HS256' })
.setSubject(String(req.user.id))
.setIssuedAt(now)
.setExpirationTime(now + 300)
.sign(secret);
res.redirect(req.query.return_to + '#jwt=' + token);
});Le rappel accepte également le jeton dans un champ de formulaire POST ou dans un paramètre de requête ?jwt=, et token peut être utilisé comme nom de champ. Le fragment évite que le jeton apparaisse dans les journaux du serveur ; privilégiez donc cette méthode.
Revendications
Revendication | Obligatoire | Description |
|---|---|---|
| Oui | L’identifiant stable de l’utilisateur. Il permet d’identifier le lecteur à chaque connexion. |
| Oui | L’adresse e-mail du lecteur. |
| Oui | La date à laquelle vous avez signé le jeton. |
| Oui | La date d’expiration. |
| Non | Le nom affiché du lecteur. |
| Non | Une URL d’image HTTPS utilisée comme avatar du lecteur. |
| Non | Attributs utilisés pour les règles de groupe, voir ci-dessous. |
Règles relatives aux jetons
Signez avec HS256. HS384 et HS512 sont également acceptés.
Un jeton est accepté pendant un maximum de 15 minutes après son
iat, quelle que soit la valeur deexp, sans tolérance pour le décalage de l’horloge.Un jeton renvoyé par la redirection ne peut être utilisé qu’une seule fois.
issetaudne sont pas vérifiés.Si un nouveau
subest envoyé avec une adresse e-mail déjà associée à un autre lecteur, la connexion échoue. Si unsubconnu est envoyé avec une nouvelle adresse e-mail, l’adresse du lecteur est mise à jour, sauf si elle est déjà associée à un autre lecteur.
Le secret de signature
Ferndesk génère le secret : choisissez Générer un secret sous Authentification unique. Les propriétaires et les administrateurs peuvent le révéler et le régénérer à cet endroit ou dans Paramètres > Espace de travail > Développeurs, sous Connexion des clients ; il s’agit du même secret. Sa régénération interrompt les connexions jusqu’à ce que votre application utilise le nouveau secret. Tester la connexion exécute le processus complet une fois le secret et l’URL de connexion définis.
Se connecter sans redirection
Pour connecter un lecteur depuis votre produit, envoyez POST /api/auth/identify sur le domaine de votre centre d’aide avec le corps JSON {"jwt": "TOKEN"}. Le SDK du widget le fait pour le widget. Sous Plus d’options, une URL de déconnexion permet de rediriger vers cette URL les lecteurs qui se sont connectés via votre application lorsqu’ils se déconnectent, avec l’ajout de return_to.
Attributs et règles de groupe
Les attributs de metadata sont enregistrés sur le lecteur et remplacés à chaque connexion. Les règles de groupe utilisent ces attributs pour leurs correspondances, et toutes les conditions d’une règle doivent être satisfaites.
Les valeurs peuvent être des chaînes (jusqu’à 256 caractères), des nombres, des booléens ou des listes contenant un seul de ces types de valeurs (jusqu’à 64 éléments).
Les objets imbriqués sont convertis en chemins séparés par des points, sur un maximum de 4 niveaux :
{"features": {"sso": true}}devientfeatures.sso.Jusqu’à 32 attributs après aplatissement. Un JWT contenant un attribut non valide est refusé.
Opérateur | Correspondance lorsque |
|---|---|
est, est l’un de | L’attribut est égal à la valeur ou à l’une des valeurs. Pour une liste, n’importe quel élément peut correspondre. |
contient | Une liste contient la valeur parmi ses éléments, ou une chaîne de caractères la contient. |
n’est pas, n’est aucun de, exclut | L’inverse de l’opérateur de correspondance, lorsque l’attribut est défini. |
est défini, n’est pas défini | L’attribut est présent ou absent. |
Un attribut manquant correspond uniquement à n’est pas défini. Les valeurs des règles sont saisies sous forme de texte : true et false correspondent aux booléens, et un nombre correspond à un attribut numérique.
OIDC
Sous Connexion des visiteurs, ouvrez Authentification unique (OIDC) et saisissez l’URL de découverte, l’ID client et le secret client de votre fournisseur. Dans les paramètres de votre fournisseur, autorisez cet URI de redirection :
https://<your help center domain><base path>/api/auth/oidc/callbackFerndesk utilise le flux de code d’autorisation avec PKCE, demande
openid,profileetemail, et envoie le secret client dans le corps de la requête de jeton.L’URL de découverte doit être publique et répertorier
issuer,authorization_endpoint,token_endpointetjwks_uri. L’émetteur du jeton d’identification doit lui correspondre, et son audience doit être l’ID client.Le jeton d’identification doit contenir
subetemail. Le nom est récupéré depuisname, puis depuispreferred_username.Un lecteur existant est identifié par son adresse e-mail uniquement si le fournisseur définit
email_verified.Toute autre revendication, comme
groups, devient un attribut du lecteur utilisé pour les règles de groupe. Les revendications liées à la connexion, telles queauth_time,jtietemail_verified, ne sont pas enregistrées.Un lecteur peut avoir jusqu’à 32 attributs. Vos propres revendications sont prises en compte en premier, puis les revendications de profil standard, comme
given_nameetlocale, utilisent les places restantes. Les revendications non valides sont ignorées.La déconnexion met uniquement fin à la session du centre d’aide, pas à celle du fournisseur.
Dépannage
Lorsqu’une connexion par redirection échoue, les lecteurs voient le message La connexion a échoué, quelle qu’en soit la cause. Pour connaître la raison, envoyez le même jeton à POST /api/auth/identify : son champ error contient l’un des messages ci-dessous.
« Ce lien de connexion a déjà été utilisé »
« Jeton non valide ou expiré »
La signature ne correspond pas au secret de signature, le jeton a expiré ou il a été signé il y a plus de 15 minutes. Signez-le avec le secret actuel juste avant la redirection et veillez à synchroniser l’horloge de votre serveur.
« JWT expiré ou revendication exp manquante »
Le jeton ne contient pas la revendication exp. Ajoutez-la.
« Le sujet du JWT ne correspond pas à l’utilisateur existant du centre d’aide »
Un autre lecteur avec un sub différent possède déjà cette adresse e-mail. Veillez à ce que sub reste stable pour chaque personne.
« Les métadonnées du JWT sont trop volumineuses ou non valides »
Un attribut dépasse les limites indiquées ci-dessus, par exemple une valeur nulle ou une liste contenant des types différents.
OIDC indique « La connexion unique n’a pas abouti »
Vérifiez l’ID client et le secret, assurez-vous que le fournisseur autorise l’URI de redirection et la méthode client_secret_post, et que le jeton d’identification contient sub et email.