pg_hba.conf в PostgreSQL: методы аутентификации клиентов и типичные ошибки доступа

Файл pg_hba.conf (Host-Based Authentication) определяет, какие клиенты, с каких адресов, к каким базам и под какими пользователями могут подключаться к PostgreSQL, а также какой метод аутентификации будет применён. Это первый барьер на пути любого соединения: если правило не найдено или метод не пройден, сервер отклоняет подключение ещё до проверки пароля.

Расположение файла и порядок загрузки​

pg_hba.conf находится в каталоге данных кластера (data_directory). Узнать точный путь можно через SQL:

sql
SHOW hba_file;

Типичные пути в зависимости от способа установки:

Дистрибутив / способ	Путь
Debian/Ubuntu (пакетная установка)	/etc/postgresql/<версия>/main/pg_hba.conf
CentOS/RHEL (пакетная установка)	/var/lib/pgsql/<версия>/data/pg_hba.conf
Сборка из исходников	<data_directory>/pg_hba.conf

После изменения файла нужно перезагрузить конфигурацию. Это можно сделать без перезапуска сервера:

sql
SELECT pg_reload_conf();

Или через оболочку:

bash
systemctl reload postgresql

Важно: pg_reload_conf() перечитывает pg_hba.conf, но не применяет изменения к уже установленным соединениям. Новые правила действуют только для новых подключений.

Структура правил​

Каждая строка pg_hba.conf — это одно правило. Формат:

TYPE DATABASE USER ADDRESS METHOD [OPTIONS]

Поля:

• TYPE — тип соединения: local (Unix-сокет), host (TCP/IP, включая SSL и не-SSL), hostssl (только SSL), hostnossl (только без SSL).
  
• DATABASE — имя базы данных, ключевое слово all, sameuser, samerole, replication или имя файла с перечнем баз (с префиксом @).
  
• USER — имя роли, all или файл с перечнем ролей (с префиксом @).
  
• ADDRESS — CIDR-нотация (например, 192.168.1.0/24), имя хоста или all (для local не указывается).
  
• METHOD — метод аутентификации.
  
• OPTIONS — дополнительные параметры метода (например, map= для peer/ident, clientcert= для cert).
  

Правила обрабатываются сверху вниз. Первое совпавшее правило определяет метод аутентификации. Если ни одно правило не подошло, соединение отклоняется.

Методы аутентификации​

trust​

Разрешает подключение без проверки пароля. Подходит только для изолированных сред (локальная разработка, доверенные Unix-сокеты).

local all all trust
host all all 127.0.0.1/32 trust

Никогда не используйте trust для сетевых подключений, даже внутри приватной сети.

md5​

Пароль передаётся в виде MD5-хеша. Устаревший метод: MD5 уязвим к collision-атакам, а сам хеш не защищает от replay. Начиная с PostgreSQL 10 рекомендуется scram-sha-256.

host all all 10.0.0.0/8 md5

scram-sha-256​

Метод на основе протокола SCRAM-SHA-256 (RFC 5802). Пароль не передаётся в открытом виде и не подвержен replay-атакам. Требует, чтобы пароль роли был сохранён в формате SCRAM (параметр password_encryption = 'scram-sha-256' в postgresql.conf).

host all all 0.0.0.0/0 scram-sha-256

Если роль была создана до переключения на SCRAM, её пароль нужно переустановить:

sql
ALTER ROLE myuser PASSWORD 'new_secure_password';

peer​

Использует имя пользователя операционной системы (через SO_PEERCRED на Linux). Работает только для local-соединений. Имя ОС-пользователя должно совпадать с именем роли PostgreSQL, либо соответствовать маппингу из файла pg_ident.conf.

local all postgres peer
local all all peer

Типичная ошибка: пользователь ОС www-data пытается подключиться как роль app_user без записи в pg_ident.conf.

ident​

Аналог peer для TCP-соединений: сервер запрашивает имя пользователя у ident-сервера клиента (порт 113). На практике почти не используется, потому что ident-серверы редко развёрнуты и не защищены от подмены.

cert​

Аутентификация по клиентскому SSL-сертификату. Требует hostssl и настроенный CA. Имя роли извлекается из поля CN сертификата (или маппится через pg_ident.conf).

hostssl all all 0.0.0.0/0 cert clientcert=verify-full

reject​

Явно отклоняет соединение. Полезно для «чёрных списков» перед более широкими разрешающими правилами.

host all all 192.168.1.100/32 reject
host all all 192.168.1.0/24 scram-sha-256

gss, sspi, ldap, radius, pam​

Интеграция с внешними системами аутентификации. Используются в корпоративных средах. Настройка выходит за рамки базового разбора, но стоит знать, что они существуют и требуют дополнительных параметров в строке правила.

Порядок правил и приоритет​

PostgreSQL не ищет «наиболее специфичное» правило — он берёт первое совпавшее. Это частый источник ошибок.

Пример неверной конфигурации:

host all all 0.0.0.0/0 trust
host all all 10.0.0.0/8 scram-sha-256

