pg_hba.conf & Autenticação

pg_hba.conf (host-based authentication) decide quais clientes podem se conectar, de quais endereços, para quais bancos de dados, usando qual método de autenticação. É seu primeiro firewall de rede e de identidade.

Receita

# TYPE  DATABASE  USER      ADDRESS         METHOD
local   all       postgres                  peer
host    all       all       127.0.0.1/32    scram-sha-256
host    all       all       ::1/128         scram-sha-256
hostssl myapp     app_user  10.0.0.0/8      scram-sha-256

# Valida a sintaxe e recarrega
sudo -u postgres pg_ctl reload -D /var/lib/postgresql/18/main

Quando usar isso: Sempre que você abrir o Postgres além do localhost, adicionar uma role de aplicativo ou rotacionar métodos de autenticação.

Exemplo de Trabalho

# Rejeita por padrão - permite apenas explícitos
host    all       all       0.0.0.0/0       reject
 
# Sub-rede da camada de aplicativo
hostssl myapp_prod  app_rw   10.10.1.0/24   scram-sha-256
hostssl myapp_prod  app_ro   10.10.2.0/24   scram-sha-256
 
# Replicação da sub-rede de standby
host    replication  replicator  10.10.3.10/32  scram-sha-256
 
# Socket de administração local
local   all       postgres                    peer

-- Cria roles de login com senhas (armazenadas como verificador SCRAM)
CREATE ROLE app_rw LOGIN PASSWORD 'rotate-me-via-vault';
CREATE ROLE app_ro LOGIN PASSWORD 'rotate-me-via-vault';
GRANT CONNECT ON DATABASE myapp_prod TO app_rw, app_ro;

O que isso demonstra:

hostssl requer TLS - use para conexões de aplicativos remotas
Roles e sub-redes separadas para leitura/escrita vs. somente leitura
reject como regra geral após regras específicas (a ordem importa - a primeira correspondência vence)
replication é um pseudo-banco de dados para conexões de replicação física

Análise Profunda

Campos da Regra

Campo	Valores	Significado
TYPE	`local`, `host`, `hostssl`, `hostnossl`	Socket vs TCP; Requisito de TLS
DATABASE	nome, `all`, `sameuser`, `replication`	Banco de dados de destino
USER	nome, `all`, `+group`	Prefixo `+` corresponde a roles de grupo
ADDRESS	CIDR, hostname	Omitir para `local`
METHOD	`scram-sha-256`, `cert`, `peer`, `reject`	Como a identidade é verificada

Métodos de Autenticação (Produção)

# Preferido para autenticação por senha (PG 10+)
password_encryption = scram-sha-256   # em postgresql.conf
 
# Autenticação por certificado (mTLS)
hostssl all app_user 0.0.0.0/0 cert clientcert=verify-full

md5 é legado - migre para scram-sha-256.
trust e password (texto claro) são falhas de auditoria - nunca em redes.
peer mapeia o usuário do sistema operacional para o usuário do banco de dados em conexões de socket Unix - bom para administração local do postgres.

Regras de Rede de Menor Privilégio

Um CIDR por zona de segurança (aplicativo, batch, BI, bastion de administração).
Estreite DATABASE e USER - evite all all em CIDRs amplos.
Use listeners separados: listen_addresses apenas em NICs internas, quando possível.

Comportamento de Recarga

Alterações em pg_hba.conf são aplicadas com SIGHUP reload - sem reinicialização.
Erros de sintaxe na recarga mantêm o arquivo antigo ativo - teste com a view pg_hba_file_rules (PG 12+):

SELECT line_number, error FROM pg_hba_file_rules WHERE error IS NOT NULL;

Armadilhas

Ordem de regras surpreendente - A primeira linha correspondente vence; um host all all 0.0.0.0/0 scram amplo antes de um reject nunca atinge o reject. Correção: Regras mais específicas primeiro, reject por último.
Esqueceu hostssl em redes públicas - Senha sem TLS pode ser interceptada. Correção: hostssl + certificado de servidor válido, ou apenas VPN/link privado.
Autenticação peer via TCP - peer só funciona para conexões de socket local. Correção: Use scram-sha-256 ou cert para entradas host.
Regra de replicação ausente - O standby não consegue se conectar com regras apenas de aplicativo. Correção: host replication replicator <standby-ip>/32 scram-sha-256.
IPv6 negligenciado - ::1 aberto com trust enquanto o IPv4 está bloqueado. Correção: Espelhe as políticas para ::1/128 ou desative o listener IPv6.

