Arreglar problemas en el flujo de restablecimiento de contraseña: entrega, expiración, tokens

Cómo suele verse un “restablecimiento de contraseña roto"

La gente rara vez informa bugs de restablecimiento con detalle técnico. Describen síntomas: “no recibí el correo”, “el enlace dice que es inválido” o “funcionó ayer y hoy no”. Esos síntomas normalmente apuntan a un pequeño conjunto de causas raíz.

Los fallos más comunes visibles para el usuario son:

• No llega el email (o llega mucho más tarde).
• El enlace abre, pero muestra “token inválido” o un error genérico.
• El enlace funciona una vez y luego funciona para siempre (sin expiración).
• El enlace dice “expirado” inmediatamente.
• El enlace funciona en móvil pero falla en escritorio (o a la inversa) por codificación de URL o ruteo.

Esta es un área de alto riesgo. Si los enlaces de restablecimiento son fáciles de abusar (tokens que no expiran, tokens reutilizables, cuentas que se pueden adivinar), aumentas el riesgo de toma de cuentas. Si son difíciles de usar (emails que no llegan, enlaces rotos), aumentas la carga de soporte y la rotación.

La mayoría de los fallos caen en dos categorías:

1) Problemas de entrega

El token puede estar bien, pero el email nunca llega o llega demasiado tarde. Causas comunes: filtrado de spam, configuración de dominio o DNS incorrecta, límites del proveedor, listas de supresión o que la app no envíe en absoluto.

2) Problemas de validación del token

El email llega, pero el token no se puede usar. Causas comunes: almacenar tokens incorrectamente, errores con hashing, cheques de TTL inconsistentes, desviación de reloj, usar el registro de usuario equivocado o marcar tokens como “usados” demasiado pronto.

Un ejemplo rápido: un fundador prueba en local y todo funciona. En producción el email llega pero el enlace falla. Luego descubre que los tokens se guardaban en una caché en memoria que se borra al desplegar, así que la validación falla tras el siguiente reinicio.

Deberías poder responder a estas preguntas desde los logs en cinco minutos:

• ¿Intentamos enviar el email de restablecimiento para esa dirección (y el proveedor lo aceptó)?
• ¿Para qué ID de usuario se creó el token y cuándo?
• ¿Dónde está almacenado el token (BD, caché, proveedor de auth) y podemos encontrar el registro coincidente?
• ¿Por qué falló la validación (no encontrado, expirado, ya usado, usuario equivocado)?
• ¿Cuántas solicitudes de restablecimiento hubo recientemente para esta cuenta o IP (abuso o rate limiting)?

Si tu app fue generada por herramientas como Bolt, v0, Cursor o Replit, es común ver logs faltantes, tokens almacenados en el lugar equivocado o cheques de expiración que en realidad nunca se ejecutan en el servidor.

Cómo funciona bien un flujo de restablecimiento (en palabras llanas)

Un buen restablecimiento debe sentirse aburrido. El usuario pide un restablecimiento, recibe un email rápido, hace clic en un enlace, pone una nueva contraseña y el enlace no puede reutilizarse.

1) La petición no debe filtrar si existe el email

Cuando alguien escribe un email y pulsa “Enviar enlace de restablecimiento”, tu app debe responder igual tanto si el email está en tu sistema como si no. Eso evita descubrimiento de cuentas y casos de soporte confusos.

Detrás, si el email coincide con un usuario, creas un token de un solo uso y guardas un registro del lado servidor. Si no coincide, no haces nada más, pero muestras el mismo mensaje de éxito.

2) El email es solo el vehículo de entrega de un token de corta duración

El flujo habitual es:

• El usuario solicita un restablecimiento.
• El servidor crea un token aleatorio, lo almacena con una fecha de expiración y lo marca como no usado.
• El servidor envía por email un enlace de restablecimiento que contiene el token.
• El usuario establece una nueva contraseña; el servidor verifica el token y lo invalida.
• Opcionalmente, el servidor termina otras sesiones y notifica al usuario.

El detalle importante: el token debe ser aleatorio (no predecible), con límite temporal y de un solo uso. El registro en la base de datos es la fuente de la verdad, no lo que diga el navegador.

3) Confirmar el restablecimiento debe ser estricto y final

