MENU
  1. Início
  2. Python
  3. Guia Completo para Gerar e Validar JWT (JSON Web Token) com Python

Guia Completo para Gerar e Validar JWT (JSON Web Token) com Python

Python

Este artigo oferece uma explicação detalhada sobre como melhorar a autenticação e a segurança utilizando JWT (JSON Web Token) em Python, desde a geração até a validação. Utilizando bibliotecas do Python, abordamos como entender completamente o processo de autenticação com JWT, incluindo conceitos básicos, exemplos de implementação e medidas de segurança. Vamos aprimorar seu conhecimento sobre como construir funcionalidades de autenticação confiáveis para aplicações web e APIs.

Índice

Conceitos Básicos e Funcionamento do JWT


JWT (JSON Web Token) é um dos formatos de token mais amplamente usados para autenticação na web. Baseado em um padrão (RFC 7519), JWT é projetado para transmitir informações de forma segura entre cliente e servidor, com a funcionalidade de prevenção de adulteração através de assinaturas.

Estrutura do JWT


O JWT é composto por três partes separadas por pontos (.) da seguinte maneira:

  1. Header
  • Define o tipo do token (por exemplo, JWT) e o algoritmo de assinatura (por exemplo, HS256).
   {
       "alg": "HS256",
       "typ": "JWT"
   }
  1. Payload
  • Dados que serão incluídos no token (claims) no formato JSON.
   {
       "sub": "1234567890",
       "name": "John Doe",
       "admin": true
   }
  1. Signature
  • Assinatura gerada a partir do header e do payload utilizando uma chave secreta ou chave pública. Serve para evitar adulterações.

Princípio de Funcionamento do JWT

  1. Quando o cliente envia suas credenciais para login, o servidor gera um JWT com base nessas informações.
  2. O JWT gerado é enviado de volta ao cliente e normalmente é armazenado em cookies ou cabeçalhos HTTP.
  3. Em cada requisição subsequente, o cliente envia o JWT ao servidor, que valida o token e permite a requisição se o token for válido.

Este processo permite uma autenticação sem estado, melhorando a escalabilidade e segurança.

Bibliotecas JWT para Python

Quando se trabalha com JWT em Python, existem várias bibliotecas úteis. Cada uma tem suas características e é importante escolher a mais adequada ao seu projeto.

Principais Bibliotecas

  1. PyJWT
  • Biblioteca mais comum e leve. Permite gerar e validar JWTs facilmente.
  • Site oficial: PyJWT GitHub
  • Características:
    • API simples e fácil de usar
    • Suporte para vários algoritmos de assinatura, como HMAC (HS256, HS512) e RSA (RS256, RS512)
  • Instalação:
    bash pip install pyjwt
  1. Authlib
  • Suporta frameworks de autenticação avançados como OAuth2 e OpenID Connect. Também oferece suporte para JWT.
  • Site oficial: Authlib
  • Características:
    • Funções de segurança avançadas
    • Focado no manuseio de tokens
  • Instalação:
    bash pip install authlib
  1. python-jose
  • Suporta JWT, JWS (JSON Web Signature) e JWE (JSON Web Encryption).
  • Características:
    • Suporte avançado para criptografia (JWE)
    • Alta customização
  • Instalação:
    bash pip install python-jose

Critérios para Escolha da Biblioteca

  • Autenticação simples: PyJWT é o ideal. Leve e intuitivo.
  • Fluxos de autenticação avançados: Authlib é recomendada se você estiver usando OAuth ou OpenID Connect.
  • Criptografia necessária: Se você precisar de criptografia de tokens, escolha python-jose.

Dependendo do tamanho do seu projeto e dos requisitos de segurança, você pode escolher uma dessas bibliotecas para usar o JWT de maneira eficiente.

Implementação de Geração de JWT com Python

Para gerar JWTs, você pode utilizar uma das bibliotecas Python mencionadas, tornando o processo mais eficiente. A seguir, mostraremos como gerar um JWT básico utilizando a biblioteca PyJWT.

Geração Básica de JWT com PyJWT

O código a seguir mostra um exemplo de como gerar um JWT com PyJWT:

import jwt
import datetime

# Definir chave secreta
SECRET_KEY = "your-secret-key"