Alternativas

Alternativa	Use Quando	Não Use Quando
Autenticação de cliente `cert`	Malha de serviço mTLS, sem senhas compartilhadas	Clientes não conseguem gerenciar rotação de certificados
Grupos de segurança RDS	ACL de rede gerenciada na nuvem	Bare metal auto-hospedado
Túnel SSH para localhost	Acesso de administração de emergência	Caminho de estado estável do aplicativo de produção

FAQs

Onde está o pg_hba.conf?

SHOW hba_file; ou pg_config --hbafile em algumas instalações. Geralmente ao lado de postgresql.conf em PGDATA.

Por que a conexão é rejeitada sem dica?

Verifique o log do servidor após log_connections = on. Causas comuns: nenhuma regra correspondente, erro de digitação em pg_hba.conf, ou SSL necessário, mas o cliente usa plano.

scram-sha-256 vs md5?

SCRAM armazena verificadores com salt e não envia hashes de senha reutilizáveis na rede. Migre roles com ALTER ROLE ... PASSWORD 'new'.

Posso usar LDAP?

Sim, via métodos ldap ou radius - comum em empresas. Ainda assim, mantenha regras de CIDR estreitas.

O reload descarta conexões?

Não. Sessões existentes mantêm seu contexto de autenticação original; novas conexões usam o arquivo atualizado.

Relacionados

Noções Básicas de Instalação - instale antes de reforçar a autenticação
Noções Básicas de Roles - roles referenciadas nas regras hba
Autenticação SCRAM - profundidade de armazenamento de senha

