Autenticação SCRAM

SCRAM-SHA-256 é a autenticação de senha padrão do PostgreSQL. O servidor armazena um verificador com salt, não a senha em texto plano, e o cliente prova o conhecimento através de um protocolo de desafio-resposta. Emparelhe SCRAM com TLS (hostssl) para produção; adicione LDAP ou IAM na nuvem quando a identidade central for necessária.

Receita

-- Padrão do servidor para novas senhas (postgresql.conf)
-- password_encryption = scram-sha-256
 
CREATE ROLE app_api LOGIN PASSWORD 'senha-secreta-gerada-pelo-vault';

# pg_hba.conf
hostssl  orders  app_api  10.20.0.0/16  scram-sha-256

# Verificar o tipo de hash armazenado
psql -c "SELECT rolname, rolpassword FROM pg_authid WHERE rolname = 'app_api';"
# rolpassword começa com SCRAM-SHA-256$

Quando usar isso:

Todas as roles baseadas em senha no PostgreSQL 14+
Migrando de md5 durante uma atualização ou auditoria de conformidade
Base antes de LDAP/SSO - mesmo fluxos federados geralmente mapeiam para uma role de banco de dados

Exemplo de Trabalho

Migrar uma role legada md5 para SCRAM e impor em conexões.

-- Confirmar configuração de criptografia
SHOW password_encryption;  -- scram-sha-256
 
-- Redefinir senha para regenerar o verificador SCRAM
ALTER ROLE app_api PASSWORD 'nova-senha-rotacionada-do-vault';
 
-- Confirmar formato do verificador
SELECT rolname,
       left(rolpassword, 14) AS hash_prefix
FROM pg_authid
WHERE rolname = 'app_api';

# pg_hba.conf - sem md5 para roles de aplicação
hostssl  orders  app_api  10.20.0.0/16  scram-sha-256

# Cliente deve usar libpq/psql/driver com suporte SCRAM (clientes PostgreSQL 10+)
psql "host=db.internal dbname=orders user=app_api sslmode=verify-full"

O que isso demonstra:

ALTER ROLE ... PASSWORD regenera o verificador SCRAM quando password_encryption = scram-sha-256
O método pg_hba deve ser scram-sha-256, não md5
JDBC/psql antigos sem SCRAM falharão rapidamente (atualize os clientes)

Mergulho Profundo

Como o SCRAM Funciona

Cliente solicita autenticação para o usuário.
Servidor envia o salt e a contagem de iteração do verificador armazenado.
Cliente deriva a prova da senha + salt sem enviar a senha pela rede.
Servidor verifica a prova contra pg_authid.rolpassword.

Visão Geral da Integração LDAP

# pg_hba.conf - Bind LDAP (diretório valida a senha)
hostssl  all  +ldap_users  10.20.0.0/16  ldap ldapserver=ldap.corp.internal ldapbasedn="dc=corp,dc=internal"

-- Mapear grupo LDAP para role (padrão)
CREATE ROLE ldap_users;
GRANT app_api TO ldap_users;  -- herdar privilégios de app via GRANT

LDAP delega verificações de senha para Active Directory/OpenLDAP. O PostgreSQL ainda autoriza com GRANT. Use LDAPS ou TLS para o diretório.

Padrões de SSO/IAM na Nuvem

Padrão	Como funciona
Autenticação IAM do RDS	Token de curta duração como senha; nenhum segredo estático no app
IAM do Cloud SQL	Conector ou autenticação IAM DB com token
Azure AD	Frequentemente via proxy ou servidor flexível habilitado para AAD

Senhas SCRAM estáticas continuam comuns para roles de migração e ferramentas de BI de terceiros sem suporte a IAM.

Notas do PostgreSQL

-- Forçar SCRAM para alterações de senha de role
ALTER SYSTEM SET password_encryption = 'scram-sha-256';
SELECT pg_reload_conf();
 
-- Listar roles ainda em md5
SELECT rolname FROM pg_authid
WHERE rolpassword LIKE 'md5%';

Armadilhas

Verificadores md5 após atualização - o login funciona apenas se o pg_hba ainda permitir md5. Correção: re-ALTER ROLE PASSWORD para cada role de login.
Discrepância auth_query do PgBouncer - o pooler deve suportar SCRAM para o backend. Correção: PgBouncer 1.21+ com auth_type = scram-sha-256.
Versões antigas do JDBC - SCRAM não suportado. Correção: PostgreSQL JDBC 42.2.0+.
Senha compartilhada na configuração do pool de conexões - a rotação requer implantação coordenada. Correção: sidecar do vault ou tokens IAM por instância.
LDAP sem TLS - senha do diretório exposta. Correção: LDAPS e hostssl para o Postgres.
Falhas de autenticação em log_statement = all - apenas ruído; use logs de conexão e correlação externa de SIEM.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Autenticação por certificado	Identidades fixas de malha de serviço	Usuários humanos e laptops
GSSAPI/Kerberos	SSO corporativo já em Kerberos	Kubernetes nativo da nuvem sem AD
Autenticação de token IAM	PostgreSQL gerenciado pela AWS/GCP	Auto-hospedado sem infra de token
`trust` (socket local)	`psql` admin apenas no host do DB	Qualquer conexão TCP

