Configurar la verificación en dos pasos

Todos los roles exigen la verificación en dos pasos (MFA), con un ingreso de gracia. Por eso se llega a esta pantalla de tres formas:

Sugerida: es el primer ingreso de la persona. Ya tiene la sesión abierta y puede elegir “Configurar más tarde”.
Obligatoria: ya usó el ingreso de gracia. Tiene un token a medias que solo sirve para configurar el MFA; si cancela, vuelve al login.
Voluntaria: desde Mi cuenta, con “Cancelar”.

Diagrama5 carriles · 15 pasos · 2 salidas de error

Los números coinciden con el paso a paso. En pantallas pequeñas el diagrama se desliza de lado.

Paso a paso

NavegadorAbre /configurar-mfa
El modo sale del estado de la sesión: token a medias con mfa_setup (obligatoria), sesión abierta con ?sugerido=1 (sugerida) o sesión abierta sin él (voluntaria).
NavegadorEnvía POST /auth/mfa/setup
API¿Ya tiene el MFA activo?
Base de datosGuarda un secreto nuevo, cifrado y sin confirmar
El secreto se cifra con la clave de la aplicación (user_mfa_factors.secret, cast encrypted) y no vale hasta que se confirma. La API lo entrega solo en esta respuesta, junto con la dirección otpauth:// del QR.
NavegadorMuestra el QR y la clave en grupos de 4
El QR se dibuja en SVG desde la matriz de la librería qrcode, sin v-html. La clave en grupos de 4 sirve para escribirla a mano si la cámara no lee el QR.
PersonaEscanea el QR y escribe el primer código
Con cualquier aplicación de autenticación (Google Authenticator, Microsoft Authenticator, 1Password…). La cuenta aparece como "Trazo" y el correo.
NavegadorEnvía POST /auth/mfa/setup/confirm
Límite mfa: 5 por minuto por persona.
API¿El código corresponde al secreto?
Base de datosActiva el factor y guarda 8 códigos de recuperación
Los códigos de recuperación se guardan solo como hash SHA-256 en user_recovery_codes. Se anota el paso de tiempo usado para que ese mismo código no sirva para entrar.
CorreoAviso de verificación activada
Va por la cola, cifrado mientras espera, en texto plano. Si no fue la persona, sabe que debe avisar.
API¿Venía de un ingreso a medias?
Base de datosCambia el token a medias por una sesión
NavegadorMuestra los 8 códigos una sola vez
Con "Copiar todos" y "Descargar .txt". Después no se pueden volver a ver; solo se pueden generar unos nuevos.
PersonaMarca "Ya guardé mis códigos"
NavegadorSigue a ?volver=, al inicio o a Mi cuenta
Mi cuenta si llegó desde ahí; si no, la página de origen o el inicio.

Qué ve la persona en cada error

Código	HTTP	Cuándo	Mensaje en pantalla
`MFA_ALREADY_ENABLED`	409	La cuenta ya tiene el MFA activo (por ejemplo, otra pestaña lo terminó)	Tu cuenta ya tiene activa la verificación en dos pasos.
`MFA_CODE_INVALID`	422	El código no corresponde al secreto	El código no es correcto. Escribe el que muestra ahora tu aplicación de autenticación.
`MFA_SETUP_NOT_STARTED`	409	Se confirma sin haber pedido el secreto	La configuración no está en curso. Vuelve a empezarla desde el primer paso.
`MFA_CHALLENGE_EXPIRED`	401	En el modo obligatorio pasaron más de 5 minutos desde la contraseña	Pasó demasiado tiempo desde que escribiste tu contraseña. Vuelve a ingresar para continuar.
`TOO_MANY_REQUESTS`	429	Más de 5 confirmaciones en un minuto	Hiciste demasiados intentos seguidos. Espera {wait} y vuelve a intentarlo.

Dónde está en el código

StartMfaSetup y ConfirmMfaSetup: secreto, activación, códigos y sesión.
MfaGate: cuándo se sugiere y cuándo se exige.
RecoveryCode y UserMfaFactor: códigos con hash y secreto cifrado.
MfaController: rutas setup y setup/confirm.
MfaSetupPage y RecoveryCodesPanel: los tres modos y la entrega de los códigos.
Explicación del módulo: Módulo Auth. Flujo anterior: Ingreso con verificación en dos pasos.