Cómo añadir autenticación de dos factores a tu app

Para añadir autenticación de dos factores (2FA) a tu app, deja que los usuarios vinculen una app de autenticación escaneando un código QR, pide el código de seis dígitos que muestra después de la contraseña, y crea una sesión completa en el servidor solo cuando ese código sea correcto. Dale a cada usuario códigos de recuperación de un solo uso al activarlo, limita cuántos códigos puede intentar adivinar alguien, y exige la contraseña más un código actual antes de poder desactivar el 2FA. Si usas un proveedor de autenticación alojado, activa su opción de multifactor integrada en lugar de construir la tuya.

Esta guía recorre las opciones, el flujo exacto, prompts que puedes dar a un constructor con IA y los errores que hacen que el 2FA parezca presente pero no haga nada. Si el concepto es nuevo, empieza con qué es la autenticación de dos factores.

Antes de empezar: necesitas un inicio de sesión que funcione

El 2FA se apoya en un inicio de sesión existente. Necesitas uno de estos primero:

• Tu propio inicio de sesión, con usuarios y contraseñas cifradas guardados en la base de datos de tu app.
• Un proveedor de autenticación alojado que gestione los usuarios por ti.

Si aún no tienes ninguno, empieza con cómo añadir inicio de sesión a tu app. El resto de esta guía asume que ya funciona un paso de contraseña.

Elige tu segundo factor

TOTP significa contraseña de un solo uso basada en el tiempo, el estándar (RFC 6238) que usan las apps de autenticación. Tu servidor y el teléfono del usuario comparten un secreto; cada uno genera el mismo código corto a partir de ese secreto y la hora actual, que normalmente cambia cada 30 segundos. No necesita conexión de red ni un proveedor de SMS.

Las passkeys sustituyen o complementan la contraseña con una clave criptográfica guardada en el dispositivo del usuario. Son más fuertes, pero requieren más trabajo si las construyes tú; por eso muchas apps empiezan con TOTP y añaden passkeys más tarde, o las obtienen de un proveedor de autenticación.

¿Construirlo o activarlo?

Consulta la documentación actual de tu proveedor para saber qué factores admite y en qué planes. En cualquier caso, nunca escribas tú la matemática de generación de códigos; usa una librería muy utilizada.

Decide primero la política

Responde estas preguntas antes de hacer el prompt, porque cambian el diseño:

1. ¿Quién debe usarlo? Opcional para todos, obligatorio para administradores y personal, o obligatorio para todos. Exigirlo a cualquiera con poder de administración es lo habitual. Consulta control de acceso basado en roles.
2. ¿Con qué frecuencia vuelven a introducir un código los usuarios? En cada inicio de sesión, o una vez por dispositivo durante 30 días («recordar este dispositivo»).
3. ¿Qué acciones necesitan una comprobación reciente? Cambiar el correo, los datos de cobro o desactivar el 2FA son buenos candidatos. Se llama autenticación de paso adicional (step-up).
4. ¿Cuál es el proceso si se pierde el teléfono? Códigos de recuperación, más una alternativa manual que estés dispuesto a gestionar.

Paso a paso: 2FA con TOTP sobre tu propio inicio de sesión

1. Guarda los campos correctos

Cada usuario necesita: si el 2FA está activado, el secreto TOTP (cifrado en reposo, no en texto plano), la fecha en que se activó y una lista de códigos de recuperación guardados cifrados, como las contraseñas. Añade un lugar donde contar los intentos fallidos.

2. Alta

1. El usuario abre Ajustes y hace clic en Activar la autenticación de dos factores.
2. El servidor genera un secreto nuevo y lo devuelve como código QR, además de la versión en texto para quien no pueda escanear.
3. El usuario lo escanea en una app de autenticación y escribe el código actual.
4. El servidor comprueba el código. Solo si es correcto guarda el secreto y marca el 2FA como activado.
5. La app muestra 8–10 códigos de recuperación una sola vez y pide al usuario que los guarde.

El paso 4 es importante: activar el 2FA antes de confirmar un código bloquea a cualquiera cuyo escaneo haya fallado.

3. Inicio de sesión con un segundo paso

1. El usuario envía correo y contraseña. El servidor los comprueba.
2. Si el 2FA está activado, el servidor no crea una sesión completa. En su lugar, crea un estado de «segundo factor pendiente» de corta duración.
3. La app muestra la pantalla del código. El servidor lo comprueba, con una pequeña ventana de tolerancia por desfase de reloj.
4. Solo entonces el servidor emite la sesión real.

Cada ruta protegida y cada endpoint de la API deben rechazar el estado pendiente. Una pantalla de 2FA que solo oculta páginas en el navegador puede saltarse llamando directamente a la API.

4. Límites y alertas

