Skip to Content

Magic Links (Email sin contraseña)

Los magic links ofrecen una experiencia de autenticación sin contraseña: el usuario introduce su dirección de correo electrónico, recibe un enlace de inicio de sesión y hace clic en él para autenticarse — sin necesidad de contraseña. Auris gestiona la generación del token, el envío del correo y la verificación.

Los magic links son adecuados como método de inicio de sesión independiente o como opción secundaria junto al correo y contraseña en la página de inicio de sesión alojada.


Cómo Funciona

El usuario envía su correo electrónico

Tu aplicación envía la dirección de correo del usuario al endpoint de magic link de Auris. Auris genera un token de un solo uso criptográficamente aleatorio, almacena un hash SHA-256 del mismo y compone el enlace de inicio de sesión.

Auris envía el correo

Auris entrega el correo con el magic link usando la configuración SMTP de tu tenant. El enlace apunta a la URL de redirección configurada en Consola → Autenticación → Sin contraseña, con el token añadido como parámetro de consulta.

El usuario hace clic en el enlace

El cliente de correo del usuario abre el enlace. La página en tu URL de redirección extrae el token de la URL y llama al endpoint de verificación de Auris.

Auris verifica el token

Auris valida el token: debe existir, no haber expirado y no haber sido utilizado anteriormente. Si todo es correcto, Auris emite un access token y un refresh token.

Registro automático para correos nuevos

Si allowSignup: true está configurado y el correo no existe en Auris, se crea automáticamente una nueva cuenta de usuario en el momento de la verificación. El usuario queda autenticado en la nueva cuenta de inmediato.


Configuración en la Consola

Antes de usar los magic links, configura la función en la Consola de Auris:

  1. Ve a Consola → Autenticación → Sin contraseña
  2. Activa Magic Links
  3. Establece la URL de redirección — la página de tu aplicación que recibirá el token y llamará al endpoint de verificación (ej. http://localhost:3000/auth/magic-link/verify)
  4. Configura la Expiración del token — el valor predeterminado es 15 minutos. Rango: 5–60 minutos
  5. Establece Permitir registro — cuando está activado, hacer clic en un magic link con un correo desconocido crea una nueva cuenta

La URL de redirección debe estar registrada en las URLs de callback permitidas de tu aplicación. Auris rechaza las redirecciones de magic link a URLs no registradas.


Implementación

import { useState } from 'react' import { useAuris } from '@auris/react' import { useSearchParams, useNavigate } from 'react-router-dom' // Formulario para enviar el magic link function FormularioMagicLink() { const { loginWithMagicLink } = useAuris() const [email, setEmail] = useState('') const [enviado, setEnviado] = useState(false) const [error, setError] = useState(null) async function handleSubmit(e) { e.preventDefault() const result = await loginWithMagicLink(email) if (result.success) { setEnviado(true) } else { setError(result.error) } } if (enviado) { return ( <div> <h2>Revisa tu correo</h2> <p>Hemos enviado un enlace de inicio de sesión a {email}. El enlace expira en 15 minutos.</p> </div> ) } return ( <form onSubmit={handleSubmit}> <label>Dirección de correo electrónico</label> <input type="email" value={email} onChange={(e) => setEmail(e.target.value)} required /> {error && <p className="error">{error}</p>} <button type="submit">Enviar enlace de acceso</button> </form> ) } // Página de verificación — recibe el token del enlace del correo function PaginaVerificacionMagicLink() { const { verifyMagicLink } = useAuris() const [searchParams] = useSearchParams() const navigate = useNavigate() useEffect(() => { const token = searchParams.get('token') if (!token) { navigate('/login?error=missing_token') return } verifyMagicLink(token).then((result) => { if (result.user) { navigate('/dashboard') } else { navigate('/login?error=invalid_token') } }) }, []) return <p>Verificando tu enlace de acceso...</p> }

Comportamiento del Registro Automático

Cuando allowSignup: true está configurado en la Consola, el flujo de magic link permite crear nuevas cuentas de usuario:

EscenarioComportamiento
Correo conocido, allowSignup: trueEnvía magic link, autentica al usuario existente
Correo desconocido, allowSignup: trueEnvía magic link, crea nueva cuenta al verificar
Correo desconocido, allowSignup: falseDevuelve error user_not_found, no se envía correo
Correo conocido, allowSignup: falseEnvía magic link, autentica al usuario existente

Cuando se crea una nueva cuenta mediante registro automático, no tiene contraseña establecida. El usuario puede añadir una contraseña posteriormente desde la configuración de la cuenta, o continuar usando magic links indefinidamente.


Personalización de la Plantilla de Correo

El correo del magic link utiliza la plantilla Inicio de sesión sin contraseña en Consola → Autenticación → Plantillas de correo. La plantilla admite las siguientes variables:

VariableDescripción
{{magic_link}}La URL completa de inicio de sesión incluyendo el token
{{user_email}}La dirección de correo del destinatario
{{expires_in}}Duración de expiración legible (ej., “15 minutos”)
{{tenant_name}}El nombre visible de tu tenant
{{app_name}}El nombre de la aplicación que solicita el inicio de sesión

Consideraciones de Seguridad

Tokens de un solo uso — Cada token de magic link solo puede usarse una vez. Hacer clic en un enlace ya utilizado devuelve un error token_already_used.

Expiración del token — Los tokens expiran tras la duración configurada (predeterminado: 15 minutos). Los tokens expirados devuelven un error token_expired con un mensaje para solicitar un nuevo enlace.

Hash del token — Auris almacena únicamente el hash SHA-256 del token. El token en bruto solo está presente en el correo y en la URL — nunca se guarda en texto plano en la base de datos.

Limitación de velocidad — Auris aplica límites de velocidad al endpoint de envío de magic links: un máximo de 5 solicitudes de enlace por dirección de correo por hora. Esto previene el abuso por inundación de correos.

Sin contraseña requerida — Los magic links son adecuados para usuarios donde las contraseñas suponen una fricción. No son más débiles que las contraseñas cuando se aplican las restricciones de expiración y uso único.


Endpoints de la API

POST/api/auth/magic-link

Envía un correo con un magic link a la dirección de correo proporcionada. Cuerpo: { email: string }. Respeta la configuración allowSignup del tenant. Con límite de velocidad: 5 solicitudes por correo por hora.

POST/api/auth/magic-link/verify

Verifica un token de magic link y emite access/refresh tokens. Cuerpo: { token: string }. El token no debe estar expirado ni haber sido utilizado anteriormente.


Guías Relacionadas