# Criar o payload
payload = {
    "sub": "1234567890",       # Identificador do usuário
    "name": "John Doe",        # Informações do usuário
    "iat": datetime.datetime.utcnow(),  # Hora de emissão do token
    "exp": datetime.datetime.utcnow() + datetime.timedelta(hours=1)  # Expiração (1 hora)
}

# Gerar o token
token = jwt.encode(payload, SECRET_KEY, algorithm="HS256")

print("JWT gerado:", token)

Explicação do Código

  1. Definir chave secreta
  • Define a chave secreta usada para assinar o token. Esta chave deve ser armazenada com segurança no servidor.
  1. Criar o Payload
  • Inclui as claims como sub e name.
  • Você pode definir também o tempo de emissão (iat) e a data de expiração (exp).
  1. Gerar o Token
  • Utiliza jwt.encode para codificar o payload e gerar o token.
  • Os algoritmos de assinatura mais comuns são HS256 e RS256.

Gerando JWT com Assinatura RSA

A seguir, um exemplo de como gerar um JWT com assinatura usando chaves públicas e privadas RSA:

import jwt

# Chaves privada e pública RSA
private_key = """-----BEGIN RSA PRIVATE KEY-----
... (conteúdo da chave privada) ...
-----END RSA PRIVATE KEY-----"""
public_key = """-----BEGIN PUBLIC KEY-----
... (conteúdo da chave pública) ...
-----END PUBLIC KEY-----"""

# Criar o payload
payload = {
    "sub": "1234567890",
    "name": "John Doe",
    "exp": datetime.datetime.utcnow() + datetime.timedelta(hours=1)
}

# Gerar o token com assinatura RSA
token = jwt.encode(payload, private_key, algorithm="RS256")
print("JWT gerado com RSA:", token)

Considerações Importantes

  1. Gerenciamento da Chave Secreta
  • As chaves secretas devem ser gerenciadas com rigor para evitar que sejam vazadas.
  1. Configuração da Expiração
  • Defina o campo exp para garantir que o token tenha um tempo de validade definido.
  1. Tamanho do Token
  • Evite incluir informações desnecessárias no payload, para não aumentar o tamanho do token.

Com esses exemplos de código, você pode gerar JWTs conforme a necessidade e construir um sistema de autenticação seguro.

Design de Dados no Payload do JWT

O payload do JWT deve conter informações sobre o usuário ou atributos do token. O design adequado do payload é importante para garantir segurança e eficiência, já que isso pode afetar o tamanho do token e sua segurança.

Estrutura Básica do Payload