Un código de seis dígitos tiene un millón de combinaciones, lo que se puede adivinar sin límites. Limita los intentos, bloquea el segundo paso durante un tiempo tras varios fallos y envía un correo al usuario cuando ocurra. Consulta limitación de peticiones y enviar correos desde tu app.

5. Recuperación y desactivación

• Un código de recuperación funciona una vez y después se elimina.
• Desactivar el 2FA exige la contraseña y un código actual o de recuperación.
• Regenerar los códigos de recuperación invalida el conjunto anterior.
• Envía un correo al usuario cada vez que se active o desactive el 2FA.

Prompts para tu constructor de IA

Empieza con el flujo principal:

Añade autenticación de dos factores opcional con apps de autenticación (TOTP) a nuestro inicio de sesión actual con correo y contraseña. Usa una librería TOTP conocida, no escribas tú el algoritmo. En Ajustes, muestra un código QR y el secreto en texto, y activa el 2FA solo después de que el usuario introduzca un código válido. Guarda el secreto cifrado y nunca lo vuelvas a mostrar tras la configuración. Muestra 10 códigos de recuperación de un solo uso una vez y guárdalos cifrados.

Después, la aplicación, que es donde el código generado suele quedarse corto:

Aplica el 2FA en el servidor. Tras una contraseña correcta, los usuarios con 2FA activado reciben un estado pendiente de corta duración, no una sesión completa. Cada página y cada ruta de API protegidas deben rechazar el estado pendiente. Limita los intentos de código a 5; después bloquea el segundo paso durante 15 minutos y envía un correo al usuario.

Después, la política:

Exige 2FA para las cuentas de administrador: un administrador sin 2FA es enviado a la configuración y no puede acceder al panel hasta completarla. Exige la contraseña y un código actual para desactivar el 2FA o cambiar el correo de la cuenta. Envía un correo al usuario cuando se active o desactive el 2FA.

Por último, pide al agente que explique lo que construyó:

Enumera cada ruta que comprueba si se ha completado un segundo factor, dónde se guardan el secreto TOTP y los códigos de recuperación, y cómo están protegidos.

Errores habituales

• Emitir la sesión después de la contraseña. El error más grave. Si la sesión completa existe antes de comprobar el código, el 2FA es pura decoración. Pruébalo llamando a una API protegida solo después del paso de contraseña.
• Sin límite de intentos. Adivinar sin límite hace que el código sea vulnerable a fuerza bruta.
• Secretos o códigos de recuperación en texto plano. Una fuga de la base de datos entrega el segundo factor de todos.
• Activar antes de verificar. Los usuarios que escanearon mal quedan bloqueados en el siguiente inicio de sesión.
• Sin proceso de recuperación. Cada teléfono perdido se convierte en un ticket de soporte o en un cliente perdido.
• Desactivación fácil. Si una sesión robada puede desactivar el 2FA sin código, la protección desaparece.
• Códigos en los registros. Asegúrate de que los códigos y secretos nunca aparezcan en los registros del servidor ni en los mensajes de error.
• Comprobarlo solo en la página de inicio de sesión. El restablecimiento de contraseña, el inicio de sesión con enlace mágico y cualquier inicio de sesión social también deben respetar el 2FA, o se convierten en una forma de saltárselo.

Lista de comprobación de pruebas

• La activación solo se completa tras un código válido
• Iniciar sesión con la contraseña correcta pero sin código no da acceso a ninguna página ni API protegida
• Un código incorrecto se rechaza; los fallos repetidos activan el bloqueo y el correo
• Un código de hace unos minutos se rechaza
• Cada código de recuperación funciona exactamente una vez
• Desactivar el 2FA exige la contraseña y un código actual
• El restablecimiento de contraseña no salta el 2FA
• Los administradores sin 2FA no pueden entrar en las páginas de administración (si es obligatorio)
• Secretos y códigos de recuperación cifrados o con hash en la base de datos
• Ningún código ni secreto aparece en los registros

Haz también la lista de seguridad para apps creadas con IA completa antes del lanzamiento.

Añadir 2FA en Mythex

Mythex no incluye un sistema de inicio de sesión integrado para los usuarios finales de tu app, así que el 2FA forma parte del enfoque de autenticación que elijas: tu propio inicio de sesión con correo y contraseña usando la base de datos del proyecto, o un proveedor alojado con soporte multifactor. Describes lo que quieres en el chat con prompts como los de arriba, y las claves del proveedor van en los secretos del proyecto (desde /secrets, la configuración del proyecto o la tarjeta de secretos que muestra el agente), no en el cuadro de mensaje. La receta de la documentación Añadir inicio de sesión a tu app tiene un prompt de inicio, y Seguridad para las apps que construyes cubre los hábitos sobre claves y permisos. Cuando el agente termine, prueba cada punto de la lista de comprobación en la vista previa antes de publicar.

Preguntas