FAQs

SCRAM é melhor que md5?

Sim. md5 é um hash único sem salt por usuário no sentido do protocolo; SCRAM usa verificadores com salt e iteração moderna.

Preciso mudar o código do aplicativo para SCRAM?

Apenas se o driver for muito antigo. Drivers modernos de pg, JDBC, Npgsql e asyncpg suportam SCRAM transparentemente.

Como rotaciono senhas SCRAM?

ALTER ROLE PASSWORD, atualize o vault/segredo, reinicie os pods do aplicativo em rolling update. Nenhuma reinicialização do servidor é necessária.

O PgBouncer pode armazenar SCRAM?

Use auth_type = scram-sha-256 e auth_file ou auth_query correspondendo aos verificadores do servidor.

E os usuários de replicação?

Roles de replicação usam as mesmas regras SCRAM; defina a senha e hostssl ... replication no pg_hba.

LDAP vs SCRAM para humanos?

LDAP para funcionários; contas de serviço SCRAM para aplicativos e roles de migração de CI.

O RDS impõe SCRAM?

O RDS suporta SCRAM para autenticação de senha. A autenticação IAM é separada e preferida para aplicativos nativos da AWS.

Depuração de autenticação falha?

Verifique a ordem do pg_hba, o atributo LOGIN da role, o requisito SSL e o suporte SCRAM do cliente.

Senha na URI de conexão?

Evite no histórico do shell. Use .pgpass com permissões 0600 ou variável de ambiente de um gerenciador de segredos.

Autenticação multifator no Postgres?

Não integrado para login SQL. MFA na camada VPN/SSO ou autenticação baseada em IAM para ofertas gerenciadas.

Relacionados

Noções Básicas de Segurança - roles e grants
Configuração SSL/TLS - criptografar canal de login
pg_hba.conf & Autenticação - regras hba
Proxies de Conexão - autenticação PgBouncer
Melhores Práticas de Segurança - higiene de credenciais

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+.

Autenticação SCRAM

Receita

-- Padrão do servidor para novas senhas (postgresql.conf)
-- password_encryption = scram-sha-256
 
CREATE ROLE app_api LOGIN PASSWORD 'senha-secreta-gerada-pelo-vault';

# pg_hba.conf
hostssl  orders  app_api  10.20.0.0/16  scram-sha-256

# Verificar o tipo de hash armazenado
psql -c "SELECT rolname, rolpassword FROM pg_authid WHERE rolname = 'app_api';"
# rolpassword começa com SCRAM-SHA-256$

Quando usar isso:

Todas as roles baseadas em senha no PostgreSQL 14+
Migrando de md5 durante uma atualização ou auditoria de conformidade
Base antes de LDAP/SSO - mesmo fluxos federados geralmente mapeiam para uma role de banco de dados

Exemplo de Trabalho

Migrar uma role legada md5 para SCRAM e impor em conexões.

-- Confirmar configuração de criptografia
SHOW password_encryption;  -- scram-sha-256
 
-- Redefinir senha para regenerar o verificador SCRAM
ALTER ROLE app_api PASSWORD 'nova-senha-rotacionada-do-vault';
 
-- Confirmar formato do verificador
SELECT rolname,
       left(rolpassword, 14) AS hash_prefix
FROM pg_authid
WHERE rolname = 'app_api';

# pg_hba.conf - sem md5 para roles de aplicação
hostssl  orders  app_api  10.20.0.0/16  scram-sha-256

# Cliente deve usar libpq/psql/driver com suporte SCRAM (clientes PostgreSQL 10+)
psql "host=db.internal dbname=orders user=app_api sslmode=verify-full"

O que isso demonstra:

ALTER ROLE ... PASSWORD regenera o verificador SCRAM quando password_encryption = scram-sha-256
O método pg_hba deve ser scram-sha-256, não md5
JDBC/psql antigos sem SCRAM falharão rapidamente (atualize os clientes)

Mergulho Profundo

Como o SCRAM Funciona

Cliente solicita autenticação para o usuário.
Servidor envia o salt e a contagem de iteração do verificador armazenado.
Cliente deriva a prova da senha + salt sem enviar a senha pela rede.
Servidor verifica a prova contra pg_authid.rolpassword.

