Tokens JWT en PHP: biblioteca firebase/php-jwt y guía completa

Tokens JWT en PHP: guía completa de la biblioteca firebase/php-jwt

JSON Web Token (JWT) es una forma compacta y segura de transferir datos entre el cliente y el servidor en formato JSON. En el desarrollo web moderno, JWT se utiliza ampliamente para la autenticación y autorización de usuarios, así como para el intercambio de información entre diferentes servicios. En PHP, la biblioteca más popular y confiable para trabajar con JWT es firebase/php-jwt.

¿Qué es JWT y para qué sirve?

JWT consta de tres partes separadas por puntos:

• Header — encabezado que contiene información sobre el tipo de token y el algoritmo de firma.
• Payload — carga útil con datos (por ejemplo, ID de usuario, rol, fecha de expiración).
• Signature — firma creada usando una clave secreta o un par de claves RSA/ECDSA.

Principales ventajas de JWT:

• No requieren almacenamiento de sesiones en el servidor (stateless).
• Pueden contener cualquier dato en formato JSON.
• Soportan diferentes algoritmos de firma: HS256, RS256, ES256 y otros.
• Resistentes a la falsificación gracias a la firma criptográfica.

Instalación de la biblioteca firebase/php-jwt

Para instalar la biblioteca, use Composer. Abra la terminal en la carpeta raíz del proyecto y ejecute el comando:

composer require firebase/php-jwt

Después de la instalación, incluya la carga automática de Composer en su script PHP:

<?phprequire_once __DIR__ . '/vendor/autoload.php';

use Firebase\\JWT\\JWT;use Firebase\\JWT\\Key;?>

Creación de un token JWT

Para crear un token, es necesario definir la carga útil (payload) y firmarla con una clave secreta. Ejemplo de creación de un token con el algoritmo HS256:

<?php$key = 'your-secret-key-here'; // Clave secreta (al menos 32 caracteres)$payload = [    'iss' => 'pythonlib.ru',       // Emisor del token    'sub' => '1234567890',         // Sujeto (por ejemplo, ID de usuario)    'name' => 'Iván Ivanov',    'role' => 'user',    'iat' => time(),               // Fecha de creación    'exp' => time() + 3600         // Fecha de expiración (1 hora)];

$jwt = JWT::encode($payload, $key, 'HS256');echo "Token JWT creado:" . $jwt;?>

En este ejemplo, definimos campos estándar: iss (emisor), sub (sujeto), iat (fecha de creación) y exp (fecha de expiración). Puede agregar cualquier campo personalizado, como role o email.

Decodificación y verificación de un token JWT

Al recibir un token del cliente, es necesario verificar su firma y fecha de expiración. La biblioteca verifica automáticamente el algoritmo y la validez de la firma:

<?phptry {    $decoded = JWT::decode($jwt, new Key($key, 'HS256'));    print_r($decoded);} catch (\\Firebase\\JWT\\ExpiredException $e) {    echo "Error: el token ha expirado — " . $e->getMessage();} catch (\\Firebase\\JWT\\SignatureInvalidException $e) {    echo "Error: firma inválida — " . $e->getMessage();} catch (\\Exception $e) {    echo "Error: " . $e->getMessage();}?>

El método decode() devuelve un objeto stdClass con los datos del payload. Si el token no es válido, se lanza una excepción correspondiente. Se recomienda siempre manejar las excepciones ExpiredException y SignatureInvalidException.

Uso de cifrado asimétrico (RS256)

Para mayor seguridad, use el algoritmo RS256 con un par de claves (privada/pública). Esto es especialmente relevante en arquitecturas de microservicios:

<?php// Generación de claves (se ejecuta una vez)// openssl genrsa -out private.pem 2048// openssl rsa -in private.pem -pubout -out public.pem

$privateKey = file_get_contents('