Gestão de Identidades e Acessos

OAuth e gestão de Tokens

O Mercadolibre disponibiliza um mecanismo único de autenticação e autorização para acessar as APIs do ecossistema em nome de um Seller. No entanto, é necessário que a aplicação que se integra implemente seus próprios controles de autenticação e autorização sólidos, que garantam que as informações possam ser gerenciadas de forma legítima e segura.

Credenciais da aplicação

Garanta em todo momento que as credenciais da aplicação que se integra (Client_ID, Client_Secret, Access_token e refresh_token) estejam armazenadas de forma segura, criptografadas em repouso e com acesso restrito.

Proteção de tokens e credenciais

Armazenamento seguro

• Criptografia no banco de dados: criptografar os Access Token por meio de uma chave de criptografia idealmente localizada em um gerenciador de chaves (vault seguro), evitando seu armazenamento em código ou arquivos de configuração, e usando o algoritmo de criptografia AES-256 para seu armazenamento no banco de dados.
• Sanitização de logs: ter especial cuidado com os logs, garantindo que estejam sanitizados e não registrem tokens nem informações confidenciais da conexão. Evitar no código registrar em logs objetos completos que possam conter dados PII ou Segredos.
• Em headers, não em URLs: os tokens devem sempre trafegar via headers e não em query strings.

A seguir mostramos como é um armazenamento inseguro vs. um seguro, para que você possa identificar em qual situação está a sua aplicação:

No banco de dados

❌ INCORRETO – Token sem criptografia:

           TABELA: seller_tokens

  +------------------+------------------------------------------+
  | seller_id        | access_token                             |
  +------------------+------------------------------------------+
  | 12345            | APP-1234567890-abcdef-123456...          |
  | 67890            | APP-0987654321-fedcba-987654...          |
  +------------------+------------------------------------------+

Problema: Se hackearem seu banco de dados, terão todos os tokens em texto simples. Podem acessar TODAS as contas dos seus sellers.

✅ CORRETO – Token criptografado com AES-256:

           TABELA: seller_tokens

  +------------------+------------------------------------------+
  | seller_id        | access_token_encrypted                   |
  +------------------+------------------------------------------+
  | 12345            | gAAAAABl2K8xQ7N...[dados criptografados] |
  | 67890            | gAAAAABl2K9yR8M...[dados criptografados] |
  +------------------+------------------------------------------+

A chave de criptografia está em um gerenciador de segredos (AWS Secrets Manager, HashiCorp Vault, etc.),
NÃO no código nem no mesmo banco de dados.

Resultado: Mesmo que hackeem o BD, os tokens são inúteis sem a chave.

No código

❌ INCORRETO - Credenciais hardcodeadas:

# config.py
CLIENT_ID = "1234567890"
CLIENT_SECRET = "AbCdEfGhIjKlMnOpQrStUvWxYz"  # PERIGO!

Problemas:
- Qualquer pessoa com acesso ao código vê as credenciais
- Se subir para o GitHub, ficam expostas publicamente
- Se um desenvolvedor sair, leva as credenciais consigo

✅ CORRETO - Credenciais em variáveis de ambiente:

# .env (este arquivo NUNCA é enviado ao repositório)
CLIENT_ID=1234567890
CLIENT_SECRET=AbCdEfGhIjKlMnOpQrStUvWxYz

# config.py (este sim é enviado)
import os
CLIENT_ID = os.environ.get("CLIENT_ID")
CLIENT_SECRET = os.environ.get("CLIENT_SECRET")

# .gitignore (garante que .env não seja enviado)
.env
.env.local
.env.*.local

Nos logs

❌ INCORRETO - Token visível nos logs:

[2026-01-15 10:30:45] INFO:  Conectando com seller 12345
[2026-01-15 10:30:45] DEBUG: Token: APP-1234567890-abcdef-123456789...
[2026-01-15 10:30:45] INFO:  Obtendo pedidos...
[2026-01-15 10:30:46] DEBUG: Headers: {"Authorization": "Bearer APP-1234567890..."}

Problema: Qualquer pessoa com acesso aos logs pode ver os tokens.

✅ CORRETO - Token sanitizado nos logs:

[2026-01-15 10:30:45] INFO:  Conectando com seller 12345
[2026-01-15 10:30:45] DEBUG: Token: [REDACTED]
[2026-01-15 10:30:45] INFO:  Obtendo pedidos...
[2026-01-15 10:30:46] DEBUG: Headers: {"Authorization": "Bearer [REDACTED]"}