Visão Geral da Integração LDAP

# pg_hba.conf - Bind LDAP (diretório valida a senha)
hostssl  all  +ldap_users  10.20.0.0/16  ldap ldapserver=ldap.corp.internal ldapbasedn="dc=corp,dc=internal"

-- Mapear grupo LDAP para role (padrão)
CREATE ROLE ldap_users;
GRANT app_api TO ldap_users;  -- herdar privilégios de app via GRANT

LDAP delega verificações de senha para Active Directory/OpenLDAP. O PostgreSQL ainda autoriza com GRANT. Use LDAPS ou TLS para o diretório.

Padrões de SSO/IAM na Nuvem

Padrão	Como funciona
Autenticação IAM do RDS	Token de curta duração como senha; nenhum segredo estático no app
IAM do Cloud SQL	Conector ou autenticação IAM DB com token
Azure AD	Frequentemente via proxy ou servidor flexível habilitado para AAD

Senhas SCRAM estáticas continuam comuns para roles de migração e ferramentas de BI de terceiros sem suporte a IAM.

Notas do PostgreSQL

-- Forçar SCRAM para alterações de senha de role
ALTER SYSTEM SET password_encryption = 'scram-sha-256';
SELECT pg_reload_conf();
 
-- Listar roles ainda em md5
SELECT rolname FROM pg_authid
WHERE rolpassword LIKE 'md5%';

Armadilhas

Verificadores md5 após atualização - o login funciona apenas se o pg_hba ainda permitir md5. Correção: re-ALTER ROLE PASSWORD para cada role de login.
Discrepância auth_query do PgBouncer - o pooler deve suportar SCRAM para o backend. Correção: PgBouncer 1.21+ com auth_type = scram-sha-256.
Versões antigas do JDBC - SCRAM não suportado. Correção: PostgreSQL JDBC 42.2.0+.
Senha compartilhada na configuração do pool de conexões - a rotação requer implantação coordenada. Correção: sidecar do vault ou tokens IAM por instância.
LDAP sem TLS - senha do diretório exposta. Correção: LDAPS e hostssl para o Postgres.
Falhas de autenticação em log_statement = all - apenas ruído; use logs de conexão e correlação externa de SIEM.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Autenticação por certificado	Identidades fixas de malha de serviço	Usuários humanos e laptops
GSSAPI/Kerberos	SSO corporativo já em Kerberos	Kubernetes nativo da nuvem sem AD
Autenticação de token IAM	PostgreSQL gerenciado pela AWS/GCP	Auto-hospedado sem infra de token
`trust` (socket local)	`psql` admin apenas no host do DB	Qualquer conexão TCP

FAQs

SCRAM é melhor que md5?

Sim. md5 é um hash único sem salt por usuário no sentido do protocolo; SCRAM usa verificadores com salt e iteração moderna.

Preciso mudar o código do aplicativo para SCRAM?

Apenas se o driver for muito antigo. Drivers modernos de pg, JDBC, Npgsql e asyncpg suportam SCRAM transparentemente.

Como rotaciono senhas SCRAM?

ALTER ROLE PASSWORD, atualize o vault/segredo, reinicie os pods do aplicativo em rolling update. Nenhuma reinicialização do servidor é necessária.

O PgBouncer pode armazenar SCRAM?

Use auth_type = scram-sha-256 e auth_file ou auth_query correspondendo aos verificadores do servidor.

E os usuários de replicação?

Roles de replicação usam as mesmas regras SCRAM; defina a senha e hostssl ... replication no pg_hba.

LDAP vs SCRAM para humanos?

LDAP para funcionários; contas de serviço SCRAM para aplicativos e roles de migração de CI.

O RDS impõe SCRAM?

O RDS suporta SCRAM para autenticação de senha. A autenticação IAM é separada e preferida para aplicativos nativos da AWS.

Depuração de autenticação falha?

Verifique a ordem do pg_hba, o atributo LOGIN da role, o requisito SSL e o suporte SCRAM do cliente.

Senha na URI de conexão?

Evite no histórico do shell. Use .pgpass com permissões 0600 ou variável de ambiente de um gerenciador de segredos.

Autenticação multifator no Postgres?

Não integrado para login SQL. MFA na camada VPN/SSO ou autenticação baseada em IAM para ofertas gerenciadas.

Relacionados

Noções Básicas de Segurança - roles e grants
Configuração SSL/TLS - criptografar canal de login
pg_hba.conf & Autenticação - regras hba
Proxies de Conexão - autenticação PgBouncer
Melhores Práticas de Segurança - higiene de credenciais

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+.

Autenticação SCRAM

Buscar na documentação

Autenticação SCRAM