---
title: "Como Lidar com JWTs em Python"
description: "Aprenda a criar, analisar e verificar seus JWTs em Python usando PyJWT"
authors:
- name: "Jessica Temporal"
url: "https://auth0.com/blog/authors/jessica-temporal/"
date: "Oct 28, 2021"
category: "Developers,Tutorial,Python"
tags: ["jwt", "pyjwt", "jwt tutorial"]
url: "https://auth0.com/blog/pt-how-to-handle-jwt-in-python/"
---
# Como Lidar com JWTs em Python
Os JSON Web Tokens, ou JWTs, estão em toda a Internet. Eles podem ser usados para rastrear bits de informação sobre um usuário de uma forma muito compacta ou em APIs para fins de autorização. Este artigo vai mostrar o que são os JSON Web Tokens e como criar JWTs no Python usando a biblioteca JWT mais popular: [PyJWT](http://pyjwt.readthedocs.io/). Você também vai descobrir como você pode assinar e verificar JWTs no Python usando algoritmos simétricos e algoritmos assimétricos.
Antes de começar, há uma coleção de scripts, com todos os códigos que abordarei neste artigo, [disponível aqui neste repositório GitHub](https://github.com/auth0-blog/jwts-in-python).
Se preferir, você pode assistir aos vídeos abaixo, onde eu explico tudo sobre os JWTs! 👇
Dica: Esses vídeos tem legenda em Português, não esqueça de ativá-las. 😉
## Introdução à JSON Web Tokens
JSON Web Tokens são uma forma muito compacta de transmitir informações. São definidos com uma estrutura de 3 partes que consiste em um cabeçalho (_header_), um corpo (_payload_) e uma assinatura (_signature_). O _header_ e o _payload_ contém declarações (_claims_) sobre uma entidade e todos os dados adicionais que precisam ser passados na solicitação:
- No cabeçalho, encontramos declarações sobre o próprio token, como qual algoritmo foi usado para assinar esse token;
- Enquanto o corpo carrega informações sobre um determinado ativo. Em um cenário de login, seriam informações sobre o usuário.
A parte final é a assinatura que ajuda a garantir que um determinado token não foi adulterado, porque a assinatura de um JWT requer um segredo ou um par de chaves pública/privada acordadas previamente. A assinatura em si é baseada no _header_ e no _payload_, em combinação com uma chave secreta (comumente uma string randômica também chamada de segredo) ou par de chaves pública/privada, dependendo do algoritmo.
As declarações seguem o padrão de par chave/valor que você vê em dicionários e objetos JSON, e a maioria das declarações usadas em JWTs tem uma nomenclatura padronizada definida pela [especificação de JWTs definida na RFC7519](https://datatracker.ietf.org/doc/html/rfc7519). A RFC7519 também contém [a descrição do que significa cada uma das declações padrão](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4).
Se você quiser saber mais sobre JWTs, deve conferir [esta página em inglês que fala sobre JSON Web Tokens](https://auth0.com/learn/json-web-tokens/) de uma forma muito prática, ou se quiser se aprofundar, recomendo o **"JWT Handbook"**, disponível gratuitamente no link abaixo (em inglês).
Embora seja bom ler definições e explicações, o melhor é ver como algo funciona. No restante deste artigo, você aprenderá sobre os JSON Web Tokens, criando, assinando, verificando e decodificando seu próprio JWT.
## Requisitos
Para seguir os passos deste artigo, você vai precisar de:
- Python `3.6` ou superior, eu estou usando `3.8.2`;
- Um ambiente virtual Python ativado, se você já sabe como criar seu próprio ambiente, pode pular para a [seção _"Instalando requisitos"_](#Instalando-requisitos);
- PyJWT com a dependência `cryptography` instalada. Confira como instalá-lo na [seção _"Instalando requisitos"_](#Instalando-requisitos);
- Também vou usar o [iPython](https://ipython.org/), um console Python interativo alternativo ao console tradicional, mas fique à vontade para escolher a interface ou console Python que preferir. 😉
### Criando seu ambiente virtual Python
Para criar um ambiente, você deve criar e navegar até sua pasta de trabalho. Gosto de usar os seguintes comandos:
```console
mkdir jwts-in-python
cd jwts-in-python
```
Depois disso, crie um ambiente chamado `.env`:
```python
python3 -m venv .env
```
E depois que o ambiente for criado, você deve ativá-lo e instalar a versão mais recente de `pip`:
```console
source .env/bin/activate
pip install -U pip
```
Observe que o comando para ativar seu ambiente irá variar de acordo com seu sistema operacional (SO). Nesta [página da documentação do Python, você encontra uma lista de todas as maneiras de ativar um ambiente](https://docs.python.org/pt-br/3/library/venv.html#creating-virtual-environments) para ver qual funciona melhor para o seu sistema operacional.
### Gerando um par de chaves RSA
Para assinar seus tokens com um [algoritmo assimétrico](https://auth0.com/docs/tokens/signing-algorithms) como RS256, você precisará de um par de chaves pública/privada que explicarei mais sobre na próxima seção. É possível que você já tenha um par de chaves, mas, caso precise gerar um novo par, aqui está um exemplo:
```console
mkdir ~/jwts-in-python/.ssh
ssh-keygen -t rsa
```
Observe que se você estiver usando o Windows como sistema operacional, dependendo da versão, será necessário instalar o OpenSSH para ter acesso à ferramenta `ssh-keygen`. [Neste tutorial (em inglês)](https://ubuntu.com/tutorials/ssh-keygen-on-windows#1-overview), você vai encontrar todas as maneiras de gerar um par de chaves no Windows.
E se quiser ter o par de chaves dentro do diretório de trabalho, lembre-se de passar o caminho para o seu diretório quando for solicitado. O caminho também deve conter o nome da chave privada. No meu caso, usei o seguinte caminho, caso você queira copiá-lo:
```console
~/jwts-in-python/.ssh/id_rsa
```
Além disso, será solicitada uma senha. Para simplificar, o par de chaves que gerei não tem uma senha. Lembre-se de que você **sempre deve usar senhas ao gerar chaves RSA** para garantir um nível extra de segurança.
### Instalando requisitos
Para fazer tudo o que abordarei neste artigo, você precisará instalar o PyJWT com o pacote `cryptography` como uma dependência. Essa dependência dará a você a capacidade de assinar e verificar JWTs assinados com algoritmos assimétricos.
```console
pip install pyjwt[crypto]
```
Se você também deseja instalar o iPython, você pode fazer isso da seguinte forma:
```console
pip install ipython
```
Agora você tem tudo o que precisa. 🎉
## Crie um JWT em Python
Vou ensinar a criar um JWT porque, ao entender como um token é criado, você entenderá melhor como lidar com os JWTs.
> Lembre-se de que se estiver usando [uma plataforma como a Auth0](http://auth0.com), você *não* deve criar seus tokens; eles serão fornecidos pela própria plataforma. Como os JWTs podem ser lidos por qualquer pessoa, desde que tenham o segredo ou a chave pública, é realmente importante seguir os padrões do setor para evitar complicações como violações de dados e de segurança.
Abra seu console. Se você estiver usando iPython, você deve digitar `ipython` no terminal e pressionar `Enter`. Depois pode começar a codificar:
A primeira coisa que você precisa fazer é importar o objeto `jwt` que vem do pacote PyJWT:
```python
import jwt
```
Antes de gerar um token, você deve criar alguns dados para passar pelo corpo do JWT e uma chave secreta para assinar o token usando o algoritmo `HS256`. Então, crie um dicionário para conter alguns dados de um usuário fictício e o segredo:
```python
payload_data = {
"sub": "4242",
"name": "Jessica Temporal",
"nickname": "Jess"
}
my_secret = 'my_super_secret'
```
Os dados de _payload_ possuem três declarações:
- `sub`: que é o identificador do usuário ou "assunto" deste token;
- `name`: que é o nome completo do usuário;
- `nickname`: também o apelido do usuário.
Lembre-se de que você está usando alguns dados fictícios que informam quem é o usuário neste exemplo, e agora a parte difícil está praticamente concluída!
### Assine um token com um algoritmo de hashing
A seguir, você vai assinar o token com os dados que acabou de criar. Ao assinar um token, podemos ter certeza de que a integridade das declarações no token é verificável. Vamos usar o [algoritmo HMAC](https://en.wikipedia.org/wiki/HMAC) (um algoritmo simétrico) primeiro. Um algoritmo simétrico usa uma função de _hashing_ e uma chave secreta que ambas as partes usarão para gerar e validar a assinatura. Geralmente [recomendamos o uso do algoritmo `RS256`](https://auth0.com/docs/tokens/signing-algorithms), que é um algoritmo assimétrico, na próxima seção, você verá como assinar um token com um algoritmo assimétrico. Agora você já pode chamar o método `encode` do objeto `jwt`, passar o dicionário que acabou de criar e deixar que esse método faça a mágica por você. E com isso, quero dizer que o método `encode` se encarrega de criar o cabeçalho padrão, codificar tudo e assinar o token com o segredo:
```python
token = jwt.encode(
payload=payload_data,
key=my_secret
)
```
Antes de continuar, quero de destacar três coisas:
- A primeira é que o parâmetro `key` funciona para uma chave ou um segredo. Nesse caso, estou usando um segredo porque o algoritmo usado por padrão no método `encode` é o `HS256`, que requer apenas um segredo para assinar;
- Isso me leva ao segundo ponto, que na realidade, você terá um segredo real sendo usado em vez desta amostra;
- E o terceiro é se você estivesse usando um algoritmo assimétrico `RS256` para assinar o token, precisaria usar a chave privada para a assinatura, e [temos um exemplo disso mais adiante](#Assine-um-token-com-RS256-um-algoritmo-assimetrico).
Se você imprimir o token, você verá esta enorme string:
```python
token
# eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI0MjQyIiwibmFtZSI6Ikplc3NpY2EgVGVtcG9yYWwiLCJuaWNrbmFtZSI6Ikplc3MifQ.EDkUUxaM439gWLsQ8a8mJWIvQtgZe0et3O3z4Fd_J8o
```
E você pode copiar essa string e usá-la onde quiser. Por exemplo, no [jwt.io](https://jwt.io).
[jwt.io](https://jwt.io) é uma ferramenta muito útil porque você pode usá-la em qualquer lugar, desde que tenha uma conexão com a internet, para que possa verificar a assinatura e o conteúdo de um determinado token diretamente no seu navegador. Você ainda pode usar [jwt.io](https://jwt.io) para criar tokens também no seu navegador!
Se você nunca usou o site [jwt.io](https://jwt.io) antes e essa é a primeira vez que está colando seu token na área do token (_"Encoded"_), você deve estar vendo que a assinatura é inválida, como na imagem acima (_"Invalid Signature"_). Isso ocorre porque você precisa fornecer o segredo correto no campo _"secret"_ da seção _"Verify Signature"_. Depois de corrigir a chave secreta, a assinatura do token é verificada, como pode ver na imagem abaixo!
Na imagem acima também possível observar que o token possui um cabeçalho com duas declarações que o PyJWT adicionou ao criar esse token:
- `typ`: usada para dizer o tipo de token;
- `alg`: usada para dizer qual algoritmo foi usado para assinar o JWT.
E você também pode verificar os dados que passamos no corpo do token. É isso! Você acabou de gerar e verificar um token! 🎉
### Assine um token com RS256 um algoritmo assimétrico
Até agora, você usou o `HS256`, um algoritmo de hashing, para assinar um token. Mas se você quiser levar sua assinatura de token um passo adiante, você pode usar algoritmos assimétricos. Essa é uma boa maneira de assinar tokens porque, se você tiver uma chave pública hospedada em algum lugar, digamos, em seu site, qualquer pessoa pode verificar se você assinou esse token. Apenas recapitulando, algoritmos assimétricos como o `RS256` são aqueles algoritmos que usam [uma **chave privada para assinar** e uma **chave pública para verificar a assinatura**](https://pt.wikipedia.org/wiki/Criptografia_de_chave_pública).
É aqui que o pacote `cryptography` entra em jogo. Você precisará importar o módulo `serialization` do pacote para carregar uma chave RSA. Para simplificar, gerei um par de chaves pública/privada usando `ssh-keygen` sem senha na pasta `.ssh` dentro do meu diretório de trabalho. Agora tudo o que você precisa fazer é carregar essas chaves:
```python
# first import the module
from cryptography.hazmat.primitives import serialization
# read and load the key
private_key = open('.ssh/id_rsa', 'r').read()
key = serialization.load_ssh_private_key(private_key.encode(), password=b'')
```
Vamos entender o que está acontecendo no exemplo acima:
- Primeiro, uso a função `open` em combinação com o método `read` para obter a chave como uma string e, em seguida, guardo a chave na variável `private_key`;
- Depois uso o `serialization.load_ssh_private_key` e passo a string _encoded_ da chave privada porque o método `load_ssh_private_key` precisa receber um objeto do tipo string de bytes. Além disso, você pode notar que o parâmetro `password` recebeu uma string de bytes vazia, porque minha chave não requer uma senha. Se a sua exigir uma senha, lembre-se de atualizar esse valor de acordo.
E a parte pesada do trabalho para você começar a usar algoritmos assimétricos para assinatura está quase chegando ao final! Tudo o que você precisa fazer é passar a variável `key` para o parâmetro `key` enquanto faz o _encoding_ do token e ajustar o valor do parâmetro do `algorithm`. Veja como fica o resultado recriando o token feito antes:
```python
new_token = jwt.encode(
payload=payload_data,
key=key,
algorithm='RS256'
)
```
E se você imprimir o token, verá algo assim:
```python
new_token
# 'eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI0M...81gVns6I_j4kSuyuRxlAJBe3pHi-yS2'
```
## Verifique um JWT
A esta altura, você deve estar se perguntando: _"Legal! Eu sei como verificar um token usando jwt.io e assinar meu próprio token usando algoritmos diferentes. Mas como faço para verificar um token usando Python?"_.
E para responder à sua pergunta, aqui está: com o PyJWT, verificar um token assinado com um algoritmo de hashing exige apenas uma linha de código! Você precisa apenas usar o `decode` e passar para o método o token e o segredo desta forma:
```python
jwt.decode(token, key='my_super_secret', algorithms=['HS256', ])
# {'sub': '4242', 'name': 'Jessica Temporal', 'nickname': 'Jess'}
```
Observe que o resultado aqui é o _payload_, o que significa que você verificou o token com sucesso. Se a verificação tivesse falhado, você veria um `InvalidSignatureError`, dizendo que a verificação da assinatura falhou (`Signature verification failed`).
Além disso, essa etapa foi simples porque você já sabe que o token foi gerado usando o `HS256` e também já sabe a chave necessária decodificá-lo. Mas digamos que você não saiba qual algoritmo foi usado para gerar esse token, certo? Então você pode acessar [jwt.io](https://jwt.io) novamente e verificar o conteúdo do cabeçalho para encontrar a declaração `alg` ou pode usar o PyJWT para fazer isso.
### Encontre o algoritmo usado em um JWT
Você poderia verificar o conteúdo do cabeçalho manualmente se quisesse: para isso precisaria separar a string por cada ponto, decodificar a parte do cabeçalho e assim por diante, mas adivinhe? O PyJWT é uma ferramenta tão boa que existe um método para fazer tudo isso! 🎉
Em vez de fazer tudo isso manualmente, você pode usar o `get_unverified_header`, veja só:
```python
jwt.get_unverified_header(token)
# {'typ': 'JWT', 'alg': 'RS256'}
```
Como você pode ver no exemplo acima, você deve chamar o `get_unverified_header` a partir do `jwt` e passar o token para o método. Como resultado, você obterá um dicionário com os dados do cabeçalho. Agora você pode armazená-lo em uma variável para usar esses dados para tornar seus scripts um pouco mais inteligentes. Vamos ver como isso funcionaria no exemplo abaixo:
```python
# saving the header claims into a variable
header_data = jwt.get_unverified_header(token)
# using that variable in the decode method
jwt.decode(
token,
key='my_super_secret',
algorithms=[header_data['alg'], ]
)
```
Com essa atualização, seu código encontra o algoritmo usado para assinar um token quase como mágica!
### Decodifique um token com um algoritmo assimétrico
Vamos combinar tudo o que você fez até agora e verificar a assinatura de um token que o algoritmo usado era assimétrico. Então, use esse outro token que você vê abaixo que foi criado usando `RS256` e uma chave SSH privada.
```python
token = 'eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI0MjQyIiwibmFtZSI6Ikplc3NpY2EgVGVtcG9yYWwiLCJuaWNrbmFtZSI6Ikplc3MifQ.HgHJPl6b5W0CiDz4cNuyRcs5B3KgaoRbMvZBgCkcXOSOCAc0m7R10tSm6d86u8oW8NgzGoIAlKxBw0CIPhdx5N7MWTE2gshzQqhuq5MB9tNX1pYrLsiOMbibeMasvcf97Kd3JiLAzPPJe6XXB4PNL4h_4RcW6aCgUlRhGMPx1eRkGxAu6ndp5zzWiHQH2KVcpdVVdAwbTznLv3OLvcZqSZj_zemj__IAZPMkBBnhdjYPn-44p9-xrNmFZ9qBth4Ps1ZC1_A6lH77Mi1zb48Ou60SUT1-dhKLU09yY3IX8Pas6xtH6NbZ-e3FxjofO_OL47p25CvdqMYW50JVit2tjU6yzaoXde8JV3J40xuQqwZeP6gsClPJTdA-71PBoAYbjz58O-Aae8OlxfWZyPsyeCPQhog5KjwqsgHUQZp2zIE0Y50CEfoEzsSLRUbIklWNSP9_Vy3-pQAKlEpft0F-xP-fkSf9_AC4-81gVns6I_j4kSuyuRxlAJBe3pHi-yS2'
```
Para fazer isso, você precisará carregar a chave pública (eu forneci [essa chave neste repositório GitHub aqui](https://github.com/auth0-blog/jwts-in-python/tree/main/.ssh) e carregar a chave pública leva as mesmas 3 etapas que você executou para carregar a chave privada, apenas ajustando o método usado para que carregue uma chave pública e o caminho da chave, veja só:
```python
# first import the module
from cryptography.hazmat.primitives import serialization
# read and load the key
public_key = open('.ssh/id_rsa.pub', 'r').read()
key = serialization.load_ssh_public_key(public_key.encode())
```
Agora que você tem um token e a chave pública, pode decodificá-lo. Você só precisa fazer a mesma coisa que fez antes, chamar o método `jwt.decode`, passando o token, a chave e o algoritmo usado:
```python
jwt.decode(jwt=token, key=key, algorithms=['RS256', ])
# {'sub': '4242', 'name': 'Jessica Temporal', 'nickname': 'Jess'}
```
É isso! Você verificou o JWT assinado com um algoritmo assimétrico! 🎉
## Confira a Data de Validade de Um JWT
Outra coisa que você deve fazer ao validar um JWT é verificar se ele expirou ou não, ou melhor ainda, o serviço que você está criando **não** deve aceitar tokens expirados. O token no exemplo abaixo tem uma data de validade (`exp`) definida no passado para você que está lendo este artigo hoje. Vamos nos preparar para decodificar o token:
```python
token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI0MiIsIm5hbWUiOiJKZXNzIFRlbXBvcmFsIiwiZXhwIjoxNTE2MjM5MDIyfQ.uqeQ60enLaCQEZ-7C0d_cgQSrWfgXRQuoB1LZD0j06E'
header_data = jwt.get_unverified_header(token)
```
E se você tentar decodificá-lo hoje vai ver o erro `ExpiredSignatureError`, vá em frente, experimente:
```python
payload = jwt.decode(
token,
key='my_super_secret',
algorithms=[header_data['alg'], ]
)
```
Como o PyJWT é uma ferramenta excelente, ele já cuidou de lidar com esta verificação de validade para você, portanto, se você tentar decodificar um token expirado, você verá um erro como na imagem abaixo:
Para evitar o erro `ExpiredSignatureError` seu código deve ter uma cláusula `try/except` para tratá-lo, algo assim:
```python
from jwt.exceptions import ExpiredSignatureError
try:
payload = jwt.decode(
token,
key='my_super_secret',
algorithms=[header_data['alg'], ]
)
except ExpiredSignatureError as error:
print(f'Unable to decode the token, error: {error}')
```
A maioria dos erros que você pode enfrentar ao verificar os tokens já está implementada no módulo `jwt.exceptions`. Você precisa apenas se lembrar de usá-los e certificar-se de que seu código esteja bem preparado para lidar com eles conforme aparecerem.
Se você precisar de mais detalhes sobre as etapas necessárias para validar os tokens, recomendo a leitura da [documentação da Auth0 (em inglês)](https://auth0.com/docs/tokens/json-web-tokens/validate-json-web-tokens#manually-implement-checks) sobre o assunto.
## Concluindo
Os JWTs são fantásticos e podem ser usados em muitos cenários. Aprender como lidar com eles é algo que toda pessoa desenvolvedora web precisa entender algum dia, e embora eu apenas tenha mostrado como é simples criar, verificar e decodificar JWTs em Python, vale a pena mencionar que **há muito espaço para erros** quando usamos JWTs para autorização.
A quebra controle de acesso, do inglês _broken access control_, é consistentemente parte dos [dez principais riscos de segurança de aplicativos web da OWASP](https://owasp.org/www-project-top-ten/2017/A5_2017-Broken_Access_Control), portanto, é importante seguir os padrões da indústria e saber [o que pode dar errado](https://auth0.com/blog/what-your-identity-solution-is-missing/) se você estiver projetando sua própria solução de autorização.
Se você quiser se livrar do fardo de gerenciar autorização por conta própria, você pode [criar uma conta gratuita na Auth0](https://auth0.com/signup) e começar a usar com JWTs em apenas alguns minutos.
E agora me conte, você usa JWTs? Qual pacote ou biblioteca você mais gosta para trabalhar com eles?
Deixe seus comentários e perguntas no [fórum da comunidade](http://community.auth0.com/). 😉