Tokens JWT em PHP: biblioteca firebase/php-jwt e guia completo

Tokens JWT em PHP: guia completo para a biblioteca firebase/php-jwt

JSON Web Token (JWT) é uma forma compacta e segura de transmitir dados entre cliente e servidor no formato JSON. No desenvolvimento web moderno, o JWT é amplamente utilizado para autenticação e autorização de usuários, bem como para troca de informações entre diferentes serviços. Em PHP, a biblioteca mais popular e confiável para trabalhar com JWT é a firebase/php-jwt.

O que é JWT e para que serve?

O JWT consiste em três partes separadas por pontos:

• Header — cabeçalho contendo informações sobre o tipo de token e o algoritmo de assinatura.
• Payload — carga útil com dados (por exemplo, ID do usuário, função, prazo de validade).
• Signature — assinatura criada usando uma chave secreta ou um par de chaves RSA/ECDSA.

Principais vantagens do JWT:

• Não requerem armazenamento de sessões no servidor (stateless).
• Podem conter quaisquer dados no formato JSON.
• Suportam vários algoritmos de assinatura: HS256, RS256, ES256 e outros.
• São resistentes a falsificação devido à assinatura criptográfica.

Instalação da biblioteca firebase/php-jwt

Para instalar a biblioteca, use o Composer. Abra o terminal na pasta raiz do projeto e execute o comando:

composer require firebase/php-jwt

Após a instalação, inclua o autoload do Composer no seu script PHP:

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

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

Criação de um token JWT

Para criar um token, é necessário definir a carga útil (payload) e assiná-la com uma chave secreta. Exemplo de criação de token com o algoritmo HS256:

<?php$key = 'your-secret-key-here'; // Chave secreta (pelo menos 32 caracteres)$payload = [    'iss' => 'pythonlib.ru',       // Emissor do token    'sub' => '1234567890',         // Assunto (por exemplo, ID do usuário)    'name' => 'João Silva',    'role' => 'user',    'iat' => time(),               // Hora de criação    'exp' => time() + 3600         // Prazo de validade (1 hora)];

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

Neste exemplo, definimos campos padrão: iss (emissor), sub (assunto), iat (hora de criação) e exp (prazo de validade). Você pode adicionar quaisquer campos personalizados, como role ou email.

Decodificação e verificação do token JWT

Ao receber um token do cliente, é necessário verificar sua assinatura e prazo de validade. A biblioteca verifica automaticamente o algoritmo e a validade da assinatura:

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

O método decode() retorna um objeto stdClass com os dados do payload. Se o token for inválido, uma exceção correspondente é lançada. Recomenda-se sempre tratar as exceções ExpiredException e SignatureInvalidException.

Uso de criptografia assimétrica (RS256)

Para aumentar a segurança, use o algoritmo RS256 com um par de chaves (privada/pública). Isso é especialmente relevante em arquitetura de microsserviços:

<?php// Geração de chaves (executada uma vez)// openssl genrsa -out private.pem 2048// openssl rsa -in private.pem -pubout -out public.pem

$privateKey = file_get_contents('