Tema 15 · Emisión de Tokens

15. Generación y Firma de Tokens JWT en PHP con HMAC-SHA256

Construye una clase en PHP nativo para codificar en Base64URL, firmar con hash_hmac SHA-256 y emitir tokens de acceso tras verificar credenciales de usuario.

La Criptografía detrás de la Firma HMAC-SHA256

La firma criptográfica es el corazón de la seguridad de un JWT. Su fórmula matemática en el estándar HS256 es:

Firma = hash_hmac('sha256', "$headerBase64Url.$payloadBase64Url", $claveSecreta, true)

Si un usuario malicioso o atacante intercepta el token e intenta cambiar su "rol": "cliente" por "rol": "admin" en el payload, la firma criptográfica dejará de coincidir porque el atacante desconoce la clave secreta guardada en el servidor VPS, y la API rechazará el token al instante con un 401 Unauthorized.

¿Por qué Base64URL en lugar de Base64 normal?

En la codificación Base64 tradicional existen los caracteres + y /, además del relleno =. En URLs y cabeceras HTTP, estos caracteres causan problemas de escape o sustitución errónea (por ejemplo + se convierte en un espacio en query strings).

Base64URL reemplaza + por -, / por _ y elimina los signos = de relleno, haciendo que el token sea completamente seguro para viajar en URLs y cabeceras sin corromperse.

⚡ Clase JwtService en PHP Nativo sin Librerías Externas

Implementación pura y ligera para generar tokens JWT con algoritmo HS256:

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

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

    /**
     * Genera un token JWT firmado.
     *
     * @param array $payload Datos a incluir en el cuerpo del token
     * @param int $expiraEnSegundos Tiempo de vida del token (por defecto 2 horas)
     */
    public static function generar(array $payload, int $expiraEnSegundos = 7200): string
    {
        // 1. Encabezado con algoritmo HS256
        $header = [
            'alg' => 'HS256',
            'typ' => 'JWT',
        ];

        // 2. Añadir timestamp de emisión (iat) y de expiración (exp)
        $ahora = time();
        $payload['iat'] = $ahora;
        $payload['exp'] = $ahora + $expiraEnSegundos;

        // 3. Codificar en Base64URL
        $headerB64 = self::base64UrlEncode((string)json_encode($header));
        $payloadB64 = self::base64UrlEncode((string)json_encode($payload));

        // 4. Generar firma criptográfica con hash_hmac SHA-256
        $contenidoAFirmar = "$headerB64.$payloadB64";
        $firmaBinaria = hash_hmac('sha256', $contenidoAFirmar, self::$secreto, true);
        $firmaB64 = self::base64UrlEncode($firmaBinaria);

        // 5. Devolver el JWT unificado por puntos
        return "$contenidoAFirmar.$firmaB64";
    }

    public static function base64UrlEncode(string $data): string
    {
        return rtrim(strtr(base64_encode($data), '+/', '-_'), '=');
    }
}

// Ejemplo de emisión tras login exitoso:
// $token = JwtService::generar(['sub' => 10, 'email' => '[email protected]', 'rol' => 'admin']);
// echo "Token JWT generado:\n" . $token;
🧠
Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección
1 Pregunta
Pregunta 1
¿Qué sucede si un usuario malicioso modifica manualmente los datos del payload de un JWT para declararse administrador?
🦉
¿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.