O payload do JWT pode incluir três tipos de claims:

  1. Claims Registradas
  • Claims padronizadas, com significados específicos. Utilize-as adequadamente.
  • Exemplos principais:
    • iss (Emissor): Indica quem emitiu o token.
    • sub (Assunto): Indica o sujeito do token (ex: ID do usuário).
    • aud (Audiência): Indica quem deve receber o token (ex: nome de um serviço específico).
    • exp (Expiração): A data de expiração do token, no formato de timestamp UNIX.
    • iat (Hora de Emissão): A data e hora em que o token foi gerado, também no formato UNIX.
  1. Claims Públicas
  • Claims definidas para dados específicos de uma aplicação.
  • Use um namespace para evitar conflitos com outros sistemas (ex: namespace/attribute).
    1. Claims Privadas
    • Claims usadas apenas internamente pela aplicação. Não é necessário um namespace.

    Melhores Práticas no Design do Payload

    Inclua Somente os Dados Necessários


    JWT é uma string codificada em Base64 e o tamanho do token pode impactar a eficiência da comunicação. Portanto, inclua apenas os dados necessários para autenticação e autorização no payload.

    {
    "sub": "1234567890",
    "name": "John Doe",
    "roles": ["admin", "user"]
}

    Considerações sobre a Sensibilidade dos Dados


    Embora o JWT seja protegido contra adulteração através de assinaturas, ele não é criptografado. Portanto, evite incluir dados sensíveis como:

    • Senhas
    • Informações de cartões de crédito
    • Informações pessoalmente identificáveis (PII)

    Defina um Prazo de Expiração Claro para o Token


    Certifique-se de definir a claim exp para limitar o tempo de validade do token e reduzir riscos de segurança.

    Exemplo de Design do Payload


    A seguir, um exemplo prático de payload de JWT:

    {
    "iss": "https://example.com",   // Emissor
    "sub": "user123",               // ID do usuário
    "aud": "https://myapi.example.com", // Audiência
    "exp": 1701209952,              // Expiração (timestamp UNIX)
    "iat": 1701206352,              // Hora de emissão
    "roles": ["user", "admin"],     // Permissões do usuário
    "preferences": {
        "theme": "dark",            // Atributos personalizados
        "notifications": true
    }
}

    Considerações sobre o Tamanho do Token


    Se o payload for grande, o tamanho do token também aumentará, o que pode resultar em:

    • Aumento no tamanho das requisições HTTP
    • Aumento no consumo de dados em dispositivos móveis

    Considere reduzir claims personalizadas para tornar o token mais leve.

    Resumo


    O design do payload é crucial para a eficiência e segurança do token. Ao utilizar claims padrão e incluir apenas informações necessárias, você pode garantir um design ideal para seu token.

    Mecanismo de Assinatura com Chaves Secretas e Públicas

    A assinatura do JWT desempenha um papel crucial na segurança, especialmente quando utilizamos chaves públicas e privadas (assinatura assimétrica) para prevenir adulteração e garantir a confiabilidade. Neste tópico, vamos explorar como funciona a assinatura e como implementá-la com Python.

    Funcionamento da Assinatura

    Existem duas abordagens para assinatura de JWT:

    1. Assinatura Simétrica (HMAC)
    • Usa uma chave secreta compartilhada para assinar e verificar o token.
    • É simples e rápido, mas o gerenciamento da chave pode ser um desafio.
    • Algoritmos comuns: HS256, HS512
    1. Assinatura Assimétrica (RSA, ECDSA)
    • Assina com a chave privada e verifica com a chave pública.
    • Ideal para comunicações entre servidores ou interações com terceiros.
    • Algoritmos comuns: RS256, ES256

    Vantagens da assinatura assimétrica:

    • Se a chave secreta for bem gerenciada, a chave pública pode ser vazada sem comprometer a segurança.
    • Ideal para quando existem múltiplos validadores.

    Implementação de Assinatura RSA com Python

    Vamos ver um exemplo de como gerar e verificar JWTs usando assinatura assimétrica (RSA) com a biblioteca PyJWT em Python.

    Preparando as Chaves


    Primeiro, é necessário gerar as chaves privada e pública.

    openssl genrsa -out private.pem 2048
openssl rsa -in private.pem -pubout -out public.pem

    Gerando o JWT


    Agora, utilizando a chave privada, geramos o JWT:

    import jwt
import datetime

# Ler a chave privada
with open("private.pem", "r") as key_file:
    private_key = key_file.read()

# Criar o payload
payload = {
    "sub": "1234567890",
    "name": "John Doe",
    "exp": datetime.datetime.utcnow

() + datetime.timedelta(hours=1)
}

# Gerar o JWT (com assinatura)
token = jwt.encode(payload, private_key, algorithm="RS256")
print("JWT gerado:", token)

    Verificando o JWT


    Agora, verificamos o JWT usando a chave pública.

    # Ler a chave pública
with open("public.pem", "r") as key_file:
    public_key = key_file.read()

# Verificar o JWT
try:
    decoded = jwt.decode(token, public_key, algorithms=["RS256"])
    print("Payload decodificado:", decoded)
except jwt.ExpiredSignatureError:
    print("O token expirou.")
