OAuth 2.0: fluxos e casos de uso

1. Fundamentos do OAuth 2.0

OAuth 2.0 é um protocolo de autorização que permite que aplicações obtenham acesso limitado a recursos de um usuário sem expor suas credenciais. Para entender seu funcionamento, é essencial conhecer seus quatro papéis principais:

  • Resource Owner: geralmente o usuário final que possui os dados
  • Client: a aplicação que deseja acessar os recursos
  • Authorization Server: servidor que emite tokens após autenticação
  • Resource Server: servidor que hospeda os recursos protegidos

O fluxo básico envolve a emissão de um token de acesso (access token) que contém escopos (scopes) definindo quais ações o cliente pode realizar. É crucial diferenciar autenticação (verificar quem é o usuário) de autorização (determinar o que ele pode fazer). OAuth 2.0 lida exclusivamente com autorização.

2. Authorization Code Grant (Fluxo com código de autorização)

Este é o fluxo mais seguro e recomendado para a maioria dos cenários. Funciona em três etapas principais:

  1. O cliente redireciona o usuário para o Authorization Server
  2. Após autenticação, o servidor retorna um código de autorização
  3. O cliente troca esse código por um access token

Exemplo de requisição de código de autorização:

GET /authorize?response_type=code
    &client_id=app-cliente-123
    &redirect_uri=https://minhaapp.com/callback
    &scope=read:profile write:posts
    &state=abc123xyz
    &code_challenge=E9Melho... (SHA256)
    &code_challenge_method=S256
Host: auth.exemplo.com

Exemplo de troca do código por token:

POST /token HTTP/1.1
Host: auth.exemplo.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=8xJO0...código_recebido
&redirect_uri=https://minhaapp.com/callback
&client_id=app-cliente-123
&client_secret=segredo-do-cliente
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

PKCE (Proof Key for Code Exchange) é essencial para clientes públicos (SPAs, apps mobile). Ele protege contra ataques de interceptação do código de autorização, gerando um code_verifier aleatório e seu code_challenge correspondente.

Casos de uso: aplicações web server-side (Node.js, Django, Rails) e aplicativos mobile nativos (iOS, Android).

3. Implicit Grant (Fluxo implícito) — por que evitar?

Neste fluxo, o token de acesso é retornado diretamente na URL de redirect após a autenticação do usuário:

https://minhaapp.com/callback#access_token=TOKEN_AQUI&token_type=Bearer&expires_in=3600

Riscos de segurança:
- Token exposto no histórico do navegador
- Logs de servidores proxy e web
- Possibilidade de vazamento via referrer headers
- Sem possibilidade de usar refresh tokens

Recomendação: Substitua o Implicit Grant pelo Authorization Code com PKCE. O fluxo com PKCE oferece a mesma simplicidade para SPAs, mas com segurança muito superior.

4. Client Credentials Grant (Fluxo de credenciais de cliente)

Este fluxo é usado para comunicação máquina-a-máquina, sem envolvimento de usuário. O cliente se autentica diretamente com suas próprias credenciais:

POST /token HTTP/1.1
Host: auth.exemplo.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=servico-interno-456
&client_secret=segredo-do-servico
&scope=read:database write:queue

Casos de uso:
- APIs internas entre microsserviços
- Jobs em lote que processam dados automaticamente
- Integrações servidor-a-servidor (ex: sincronização de dados)

Cuidados: Armazene o client_secret em cofres de segredos (HashiCorp Vault, AWS Secrets Manager) e nunca em código-fonte.

5. Resource Owner Password Credentials Grant (Fluxo de senha)

Neste fluxo, o usuário fornece login e senha diretamente ao cliente, que os envia ao Authorization Server:

POST /token HTTP/1.1
Host: auth.exemplo.com
Content-Type: application/x-www-form-urlencoded

grant_type=password
&username=usuario@exemplo.com
&password=senha123
&client_id=app-legado-789
&client_secret=segredo-legado

Riscos de segurança:
- Cliente armazena credenciais do usuário temporariamente
- Credenciais trafegam em texto plano (mesmo com HTTPS, o risco existe)
- Usuário precisa confiar totalmente no cliente

Casos de uso restritos: Apenas para migração de sistemas legados ou cenários de alta confiança (aplicação proprietária com servidor próprio). A recomendação atual é evitar este fluxo sempre que possível.

6. Refresh Token Grant (Renovação de tokens)

Access tokens têm vida curta (geralmente 15-60 minutos). Refresh tokens permitem obter novos access tokens sem exigir nova autenticação do usuário:

POST /token HTTP/1.1
Host: auth.exemplo.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=rt_abc123xyz
&client_id=app-cliente-123
&client_secret=segredo-do-cliente

Estratégias seguras:
- Rotação de refresh tokens: cada uso gera um novo refresh token e invalida o anterior
- Revogação: implemente endpoints para revogar tokens quando necessário (logout, suspeita de vazamento)
- Tempo de vida limitado: refresh tokens devem expirar (dias ou semanas, não permanentemente)

Casos de uso: Sessões longas em aplicativos mobile, SPAs que precisam manter o usuário logado, e aplicações que realizam operações assíncronas.

7. Boas práticas de segurança no OAuth 2.0

Validação de redirect URIs

Sempre valide as URIs de redirecionamento no servidor de autorização. Use URIs exatas, sem curingas:

// RUIM - permite qualquer subdomínio
redirect_uri=https://*.minhaapp.com/callback

// BOM - URI exata
redirect_uri=https://minhaapp.com/callback

Proteção contra CSRF com state parameter

Sempre use e valide o parâmetro state para evitar ataques de falsificação de requisição entre sites:

// Geração do state (no cliente)
const state = crypto.randomBytes(16).toString('hex');
session.state = state;

// Redirecionamento para autorização
GET /authorize?response_type=code&state=...session.state...&...

// Validação no callback
if (req.query.state !== session.state) {
    throw new Error('Possível ataque CSRF detectado');
}

HTTPS obrigatório

Todo o tráfego OAuth 2.0 deve usar HTTPS. Tokens e códigos de autorização nunca devem trafegar em texto plano.

Escopos mínimos necessários

Solicite apenas os escopos realmente necessários para a funcionalidade:

// RUIM - escopos excessivos
scope=read:all write:all delete:all admin

// BOM - escopos mínimos
scope=read:profile write:posts

Auditoria e monitoramento

Registre todas as concessões de tokens, incluindo:
- Qual cliente solicitou
- Quais escopos foram concedidos
- IP de origem
- Timestamp
- Sucesso ou falha da operação

Monitore padrões suspeitos como múltiplas trocas de código em curto período ou refresh tokens sendo usados de locais geográficos distintos.

Referências