Gestão de segredos (secrets management) é a prática de armazenar, distribuir, rotacionar e revogar com segurança credenciais como API keys, senhas de banco de dados, tokens OAuth e chaves de criptografia. Se sua aplicação [consome a API de um provedor de IA](/artigo/como-consumir-api-anthropic-python), de um banco de dados na nuvem ou de qualquer serviço externo, ela depende de pelo menos um segredo, e a forma como você guarda esse segredo determina se um vazamento vira um incidente controlável ou uma conta invadida com a fatura explodindo da noite para o dia.
O que conta como um segredo
Qualquer credencial que, se exposta, permite a alguém agir como se fosse você ou seu sistema é um segredo. Isso inclui:
- API keys de serviços de terceiros (provedores de IA, pagamento, e-mail transacional)
- Tokens de acesso OAuth 2.0 e refresh tokens
- Senhas e strings de conexão de banco de dados
- Chaves privadas de criptografia e certificados TLS
- Segredos de assinatura de webhook (usados para validar que uma requisição realmente veio do remetente esperado)
- Credenciais de contas de serviço em nuvem (AWS, GCP, Azure)
O fio condutor entre todos esses exemplos: quem possui o segredo tem o mesmo poder que o sistema legítimo que o emitiu. Por isso o objetivo da gestão de segredos não é só "esconder" a credencial, é controlar quem pode acessá-la, por quanto tempo ela vale e como substituí-la rapidamente se vazar. Para entender os fundamentos de como esses valores são protegidos matematicamente em trânsito e em repouso, veja nosso guia de [criptografia de dados](/artigo/criptografia-de-dados-o-que-e-como-funciona).
Por que colocar o segredo direto no código é o primeiro erro
O padrão Twelve-Factor App, referência amplamente adotada para aplicações que rodam na nuvem, define como regra separar configuração (incluindo credenciais) do código-fonte. A recomendação do próprio 12factor.net é guardar configuração em variáveis de ambiente porque elas são fáceis de trocar entre implantações sem alterar código e, diferentemente de arquivos de configuração, dificilmente acabam commitadas por acidente no repositório.
# Errado: a chave fica gravada no histórico do Git para sempre,
# mesmo que você a remova em um commit futuro.
API_KEY = "sk-live-4f9a2c8e1b7d3f6a9c0e5b2d8f1a4c7e"
# Certo: a chave vem do ambiente de execução, nunca do código.
import os
API_KEY = os.environ["API_KEY"]
if not API_KEY:
raise RuntimeError("API_KEY não configurada no ambiente")Remover a linha com a chave em um commit novo não apaga o segredo do histórico do Git. Uma chave commitada por engano deve ser tratada como comprometida e revogada no provedor — reescrever o histórico é um passo adicional, não um substituto para a revogação.
Variável de ambiente é o mínimo viável, não o ideal
Usar variáveis de ambiente (muitas vezes carregadas de um arquivo .env em desenvolvimento) já resolve o problema de deixar credenciais soltas no código-fonte. Mas isso é apenas o primeiro degrau. Variáveis de ambiente, por padrão, não têm rotação automática, não geram log de quem acessou o valor, ficam visíveis em texto puro para qualquer processo com acesso ao ambiente da aplicação (e frequentemente aparecem inteiras em relatórios de erro ou ferramentas de monitoramento mal configuradas) e não diferenciam automaticamente segredo de desenvolvimento e de produção — é comum a mesma chave circular entre ambientes só porque está no mesmo arquivo .env copiado de máquina em máquina.
- Nunca commitar o arquivo .env — ele deve estar no .gitignore desde o primeiro commit do projeto
- Manter um .env.example sem valores reais, apenas com os nomes das variáveis esperadas
- Usar um valor diferente por ambiente (desenvolvimento, homologação, produção) — nunca reaproveitar a chave de produção localmente
Gerenciadores de segredos dedicados
Para além de variáveis de ambiente, existem serviços construídos especificamente para armazenar, controlar acesso e rotacionar segredos — entre os mais usados estão AWS Secrets Manager, Google Cloud Secret Manager, Azure Key Vault e o HashiCorp Vault (este último com opção self-hosted ou gerenciada). Eles resolvem o que uma variável de ambiente sozinha não resolve: quem acessou o segredo, quando, e com que permissão.
import boto3
import json
client = boto3.client("secretsmanager", region_name="us-east-1")
response = client.get_secret_value(SecretId="prod/minha-api/chave")
segredo = json.loads(response["SecretString"])
api_key = segredo["API_KEY"]O HashiCorp Vault vai além do armazenamento estático e oferece segredos dinâmicos: em vez de guardar uma senha de banco de dados fixa, o Vault gera uma credencial nova, exclusiva para aquela requisição, com um TTL (tempo de vida) configurável, e a revoga automaticamente ao expirar. Isso reduz a janela de exploração se uma credencial vazar — ela deixa de existir antes que alguém consiga reutilizá-la.
Rotação de segredos: por que e com que frequência
Rotacionar um segredo significa substituí-lo por um novo valor periodicamente, mesmo sem evidência de vazamento — o objetivo é limitar quanto tempo uma credencial furtada continua funcionando caso já tenha sido comprometida sem que ninguém tenha percebido. O AWS Secrets Manager, por exemplo, automatiza esse processo chamando uma função Lambda segundo um cronograma definido pelo usuário; a rotação segue etapas padronizadas de criação, configuração, teste e finalização do novo segredo antes de descartar o antigo.
- Segredos de altíssimo privilégio (acesso root, chaves-mestre): rotação mais frequente e revisão manual
- Credenciais de serviço usadas por aplicações (API keys de terceiros, senhas de banco): rotação automatizada e programada
- Qualquer segredo exposto acidentalmente (log, commit, print de tela): rotação imediata, fora do cronograma normal
Rotação e controle de uso andam juntos: um segredo rotacionado com frequência perde valor para quem o rouba, e um segredo protegido por [limites de requisição bem configurados](/artigo/rate-limiting-apis-guia-pratico) reduz o estrago que alguém consegue fazer mesmo antes da rotação acontecer.
Como evitar vazar segredos no controle de versão
A causa mais comum de vazamento de segredo não é um ataque sofisticado — é um commit. O GitHub oferece push protection, um recurso de secret scanning que analisa o conteúdo antes mesmo de aceitar o push: se detecta um padrão de credencial reconhecido, bloqueia o envio e explica o motivo, obrigando quem está commitando a remover o segredo antes de tentar novamente.
Push protection reduz o risco, mas não substitui hooks de pre-commit locais (como git-secrets ou gitleaks) nem a revisão de código — ela é uma última barreira, não a única.
Princípio do menor privilégio aplicado a segredos
O OWASP Secrets Management Cheat Sheet recomenda controle de acesso granular no nível de cada segredo individual, aplicando o princípio do menor privilégio a todo usuário e serviço que precisa tocar no sistema de gestão de segredos — e defende a centralização do armazenamento, provisionamento, auditoria e rotação como forma de reduzir a superfície de vazamento. Na prática isso significa: um serviço que só precisa ler pedidos de um banco de dados não deveria ter a credencial de escrita, e uma chave de API usada apenas por um microsserviço específico não deveria estar acessível a todos os outros serviços do sistema.
Erros comuns que anulam qualquer estratégia de gestão de segredos
- Reaproveitar a mesma chave de API entre ambiente de desenvolvimento, homologação e produção
- Deixar um segredo sem data de expiração ou rotação prevista
- Logar o valor completo de um segredo em mensagens de erro ou ferramentas de observabilidade
- Colocar uma chave de API sensível em código que roda no navegador (frontend) — qualquer pessoa pode abrir o DevTools e ler o valor
- Compartilhar segredos de produção por chat ou e-mail em vez de por um cofre com controle de acesso
Se uma chave precisa ser usada em código que roda no navegador, ela nunca deveria ter permissão equivalente a uma chave de backend. A solução correta é um proxy no servidor que guarda o segredo real e expõe ao frontend apenas o necessário, com escopo limitado.
Checklist prático para começar
- Nenhum segredo real está commitado no repositório (nem no histórico)
- .env está no .gitignore e existe um .env.example sem valores reais
- Cada ambiente (dev, homologação, produção) usa credenciais diferentes
- Segredos de produção estão em um secrets manager, não soltos em variável de ambiente de um servidor
- Existe um plano de rotação, mesmo que manual, para as credenciais mais sensíveis
- Push protection ou uma ferramenta equivalente de secret scanning está ativa no repositório
Nenhuma dessas medidas exige reescrever a aplicação do zero — a maior parte é configuração de processo e pode ser adotada de forma incremental, começando pelo item mais barato: tirar qualquer segredo que hoje está hardcoded no código.
Perguntas frequentes
É qualquer credencial que, se exposta, permite que outra pessoa ou sistema aja com a mesma autoridade do dono legítimo — API keys, senhas de banco de dados, tokens OAuth, chaves de criptografia e segredos de assinatura de webhook são exemplos comuns.
