DEV Community

Mind vs Drive
Mind vs Drive

Posted on

Base64URL sem o "=": como tirar e recolocar o padding sem quebrar o token

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
Enter fullscreen mode Exit fullscreen mode

Em Base64 padrão, ele vira:

++++DzyK/+HSw7Sllod4/g==
Enter fullscreen mode Exit fullscreen mode

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=="
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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'
Enter fullscreen mode Exit fullscreen mode

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

  1. Abra base64decodetool.com/pt/url-safe/. Nesta página, a opção Formato Seguro para URL já vem ativada e travada.
  2. 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 =.
  3. 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)