SMS OTP

Auris admite contraseñas de un solo uso por SMS (OTP) en dos modos:

• Sin contraseña: El usuario introduce su número de teléfono, recibe un código por SMS y se autentica sin contraseña
• Autenticación de dos factores (2FA): El usuario completa el inicio de sesión con contraseña y luego recibe un código SMS como segundo factor

Ambos modos usan el mismo mecanismo subyacente — un código numérico de corta duración entregado a través de Twilio. El modo se determina por cómo se inicia el flujo.

Configuración de Twilio

Auris utiliza Twilio como proveedor de SMS. Debes tener una cuenta de Twilio con un número de teléfono o servicio de mensajería.

SMS como Inicio de Sesión sin Contraseña

En este modo, el usuario se autentica usando únicamente su número de teléfono y el código OTP — no se requiere contraseña.

Requisitos previos

• El número de teléfono del usuario ya debe estar registrado y verificado en su cuenta. Los números de teléfono no pueden recopilarse como parte de un flujo de inicio sin contraseña.
• El SMS sin contraseña debe estar habilitado en Consola → Autenticación → Sin contraseña → SMS OTP.

Flujo

Uso de la API

SMS como Autenticación de Dos Factores (2FA)

En este modo, el SMS OTP es un segundo factor. El usuario primero completa la autenticación por correo/contraseña (o social) y, si se requiere 2FA, Auris entrega un código SMS antes de emitir los tokens.

Habilitar SMS 2FA

Por usuario (autoservicio): El usuario habilita SMS 2FA desde la configuración de seguridad de su cuenta:

import { AurisClient } from '@auris/js'
 
const auris = new AurisClient({ domain: 'auth.tudominio.com', clientId: 'tu-client-id' })
 
// Paso 1: Establecer y verificar número de teléfono
await fetch('/api/user/phone', {
  method: 'POST',
  headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ phoneNumber: '+15551234567' }),
})
 
// Paso 2: Verificar propiedad — enviar OTP al teléfono
await fetch('/api/user/phone/verify', {
  method: 'POST',
  headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ code: '123456' }),
})
 
// Paso 3: Habilitar SMS 2FA
await fetch('/api/user/2fa/sms', {
  method: 'POST',
  headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
})

import { useAuris } from '@auris/react'
 
function ConfiguracionSms2FA() {
  const { getAccessToken } = useAuris()
  const [paso, setPaso] = useState('telefono') // 'telefono' | 'verificar' | 'listo'
  const [telefono, setTelefono] = useState('')
  const [codigo, setCodigo] = useState('')
 
  async function establecerTelefono() {
    const token = await getAccessToken()
    await fetch('/api/user/phone', {
      method: 'POST',
      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({ phoneNumber: telefono }),
    })
    setPaso('verificar')
  }
 
  async function verificarYHabilitar() {
    const token = await getAccessToken()
    await fetch('/api/user/phone/verify', {
      method: 'POST',
      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({ code: codigo }),
    })
    await fetch('/api/user/2fa/sms', {
      method: 'POST',
      headers: { Authorization: `Bearer ${token}` },
    })
    setPaso('listo')
  }
 
  if (paso === 'telefono') {
    return (
      <form onSubmit={(e) => { e.preventDefault(); establecerTelefono() }}>
        <input
          type="tel"
          placeholder="+15551234567"
          value={telefono}
          onChange={(e) => setTelefono(e.target.value)}
        />
        <button type="submit">Enviar código de verificación</button>
      </form>
    )
  }
 
  if (paso === 'verificar') {
    return (
      <form onSubmit={(e) => { e.preventDefault(); verificarYHabilitar() }}>
        <input
          placeholder="Código de 6 dígitos"
          value={codigo}
          onChange={(e) => setCodigo(e.target.value)}
          maxLength={6}
        />
        <button type="submit">Verificar y habilitar SMS 2FA</button>
      </form>
    )
  }
 
  return <p>La autenticación de dos factores por SMS está ahora habilitada.</p>
}

El Flujo de Inicio de Sesión con 2FA

Durante un inicio de sesión donde se requiere SMS 2FA, la página de inicio de sesión alojada gestiona el segundo factor automáticamente. Si implementas una interfaz de inicio de sesión personalizada usando la API directamente:

Gestión del Número de Teléfono

Los usuarios gestionan su número de teléfono desde la configuración de la cuenta. El teléfono debe estar verificado mediante OTP antes de poder usarse para la autenticación.

Límites de Velocidad

Auris aplica límites de velocidad estrictos en los endpoints de SMS para prevenir abusos y controlar los costes de Twilio:

Tras 5 intentos de verificación fallidos, el código queda invalidado. El usuario debe solicitar un nuevo código.

Cuando se alcanza el límite por hora, el endpoint devuelve una respuesta 429 Too Many Requests con una cabecera Retry-After que indica cuándo se restablece el límite.

Consideraciones de Seguridad

Validación E.164 — Los números de teléfono se validan contra el formato E.164 en la entrada. Los formatos inválidos son rechazados antes de enviar cualquier SMS.

Verificación de propiedad del teléfono — Auris requiere verificación OTP antes de marcar un número de teléfono como verificado. Un número de teléfono no puede usarse para autenticación hasta que haya sido verificado.

Hash del código — Los códigos OTP se almacenan como hashes SHA-256. El código en bruto solo está presente en el mensaje SMS — nunca en la base de datos de Auris.

Riesgo de intercambio de SIM — El SMS OTP es menos resistente a los ataques de intercambio de SIM que TOTP o WebAuthn. Para aplicaciones con cuentas de alto valor, considera usar Passkeys / WebAuthn o TOTP como método 2FA.

Guías Relacionadas

• Passkeys / WebAuthn — 2FA más robusto usando biometría y llaves de hardware
• Magic Links — Autenticación sin contraseña basada en correo electrónico
• Hosted Login (PKCE) — El flujo completo de autenticación usado en producción