Cómo implementar OTP por SMS en PHP y Laravel, paso a paso

Un OTP por SMS parece simple —generar seis dígitos y enviarlos—, pero la seguridad está en los detalles: cómo se genera el código, dónde se guarda, cuánto dura, cuántas veces se puede intentar y cómo se evita el abuso. Esta guía muestra una implementación completa en Laravel que puede adaptar a cualquier proyecto PHP. Implementar OTP por SMS en Laravel es más sencillo de lo que parece si sigue estos pasos.

Las reglas que vamos a implementar

Desarrollador trabaja en el diseño de una interfaz
  • Código de 6 dígitos generado con un generador criptográficamente seguro.
  • Se guarda solo un hash del código, nunca el código en claro.
  • Vigencia de 5 minutos y un solo código activo por usuario y propósito.
  • Máximo 5 intentos de validación.
  • Máximo 3 solicitudes por número cada 10 minutos, para frenar el SMS pumping.
  • Comparación en tiempo constante y eliminación del código al usarlo.

1. El servicio de envío

Usaremos el SmsService descrito en la guía para enviar SMS con Laravel, que llama a la API REST con token, IP autorizada y manejo de errores.

2. El servicio de OTP

<?php

namespace App\Services;

use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\RateLimiter;
use RuntimeException;

class OtpService
{
    private const TTL_SECONDS  = 300; // vigencia: 5 minutos
    private const MAX_ATTEMPTS = 5;   // intentos de validacion

    public function __construct(private SmsService $sms)
    {
    }

    public function send(string $phone, string $purpose): void
    {
        // Maximo 3 solicitudes por numero cada 10 minutos (anti SMS pumping)
        $limiterKey = "otp-send:{$purpose}:{$phone}";
        if (RateLimiter::tooManyAttempts($limiterKey, 3)) {
            throw new RuntimeException('Demasiadas solicitudes. Intente mas tarde.');
        }
        RateLimiter::hit($limiterKey, 600);

        $code = (string) random_int(100000, 999999);

        // Se guarda solo el hash; un codigo nuevo invalida el anterior
        Cache::put($this->key($phone, $purpose), [
            'hash'     => hash_hmac('sha256', $code, config('app.key')),
            'attempts' => 0,
        ], self::TTL_SECONDS);

        $this->sms->send($phone, "MiMarca: Tu codigo es {$code}. Vence en 5 minutos. No lo compartas con nadie.");
    }

    public function verify(string $phone, string $purpose, string $code): bool
    {
        $key  = $this->key($phone, $purpose);
        $data = Cache::get($key);

        if (! $data || $data['attempts'] >= self::MAX_ATTEMPTS) {
            return false;
        }

        $valid = hash_equals($data['hash'], hash_hmac('sha256', $code, config('app.key')));

        if ($valid) {
            Cache::forget($key); // un solo uso
        } else {
            $data['attempts']++;
            Cache::put($key, $data, self::TTL_SECONDS);
        }

        return $valid;
    }

    private function key(string $phone, string $purpose): string
    {
        return "otp:{$purpose}:{$phone}";
    }
}

3. Los endpoints

// Solicitar el codigo
public function request(Request $request, OtpService $otp)
{
    $data = $request->validate(['phone' => ['required', 'regex:/^\+52\d{10}$/']]);
    $otp->send($data['phone'], 'login');

    return response()->json(['message' => 'Si el numero es valido, recibira un codigo.']);
}

// Validar el codigo
public function verify(Request $request, OtpService $otp)
{
    $data = $request->validate([
        'phone' => ['required', 'string'],
        'code'  => ['required', 'digits:6'],
    ]);

    abort_unless($otp->verify($data['phone'], 'login', $data['code']), 422, 'Codigo invalido o vencido.');

    // ... continuar con el inicio de sesion
}

Observe que la respuesta de solicitud no confirma si el número existe: así no se filtra información a quien intenta enumerar usuarios.

Detalles que marcan la diferencia

  • Mensaje sin enlaces y con advertencia de no compartir el código.
  • Mismo propósito, mismo código: separe los códigos de inicio de sesión, recuperación y confirmación de operaciones.
  • Monitoree la tasa de verificación: códigos validados frente a enviados. Una caída brusca suele indicar abuso; vea cómo funciona el OTP por SMS.
  • Prepare un respaldo: permitir el reenvío tras 30 a 60 segundos y ofrecer un canal alternativo si el reporte de entrega indica que no llegó.
  • Pruebe en sandbox el flujo completo antes de pasar a producción.

Para el contexto de seguridad y regulación, vea OTP por SMS para autenticación y verificación. Si necesita credenciales de prueba, contáctenos.

Fuentes

  • “Grupo Tecnophone API — Documentación de la API de SMS”, Grupo Tecnophone. Ver fuente
  • “NIST SP 800-63B-4: Digital Identity Guidelines — Authentication and Authenticator Management”, NIST, 2025. Ver fuente
  • “Rate Limiting”, Laravel Documentation. Ver fuente

Preguntas frecuentes

Scroll al inicio