except jwt.InvalidTokenError:
    print("O token é inválido.")

    Critérios para Seleção do Algoritmo de Assinatura

    • HS256 (HMAC): Ideal para sistemas simples de autenticação no lado do servidor.
    • RS256 (RSA): Ideal para comunicação entre servidores ou quando for necessário integrar com sistemas externos.
    • ES256 (ECDSA): Eficaz quando for necessário um algoritmo de assinatura mais leve com chave pública.

    Melhores Práticas

    1. Gerenciamento rigoroso da chave secreta
    • As chaves secretas devem ser armazenadas de forma segura e com restrições de acesso.
    1. Definir a Expiração
    • Use o campo exp para definir um prazo de validade curto para os tokens.
    1. Especificar o Algoritmo de Assinatura
    • Especifique sempre o algoritmo de assinatura e não use valores padrão.

    Resumo


    Usar assinatura com chaves secretas e públicas é fundamental para garantir alta segurança. A assinatura RSA, por exemplo, é ideal para comunicação entre servidores ou sistemas que exigem distribuição de chaves públicas. Vamos implementar sistemas de autenticação seguros e confiáveis usando Python.

    Processo de Validação de JWT

    Na autenticação com JWT, o processo de validação é essencial para verificar a autenticidade do token. Durante a validação, é garantido que o token não tenha sido adulterado, que tenha sido assinado com a chave secreta ou pública correta e que ainda esteja dentro do prazo de validade.

    Processo Básico de Validação de JWT

    1. Verificação da Assinatura
    • Verifique se o token foi assinado com a chave secreta ou pública correta. Se a assinatura não coincidir, o token será inválido.
    1. Verificação do Prazo de Expiração
    • Verifique a claim exp para garantir que o token ainda está dentro do prazo de validade. Tokens expirados são inválidos.
    1. Verificação de Outras Claims
    • Verifique claims como iss (emissor) e aud (destinatário) quando necessário, para garantir que o token está sendo utilizado corretamente.

    Validação de JWT com Python

    Aqui está um exemplo de como validar JWT utilizando a biblioteca PyJWT:

    Validação Básica

    import jwt

# Definir chave secreta ou pública
SECRET_KEY = "your-secret-key"

# Token a ser validado
token = "your.jwt.token"

# Decodificar e validar o JWT
try:
    decoded = jwt.decode(token, SECRET_KEY, algorithms=["HS256"])
    print("Payload verificado:", decoded)
except jwt.ExpiredSignatureError:
    print("O token expirou.")
except jwt.InvalidTokenError:
    print("O token é inválido.")

    Validação com RS256 (Chave Pública)

    Para validação com assinatura assimétrica (RS256), usamos a chave pública.

    # Ler chave pública
with open("public.pem", "r") as key_file:
    public_key = key_file.read()

# Validar o JWT
try:
    decoded = jwt.decode(token, public_key, algorithms=["RS256"])
    print("Payload verificado:", decoded)
except jwt.ExpiredSignatureError:
    print("O token expirou.")
except jwt.InvalidTokenError:
    print("O token é inválido.")

    Verificação de Claims Adicionais durante a Validação

    Você pode adicionar opções para realizar verificações adicionais durante a validação, como verificar a expiração, o destinatário e o emissor:

    decoded = jwt.decode(
    token,
    SECRET_KEY,
    algorithms=["HS256"],
    options={"verify_exp": True},  # Verificar expiração
    audience="https://myapi.example.com",  # Verificar audiência
    issuer="https://example.com

"  # Verificar emissor
)

    Considerações durante a Validação

    1. Especificação do Algoritmo
    • Durante a validação, sempre especifique o algoritmo usado. Não permita algoritmos não confiáveis como none.
    1. Tratamento de Tokens Expirados
    • Tokens expirados devem ser rejeitados, e o usuário deve ser solicitado a fazer login novamente ou atualizar o token.
    1. Verificação da Fonte do Token
    • Certifique-se de que o token foi obtido de uma fonte confiável.

    Fluxo Completo de Validação de Token

    1. Receber o token
    2. Verificar a estrutura do token (Header, Payload, Signature)
    3. Verificar o algoritmo no header e validar a assinatura
    4. Verificar exp e iss no payload
    5. Aceitar a requisição apenas se a validação for bem-sucedida

    Resumo

    Validar JWTs é um passo fundamental no processo de autenticação. Ao verificar corretamente a assinatura, a expiração e outras claims, podemos garantir a segurança e confiabilidade do sistema de autenticação.

    Implementação do Prazo de Validade e Atualização de Tokens

    Quando usamos JWTs, configurar a validade e implementar tokens de atualização é essencial para aumentar a segurança. Nesta seção, mostramos como configurar o tempo de expiração e atualizar o token usando Python.

    Configurando o Prazo de Expiração

    Utilizamos a claim exp (expiration) para configurar o prazo de validade de um JWT. Veja o exemplo abaixo de como configurar o tempo de expiração em Python:

    import jwt
