OAuth State CSRF Token

Parâmetro state em OAuth: proteção contra CSRF no Authorization Code flow

O parâmetro state é a defesa canônica contra CSRF (Cross-Site Request Forgery) no fluxo Authorization Code do OAuth 2.0. A RFC 6749 §10.12 o recomenda; o OAuth 2.1 mantém o state lado a lado com o PKCE (agora obrigatório). Sem state, um site malicioso pode enganar o navegador de uma vítima já logada para concluir um callback de autorização com a conta do atacante — e o app da vítima vincularia os tokens resultantes à sessão errada.

A mecânica é simples: antes de redirecionar para o endpoint de autorização, o cliente gera uma string aleatória criptograficamente forte, armazena no servidor vinculada à sessão do usuário e envia em state na query string. Quando o authorization server redireciona de volta com o código, devolve o mesmo state ipsis litteris. O cliente compara o state recebido com o armazenado — divergência aborta o fluxo.

Geração e verificação

Use um CSPRNG — nunca Math.random(). Entropia mínima: 128 bits (16 bytes); 256 bits (32 bytes) é mais seguro:

// Node
const state = crypto.randomBytes(32).toString('base64url');
req.session.oauthState = state;
res.redirect(`https://idp.example.com/authorize?state=${state}&...`);

// callback
if (req.query.state !== req.session.oauthState) {
  return res.status(400).send('CSRF detectado');
}
delete req.session.oauthState; // uso único

Codifique em base64url para evitar pegadinhas de URL-encoding. Torne o valor de uso único (apague após verificar) e com TTL curto (5-10 min).

State vs PKCE — usar os dois, não escolher

O PKCE (RFC 7636) previne interceptação do authorization code em clientes públicos; o state previne CSRF no callback. Mitigam ataques diferentes. O OAuth 2.1 torna PKCE obrigatório para todos os clientes mas ainda recomenda state. SDKs grandes (Passport.js, NextAuth, Auth0, Spring Security, Authlib) geram e verificam state automaticamente — mas confirme em testes que o seu handler realmente compara.

Codificando rota de retorno dentro do state

É comum carregar também uma "URL de retorno" via state — ex.: JSON { csrf: "", returnTo: "/dashboard" } codificado em base64url. Sempre assine ou HMAC o payload (o cliente controla o que volta). Nunca confie em uma URL de retorno bruta — valide que é do mesmo origin para evitar open redirect.

FAQ

Qual o tamanho ideal do state? 128 bits no mínimo (16 bytes aleatórios ≈ 22 chars em base64url); 256 bits (32 bytes ≈ 43 chars) é o padrão moderno. Valores mais curtos podem ser quebrados offline.

Posso reusar o mesmo state entre usuários? Não. O state precisa ser por-fluxo e vinculado à sessão — reuso quebra a garantia anti-CSRF.

Com cookies SameSite ainda preciso de state? Sim. SameSite=Lax mitiga a maior parte de CSRF, mas o callback OAuth é uma navegação top-level que envia cookies Lax — então o state continua sendo a defesa explícita e independente de framework.

E se a lib já cuida do state? Verifique — escreva um teste de integração que adultera o callback e espera rejeição. Falhas silenciosas na verificação do state já viraram CVE real.