Cuando el usuario abre el enlace y envía una nueva contraseña, tu servidor debe comprobar que el token existe, coincide con lo guardado, no ha expirado y no ha sido usado. Solo entonces actualizas la contraseña.

Invalida el token inmediatamente tras el éxito para que no pueda reutilizarse. Muchas apps también terminan otras sesiones activas para que una cookie de sesión robada deje de funcionar.

Ejemplo: un usuario hace clic en el enlace dos veces (común en móvil). El primer intento debe tener éxito. El segundo debe decir que el enlace ya no es válido y no debe volver a cambiar la contraseña.

Paso a paso: crear y almacenar tokens de restablecimiento de forma segura

Si vas a arreglar bugs del flujo de restablecimiento, empieza por el token. Muchos “funciona en local” fallan en producción porque los tokens son predecibles, se almacenan de forma insegura o se pueden reutilizar.

1) Genera un token que no se pueda adivinar

Usa un generador criptográficamente seguro (CSPRNG), no timestamps, IDs de usuario o códigos cortos. Una buena regla es al menos 32 bytes de aleatoriedad y luego codifícalo (por ejemplo, base64url) para que encaje bien en URLs y emails.

Mantén los tokens para un solo propósito. Un token de restablecimiento debe aceptarse solo para restablecer contraseñas, no para verificar email o sign-in por magic link.

2) Guarda lo mínimo y guárdalo seguro

Nunca almacenes el token en bruto en tu base de datos. Almacena solo un hash. Así, si la base de datos se filtra, los atacantes no pueden usar los enlaces de restablecimiento directamente.

Junto al hash del token, guarda:

• El ID de usuario (o ID de cuenta) al que pertenece el token
• El propósito (password_reset)
• Tiempos como created_at, expires_at y later used_at

Decide cómo manejarás múltiples solicitudes y haz la regla obvia en el código. En la mayoría de productos, “un token activo por usuario” es lo más sencillo: una petición nueva invalida la anterior.

Finalmente, invalida tokens después de usarlos y hazlo de forma atómica para evitar reutilización. El patrón más seguro es “consumir” el token en una sola operación de base de datos (por ejemplo, establecer used_at solo si used_at aún es null y el hash coincide) y luego confirmar que exactamente una fila fue actualizada antes de permitir el cambio de contraseña.

Ejemplo concreto: un usuario hace clic en el enlace dos veces (o abre dos pestañas). Sin un paso de consumo atómico, ambos clics podrían tener éxito.

Paso a paso: fijar TTLs y hacer la expiración fiable

Un enlace que nunca expira es un riesgo de seguridad. Un enlace que expira demasiado rápido parece roto. Elige un TTL claro y aplícalo en un solo lugar: tu servidor.

1) Elige un TTL que encaje con usuarios reales

La mayoría de apps funcionan bien con 15 a 60 minutos. Más corto es más seguro; más largo es más tolerante para quien se interrumpe.

Guía práctica:

• Cuentas de alto riesgo (admin, finanzas): 10-20 minutos
• App de consumo típica: 30-60 minutos
• B2B donde la gente está en reuniones: 60-120 minutos

Sea cual sea, haz que el texto del email lo refleje (por ejemplo: “Este enlace expira en 30 minutos”). Si dices 30 minutos pero aplicas 10, los usuarios volverán a intentar y pensarán que la entrega está rota.

2) Almacena created_at y expires_at en el servidor

No confíes en el cliente (navegador o móvil) para calcular la expiración. No almacenes solo created_at y recalcules expiry en distintas partes del código. Almacena expires_at en el registro del token.

Cuando se use el enlace, el servidor debe comprobar:

• que el token existe
• que no ha sido usado
• que la hora actual del servidor está antes de expires_at

Esto mantiene el comportamiento consistente entre dispositivos.

3) Evita problemas de zona horaria y deriva de reloj

Usa tiempo del servidor en UTC tanto para escribir como para chequear expiraciones. Si tienes varios servidores, asegúrate de que coincidan en tiempo. Una pequeña deriva puede causar fallos aleatorios cerca del borde de expiración.

Si ves expiraciones falsas en logs (especialmente con entrega de email encolada), una pequeña ventana de gracia (1-2 minutos) puede ayudar. Manténla ajustada para que no se convierta en un agujero de seguridad.

4) Decide qué pasa cuando alguien pide otro restablecimiento

Necesitas una regla clara. Dos opciones comunes:

• Revocar tokens viejos cuando se emite uno nuevo
• Permitir múltiples tokens activos que expiran de forma independiente

Para la mayoría, revocar tokens viejos es la mejor opción por defecto. Reduce confusión y baja el riesgo de que enlaces antiguos se usen más tarde.

5) Limpia tokens expirados (sin romper nada)

Los tokens expirados se acumulan y complican la depuración. Puedes limpiarlos con un job programado que borre registros expirados, o con “limpieza perezosa” (eliminar en la consulta si está expirado). La limpieza perezosa es más rápida de implementar; la programada mantiene la tabla ordenada. Muchos equipos hacen ambas cosas.

Paso a paso: básicos de entregabilidad de email que importan

Un flujo perfecto en código puede fallar porque el email nunca llega, cae en spam o el enlace se rompe. Trata el email como parte del sistema.

1) Confirma que el email se envió realmente

Empieza demostrando que tu app entregó el mensaje a un proveedor real. Registra la respuesta del proveedor para cada email de restablecimiento, incluyendo un ID de mensaje y estado de envío.

Registra lo que realmente te ayudará a depurar después:

• ID de usuario (o email hasheado), timestamp y dominio de destino (no la dirección completa)
• ID de mensaje del proveedor y estado (queued, sent, deferred, rejected)
• Plantilla o versión usada y la longitud de la URL de restablecimiento
• Código de error o motivo de rechazo (si hubiera)
• ID de correlación que enlace el email con el registro del token

Si no puedes ver un ID de mensaje, estás adivinando.

2) Higiene básica que afecta la entrega a bandeja

Usa un nombre y dirección From reconocibles y mantenlos consistentes. Mantén el asunto simple (“Restablece tu contraseña”) y evita lenguaje comercial.

También verifica autenticación de dominio (SPF, DKIM, DMARC). Si faltan o están mal configurados, la entregabilidad será poco fiable, especialmente en bandejas corporativas.

3) Vigila rebotes, quejas y supresiones

Si un proveedor suprime una dirección tras un rebote o una queja, el siguiente email de restablecimiento puede ser descartado sin errores obvios. Revisa el dashboard del proveedor para hard bounces, spam complaints, dominios bloqueados y entradas en la lista de supresión.

4) Errores en la plantilla que rompen el enlace

Los emails de restablecimiento fallan incluso cuando se entregan porque el enlace no es usable. Causas comunes: falta el parámetro token, mala codificación de URL o emails que se renderizan mal.

Haz el enlace fácil de clicar y seguro para copiar/pegar. Mantén la URL corta, evita quiebres de línea e incluye una versión en texto plano con el enlace completo visible. Observa la puntuación cerca del enlace ya que algunos clientes la incluyen.

Casos límite que rompen restablecimientos

La mayoría de bugs aparecen en pruebas normales, pero los más molestos se esconden en comportamientos reales.

Múltiples emails, enlaces obsoletos y cambio de email

La gente a menudo pulsa “Olvidé la contraseña” dos veces y luego clican el primer email. Si permites múltiples tokens activos, un enlace antiguo puede seguir funcionando y sobreescribir el nuevo. Si invalida tokens viejos, los usuarios seguirán clicando emails antiguos, así que tu mensaje de error debe ser claro.

Un defecto simple funciona bien: permite solo un token activo por usuario a la vez y devuelve un mensaje neutral cuando el enlace ya no es válido.

Otro fallo común: el usuario cambia su dirección de email durante la ventana de restablecimiento. Si la búsqueda del token depende del email actual, el token queda huérfano. Guarda los tokens contra un ID de usuario estable, no contra una cadena mutable como el email.

Dispositivos, métodos de inicio y clientes de email raros

Los restablecimientos a menudo empiezan en móvil y terminan en escritorio. Si tu página de restablecimiento asume una cookie de sesión existente, token CSRF o almacenamiento local del mismo navegador, el paso final puede fallar. Trata el restablecimiento como un flujo independiente: el enlace debe identificar el intento y el envío final no debe requerir una sesión previa.

También decide qué hacer con usuarios OAuth-only (Google, Apple) o usuarios de magic-link que quizá no tengan contraseña. Si les permites “restablecer”, podrías cambiar silenciosamente su forma de inicio. Elige una política y explícalo con claridad.