import datetime

# Configuração da chave secreta
SECRET_KEY = "your-secret-key"

# Adicionando o prazo de expiração ao payload
payload = {
    "sub": "1234567890",       # ID do usuário
    "name": "John Doe",        # Informações do usuário
    "iat": datetime.datetime.utcnow(),  # Hora de emissão
    "exp": datetime.datetime.utcnow() + datetime.timedelta(minutes=30)  # Válido por 30 minutos
}

# Gerar o token
token = jwt.encode(payload, SECRET_KEY, algorithm="HS256")
print("Token de Acesso:", token)

    Considerações Importantes

    • Configure o prazo de validade curto (5 a 30 minutos) para reduzir riscos caso o token seja roubado.
    • Se o token expirar, implemente um processo de reautenticação ou atualização do token.

    Design de Tokens de Atualização

    Tokens de atualização são usados para atualizar tokens de acesso expostos quando o token principal expira. Veja as características de um token de atualização:

    1. Prazo de validade mais longo (de alguns dias a semanas)
    2. Normalmente armazenado e gerenciado no lado do servidor

    Exemplo de Geração de Token de Atualização

    # Payload do Token de Atualização
refresh_payload = {
    "sub": "1234567890",       # ID do usuário
    "iat": datetime.datetime.utcnow(),  # Hora de emissão
    "exp": datetime.datetime.utcnow() + datetime.timedelta(days=7)  # Válido por 7 dias
}

# Gerar o Token de Atualização
refresh_token = jwt.encode(refresh_payload, SECRET_KEY, algorithm="HS256")
print("Token de Atualização:", refresh_token)

    Implementação do Processo de Atualização

    Quando o token expira, usamos o token de atualização para gerar um novo token de acesso. Veja o código para esse processo:

    # Decodificar o Token de Atualização e gerar um novo Token de Acesso
try:
    decoded_refresh = jwt.decode(refresh_token, SECRET_KEY, algorithms=["HS256"])

    # Gerar o novo Token de Acesso
    new_access_payload = {
        "sub": decoded_refresh["sub"],
        "name": "John Doe",
        "iat": datetime.datetime.utcnow(),
        "exp": datetime.datetime.utcnow() + datetime.timedelta(minutes=30)
    }
    new_access_token = jwt.encode(new_access_payload, SECRET_KEY, algorithm="HS256")
    print("Novo Token de Acesso:", new_access_token)
except jwt.ExpiredSignatureError:
    print("O token de atualização expirou.")
except jwt.InvalidTokenError:
    print("O token de atualização é inválido.")

    Considerações de Segurança para Tokens de Atualização

    1. Gerenciamento no Lado do Servidor
    • Os tokens de atualização devem ser armazenados de forma segura no lado do servidor para prevenir roubo ou adulteração.
    1. Uso Único
    • Um token de atualização deve ser invalidado após o seu uso para evitar ataques de repetição de sessão.
    1. Reautenticação ao Usar
    • Solicite reautenticação ao usar o token de atualização para melhorar a segurança.

    Exemplo de API para Atualização de Token

    Veja um exemplo de como projetar uma API para atualização de tokens:

    1. O cliente envia um token de acesso expirado e um token de atualização
    2. O servidor valida o token de atualização
    3. Se válido, o servidor emite um novo token de acesso

    Exemplo de Endpoint de API

    POST /api/token/refresh