Здесь первое правило разрешает подключение без пароля с любого адреса, и второе правило никогда не сработает.

Правильный подход — от частного к общему:

host all all 10.0.0.0/8 scram-sha-256
host all all 0.0.0.0/0 reject

Диагностика отказов​

Сообщение об ошибке​

При отказе клиент получает одно из типичных сообщений:

Сообщение	Причина
no pg_hba.conf entry for host ...	Ни одно правило не совпало по адресу, базе или пользователю
password authentication failed for user ...	Правило найдено, но пароль неверен
peer authentication failed for user ...	Имя ОС-пользователя не совпадает с ролью и нет маппинга
SSL required / non-SSL connection not allowed	Несовпадение TYPE (hostssl vs hostnossl)

Логирование​

Для диагностики включите логирование подключений в postgresql.conf:

log_connections = on
log_disconnections = on

В логе будет видно, какое правило сработало и почему соединение отклонено.

Проверка текущего правила​

Начиная с PostgreSQL 15, функция pg_hba_file_rules позволяет просмотреть разобранные правила без чтения файла вручную:

sql
SELECT line_number, type, database, user_name, address, auth_method, error
FROM pg_hba_file_rules;

Если в столбце error есть значение, правило содержит синтаксическую ошибку и будет пропущено.

Типичные ошибки конфигурации​

1. Забыт reload после правки​

Изменения в pg_hba.conf не применяются автоматически. Без pg_reload_conf() или systemctl reload сервер продолжает использовать старую версию файла.

2. Несоответствие password_encryption и метода​

Если в pg_hba.conf указан scram-sha-256, но пароль роли хранится в формате MD5 (потому что password_encryption был md5 при создании роли), аутентификация завершится ошибкой. Проверить формат хеша:

sql
SELECT rolname, substring(rolpassword, 1, 15) AS hash_prefix
FROM pg_authid
WHERE rolpassword IS NOT NULL;

Если hash_prefix начинается с md5, а метод — scram-sha-256, пароль нужно переустановить.

3. local-правило отсутствует​

Если в файле нет строки local ... peer или local ... trust, подключение через Unix-сокет (например, psql -U postgres) будет отклонено. Это часто случается после «чистки» файла.

4. IPv6 не учтён​

Правило host all all 127.0.0.1/32 md5 покрывает только IPv4-loopback. Если клиент подключается через ::1 (IPv6), нужно отдельное правило:

host all all ::1/128 scram-sha-256

5. Широкий trust в продакшене​

Строка host all all 0.0.0.0/0 trust — критическая уязвимость. Любой хост в сети получит полный доступ без пароля.

Безопасная базовая конфигурация​

Пример для сервера, принимающего подключения только из приватной подсети и с localhost:

TYPE DATABASE USER ADDRESS METHOD​

local all postgres peer
local all all peer
host all all 127.0.0.1/32 scram-sha-256
host all all ::1/128 scram-sha-256
host all all 10.0.0.0/8 scram-sha-256
host all all 0.0.0.0/0 reject

Для репликации отдельная строка:

host replication repl_user 10.0.1.0/24 scram-sha-256

Взаимодействие с pg_ident.conf​

Когда метод peer или cert требует сопоставить имя ОС-пользователя или CN сертификата с именем роли PostgreSQL, используется файл pg_ident.conf. Формат:

MAP_NAME SYSTEM_USERNAME PG_USERNAME

Пример:

mymap www-data app_user

Затем в pg_hba.conf:

local all all peer map=mymap

Без записи в pg_ident.conf пользователь ОС www-data не сможет подключиться как роль app_user через peer.

Проверка результата после настройки​

1. Выполните SELECT pg_reload_conf(); и убедитесь, что в логе нет ошибок парсинга.
   
2. Проверьте правила через pg_hba_file_rules (PostgreSQL 15+).
   
3. Попробуйте подключиться с целевого хоста:
   

bash
psql -h 10.0.0.5 -U app_user -d mydb

• Убедитесь, что подключение с неразрешённого адреса отклоняется:
  

bash
psql -h 192.168.99.99 -U app_user -d mydb

Ожидается: no pg_hba.conf entry ...​

• Проверьте, что log_connections = on фиксирует успешные и отклонённые попытки.
  

Ограничения и нюансы​

• pg_hba.conf не управляет авторизацией (правами на таблицы, схемы и т. д.) — только аутентификацией.
  
• Правила не поддерживают регулярные выражения для имён баз и пользователей.
  
• Изменение pg_hba.conf не влияет на уже открытые сессии.
  
• При использовании пулера соединений (например, PgBouncer PgBouncer для PostgreSQL: пул соединений, режимы работы и настройка под нагрузку) аутентификация происходит на двух уровнях: клиент → PgBouncer и PgBouncer → PostgreSQL. Оба уровня должны быть согласованы.
  
• Для резервного копирования и восстановления убедитесь, что pg_hba.conf включён в бэкап конфигурации Резервная копия PostgreSQL: pg_dump, pg_restore и проверка восстановления.
  

Источники​

• Ubuntu Server documentation
  
• Docker Engine | Docker Docs