Saltar al contenido principal

Magic link (Token de un solo uso)

Cloud availabilityOSS availability

Similar al código de un solo uso (OTP), un token de un solo uso es otro método de autenticación sin contraseña que puede utilizarse para verificar la identidad de un usuario. El token es válido por un período de tiempo limitado y está asociado con una dirección de correo electrónico del usuario final.

A veces, es posible que desees invitar a nuevos usuarios a tu aplicación / organización sin requerir que creen una cuenta primero. O puedes olvidar tu contraseña y querer iniciar sesión / restablecer tu contraseña verificando rápidamente tu identidad por correo electrónico. En tales casos, la aplicación puede enviar un "magic link" a tu correo electrónico. Y serás autenticado inmediatamente al hacer clic en el enlace.

Los desarrolladores de aplicaciones pueden usar el token de un solo uso para componer un magic link y enviarlo a la dirección de correo electrónico del usuario final.

Flujo de token de un solo uso​

Aquí tienes el diagrama de secuencia del flujo de autenticación usando el token de un solo uso:

Guía de implementación​

Logto ofrece un conjunto de Management API (Management APIs) y Experience API (Experience APIs) para facilitar la implementación de tu magic link.

Antes de comenzar, asegúrate de tener una instancia de Logto lista y haber establecido la conexión Máquina a máquina entre tu servidor de aplicaciones y el endpoint de Logto (requerido para las Management API). Aprende más sobre Logto Management API.

Paso 1: Solicita el token de un solo uso​

Utiliza Logto Management API para crear un token de un solo uso.

POST /api/one-time-tokens

Ejemplo de payload del cuerpo de la solicitud:

{
  "email": "[email protected]",
  // Opcional. Por defecto es 600 (10 minutos).
  "expiresIn": 3600,
  // Opcional. El usuario será aprovisionado a las organizaciones especificadas tras la verificación exitosa.
  "context": {
    "jitOrganizationIds": ["abcdefgh1234"]
  }
}

Después de obtener el token de un solo uso, puedes componer un magic link y enviarlo a la dirección de correo electrónico del usuario final. El magic link debe contener al menos el token y el correo electrónico del usuario como parámetros, y debe navegar a una página de destino en tu propia aplicación. Por ejemplo: https://yourapp.com/landing-page.

Aquí tienes un ejemplo simple de cómo podría verse el magic link:

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

Los nombres de los parámetros en el magic link pueden ser completamente personalizados. Puedes añadir información adicional al magic link según los requisitos de tu aplicación, así como codificar todos los parámetros de la URL.

Paso 3: Dispara el flujo de autenticación vía Logto SDK​

Después de que el usuario final haga clic en el magic link y navegue a tu aplicación, puedes extraer los parámetros token y email de la URL, y luego llamar a la función signIn() de Logto SDK para iniciar el flujo de autenticación.

TokenLandingPage.tsx
// Ejemplo en 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(() => {
    // Extrae el token y el email del magic link
    const oneTimeToken = searchParams.get('token');
    const email = searchParams.get('email');

    // Suponiendo que esta es tu URI de redirección de inicio de sesión
    const redirectUri = 'https://yourapp.com/callback';

    if (oneTimeToken && email) {
      signIn({
        redirectUri,
        clearTokens: false, // Opcional. Ver mensaje de advertencia abajo
        extraParams: {
          'one_time_token': oneTimeToken,
          'login_hint': email,
        },
      });
    }
  }, [searchParams, signIn]);

  return <>Por favor, espera...</>;
};
aviso:

Si un usuario ya ha iniciado sesión, llamar a la función signIn() del SDK limpiará automáticamente todos los tokens almacenados en caché (Token de ID, Token de acceso y Token de actualización) del almacenamiento del cliente, lo que termina perdiendo el estado de autenticación del usuario actual.

Por lo tanto, debes especificar un parámetro adicional de inicio de sesión clearTokens: false para evitar limpiar los tokens existentes. Si esto se especifica, también tendrás que limpiar manualmente los tokens en la página de callback de inicio de sesión.

Ignora esto si tus magic links no están diseñados para usuarios autenticados.

Paso 4: (Opcional) Limpia los tokens en caché en la página de callback de inicio de sesión​

Si especificas clearTokens: false en la función de inicio de sesión, necesitas limpiar manualmente los tokens en la página de callback de inicio de sesión.

Callback.tsx
// Ejemplo en React
import { useHandleSignInCallback, useLogto } from '@logto/react';
import { useEffect } from 'react';

const Callback = () => {
  const { clearAllTokens } = useLogto();

  useEffect(() => {
    void clearAllTokens();
  }, [clearAllTokens]);

  useHandleSignInCallback(() => {
    // Navega a tu página de inicio
  });

  return <>Por favor, espera...</>;
};

Preguntas frecuentes (FAQs)​

Sí, puedes usar el magic link para invitar nuevos usuarios a tu aplicación, así como a organizaciones. Si deseas invitar nuevos usuarios a tu organización, simplemente especifica los jitOrganizationIds en el cuerpo de la solicitud.

El usuario se unirá automáticamente a las organizaciones tras la verificación exitosa, y se asignarán los roles predeterminados de la organización. Consulta la sección "Just-in-time provisioning" en la página de detalles de tu organización y configura los roles predeterminados para tus organizaciones.

¿El token de un solo uso expira?​

Sí, el token de un solo uso expirará después del tiempo especificado en expiresIn (en segundos). El tiempo de expiración por defecto es de 10 minutos.

Sí, puedes seguir usando magic link para invitar usuarios incluso si desactivas el registro de usuarios en "Experiencia de inicio de sesión".

Existen varios escenarios posibles:

  1. El usuario ya ha iniciado sesión y luego hace clic en un magic link que está asociado con la cuenta de usuario actual. En este caso, Logto seguirá verificando el token de un solo uso y aprovisionará al usuario a las organizaciones especificadas si es necesario.
  2. El usuario ya ha iniciado sesión y luego hace clic en un magic link que está asociado con una cuenta diferente. En este caso, Logto le pedirá al usuario continuar como la nueva cuenta o regresar a la aplicación con la cuenta actual.
    1. Si el usuario elige continuar como la nueva cuenta, Logto cambiará a la nueva cuenta después de que la verificación del token sea exitosa.
    2. Si el usuario elige permanecer con la cuenta actual, Logto no verificará el token y regresará a la aplicación con la cuenta actual.
  3. Si tu prompt de inicio de sesión está configurado como "login" o contiene "login", Logto iniciará sesión automáticamente con la cuenta asociada al token de un solo uso sin solicitar el cambio.