Aller au contenu principal

Magic link (Jeton à usage unique)

Cloud availabilityOSS availability

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 vouloir inviter de nouveaux utilisateurs à votre application / organisation sans leur demander de créer un compte au préalable. Ou vous pouvez oublier votre mot de passe et vouloir vous connecter / réinitialiser votre mot de passe en vérifiant rapidement votre identité par e-mail. Dans de tels cas, l'application peut envoyer un "magic link" à votre adresse e-mail. Et vous serez authentifié immédiatement lorsque vous cliquerez sur le lien.

Les développeurs d'applications peuvent utiliser le jeton à usage unique pour composer un magic link et l'envoyer à l'adresse e-mail de l'utilisateur final.

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 Management API et Experience API pour faciliter la mise en œuvre de votre magic link.

Avant de commencer, assurez-vous d'avoir une instance Logto prête et d'avoir établi la connexion Machine à machine entre votre serveur d'application et l'endpoint 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 payload du corps de la requête :

{
  "email": "[email protected]",
  // 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"]
  }
}

Après avoir obtenu le jeton à usage unique, vous pouvez composer un magic link et l'envoyer à l'adresse e-mail de l'utilisateur final. Le magic link doit au moins contenir le jeton et l'e-mail de l'utilisateur comme paramètres, et doit rediriger 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 magic link :

https://yourapp.com/landing-page?token=YHwbXSXxQfL02IoxFqr1hGvkB13uTqcd&[email protected]
remarque:

Les noms des paramètres dans le magic link peuvent être entièrement personnalisés. Vous pouvez ajouter des informations supplémentaires au magic link selon les besoins de votre application, ainsi qu'encoder tous les paramètres de l'URL.

Étape 3 : Déclencher le flux d'authentification via Logto SDK​

Après que l'utilisateur final ait cliqué sur le magic link et soit arrivé sur votre application, vous pouvez extraire les paramètres token et email de l'URL, puis appeler la fonction signIn() du Logto SDK pour déclencher le flux d'authentification.

TokenLandingPage.tsx
// 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 magic link
    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...</>;
};
attention:

Si un utilisateur est déjà connecté, appeler la fonction signIn() du SDK effacera automatiquement tous les jetons mis en cache (jeton d’identifiant (ID token), jeton d’accès (access token) et jeton de rafraîchissement (refresh token)) 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 pour éviter d'effacer les jetons existants. Si cela est spécifié, vous devrez également effacer manuellement les jetons dans la page de callback de connexion.

Ignorez ceci si vos magic links 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 callback de connexion​

Si vous spécifiez clearTokens: false dans la fonction de connexion, vous devez effacer manuellement les jetons dans la page de callback de connexion.

Callback.tsx
// 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​

Oui, vous pouvez utiliser le magic link pour inviter de nouveaux utilisateurs à votre application, ainsi qu'à des organisations. Si vous souhaitez inviter de nouveaux utilisateurs à votre organisation, il suffit de spécifier 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 par défaut de l'organisation 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.

Le flux d'authentification par magic link 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.

Oui, vous pouvez toujours utiliser le magic link pour inviter des utilisateurs même si vous désactivez l'inscription des utilisateurs dans "Expérience de connexion".

Plusieurs scénarios sont possibles :

  1. L'utilisateur est déjà connecté, puis clique sur un magic link associé au compte utilisateur actuel. Dans ce cas, Logto vérifiera toujours le jeton à usage unique et provisionnera l'utilisateur dans les organisations spécifiées si nécessaire.
  2. L'utilisateur est déjà connecté, puis clique sur un magic link associé à un autre compte. Dans ce cas, Logto invitera l'utilisateur à continuer avec le nouveau compte ou à revenir à l'application avec le compte actuel.
    1. 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.
    2. 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.
  3. Si votre invite de connexion est définie sur "login" ou contient "login", Logto connectera automatiquement le compte associé au jeton à usage unique sans demander de changement.