Algunos clientes de email prerenderizan enlaces para “navegación segura”, lo que puede consumir accidentalmente un token de un solo uso antes de que el usuario lo toque. Por eso no marques el token como usado hasta que la contraseña cambie realmente.

Algunas guard rails previenen la mayoría de fallos:

• Mantén el token de un solo uso, pero no lo marques como usado hasta que la contraseña cambie.
• Vincula el token a un ID de usuario y guarda created_at y expires_at en el servidor.
• Soporta restablecimientos entre dispositivos sin depender de cookies o almacenamiento local.
• Maneja explícitamente usuarios OAuth-only.
• Añade límites básicos de tasa para frenar bots sin bloquear a usuarios reales.

Controles de seguridad y privacidad que no debes omitir

El restablecimiento es una vía directa a una cuenta. Arreglar “restablecimientos rotos” es solo la mitad del trabajo; cerrar fallos de seguridad comunes importa igual.

Evita la enumeración de cuentas primero

Tu pantalla de solicitud debe responder igual, exista o no el email. Si dices “No se encontró cuenta”, los atacantes pueden probar quién tiene cuenta.

Usa un mensaje neutral como: “Si ese email está registrado, recibirás un mensaje de restablecimiento en breve.” Mantén tiempos similares también, para que la página no responda notablemente más rápido cuando la cuenta no existe.

Protege los tokens como contraseñas

Trata los tokens de restablecimiento como secretos. Nunca los registres en texto plano y nunca los almacenes de forma que una fuga de BD se convierta en una toma de cuentas instantánea.

Un patrón seguro es guardar solo una versión hasheada del token y comparar hashes cuando el usuario hace clic en el enlace. En los logs, registra solo un fragmento enmascarado (por ejemplo, los primeros 4 caracteres) más un request ID.

Cheques que previenen la mayoría de incidentes reales:

• Limitar la tasa de solicitudes por usuario y por IP
• Asegurar que los enlaces usan HTTPS desde el clic hasta el cambio final de contraseña
• Evitar poner el token en lugares que se filtren (como eventos de analítica o scripts de terceros)
• Hacer cumplir tu política de contraseñas (longitud, reglas de reutilización) de forma consistente
• Invalidar tokens antiguos cuando se solicita uno nuevo

Un error común es poner el token en la URL y luego cargar contenido de terceros en la página de restablecimiento. En algunos setups, el navegador puede filtrar la URL completa como referrer. Si no puedes evitar scripts de terceros, considera mantener el token fuera de la URL y usar un código de un solo uso corto introducido por el usuario.

La privacidad también importa: los emails y las pantallas no deben revelar si una persona tiene cuenta, y las herramientas internas deben tener trazabilidad para acciones sensibles.

Errores y trampas comunes (y cómo evitarlos)

Pequeños bugs en los flujos suelen parecer aleatorios: algunos usuarios nunca reciben el email, algunos pueden reutilizar el mismo enlace, otros ven “expirado” inmediatamente. La mayoría de las veces son un puñado de errores repetitivos.

Trampas en el manejo de tokens

El mayor error es almacenar tokens en bruto en cualquier lugar que pueda filtrarse: base de datos, logs, trackers de errores o eventos de analítica. Un token es una contraseña temporal.

Los bugs de expiración vienen después. Los tokens “nunca expiran” cuando el código revisa el campo equivocado, compara tiempos como strings, mezcla unidades (segundos vs milisegundos) o usa zonas horarias inconsistentes. Haz que la expiración sea aburrida: guarda un único expires_at y compara siempre usando tiempo del servidor.

Otra trampa silenciosa es la lógica no atómica: “comprobar que el token es válido” y luego “marcar token como usado” en dos pasos. Bajo carga, dos requests pueden pasar la comprobación. Consume el token con una actualización atómica y verifica que exactamente una fila cambió.

Si quieres un endurecimiento rápido, estas correcciones cubren la mayoría de roturas:

• Hashea tokens y evita registrarlos en claro.
• Aplica la expiración con un único expires_at usando tiempo del servidor.
• Haz que el uso del token sea de una sola vez con un paso atómico.
• Valida contra la identidad correcta (vincula al ID de usuario, no al email).
• Devuelve la misma respuesta para emails desconocidos.

Trampas de email y UX

Un bug común es mezclar ID de usuario y email durante la búsqueda, especialmente cuando la nomenclatura es inconsistente. Decide a qué está ligado el token (normalmente el ID de usuario) y mantenlo.

