Você gera um token aleatório, codifica em Base64, cola num link de confirmação de e-mail e… o backend devolve "token inválido". Na maioria das vezes, o culpado é um destes três caracteres: +, / ou =. Este post mostra, com um exemplo de ponta a ponta, por que o Base64URL troca os dois primeiros e simplesmente apaga o terceiro, e como recolocar o = na hora de decodificar.
Aviso: eu criei o Base64 URL-Safe da base64decodetool.com usado nos exemplos. Todos os tokens abaixo são fictícios, gerados só para este artigo. Não cole tokens reais de produção em nenhuma ferramenta online.
O problema em um exemplo
Imagine um token de 16 bytes (fictício), em hexadecimal:
fb ef be 0f 3c 8a ff e1 d2 c3 b4 a5 96 87 78 fe
Em Base64 padrão, ele vira:
++++DzyK/+HSw7Sllod4/g==
Agora coloque isso numa query string, ?t=++++DzyK/+HSw7Sllod4/g==, e leia com URLSearchParams (JavaScript) ou parse_qs (Python). Os dois devolvem:
" DzyK/ HSw7Sllod4/g=="
Cada + virou espaço, porque na codificação de formulários (application/x-www-form-urlencoded) + significa espaço. A / pode confundir o roteamento se o token for parte do caminho, e o = costuma ser percent-encoded como %3D. O token chega corrompido sem que ninguém tenha feito nada de "errado".
O que o Base64URL muda
A RFC 4648, seção 5, define o alfabeto "URL and filename safe":
-
+vira- -
/vira_ - o restante do alfabeto continua igual
Sobre o =, a própria RFC diz que ele costuma ser percent-encoded em URIs, mas que dá para omiti-lo quando o tamanho dos dados é conhecido implicitamente (seção 3.2). O JWT (RFC 7515) vai além: lá, "base64url" significa obrigatoriamente sem os = finais, sem quebras de linha e sem espaços.
Aplicando ao nosso token:
| Formato | Resultado | Tamanho |
|---|---|---|
| Base64 padrão | ++++DzyK/+HSw7Sllod4/g== |
24 |
| Base64URL sem padding | ----DzyK_-HSw7Sllod4_g |
22 |
Mesmos 16 bytes, nenhum caractere que precise de escape na URL.
A regra para recolocar o "="
O Base64 trabalha em blocos de 4 caracteres. Sem padding, o último bloco fica incompleto, e o resto da divisão do tamanho por 4 diz quantos = faltam:
| comprimento % 4 | O que fazer | Exemplo (fictício) |
|---|---|---|
| 0 | nada |
YcOnw6Nv → "ação" |
| 2 | acrescentar ==
|
U8OjbyBQYXVsbw (14) → "São Paulo" |
| 3 | acrescentar =
|
cGVkaWRvPTEyMzQ (15) → "pedido=1234" |
| 1 | inválido | nenhum tamanho de dados gera isso |
O caso "resto 1" é importante: não existe sequência de bytes cuja codificação tenha esse tamanho. Se aparecer, o texto foi truncado, ganhou um caractere a mais ou foi colado errado. Não adianta "completar com =".
Nosso token tem 22 caracteres: 22 % 4 = 2, então recolocamos == e voltamos para ----DzyK_-HSw7Sllod4_g==, que decodifica exatamente para os 16 bytes originais.
No código
Python. base64.urlsafe_b64decode troca -/_, mas exige o padding. Sem ele, levanta binascii.Error: Incorrect padding:
import base64
def b64url_decode(s: str) -> bytes:
return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
def b64url_encode(b: bytes) -> str:
return base64.urlsafe_b64encode(b).rstrip(b"=").decode("ascii")
print(b64url_decode("----DzyK_-HSw7Sllod4_g").hex())
# fbefbe0f3c8affe1d2c3b4a5968778fe
O truque -len(s) % 4 dá 0, 2 ou 1 para os restos 0, 2 e 3. Com resto 1, ele acrescenta três =, e o Python rejeita a string com um erro explícito, que é o comportamento certo.
Node.js. O Buffer aceita base64url diretamente, com ou sem padding:
Buffer.from("----DzyK_-HSw7Sllod4_g", "base64url").toString("hex");
// 'fbefbe0f3c8affe1d2c3b4a5968778fe'
Buffer.from("fbefbe0f3c8affe1d2c3b4a5968778fe", "hex").toString("base64url");
// '----DzyK_-HSw7Sllod4_g'
Testei os dois trechos no Python 3.13 e no Node.js 24.
Uma armadilha: o "%3D" colado sem decodificar
Às vezes alguém copia o token direto da barra de endereço, ainda percent-encoded: cGVkaWRvPTEyMzQ%3D. Se você jogar isso num decodificador Base64, o % é descartado e sobra ...MzQ3D. O 3D vira parte dos dados, o tamanho fica com resto 1 e a decodificação falha. Primeiro desfaça a codificação da URL (decodeURIComponent no JS, urllib.parse.unquote no Python). Depois decodifique o Base64. cGVkaWRvPTEyMzQ= ou cGVkaWRvPTEyMzQ voltam corretamente para "pedido=1234".
Lembretes rápidos
- Base64URL é codificação, não criptografia. Qualquer pessoa decodifica um token desses em segundos. A segurança vem de o token ser aleatório, de ter vida curta e de ser validado no servidor.
- Decodificar um JWT não verifica a assinatura. Isso é outra etapa.
- Escolha um formato e documente. Se a API emite sem padding, o cliente não deve "adivinhar". Use a regra do resto por 4.
Como testar na ferramenta
- Abra base64decodetool.com/pt/url-safe/. Nesta página, a opção Formato Seguro para URL já vem ativada e travada.
- Para codificar, clique em Codificar para Base64. Para testar bytes como os do exemplo, escolha Hexadecimal no seletor de codificação e cole
fbefbe0f3c8affe1d2c3b4a5968778fe. A saída é----DzyK_-HSw7Sllod4_g, sem=. - Para decodificar, clique em Decodificar Base64 e cole a string com ou sem
=. A ferramenta troca-/_e completa o padding sozinha. Para o token do exemplo, deixe Hexadecimal selecionado para ver os bytes; para texto, use UTF-8. Depois, clique em Copiar.
Se a entrada tiver resto 1 (como no caso do %3D), a ferramenta não mostra resultado e exibe uma mensagem de erro. O texto dessa mensagem vem do navegador e pode aparecer em inglês, assim como alguns rótulos (por exemplo, a opção "Binary").
Fontes: RFC 4648, seções 3.2 e 5 (https://www.rfc-editor.org/rfc/rfc4648); RFC 7515, seção 2 e Apêndice C (https://www.rfc-editor.org/rfc/rfc7515). Consultadas em 16/11/2026. Exemplos conferidos com a lógica JavaScript da própria ferramenta (base64.worker.js), com o Python 3.13 e com o Node.js 24.
Top comments (0)