Lien magique (Jeton à usage unique)
Similaire au mot de passe à usage unique (OTP), un jeton à usage unique est une autre méthode d’authentification sans mot de passe qui peut être utilisée pour vérifier l’identité d’un utilisateur. Le jeton est valable pour une période limitée et est associé à une adresse e-mail de l’utilisateur final.
Parfois, vous pouvez souhaiter inviter de nouveaux utilisateurs à votre application / organisation sans leur demander de créer un compte au préalable. Dans ce cas, l’application peut envoyer un "lien magique" à votre adresse e-mail. Vous serez alors authentifié immédiatement lorsque vous cliquerez sur le lien.
Les développeurs d’applications peuvent utiliser le jeton à usage unique pour composer un lien magique et l’envoyer à l’adresse e-mail de l’utilisateur final.
Cas d’utilisation
Logto prend en charge les scénarios suivants avec les liens magiques :
- Inscription sur invitation uniquement : Pour les outils internes ou les produits IA en phase de test, vous pouvez désactiver l’inscription publique et inviter des utilisateurs spécifiques via des liens magiques.
- Invitation de membres d’organisation : Pour les produits SaaS, utilisez des liens magiques pour inviter de nouveaux membres à rejoindre une organisation, simplifiant ainsi le processus d’intégration.
- Connexion / Inscription : Envoyez un lien magique pour une connexion ou une inscription sans mot de passe par e-mail.
- Réinitialisation du mot de passe : Envoyez un lien magique de réinitialisation du mot de passe depuis votre propre application afin que l’utilisateur puisse vérifier le jeton à usage unique et définir un nouveau mot de passe dans Logto.
Par exemple, lorsque vous avez désactivé l’inscription publique, vous pouvez envoyer un lien magique avec un jeton à usage unique (ex. https://yourapp.com/landing-page?token=YHwbXSXxQfL02IoxFqr1hGvkB13uTqcd&email=user@example.com) à l’e-mail de l’utilisateur pour l’inviter à finaliser la création de son compte. Vous pouvez personnaliser le modèle d’e-mail dans votre propre service d’envoi d’e-mails, comme ceci :
Actuellement non pris en charge :
- Utiliser le numéro de téléphone ou le nom d’utilisateur comme identifiant.
Flux du jeton à usage unique
Voici le diagramme de séquence du flux d’authentification utilisant un jeton à usage unique :
Guide de mise en œuvre
Logto propose un ensemble d’APIs de gestion (Management APIs) et d’APIs d’expérience (Experience APIs) pour faciliter la mise en œuvre de votre lien magique.
Avant de commencer, assurez-vous de disposer d’une instance Logto prête à l’emploi et d’avoir établi la connexion Machine à machine entre votre serveur d’application et le point de terminaison Logto (requis pour les Management APIs). En savoir plus sur Logto Management API.
Étape 1 : Demander un jeton à usage unique
Utilisez Logto Management API pour créer un jeton à usage unique.
POST /api/one-time-tokens
Exemple de charge utile de la requête :
{
"email": "user@example.com",
// Optionnel. Par défaut à 600 (10 min).
"expiresIn": 3600,
// Optionnel. L’utilisateur sera provisionné dans les organisations spécifiées après vérification réussie.
"context": {
"jitOrganizationIds": ["abcdefgh1234"]
}
}
Pour un lien magique de réinitialisation de mot de passe, restreignez le jeton au flux "mot de passe oublié" :
{
"email": "user@example.com",
"expiresIn": 3600,
"context": {
"interactionEvent": "ForgotPassword"
}
}
Étape 2 : Composer votre lien magique
Après avoir obtenu le jeton à usage unique, vous pouvez composer un lien magique et l’envoyer à l’adresse e-mail de l’utilisateur final.
Pour les liens magiques de connexion ou d’inscription, le lien doit au minimum contenir le jeton et l’e-mail de l’utilisateur en tant que paramètres.
Pour les liens magiques de réinitialisation de mot de passe, le paramètre e-mail est optionnel ; si vous l’omettez, Logto demandera à l’utilisateur de saisir son adresse e-mail avant de vérifier le jeton à usage unique.
Le lien magique doit diriger vers une page d’atterrissage dans votre propre application.
Ex. https://yourapp.com/landing-page.
Voici un exemple simple de ce à quoi peut ressembler le lien magique :
https://yourapp.com/landing-page?token=YHwbXSXxQfL02IoxFqr1hGvkB13uTqcd&email=user@example.com
Les noms des paramètres dans le lien magique sont entièrement personnalisables. Vous pouvez ajouter des informations supplémentaires au lien magique selon les besoins de votre application, ainsi qu’encoder tous les paramètres d’URL.
Étape 3 : Déclencher le flux d’authentification via Logto SDK
Connexion ou inscription
Après que l’utilisateur final a cliqué sur le lien magique et a été redirigé vers votre application, vous pouvez extraire les paramètres token et email de l’URL, puis appeler la fonction signIn() du SDK Logto pour déclencher le flux d’authentification.
// Exemple React
import { useLogto } from '@logto/react';
import { useEffect } from 'react';
import { useSearchParams } from 'react-router-dom';
const TokenLandingPage = () => {
const { signIn } = useLogto();
const [searchParams] = useSearchParams();
useEffect(() => {
// Extraire le jeton et l’e-mail du lien magique
const oneTimeToken = searchParams.get('token');
const email = searchParams.get('email');
// Supposons que ceci est votre URI de redirection de connexion
const redirectUri = 'https://yourapp.com/callback';
if (oneTimeToken && email) {
signIn({
redirectUri,
clearTokens: false, // Optionnel. Voir le message d’avertissement ci-dessous
extraParams: {
'one_time_token': oneTimeToken,
'login_hint': email,
},
});
}
}, [searchParams, signIn]);
return <>Veuillez patienter...</>;
};
Réinitialisation du mot de passe
Pour les liens magiques de réinitialisation de mot de passe, lancez une requête d’authentification avec first_screen défini sur reset_password.
Passez le jeton à usage unique via one_time_token.
Si vous avez déjà l’e-mail de l’utilisateur depuis votre page d’atterrissage, transmettez-le via login_hint ; sinon, omettez login_hint et Logto demandera à l’utilisateur de saisir son e-mail avant la vérification du jeton.
// Exemple React
import { useLogto } from '@logto/react';
import { useEffect } from 'react';
import { useSearchParams } from 'react-router-dom';
const ResetPasswordTokenLandingPage = () => {
const { signIn } = useLogto();
const [searchParams] = useSearchParams();
useEffect(() => {
const oneTimeToken = searchParams.get('token');
const email = searchParams.get('email');
if (oneTimeToken) {
signIn({
redirectUri: 'https://yourapp.com/callback',
extraParams: {
'one_time_token': oneTimeToken,
'first_screen': 'reset_password',
...(email && { 'login_hint': email }),
},
});
}
}, [searchParams, signIn]);
return <>Veuillez patienter...</>;
};
Si un utilisateur est déjà connecté, appeler la fonction signIn() du SDK effacera automatiquement tous les jetons mis en cache (jeton d’identifiant, jeton d’accès et jeton de rafraîchissement) du stockage client,
ce qui entraîne la perte du statut d’authentification de l’utilisateur actuel.
Par conséquent, vous devez spécifier un paramètre supplémentaire clearTokens: false lors de la connexion pour éviter d’effacer les jetons existants.
Si cela est spécifié, vous devrez également effacer manuellement les jetons dans la page de rappel de connexion.
Ignorez ceci si vos liens magiques ne sont pas conçus pour des utilisateurs déjà authentifiés.
Étape 4 : (Optionnel) Effacer les jetons mis en cache dans la page de rappel de connexion
Si vous spécifiez clearTokens: false dans la fonction de connexion, vous devez effacer manuellement les jetons dans la page de rappel de connexion.
// Exemple React
import { useHandleSignInCallback, useLogto } from '@logto/react';
import { useEffect } from 'react';
const Callback = () => {
const { clearAllTokens } = useLogto();
useEffect(() => {
void clearAllTokens();
}, [clearAllTokens]);
useHandleSignInCallback(() => {
// Naviguer vers votre page d’accueil
});
return <>Veuillez patienter...</>;
};
FAQ
Puis-je utiliser le lien magique pour inviter de nouveaux utilisateurs à mes organisations ?
Oui, vous pouvez utiliser le lien magique pour inviter de nouveaux utilisateurs à votre application, ainsi qu’à des organisations.
Si vous souhaitez inviter de nouveaux utilisateurs à votre organisation, indiquez simplement les jitOrganizationIds dans le corps de la requête.
L’utilisateur rejoindra automatiquement les organisations après vérification réussie, et les rôles d’organisation par défaut seront attribués. Consultez la section "Approvisionnement Just-in-Time" dans la page de détails de votre organisation et configurez les rôles par défaut pour vos organisations.
Puis-je attribuer des rôles spécifiques aux utilisateurs via le lien magique ?
Le flux d’authentification par lien magique ne prend pas en charge l’attribution de rôles aux utilisateurs. Mais vous pouvez toujours utiliser les Webhooks et la Management API pour mettre à jour les rôles de l’utilisateur après son inscription.
Le jeton à usage unique expire-t-il ?
Oui, le jeton à usage unique expirera après le temps expiresIn spécifié (en secondes). Le temps d’expiration par défaut est de 10 minutes.
Si je désactive l’inscription des utilisateurs dans "Inscription et connexion", puis-je toujours utiliser le lien magique pour inviter des utilisateurs ?
Oui, vous pouvez toujours utiliser le lien magique pour inviter des utilisateurs même si vous désactivez l’inscription des utilisateurs dans "Inscription et connexion".
Que se passe-t-il si un utilisateur est déjà connecté et clique ensuite sur un autre lien magique ?
Plusieurs scénarios sont possibles :
- L’utilisateur est déjà connecté, puis clique sur un lien magique associé au compte utilisateur actuel. Dans ce cas, Logto vérifiera quand même le jeton à usage unique et provisionnera l’utilisateur dans les organisations spécifiées si nécessaire.
- L’utilisateur est déjà connecté, puis clique sur un lien magique associé à un autre compte. Dans ce cas, Logto invitera l’utilisateur à continuer avec le nouveau compte ou à revenir à l’application avec le compte actuel.
- Si l’utilisateur choisit de continuer avec le nouveau compte, Logto basculera vers le nouveau compte après la vérification réussie du jeton.
- Si l’utilisateur choisit de rester sur le compte actuel, Logto ne vérifiera pas le jeton et retournera à l’application avec le compte actuel.
- Si votre invite de connexion est définie sur "login" ou contient "login", Logto connectera automatiquement le compte associé au jeton à usage unique sans inviter à changer de compte. Cela s’explique par le fait que l’invite "login" indique une intention explicite d’authentification, qui prévaut sur la session en cours.