# Autenticacao OAuth: guia pratico de implementacao passo a passo

> OAuth 2.0 é um protocolo de autorização que permite acesso seguro a recursos sem compartilhar credenciais. Implementar OAuth exige configurar provedor, definir escopos e gerenciar tokens de acesso e refresh. Erros comuns incluem exposição de client_secret e validação incorreta de redirect URIs. Seguir fluxo de autorização padrão garante segurança e usabilidade.

*TNT Web · Apps e Software · 21 de julho de 2026 · Eloá Pimentel*

Implementar autenticacao OAuth 2.0 exige entender o fluxo de autorizacao, escolher o provedor e configurar tokens. Este guia mostra cada etapa com exemplos concretos e erros comuns a evitar.

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.

---

Fonte (canonical): https://tntweb.com.br/apps-e-software/autenticacao-oauth-guia-pratico-de-implementacao-passo-a-passo/