OAuth 2.0 implementação: guia passo a passo cauteloso

Implementar OAuth 2.0 exige cuidado com redirect URIs, armazenamento de tokens e validação de estado. Neste guia, mostro o passo a passo que uso para integrar autorização com segurança e evitar brechas comuns.

Antes de começar, você precisa de: uma aplicação registrada no provedor de identidade (Google, Microsoft, Auth0 etc.), uma URL de redirecionamento HTTPS válida, e definição clara de quais escopos seu app realmente necessita. Sem isso, o fluxo quebra na primeira tentativa.

Passo 1: Registre a aplicação e configure a redirect URI

Acesse o console do provedor e crie um novo cliente OAuth. Informe o tipo de aplicação (web, mobile, SPA). A redirect URI deve ser exata, sem curingas. Erro comum: usar http://localhost em produção ou permitir múltiplas URIs genéricas. Isso abre espaço para interceptação de código. Dica: se seu app é SPA ou mobile, use PKCE (Proof Key for Code Exchange) desde o início.

Passo 2: Escolha o fluxo de autorização adequado

Para apps com backend, use Authorization Code. Para apps públicos (sem segredo), Authorization Code com PKCE. Evite o fluxo Implicit, considerado inseguro. Erro comum: usar Client Credentials para autenticar usuários, quando ele serve apenas para comunicação entre serviços. A escolha errada expõe tokens ou impede a renovação.

Passo 3: Solicite autorização e troque o código por tokens

Redirecione o usuário para o endpoint de autorização com response_type=code, client_id, redirect_uri, scope e state. O state é um valor aleatório que você valida no retorno para prevenir CSRF. Após receber o código, troque-o por um access token via POST no endpoint de token. Nunca faça essa troca no front-end. Erro comum: ignorar a validação do state ou reutilizar o mesmo código.

Passo 4: Armazene e renove tokens com segurança

Guarde o access token em memória ou cookie HttpOnly, nunca em localStorage. Use refresh token para renovar sem novo login, mas rotacione-o a cada uso. Erro comum: armazenar tokens em texto puro no banco. Se possível, criptografe. Defina expiração curta para access tokens (ex.: 1 hora).

Checklist rápido

• [ ] Aplicação registrada com redirect URI exata
• [ ] Fluxo correto escolhido (Authorization Code + PKCE para apps públicos)
• [ ] Parâmetro state gerado e validado
• [ ] Escopos mínimos solicitados
• [ ] Tokens armazenados com segurança e renovação configurada

FAQ

O que é PKCE e por que usar?

PKCE (Proof Key for Code Exchange) é uma extensão que protege o fluxo Authorization Code em apps públicos. Ele gera um code_verifier e um code_challenge, impedindo que um atacante intercepte o código de autorização. Use sempre que o cliente não puder guardar um segredo com segurança.

Posso usar OAuth 2.0 sem HTTPS?

Nunca em produção. OAuth 2.0 depende de HTTPS para proteger tokens e códigos em trânsito. Em desenvolvimento, localhost é aceitável, mas mesmo assim evite expor dados sensíveis. Provedores sérios rejeitam redirect URIs HTTP.

Qual a diferença entre OAuth 2.0 e OpenID Connect?

OAuth 2.0 é um framework de autorização, não de autenticação. OpenID Connect (OIDC) é uma camada sobre OAuth 2.0 que adiciona identidade, com um ID token. Se você precisa saber quem é o usuário, use OIDC. Para apenas conceder acesso a recursos, OAuth 2.0 basta.

O que é o parâmetro state e por que validar?

O state é um valor aleatório enviado na requisição de autorização e devolvido no redirect. Você deve compará-lo com o valor armazenado na sessão. Isso previne ataques CSRF, onde um site malicioso força o usuário a autorizar sem perceber. Ignorar essa validação é um erro crítico.

Como evitar vazamento de tokens no front-end?

Nunca coloque tokens em localStorage ou variáveis globais acessíveis por scripts. Prefira cookies HttpOnly, SameSite=Strict, ou mantenha o token apenas em memória e use um backend proxy para chamadas de API. SPAs devem usar PKCE e evitar expor refresh tokens.

O que fazer se o access token expirar?

Use o refresh token para obter um novo access token sem interação do usuário. Implemente uma fila para evitar múltiplas renovações simultâneas. Se o refresh token for inválido, redirecione para novo login. Monitore a expiração e renove proativamente antes de falhas.