Autenticación de dos factores
Pier admite autenticación de dos factores TOTP (contraseña de un solo uso basada en el tiempo) opcional, compatible con cualquier aplicación de autenticación — Google Authenticator, Aegis, 1Password y otras. Activarla añade un segundo paso a tu inicio de sesión: después de tu contraseña, presentas un código de 6 dígitos o un código de recuperación de un solo uso.
La 2FA se activa por usuario desde el área de Cuenta. No cambia el funcionamiento de las sesiones — una vez que superas el segundo factor, obtienes la misma sesión opaca mediante cookie que en un inicio de sesión solo con contraseña.
Activación
Sección titulada «Activación»La activación es un intercambio de dos llamadas, de modo que el secreto nunca se almacena hasta que demuestres que puedes generar un código válido.
- Iniciar configuración —
POST /api/v1/account/2fa/setup. Pier devuelve unsecretnuevo en base32, unotpauth_url, unqr_svgen línea y 10 códigos de recuperación de un solo uso. Aún no se conserva nada. - Escanea el QR (o escribe el secreto manualmente) en tu aplicación de autenticación. El emisor que se muestra es
Pier. - Guarda tus códigos de recuperación. Solo se muestran una vez. Cada uno tiene el aspecto de
XXXX-XXXX-XXXXy funciona exactamente una vez. - Verificar —
POST /api/v1/account/2fa/verifycon elsecret, elcodeactual de 6 dígitos y los hashes de recuperación. Con un código correcto, Pier cifra el secreto (AES-256-GCM, la misma clave que tus variables de entorno) y lo confirma. Un código incorrecto deja la 2FA desactivada.
El código TOTP se verifica con una ventana de ±1 paso (±30 s), de modo que se tolera una pequeña desviación del reloj en tu teléfono.
Puedes volver a comprobar el estado de la activación en cualquier momento con GET /api/v1/account/2fa, que informa de enabled, enabled_at y recovery_codes_remaining.
El flujo de inicio de sesión con 2FA
Sección titulada «El flujo de inicio de sesión con 2FA»Cuando la 2FA está activada, el inicio de sesión se convierte en dos pasos:
| Paso | Endpoint | Lo que envías | Lo que recibes |
|---|---|---|---|
| 1 | POST /api/v1/auth/login | usuario + contraseña | requires_2fa: true y un partial_token de corta duración |
| 2 | POST /api/v1/auth/login/2fa | partial_token + code | la cookie de sesión |
El partial_token no es una sesión — solo demuestra que superaste el paso de la contraseña. Es un token de un solo uso que se mantiene en memoria, caduca después de 5 minutos y está vinculado a tu IP. Si pier-core se reinicia entremedias, vuelve a escribir tu contraseña.
En el paso 2, el campo code acepta bien tu código TOTP actual o bien uno de tus códigos de recuperación. Un código de recuperación se consume (se elimina) al usarlo, de modo que nunca funciona dos veces.
Ambos endpoints de inicio de sesión tienen límite de tasa para frenar los intentos de fuerza bruta contra el código de 6 dígitos.
Códigos de recuperación
Sección titulada «Códigos de recuperación»Los códigos de recuperación son tu alternativa cuando pierdes tu dispositivo de autenticación.
- Se generan 10 en la activación; solo se almacenan sus hashes.
- No distinguen entre mayúsculas y minúsculas ni guiones al introducirlos (
abcd-EFGH-1234coincide conABCDEFGH1234). - Cada uno es de un solo uso. Cuando
recovery_codes_remainingllega a cero, desactiva y vuelve a activar la 2FA para obtener un conjunto nuevo.
Desactivar la 2FA
Sección titulada «Desactivar la 2FA»POST /api/v1/account/2fa/disable desactiva la 2FA, pero requiere un código TOTP actual válido o un código de recuperación en el cuerpo de la solicitud. Esto impide que alguien que haya secuestrado una sesión activa debilite tu cuenta de forma silenciosa. Si tiene éxito, se borran el secreto y los códigos de recuperación.
Para rotar tu secreto (por ejemplo, después de cambiar de teléfono), desactiva la 2FA y vuelve a activarla — Pier se niega a reemitir un secreto mientras la 2FA siga activa.