Autenticacao OAuth: guia pratico de implementacao passo a passo

Implementar autenticacao OAuth 2.0 em uma aplicacao resolve o problema de acessar recursos protegidos de um usuario sem manipular diretamente suas credenciais. O protocolo define um fluxo de autorizacao entre o cliente (sua app), o proprietario do recurso (usuario) e o servidor de autorizacao (provedor OAuth). Ao final deste guia, voce tera uma integracao funcional com um provedor como Google, GitHub ou Auth0.

Pre-requisitos:

• Uma aplicacao web ou mobile em desenvolvimento
• Conta de desenvolvedor no provedor OAuth escolhido
• Conhecimento basico de HTTP, JSON e sua linguagem de programacao

Passo 1: Registrar sua aplicacao no provedor OAuth

Acesse o console de desenvolvedor do provedor (ex.: Google Cloud Console, GitHub Developer Settings) e crie um novo projeto ou aplicacao. Voce precisara fornecer:

• Nome da aplicacao: identificacao exibida ao usuario.
• URI de redirecionamento: endpoint da sua app que recebera o codigo de autorizacao apos o consentimento do usuario. Exemplo: https://seudominio.com/callback.
• Escopos (scopes): permissoes que sua app solicita, como "ler email" ou "acessar calendario".

Apos o registro, voce recebera um Client ID e um Client Secret. O Client ID e publico; o Client Secret deve ser armazenado com seguranca no servidor.

Erro comum a evitar: Usar o Client Secret no front-end. Isso expoe a chave e permite que qualquer um faca requisicoes em nome da sua app.

Passo 2: Iniciar o fluxo de autorizacao

Quando o usuario desejar se autenticar, redirecione-o para a URL de autorizacao do provedor. A URL inclui parametros obrigatorios:

• response_type=code para o fluxo Authorization Code Grant
• client_id (seu Client ID)
• redirect_uri (a mesma cadastrada no passo 1)
• scope (espacos separados por espaco)
• state (valor aleatorio para prevenir CSRF)

Exemplo de URL: https://accounts.google.com/o/oauth2/v2/auth? response_type=code& client_id=SEU_CLIENT_ID& redirect_uri=https://seudominio.com/callback& scope=openid%20email& state=xyz123

Dica: Gere o parametro state como um hash criptografado e valide-o no callback. Isso protege contra ataques de falsificacao de requisicao entre sites.

Passo 3: Receber o codigo de autorizacao

Apos o usuario consentir, o provedor redireciona para sua redirect_uri com um codigo de autorizacao na query string: https://seudominio.com/callback?code=AUTH_CODE&state=xyz123.

Valide o state recebido contra o que foi enviado. Se nao corresponder, rejeite a requisicao.

Erro comum a evitar: Ignorar a validacao do state. Sem ela, um atacante pode interceptar o codigo e obter acesso nao autorizado.

Passo 4: Trocar o codigo por um token de acesso

Com o codigo em maos, sua aplicacao faz uma requisicao POST ao endpoint de token do provedor, enviando:

• grant_type=authorization_code
• code (o codigo recebido)
• redirect_uri (a mesma usada anteriormente)
• client_id e client_secret (para autenticar sua app)

A resposta JSON contem: { "access_token": "ya29.a0AfH6S...", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "1//0g..." }

Dica: Armazene o refresh_token com seguranca para renovar o access_token sem nova interacao do usuario. O access_token expira em um tempo curto (tipicamente 1 hora).

Passo 5: Usar o token de acesso para acessar recursos

Inclua o access_token no cabecalho Authorization de requisicoes a API protegida: GET /userinfo HTTP/1.1 Host: www.googleapis.com Authorization: Bearer ya29.a0AfH6S...

A API retorna os dados solicitados se o token for valido e tiver os escopos necessarios.

Erro comum a evitar: Assumir que o token nunca expira. Sempre trate erros HTTP 401 e use o refresh_token para obter um novo token automaticamente.

Checklist do que foi feito

• [ ] Aplicacao registrada com Client ID e Client Secret
• [ ] URI de redirecionamento configurada e validada
• [ ] Fluxo de autorizacao implementado com parametro state
• [ ] Codigo de autorizacao trocado por token de acesso
• [ ] Token usado em requisicoes autenticadas
• [ ] Tratamento de expiracao com refresh token

Perguntas frequentes sobre autenticacao OAuth

O que e o fluxo Authorization Code Grant?

E o fluxo mais seguro do OAuth 2.0, onde o cliente nunca ve o token de acesso diretamente no navegador. O codigo intermediario e trocado por token no servidor, protegendo contra vazamento em logs ou extensoes.

Qual a diferenca entre OAuth 2.0 e OpenID Connect?

OAuth 2.0 e um protocolo de autorizacao (permite acesso a recursos). OpenID Connect e uma camada de autenticacao construida sobre OAuth 2.0 que adiciona um token ID (JWT) para identificar o usuario.

Preciso implementar refresh token?

Sim, se sua aplicacao precisar de acesso prolongado sem nova interacao do usuario. O refresh token permite renovar o access token expirado sem reautenticacao.

Como proteger o Client Secret?

Armazene-o em variaveis de ambiente ou em um cofre de segredos (ex.: HashiCorp Vault). Nunca inclua em codigo-fonte versionado ou no front-end.

O que fazer se o token for revogado pelo usuario?

Sua aplicacao deve tratar erros de token invalido (HTTP 401) e redirecionar o usuario para reautenticacao. O refresh token tambem pode ser revogado.

E possivel usar OAuth sem servidor backend?

Para aplicacoes puramente client-side, use o fluxo Implicit Grant (depreciado) ou o mais recente Authorization Code com PKCE, que nao exige Client Secret.