Versões do Stack: Esta página foi escrita para PostgreSQL 18.4 (estável 18, manutenção 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x, e PostGIS 3.5+.

pg_hba.conf & Autenticação

Receita

# TYPE  DATABASE  USER      ADDRESS         METHOD
local   all       postgres                  peer
host    all       all       127.0.0.1/32    scram-sha-256
host    all       all       ::1/128         scram-sha-256
hostssl myapp     app_user  10.0.0.0/8      scram-sha-256

# Valida a sintaxe e recarrega
sudo -u postgres pg_ctl reload -D /var/lib/postgresql/18/main

Quando usar isso: Sempre que você abrir o Postgres além do localhost, adicionar uma role de aplicativo ou rotacionar métodos de autenticação.

Exemplo de Trabalho

# Rejeita por padrão - permite apenas explícitos
host    all       all       0.0.0.0/0       reject
 
# Sub-rede da camada de aplicativo
hostssl myapp_prod  app_rw   10.10.1.0/24   scram-sha-256
hostssl myapp_prod  app_ro   10.10.2.0/24   scram-sha-256
 
# Replicação da sub-rede de standby
host    replication  replicator  10.10.3.10/32  scram-sha-256
 
# Socket de administração local
local   all       postgres                    peer

-- Cria roles de login com senhas (armazenadas como verificador SCRAM)
CREATE ROLE app_rw LOGIN PASSWORD 'rotate-me-via-vault';
CREATE ROLE app_ro LOGIN PASSWORD 'rotate-me-via-vault';
GRANT CONNECT ON DATABASE myapp_prod TO app_rw, app_ro;

O que isso demonstra:

hostssl requer TLS - use para conexões de aplicativos remotas
Roles e sub-redes separadas para leitura/escrita vs. somente leitura
reject como regra geral após regras específicas (a ordem importa - a primeira correspondência vence)
replication é um pseudo-banco de dados para conexões de replicação física

Análise Profunda

Campos da Regra

Campo	Valores	Significado
TYPE	`local`, `host`, `hostssl`, `hostnossl`	Socket vs TCP; Requisito de TLS
DATABASE	nome, `all`, `sameuser`, `replication`	Banco de dados de destino
USER	nome, `all`, `+group`	Prefixo `+` corresponde a roles de grupo
ADDRESS	CIDR, hostname	Omitir para `local`
METHOD	`scram-sha-256`, `cert`, `peer`, `reject`	Como a identidade é verificada

Métodos de Autenticação (Produção)

# Preferido para autenticação por senha (PG 10+)
password_encryption = scram-sha-256   # em postgresql.conf
 
# Autenticação por certificado (mTLS)
hostssl all app_user 0.0.0.0/0 cert clientcert=verify-full

md5 é legado - migre para scram-sha-256.
trust e password (texto claro) são falhas de auditoria - nunca em redes.
peer mapeia o usuário do sistema operacional para o usuário do banco de dados em conexões de socket Unix - bom para administração local do postgres.

Regras de Rede de Menor Privilégio

Um CIDR por zona de segurança (aplicativo, batch, BI, bastion de administração).
Estreite DATABASE e USER - evite all all em CIDRs amplos.
Use listeners separados: listen_addresses apenas em NICs internas, quando possível.

Comportamento de Recarga

Alterações em pg_hba.conf são aplicadas com SIGHUP reload - sem reinicialização.
Erros de sintaxe na recarga mantêm o arquivo antigo ativo - teste com a view pg_hba_file_rules (PG 12+):

SELECT line_number, error FROM pg_hba_file_rules WHERE error IS NOT NULL;

Armadilhas

Ordem de regras surpreendente - A primeira linha correspondente vence; um host all all 0.0.0.0/0 scram amplo antes de um reject nunca atinge o reject. Correção: Regras mais específicas primeiro, reject por último.
Esqueceu hostssl em redes públicas - Senha sem TLS pode ser interceptada. Correção: hostssl + certificado de servidor válido, ou apenas VPN/link privado.
Autenticação peer via TCP - peer só funciona para conexões de socket local. Correção: Use scram-sha-256 ou cert para entradas host.
Regra de replicação ausente - O standby não consegue se conectar com regras apenas de aplicativo. Correção: host replication replicator <standby-ip>/32 scram-sha-256.
IPv6 negligenciado - ::1 aberto com trust enquanto o IPv4 está bloqueado. Correção: Espelhe as políticas para ::1/128 ou desative o listener IPv6.

Alternativas

Alternativa	Use Quando	Não Use Quando
Autenticação de cliente `cert`	Malha de serviço mTLS, sem senhas compartilhadas	Clientes não conseguem gerenciar rotação de certificados
Grupos de segurança RDS	ACL de rede gerenciada na nuvem	Bare metal auto-hospedado
Túnel SSH para localhost	Acesso de administração de emergência	Caminho de estado estável do aplicativo de produção

FAQs

Onde está o pg_hba.conf?

SHOW hba_file; ou pg_config --hbafile em algumas instalações. Geralmente ao lado de postgresql.conf em PGDATA.

Por que a conexão é rejeitada sem dica?

Verifique o log do servidor após log_connections = on. Causas comuns: nenhuma regra correspondente, erro de digitação em pg_hba.conf, ou SSL necessário, mas o cliente usa plano.

scram-sha-256 vs md5?

SCRAM armazena verificadores com salt e não envia hashes de senha reutilizáveis na rede. Migre roles com ALTER ROLE ... PASSWORD 'new'.

Posso usar LDAP?

Sim, via métodos ldap ou radius - comum em empresas. Ainda assim, mantenha regras de CIDR estreitas.

O reload descarta conexões?

Não. Sessões existentes mantêm seu contexto de autenticação original; novas conexões usam o arquivo atualizado.

Relacionados

Noções Básicas de Instalação - instale antes de reforçar a autenticação
Noções Básicas de Roles - roles referenciadas nas regras hba
Autenticação SCRAM - profundidade de armazenamento de senha

Versões do Stack: Esta página foi escrita para PostgreSQL 18.4 (estável 18, manutenção 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x, e PostGIS 3.5+.

pg_hba.conf & Autenticação

Buscar na documentação

pg_hba.conf & Autenticação