Guia: como implementar autenticação OAuth2 na sua aplicação

Implementar autenticação OAuth2 na sua aplicação é o caminho mais seguro para permitir que usuários acessem recursos de terceiros sem compartilhar senhas. O protocolo, definido pela RFC 6749, padroniza a troca de tokens entre cliente, servidor de autorização e API. Antes de começar, você precisa de: uma aplicação registrada em um provedor OAuth (Google, GitHub, Auth0), uma URL de redirecionamento configurada e acesso a um endpoint de autorização.

Passo 1: Registrar sua aplicação no provedor OAuth

Todo fluxo OAuth2 começa com o registro da sua aplicação no provedor de identidade. Acesse o console de desenvolvedor do provedor escolhido (ex.: Google Cloud Console, GitHub Developer Settings) e crie um novo projeto ou aplicação. Você receberá um client_id e um client_secret. O client_id é público e pode ficar no frontend; o client_secret é confidencial e deve ser armazenado apenas no backend.

Dica: Nunca exponha o client_secret em código frontend ou em repositórios públicos. Use variáveis de ambiente para protegê-lo.

Passo 2: Redirecionar o usuário para o servidor de autorização

Quando o usuário clicar em "Fazer login com Google" (ou similar), sua aplicação deve redirecioná-lo para a URL de autorização do provedor. Essa URL inclui parâmetros obrigatórios: response_type=code, client_id, redirect_uri e scope (escopo de permissões solicitadas). Exemplo:

https://accounts.google.com/o/oauth2/auth?response_type=code&client_id=SEU_CLIENT_ID&redirect_uri=https://seusite.com/callback&scope=openid%20profile%20email

Erro comum: Usar redirect_uri que não corresponde exatamente ao cadastrado no provedor. Qualquer diferença (barras, maiúsculas) causa erro de redirect mismatch.

Passo 3: Trocar o código de autorização por um token de acesso

Após o usuário autorizar, o provedor redireciona de volta para a sua redirect_uri com um parâmetro code. Seu backend deve fazer uma requisição POST para o endpoint de token do provedor, enviando grant_type=authorization_code, code, redirect_uri e client_secret (autenticação básica ou via corpo). O provedor responde com um JSON contendo access_token, token_type e, opcionalmente, refresh_token e id_token.

Dica: Guarde o refresh_token para renovar o acesso sem exigir nova autorização do usuário. Ele tem validade longa, enquanto o access_token geralmente expira em 1 hora.

Passo 4: Usar o token de acesso para consumir a API protegida

Com o access_token em mãos, sua aplicação pode fazer requisições autenticadas à API do provedor. Inclua o token no cabeçalho HTTP Authorization: Bearer <token>. Exemplo com cURL:

curl -H "Authorization: Bearer ya29.a0AfH6S..." https://www.googleapis.com/oauth2/v2/userinfo

Se o token expirar, use o refresh_token para obter um novo sem incomodar o usuário. Envie uma requisição POST para o endpoint de token com grant_type=refresh_token e o refresh_token.

Erro comum: Ignorar a validação do token no backend. Sempre verifique se o token é válido e se os escopos concedidos são os esperados antes de liberar recursos.

Checklist do que foi implementado

• [ ] Aplicação registrada com client_id e client_secret
• [ ] URL de redirecionamento configurada e correspondente
• [ ] Fluxo de redirecionamento para servidor de autorização
• [ ] Troca do código por token de acesso
• [ ] Uso do token em requisições autenticadas
• [ ] Tratamento de renovação com refresh_token

FAQ

O que é OAuth2 e para que serve?

OAuth2 é um protocolo de autorização que permite que uma aplicação acesse recursos de um usuário em outro serviço sem compartilhar a senha. Ele é usado para logins sociais (Google, Facebook) e integrações entre APIs.

Qual a diferença entre OAuth2 e OpenID Connect?

OAuth2 foca em autorização (acesso a recursos). OpenID Connect é uma camada sobre OAuth2 que adiciona autenticação, fornecendo um token de identidade (id_token) que confirma quem é o usuário.

Preciso de um servidor de autorização próprio?

Não necessariamente. Você pode usar provedores como Auth0, Google ou GitHub. Eles gerenciam a autenticação e emissão de tokens, reduzindo a complexidade de implementação.

O que fazer se o token de acesso expirar?

Use o refresh_token para obter um novo access_token sem exigir nova autorização do usuário. O refresh_token tem validade maior e é armazenado de forma segura no backend.

Como proteger o client_secret?

Armazene o client_secret em variáveis de ambiente no servidor, nunca no código frontend. Utilize serviços de gerenciamento de segredos (como AWS Secrets Manager ou HashiCorp Vault) para ambientes de produção.

O que é o escopo (scope) no OAuth2?

O escopo define as permissões que sua aplicação solicita. Exemplos: "email" para ler o e-mail do usuário, "profile" para dados básicos. O usuário vê e aprova esses escopos no momento da autorização.