Revisa también la URL de restablecimiento. Un fallo frecuente en producción es enviar el dominio del frontend equivocado o un entorno (staging, preview, subdominio antiguo). El email está “entregado”, pero los restablecimientos no se completan.

Lista de comprobación rápida antes de marcarlo como arreglado

Antes de darlo por resuelto, haz un restablecimiento completo desde un navegador real, usando bandejas reales. La mayoría de bugs se esconden en las transiciones (API -> BD -> email -> enlace -> comprobación de token).

Traza una petición de extremo a extremo

Elige una cuenta de prueba y lanza un restablecimiento. Confirma que puedes seguirlo en los logs: petición recibida, token creado, email encolado o enviado, enlace clicado, token verificado, contraseña cambiada.

Un simple aprobado/fallido:

• Puedes encontrar un intento de restablecimiento por email (o ID de usuario) y trazarlo de la petición a la finalización.
• El paso de envío de email es visible (respuesta del proveedor, ID de mensaje o estado claro sent/failed).
• Al clicar el enlace obtienes un resultado claro (éxito, expirado, ya usado), no un error genérico.

Expiración, reintentos y comportamiento con emails antiguos

Prueba lo que hacen los usuarios reales: esperar demasiado, pedir múltiples restablecimientos, clicar un email antiguo.

Confirma:

• Los tokens expiran cuando corresponde, incluso después de reinicios o despliegues.
• Un email antiguo falla de forma segura con un mensaje claro.
• Múltiples solicitudes siguen la regla documentada.
• Reusar un enlace tras un restablecimiento exitoso falla.
• Enviar el formulario dos veces no genera dos cambios de contraseña.

Comprobación de entregabilidad (Gmail + Outlook)

No asumas que “enviado” significa “recibido”. Envía a bandejas reales de Gmail y Outlook y confirma dónde cae el mensaje.

Verifica:

• El mensaje llega rápido.
• No entra en Spam en una bandeja nueva de prueba.
• El enlace de restablecimiento es clicable y no está roto por saltos de línea.

Siguientes pasos: hazlo fiable y luego mantén la fiabilidad

Después de arreglar el flujo, trata el restablecimiento como un pequeño producto. Se usa cuando alguien está estresado, así que quieres señales de fallo claras y una forma rutinaria de confirmar que funciona tras cada cambio.

Añade monitorización ligera

No necesitas un gran sistema de observabilidad. Unos pocos contadores y alertas atraparán la mayoría de problemas:

• Solicitudes de restablecimiento creadas por hora/día (vigila caídas o picos)
• Fallos y rebotes de envío de email (por respuesta del proveedor)
• Fallos en confirmación de restablecimiento (inválido, expirado, ya usado)
• Tiempo medio desde la petición hasta el restablecimiento exitoso
• Errores principales en los endpoints de restablecimiento

Si las solicitudes son constantes pero las confirmaciones caen a cero, suele ser entrega (emails que no llegan) o expiración (TTL demasiado corto, problemas de tiempo).

Escribe algunas pruebas repetibles

Apunta a 3–5 pruebas que ejecutes en cada deploy:

• Camino feliz: pedir restablecimiento, cambiar contraseña, iniciar sesión
• Token expirado: mayor que el TTL debe fallar con mensaje claro
• La segunda petición gana: el token más nuevo funciona, el antiguo es rechazado
• Comportamiento de rate limit: solicitudes repetidas frenan bots sin bloquear usuarios reales
• Contenido del email: el enlace apunta al entorno correcto

Prepara un pequeño playbook de soporte

Cuando un usuario diga “no funciona el restablecimiento”, soporte debe preguntar lo básico: qué email usó, aproximadamente cuándo, si pidió varias veces y si revisó spam y pestañas de bandeja. Internamente, soporte debe tener un sitio para chequear logs de restablecimiento y la razón de fallo más reciente.

Si heredaste una base de código generada por IA y el flujo es frágil, una auditoría enfocada suele identificar si tienes un problema de entrega, un problema de tokens o ambos. FixMyMess (fixmymess.ai) hace ese diagnóstico y reparación en apps generadas por IA, empezando por logs claros y luego endureciendo manejo de tokens, expiración y envío de emails para que los restablecimientos funcionen consistentemente en producción.