Rede, allowlist e mTLS¶

Para: Dev · Adm — Conferido em 2026-10-18.

Esta página mostra cada camada de proteção entre o seu conector e a API do Dracma: o que está ligado hoje, o que é opcional e o que você vê quando uma camada recusa a chamada. Ela existe para você não esperar uma proteção que não está ativa nem montar um go-live em torno de uma que não existe.

O que é¶

Uma chamada à API passa por até quatro camadas:

A segurança da chamada hoje se apoia em TLS e na assinatura HMAC com segredo por operação. Veja Autenticação HMAC.

Quando usar¶

Leia antes de desenhar a rede do seu conector, antes de preencher o formulário de IPs e antes do go-live. O checklist só cobra o que está ativo.

Como funciona¶

TLS¶

• Todo host do Dracma fala HTTPS, com certificado público emitido e renovado automaticamente. A instância de produção só aceita certificado público.
• O ingress atende HTTP/1.1 e HTTP/2. Use TLS 1.2 ou superior e valide o certificado do servidor: nunca desligue a verificação no cliente.
• O IP de origem de uma chamada vem do socket da conexão. Um X-Forwarded-For enviado por você não vale. O cabeçalho só é considerado quando o salto anterior é o proxy de borda do próprio Dracma.

mTLS¶

O mTLS é uma opção de instância: se estiver ligado na instância em que você integra, a borda recusa a conexão TLS de quem não apresenta um certificado assinado pela autoridade configurada para aquela instância. A confiança é de uma autoridade por instância, não por operação, e a API não cruza a chave com o certificado. Hoje o padrão é desligado. O Dracma avisa no onboarding se a sua instância o exigir.

Como o Dracma não emite certificado de cliente, não existe prazo de validade nem rotina de renovação de certificado do lado da API: a regra de "certificado de até 90 dias" não se aplica.

Um certificado de cliente recusado na borda não gera problem+json: a conexão falha no handshake TLS.

Lista de IPs de origem¶

A lista de IPs da operação é opcional e altamente recomendada. Sem ela, qualquer origem com a chave e a assinatura válidas consegue chamar a API; isso deixa o teste livre, mas em Real deixa a assinatura como única barreira.

• Lista vazia: sem restrição, em Teste e em Real.
• Com ao menos um IP, a API responde 403 ip_not_allowed quando a chave é válida e a origem não está na lista da operação. A resposta não lista os IPs permitidos. Isso só aparece a quem prova ter o segredo.
• O IP considerado é o de origem visto pelo Dracma, e não um cabeçalho que o seu conector envie. Atrás de proxy, NAT ou nuvem, use o IP público de saída.
• O Dracma registra por 30 dias os IPs de origem das chamadas autenticadas e, enquanto a operação não tem IP liberado, o painel sugere Bloquear para estes IPs; nada é aplicado sem a sua confirmação; confirmando, vale na hora (só aperta o acesso, com confirmação recente de identidade), e dá para desfazer removendo os IPs (IPs do conector).

Recomendação: em produção, cadastre todos os IPs de saída do conector (cluster, NAT redundante, recuperação de desastre), em IPv4 e IPv6, e só depois de confirmar que são fixos. A lista aceita rede no mínimo /24 (IPv4) e /56 (IPv6) e um IP solto vira /32 ou /128. Incluir um IP exige aprovação de outra pessoa e 24 h de espera; remover é imediato. Veja IPs do conector.

Painel e login abertos à internet¶

O painel (painel.) e o login (auth.) são acessíveis pela internet: não há trava de IP para pessoas. A barreira é:

1. login com dois fatores, com sessão de 7 dias (90 com dispositivo confiável);
2. autorização por papel, negando tudo o que não foi concedido;
3. confirmação com fator forte nos últimos 5 minutos para ações sensíveis;
4. aprovação de outra pessoa nas mudanças que pedem 4-eyes;
5. trilha de auditoria encadeada.

A API do login nunca é publicada: só as páginas e os endereços OIDC. Veja Conta, login e dispositivos.

Exemplos¶

Hardening do seu lado (opcional, recomendado):

• Deixe só o usuário do sistema do conector alcançar o host do Dracma (regra de saída por usuário no firewall). Assim, outro processo comprometido não usa a credencial.
• Não filtre a rota do webhook pelo IP de origem: o Dracma não publica a lista de IPs de saída ("Não disponível"). A defesa da rota é a assinatura mais o fetch-back. Veja Seu endpoint.
• Sincronize o relógio por NTP em pelo menos três fontes e alerte quando |server_time - agora| > 5 s em GET /v1/ping.

Erros e casos de borda¶

Veja também¶

• Autenticação HMAC
• Segredos e vazamento
• IPs do conector
• Ambientes, tipos de operação e hosts