Implementando Controles de Segurança de Chaves de API

Quando Usar

• Projetando a geração segura de chaves de API com entropia suficiente e prefixos identificáveis para detecção de vazamentos.
• Implementando o hashing de chaves de API no lado do servidor (nunca armazenando chaves em texto puro) com SHA-256 ou bcrypt.
• Construindo fluxos de rotação de chaves que permitem a substituição de chaves sem interrupção para consumidores de API.
• Configurando escopos por chave para limitar cada chave de API a endpoints específicos, intervalos de IP e limites de taxa.
• Configurando monitoramento automatizado para vazamento de chaves de API em repositórios GitHub, logs e código do lado do cliente.

Não use chaves de API como o único mecanismo de autenticação para aplicativos voltados para o usuário. As chaves de API são mais adequadas para comunicação servidor a servidor e acesso de desenvolvedor.

Pré-requisitos

• Gerador de números aleatórios seguro (os.urandom, módulo secrets) para geração de chaves.
• Banco de dados com criptografia adequada em repouso para armazenar chaves de API com hash.
• Redis ou armazenamento similar para cache de chave para metadados e limitação de taxa.
• Ferramentas de varredura de segredos (varredura de segredos do GitHub, truffleHog, gitleaks).
• Infraestrutura de monitoramento e alerta para anomalias de uso de chaves.

Fluxo de Trabalho

Etapa 1: Geração Segura de Chaves de API

import secrets
import hashlib
import hmac
import time
import json
from datetime import datetime, timedelta

class APIKeyManager:
    """Gerencia o ciclo de vida seguro das chaves de API: geração, armazenamento, validação, rotação."""

    # Formato da chave: prefixo_aleatório_base64 (ex: sk_live_a1b2c3d4e5f6...)
    # O prefixo identifica o tipo de chave e o ambiente para detecção de vazamentos
    KEY_PREFIXES = {
        "live_secret": "sk_live_",
        "test_secret": "sk_test_",
        "live_public": "pk_live_",
        "test_public": "pk_test_",
    }

    def __init__(self, db_connection, redis_connection):
        self.db = db_connection
        self.redis = redis_connection

    def generate_key(self, key_type="live_secret", owner_id=None, scopes=None,
                     rate_limit=None, ip_allowlist=None, expires_days=365):
        """Gera uma nova chave de API com metadados."""
        prefix = self.KEY_PREFIXES.get(key_type, "sk_live_")

        # Gera 32 bytes (256 bits) de aleatoriedade
        random_bytes = secrets.token_bytes(32)
        key_body = secrets.token_urlsafe(32)  # Codificado em Base64url

        # Chave de API completa que o cliente recebe (mostrada apenas uma vez)
        full_key = f"{prefix}{key_body}"

        # Gera o hash da chave para armazenamento (nunca armazene a chave bruta)
        key_hash = hashlib.sha256(full_key.encode()).hexdigest()

        # Cria um ID de chave curto para referência (primeiros 8 caracteres)
        key_id = f"{prefix}{key_body[:8]}..."

        # Armazena a chave com hash e metadados
        key_metadata = {
            "key_hash": key_hash,
            "key_id": key_id,
            "key_type": key_type,
            "owner_id": owner_id,
            "scopes": scopes or ["read"],
            "rate_limit": rate_limit or {"requests": 1000, "window": 3600},
            "ip_allowlist": ip_allowlist or [],
            "created_at": datetime.utcnow().isoformat(),
            "expires_at": (datetime.utcnow() + timedelta(days=expires_days)).isoformat(),
            "last_used": None,
            "is_active": True,
            "usage_count": 0,
        }

        # Armazena no banco de dados
        self.db.execute(
            "INSERT INTO api_keys (key_hash, key_id, metadata) VALUES (?, ?, ?)",
            (key_hash, key_id, json.dumps(key_metadata))
        )

        # Armazena em cache no Redis para validação rápida
        self.redis.setex(
            f"apikey:{key_hash}",
            86400,  # TTL de cache de 24 horas
            json.dumps(key_metadata)
        )

        return {
            "api_key": full_key,       # Mostra ao usuário APENAS UMA VEZ
            "key_id": key_id,          # Para referência/gerenciamento
            "scopes": key_metadata["scopes"],
            "expires_at": key_metadata["expires_at"],
        }

    def validate_key(self, api_key):
        """Valida uma chave de API e retorna seus metadados."""
        key_hash = hashlib.sha256(api_key.encode()).hexdigest()

        # Verifica o cache do Redis primeiro
        cached = self.redis.get(f"apikey:{key_hash}")
        if cached:
            metadata = json.loads(cached)
        else:
            # Volta para o banco de dados
            row = self.db.execute(
                "SELECT metadata FROM api_keys WHERE key_hash = ?",
                (key_hash,)
            ).fetchone()
            if not row:
                return None, "invalid_key"
            metadata = json.loads(row[0])

…