Key Takeways
- TOTP se genera en el lado del cliente a partir de un secreto compartido según RFC 6238, es válido por 30 segundos, gratuito por verificación e inmune a ataques de SMS pumping y SS7.
- Integración en tres pasos: generar secreto en la inscripción, crear URI de aprovisionamiento de código QR, verificar códigos introducidos por el usuario en el lado del servidor con valid_window=1.
- Cinco patrones de UX importantes: mostrar QR + secreto como texto, verificar la inscripción inmediatamente, generar códigos de recuperación, permitir múltiples aplicaciones, mostrar qué aplicación instalar.
- Opciones de librerías en 8 lenguajes: otplib (Node), pyotp (Python), java-otp, otphp (PHP), otp (Go), rotp (Ruby), totp-rs (Rust), Otp.NET. Todas implementan RFC 6238 de forma idéntica.
- Arquitectura correcta: OTP por SMS en el registro (cobertura universal), sugerir la inscripción en TOTP durante 30-90 días a usuarios preocupados por la seguridad, establecer TOTP por defecto una vez inscrito, pasar a clave de acceso para acciones de alto riesgo.
TOTP (Contraseña de un solo uso basada en el tiempo) es el segundo factor que, discretamente, impulsa la mayoría de las autenticaciones empresariales y de consumidores preocupados por la seguridad en 2026. Generado en el lado del cliente a partir de un secreto compartido, válido por 30 segundos, gratuito por uso, inmune a ataques de SMS pumping y SS7. El inconveniente: los usuarios tienen que instalar una aplicación de autenticación y completar una inscripción única. Bien implementado, TOTP es el segundo factor adecuado para usuarios recurrentes de alto volumen y el paso natural desde el OTP por SMS. Esta guía cubre la integración de la API de TOTP para aplicaciones de EE. UU. en 2026, el estándar, las librerías, la UX de inscripción y los patrones de producción.
¿Qué es TOTP?
TOTP es un código de 6-8 dígitos generado por una aplicación de autenticación (Google Authenticator, Authy, 1Password, Microsoft Authenticator) a partir de un secreto compartido que configuras en la inscripción, válido por una ventana de 30 segundos. El código rota cada 30 segundos. Tanto la aplicación de autenticación del usuario como tu servidor calculan el mismo código a partir del mismo secreto, y la verificación los compara.
El estándar es RFC 6238, publicado en 2011 y estable desde entonces. Existen implementaciones en todos los lenguajes principales. La verificación es gratuita por uso porque no se envía ningún mensaje; ambas partes calculan el código localmente.
TOTP vs OTP por SMS: Cuándo usar cada uno
DimensiónOTP por SMSTOTPConfiguración de usuarioNinguna (todo usuario tiene SMS)Inscripción única con escaneo de código QR (~30 segundos)Tiempo de verificación de usuarioLeer SMS, introducir código (10-30 segundos)Abrir app, leer código, introducir (10-15 segundos)Costo por uso$0.01-0.04 en EE. UU.$0 (no se envía mensaje)Nivel de seguridad (NIST)"Restringido""Permitido"Vulnerable a SS7/intercambio de SIMSíNoResistencia al phishingVulnerable a ingeniería socialLigeramente mejor, pero no a prueba de phishingFunciona sin conexiónNo (necesita SMS celular)Sí (códigos generados localmente)Recuperación si se pierde el dispositivoFácil (aún se tiene el número de teléfono)Requiere códigos de recuperación pregenerados en la inscripciónCobertura en EE. UU.~99% (universal)~30-40% de los usuarios consumidores tienen una aplicación de autenticación
Arquitectura correcta: OTP por SMS en el registro para cobertura universal, sugerir la inscripción en TOTP como una "mejora" para usuarios recurrentes, establecer TOTP por defecto para los usuarios que se han inscrito. Nuestro tutorial de 2FA cubre el patrón de capas.
Integración de TOTP: Cómo funciona
Tres pasos de principio a fin:
Paso 1: Generar un secreto en la inscripción
# Python con la librería pyotp
import pyotp
secret = pyotp.random_base32() # secreto codificado en base32 de 32 caracteres
# Almacena el secreto en el registro de tu usuario (cifrado en reposo)
user.totp_secret = encrypt(secret)
user.save()
El secreto es la clave compartida. Tanto tu servidor como la aplicación de autenticación del usuario lo necesitan. Almacénalo cifrado en reposo en tu base de datos de usuarios.
Paso 2: Crear el URI de aprovisionamiento y el código QR
# Generar el URI otpauth según RFC 6238
uri = pyotp.totp.TOTP(secret).provisioning_uri(
name=user.email,
issuer_name='YourApp'
)
# Formato: otpauth://totp/YourApp:user@example.com?secret=ABC...&issuer=YourApp
# Generar un código QR que el usuario escanea con su aplicación de autenticación
import qrcode
qr_image = qrcode.make(uri)
return qr_image # mostrar al usuario
El usuario abre su aplicación de autenticación, toca "escanear código QR" y la aplicación lee el URI. La aplicación extrae el secreto y comienza a generar códigos para esa cuenta.
Paso 3: Verificar un código introducido por el usuario
# Verificar el código al iniciar sesión
def verify_totp(user, user_entered_code):
secret = decrypt(user.totp_secret)
totp = pyotp.TOTP(secret)
# valid_window=1 significa aceptar la ventana de 30 segundos anterior y siguiente
# en caso de desincronización del reloj entre el servidor y el dispositivo del usuario
return totp.verify(user_entered_code, valid_window=1)
El servidor calcula el código esperado a partir del secreto almacenado y lo compara con el código introducido por el usuario. La verificación tiene éxito si coinciden dentro de la ventana de validez.
UX de inscripción que realmente funciona
Cinco patrones de UX que distinguen una buena inscripción en TOTP de una frustrante:
Mostrar el código QR Y el secreto como texto
Los usuarios en dispositivos móviles no pueden escanear fácilmente el código QR en la misma pantalla. Muestra ambos: el código QR para la configuración de escritorio a móvil, y el secreto como texto para los usuarios que lo introducen manualmente en su aplicación de autenticación.
Verificar la inscripción inmediatamente
Después de que el usuario escanee el código QR, pídele que introduzca el código actual de su aplicación de autenticación. Verifícalo antes de guardar el secreto como inscrito. Esto detecta errores de configuración en la inscripción en lugar de en el primer inicio de sesión.
Generar códigos de recuperación en la inscripción
Genera 8-10 códigos de recuperación de un solo uso que el usuario guarda antes de completar la inscripción. Sin ellos, los usuarios que pierden su dispositivo no pueden recuperar su cuenta. Almacena los códigos de recuperación con hash en tu base de datos; marca cada uno como usado después de su consumo.
Permitir múltiples aplicaciones de autenticación
Algunos usuarios utilizan Google Authenticator en el teléfono y Authy en el escritorio. El estándar TOTP permite el mismo secreto inscrito en múltiples aplicaciones simultáneamente. Tu flujo de inscripción debería dejar esto claro.
Mostrar qué aplicación instalar
La mayoría de los usuarios no han visto TOTP antes. Muestra las cuatro aplicaciones más populares (Google Authenticator, Microsoft Authenticator, Authy, 1Password) con enlaces de descarga durante la inscripción.
Referencia de librerías: TOTP en los principales lenguajes
LenguajeLibreríaInstalarNode.js / TypeScriptotplibnpm install otplibPythonpyotppip install pyotpJavajava-otpMaven: com.eatthepath:java-otpPHPotphpcomposer require spomky-labs/otphpGootpgo get github.com/pquerna/otpRubyrotpgem install rotpRusttotp-rsCargo: totp-rs.NETOtp.NETNuGet: Otp.NET
Todas implementan RFC 6238 de la misma manera. Elige la librería para tu lenguaje; la superficie de la API es esencialmente idéntica (generar secreto, construir URI, verificar código).
Errores comunes de implementación
Almacenar el secreto en texto plano
El secreto es la clave compartida; cualquiera que lo tenga puede calcular los códigos del usuario. Cifra en reposo con claves gestionadas por el proveedor o por el cliente.
Omitir el paso de los códigos de recuperación
Los usuarios que pierden su dispositivo sin códigos de recuperación tienen que pasar por una verificación manual de identidad con tu equipo de soporte. Los códigos de recuperación generados en la inscripción no cuestan nada y ahorran horas de tiempo de soporte por cada usuario bloqueado.
Sin tolerancia a la desincronización del reloj
Si el reloj de tu servidor y el del dispositivo del usuario se desincronizan por más de 30 segundos, la verificación falla. Usa valid_window=1 (acepta ventanas anteriores y posteriores) para tolerar un pequeño desfase. Para una mayor tolerancia, usa valid_window=2.
Permitir que el mismo código se verifique dos veces
Una vez que se ha utilizado un código, marca el ID de verificación como consumido. De lo contrario, un atacante que espíe el código por encima del hombro podría usarlo dentro de la ventana de 30 segundos.
No limitar la tasa de intentos de verificación
Forzar por fuerza bruta un código de 6 dígitos es factible sin límites de tasa. Limita a 5 intentos por sesión, con retroceso exponencial después.
Cuándo pasar de TOTP a clave de acceso
TOTP es considerablemente más fuerte que el OTP por SMS, pero más débil que las claves de acceso. La trayectoria de madurez típica:
- OTP por SMS al registrarse para una cobertura universal (todo el mundo tiene SMS).
- Fomentar la inscripción en TOTP durante los primeros 30-90 días para usuarios preocupados por la seguridad.
- Una vez que TOTP sea de uso generalizado en tu base de usuarios, fomenta la inscripción en claves de acceso como la siguiente mejora.
- Para acciones administrativas de alto riesgo, exige claves de hardware FIDO2 independientemente de otros factores.
La FIDO Alliance publica la guía de migración a claves de acceso a varios años. Nuestra guía de claves de acceso vs OTP cubre las ventajas y desventajas.
Preguntas frecuentes
¿Por qué usar TOTP si las claves de acceso son mejores?
TOTP tiene una mayor adopción por parte de los usuarios hoy en día que las claves de acceso (los usuarios con Google Authenticator o Authy instalados son comunes; los usuarios con claves de acceso inscritas en tu servicio son más raros en 2026). TOTP es también el paso intermedio natural entre el OTP por SMS y las claves de acceso para los usuarios que aún no confían en las claves de acceso o cuyos dispositivos no las soportan. Patrón: soporta los tres.
¿TOTP requiere una API de OTP en absoluto?
No para la verificación en sí — los códigos se calculan en el lado del cliente y se verifican en el lado del servidor usando una biblioteca estándar. Pero normalmente usas una API de OTP junto con TOTP para: (a) el factor inicial de OTP por SMS en la inscripción (verificar que el usuario es propietario del teléfono antes de permitir la inscripción en TOTP), (b) la recuperación de cuenta por SMS cuando el usuario pierde su dispositivo TOTP, (c) un factor de respaldo en dispositivos donde TOTP no está disponible.
¿Qué longitud debe tener el código TOTP?
RFC 6238 admite 6, 7 u 8 dígitos. Seis dígitos es el valor predeterminado universal: todas las aplicaciones de autenticación muestran códigos de 6 dígitos y todos los usuarios los esperan. Ocho dígitos añaden seguridad marginal con un coste significativo para la experiencia de usuario. Quédate con 6.
Añade TOTP como la capa de alta seguridad en tu pila
TOTP es gratuito por verificación, resistente al phishing y el segundo factor adecuado para usuarios recurrentes preocupados por la seguridad. Añádelo junto con tu integración existente de OTP por SMS como una opción de "mejora" para los usuarios que desean una mayor seguridad. VerifyNow for USA gestiona la capa de SMS con rutas 10DLC y IDs de remitente preaprobadas (empieza a enviar en menos de 5 minutos); combínalo con la biblioteca TOTP de tu elección para la capa de alta seguridad. Créditos de prueba gratuitos, no se requiere tarjeta de crédito.
.png){kind=small}