Authorization: Bearer {refresh_token}

    Exemplo de resposta:

    {
    "access_token": "new_access_token",
    "expires_in": 1800
}

    Resumo

    Com a implementação de tokens de atualização e a configuração adequada da expiração dos tokens, podemos garantir um sistema de autenticação seguro e aumentar a experiência do usuário. A combinação de tokens de acesso de curto prazo com tokens de atualização garante um sistema confiável e eficiente.

    Riscos de Segurança e suas Soluções

    Embora JWT seja uma ferramenta poderosa para autenticação e gerenciamento de sessões, a implementação inadequada pode resultar em sérios riscos de segurança. Nesta seção, abordamos os riscos comuns relacionados ao JWT e como mitigá-los.

    Riscos Comuns de Segurança

    1. Vazamento da Chave Secreta


    Se a chave secreta do JWT for vazada, isso permite a criação de tokens inválidos ou o sequestro do sistema.

    Soluções:

    • Armazene a chave secreta em ambientes seguros (exemplo: variáveis de ambiente, serviços de gerenciamento de chaves).
    • Rotacione a chave periodicamente.

    2. Adulteração de Tokens


    Se a assinatura não for verificada corretamente, um token pode ser adulterado.

    Soluções:

    • Verifique sempre a assinatura do token.
    • Especifique o algoritmo de assinatura de forma explícita e não permita algoritmos não confiáveis (exemplo: none).

    3. Roubo de Token


    Se o token for roubado, um atacante pode usá-lo para agir como o usuário legítimo.

    Soluções:

    • Use HTTPS para criptografar as comunicações.
    • Armazene o token em um local seguro (exemplo: cookies com a flag HttpOnly).
    • Defina um prazo de expiração curto para os tokens.

    4. Ataques de Repetição de Token


    Se um token roubado for reutilizado, um atacante pode assumir a sessão do usuário.

    Soluções:

    • Use um identificador único (jti) para cada token e registre o histórico de uso no servidor.
    • Adicione tokens usados à lista negra.

    5. Dificuldade para Invalidar Tokens


    JWT é sem estado, o que pode dificultar a invalidação de tokens após sua emissão.

    Soluções:

    • Use tokens de atualização e a lista negra para invalidar tokens.
    • Defina um prazo de expiração curto e atualize tokens com frequência.

    Implementando Medidas de Segurança em Python

    1. Gerenciamento de Chaves


    Exemplo de como obter a chave secreta a partir de variáveis de ambiente:

    import os

SECRET_KEY = os.getenv("JWT_SECRET_KEY")
if not SECRET_KEY:
    raise ValueError("A chave secreta deve ser definida!")

    2. Especificando o Algoritmo


    Para evitar algoritmos não seguros, sempre defina explicitamente o algoritmo de assinatura:

    import jwt

# Verificar o token
decoded = jwt.decode(token, SECRET_KEY, algorithms=["HS256"])

    3. Usando HTTPS


    Exemplo de como forçar HTTPS no Flask:

    from flask import Flask

app = Flask(__name__)
app.config['PREFERRED_URL_SCHEME'] = 'https'

    4. Prevenindo Ataques de Repetição


    Definindo um identificador único (jti) e registrando o histórico de uso:

    import uuid

payload = {
    "sub": "1234567890",
    "jti": str(uuid.uuid4()),  # ID único
    "exp": datetime.datetime.utcnow() + datetime.timedelta(minutes=30)
}

    5. Implementando Lista Negra


    Exemplo de como invalidar tokens usando Redis:

    import redis

# Cliente Redis
redis_client = redis.StrictRedis(host='localhost', port=6379, db=0)

# Invalidar o token
redis_client.setex("blacklist:" + token, 1800, "true")  # Invalidar em 30 minutos

    Outras Recomendações

    • Prevenção de Cross-Site Scripting (XSS)
      Use cookies HttpOnly para proteger o token.
    • Monitoramento de Logs
      Registre logs de emissão e validação de tokens para detectar usos suspeitos.

    Resumo

    Embora o JWT ofereça muitos benefícios, falhas nas medidas de segurança podem levar a sérios riscos. Ao adotar boas práticas de gerenciamento de chaves, validação de assinatura e configuração de expiração de tokens, você pode construir um sistema de autenticação seguro e eficiente.

    Conclusão

    Este artigo explicou como gerar e validar JWTs com Python, abordando desde os conceitos fundamentais até as implementações e estratégias de segurança necessárias.

    JWT é uma excelente opção para sistemas de autenticação escaláveis e sem estado, mas a segurança deve ser uma prioridade. Ao usar bibliotecas Python adequadas e seguindo as melhores práticas, você pode implementar um sistema de autenticação seguro e confiável.

Python
autenticação Autenticação Sem Estado Authlib Desenvolvimento de API Desenvolvimento de Aplicativos Web Geração de Tokens JSON Web Token JWT medidas de segurança PyJWT Python python-jose Segurança Verificação de Tokens
Índice