Ou melhor: Não registrar tokens nem headers de autorização nos logs.

Em trânsito / transmissão

❌ INCORRETO - Token na URL (query string):

GET https://api.mercadolibre.com/orders?access_token=APP-1234567890...

Problemas:
- Fica nos logs do servidor
- Fica no histórico do navegador
- Pode ficar nos logs de proxies intermediários
- Visível na barra de endereços

✅ CORRETO - Token no header:

GET https://api.mercadolibre.com/orders
Headers:
  Authorization: Bearer APP-1234567890...

Vantagens:
- Não fica nas URLs
- Não fica no histórico
- Mais difícil de vazar acidentalmente

Como poderíamos verificar?

Buscar credenciais hardcodeadas no seu código:

# Buscar client_secret hardcodeado
grep -rn "client_secret.*=.*['\"]" --include="*.py" --include="*.js" --include="*.ts" .

# Buscar padrões de tokens do MercadoLibre
grep -rn "APP-[0-9]" --include="*.py" --include="*.js" --include="*.ts" .

Verificar que .env está no .gitignore:

cat .gitignore | grep ".env"

Revisar os logs em busca de tokens ou informações confidenciais:

grep -rn "APP-" logs/  # Ajustar o caminho conforme seu projeto
grep -rn "access_token" logs/

Renovação e revogação de tokens

Por isso é necessário que:

• Implementar refresh automático revogando antes que o access_token expire.
• Tratar erros de refresh: se o refresh falhar, deve-se solicitar nova re-autorização ao seller.
• Armazenar de forma segura o novo refresh token gerado a cada revogação.
• Deve-se eliminar tokens armazenados caso o seller desconecte seu app da sua conta.
• Em caso de suspeita de comprometimento dos tokens, deve-se revogar tokens via API e solicitar re-autorização.
• Caso um funcionário deixe a empresa, deve-se auditar e rotacionar as credenciais que ele pudesse conhecer.

A seguir mostramos como é um tratamento incorreto e correto de tokens:

Revogação de tokens

❌ INCORRETO - Não tratar a expiração:

1. Você obtém o access_token
2. Você o salva
3. Você o usa para sempre até que falhe
4. Quando falha, exibe erro ao usuário

Problema: O usuário experimenta erros inesperados.

✅ CORRETO - Refresh automático:

1. Você obtém o access_token (válido por 6 horas)
2. Salva o access_token E o refresh_token
3. Antes de expirar (ex: às 5 horas), faz o refresh automaticamente
4. Salva o novo access_token e refresh_token
5. O usuário nunca vê um erro de token expirado

A seguir um exemplo visual:

Cenários de revogação

Cenário	Ação necessária
Seller desconecta do seu app	Eliminar todos os tokens armazenados desse seller
Suspeita de comprometimento	Revogar tokens via API e solicitar re-autorização
Funcionário deixa a empresa	Auditar e rotacionar todas as credenciais que ele conhecia
Erro de refresh	Solicitar re-autorização ao seller

Referências

• OWASP Password Storage: como armazenar senhas de forma segura.
• OWASP Secrets Management: guia completo de gestão de segredos e credenciais.
• CWE-312: documentação técnica do problema exato (armazenar tokens sem criptografia). Útil para entender o risco.
• OWASP TOP 10 - A02:2021 Cryptographic Failures: referência de alto nível sobre falhas criptográficas.

Glossário

Termo	Significado
Access token	Credencial temporária que permite ao seu app agir em nome do seller
Refresh Token	Token de longa duração usado para obter novos access tokens sem solicitar autorização ao seller novamente
Criptografia em repouso	Criptografar dados quando estão armazenados (no banco de dados ou disco), não apenas quando trafegam pela rede
Texto simples	Dados sem criptografia, legíveis por qualquer pessoa que acesse
Hardcodear	Escrever credenciais diretamente no código-fonte (má prática)
Variáveis de ambiente	Forma de passar configurações sensíveis ao programa sem escrevê-las no código
Secrets Manager	Serviço especializado para armazenar e gerenciar credenciais de forma segura (ex: HashiCorp Vault, AWS Secrets Manager)
Rotação de credenciais	Trocar tokens/senhas periodicamente para limitar o impacto caso tenham sido comprometidos
.env	Arquivo onde são armazenadas variáveis de ambiente localmente. Nunca deve ser enviado ao repositório
.gitignore	Arquivo que indica ao Git quais arquivos NÃO devem ser enviados ao repositório (como .env)

Próximo: Autenticação segura.