Tema 16 · Protección de Rutas

16. Middleware de Verificación: Lectura del Header Authorization Bearer y Protección de Rutas

Intercepta peticiones entrantes, extrae el Bearer token, valida la firma criptográfica, comprueba la fecha de expiración (exp) y autoriza el acceso.

El Flujo de Protección de Endpoints

En una API RESTful profesional, los endpoints privados (como GET /api/perfil o POST /api/pedidos) están resguardados por un Middleware de Autenticación que intercepta la petición antes de que llegue al controlador.

El middleware realiza cuatro pasos obligatorios:

  1. Extracción de la Cabecera: Lee la cabecera estándar Authorization: Bearer <token>. Si falta, responde 401 Unauthorized.
  2. Validación de Estructura: Confirma que el token tenga exactamente tres partes separadas por puntos.
  3. Verificación Criptográfica: Recalcula la firma HMAC-SHA256 con la clave secreta del servidor y la compara con hash_equals() (para prevenir ataques de tiempo o timing attacks).
  4. Comprobación de Expiración: Verifica que el timestamp actual sea menor al claim exp del token.

Prevención de Timing Attacks con hash_equals()

🛡️ Regla de Oro en Criptografía: Nunca compares firmas criptográficas usando el operador igual clásico ($firma1 === $firma2). En su lugar, utiliza hash_equals($firma1, $firma2). Esta función compara cadenas en tiempo constante, evitando que un atacante deduzca la firma midiendo los microsegundos que tarda la comparación en fallar.

⚡ Middleware Completo de Autenticación JWT en PHP Puro

Función de protección de endpoints lista para producción que valida el Bearer Token y devuelve el usuario autenticado:

auth_middleware.php
Solo lectura
<?php
declare(strict_types=1);

final class AuthMiddleware
{
    private static string $secreto = 'ClaveUltraSecretaDeKilopolis2026!#$';

    /**
     * Valida el Bearer Token entrante. Si es válido devuelve los claims; si falla aborta con 401.
     *
     * @return array Claims decodificados del usuario (sub, email, rol)
     */
    public static function autenticar(): array
    {
        // 1. Obtener la cabecera Authorization
        $cabeceraAuth = $_SERVER['HTTP_AUTHORIZATION'] ?? $_SERVER['REDIRECT_HTTP_AUTHORIZATION'] ?? '';

        if (empty($cabeceraAuth) && function_exists('apache_request_headers')) {
            $headers = apache_request_headers();
            $cabeceraAuth = $headers['Authorization'] ?? $headers['authorization'] ?? '';
        }

        if (!preg_match('/^Bearer\s+(.+)$/i', $cabeceraAuth, $matches)) {
            http_response_code(401);
            header('Content-Type: application/json; charset=utf-8');
            echo json_encode(['error' => 'Cabecera Authorization: Bearer <token> requerida']);
            exit;
        }

        $jwt = trim($matches[1]);
        $partes = explode('.', $jwt);

        if (count($partes) !== 3) {
            http_response_code(401);
            header('Content-Type: application/json; charset=utf-8');
            echo json_encode(['error' => 'Formato de Token JWT inválido']);
            exit;
        }

        [$headerB64, $payloadB64, $firmaB64] = $partes;

        // 2. Recalcular la firma criptográfica esperada
        $firmaEsperada = rtrim(strtr(base64_encode(
            hash_hmac('sha256', "$headerB64.$payloadB64", self::$secreto, true)
        ), '+/', '-_'), '=');

        // 3. Comparación segura en tiempo constante
        if (!hash_equals($firmaEsperada, $firmaB64)) {
            http_response_code(401);
            header('Content-Type: application/json; charset=utf-8');
            echo json_encode(['error' => 'Firma de Token inválida o alterada']);
            exit;
        }

        // 4. Decodificar el payload
        $payloadJson = base64_decode(strtr($payloadB64, '-_', '+/'));
        $payload = json_decode($payloadJson, true);

        // 5. Validar fecha de expiración
        if (!isset($payload['exp']) || time() >= $payload['exp']) {
            http_response_code(401);
            header('Content-Type: application/json; charset=utf-8');
            echo json_encode(['error' => 'El Token de acceso ha expirado. Inicia sesión nuevamente.']);
            exit;
        }

        return $payload;
    }
}

// En cualquier endpoint protegido:
// $usuarioAuth = AuthMiddleware::autenticar();
// echo "Acceso concedido a: " . $usuarioAuth['email'];
🧠
Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección
1 Pregunta
Pregunta 1
¿Por qué se debe utilizar la función hash_equals() en lugar de "===" al comparar firmas criptográficas en PHP?
🦉
¿Tienes dudas con este tema?
Sócrates AI puede darte analogías y explicarte este código paso a paso.

🚀 ¿Quieres dominar APIs RESTful con PHP Puro, JSON & JWT y crear proyectos reales?

Aprende arquitectura limpia, desarrollo web moderno, buenas prácticas y despliegue en producción con nuestro Bootcamp Fullstack Developer con mentorías en vivo.

🏛️ Autoría y Propiedad Intelectual: Obra educativa original de Juan Sebastián Amador para Kilopolis Academia, estructurada sobre las especificaciones y estándares abiertos del W3C, el estándar vivo de WHATWG y la documentación oficial de código abierto. © Todos los derechos reservados.