Сквозная аутентификация

В Pangolin Pooler и Pangolin DBMS реализован механизм сквозной аутентификации. Программа Pangolin Pooler выступает в режиме проксирования данных аутентификации от клиента к Pangolin и обратно, аутентификация пользователя выполняется только на Pangolin.

Данная функциональность позволяет избежать:

• порождения процессов на СУБД для целей аутентификации в избыточном количестве - в случае неуспешной аутентификации процесс, порожденный клиентским подключением, терминируется;
• избыточных пользовательских аутентификаций;
• хранения паролей в открытом виде с использованием параметра auth_file файла userlist.txt;
• использования слабых типов аутентификации: trust, plain, password и peer;
• рассинхронизации информации об имени и пароле пользователя;
• ограничений ядра Pangolin Pooler в части аудирования действий пользователя.

Дополнительно она позволяет:

• выполнять аутентификацию пользователей в Pangolin Pooler всеми поддерживаемыми способами СУБД Pangolin, включая LDAP;
• повышает безопасность;
• упрощает конфигурирование кластера СУБД.

Описание механизма

В стандартной конфигурации при подключении клиента к СУБД Pangolin происходит создание отдельного серверного процесса и выполнение аутентификации. При подключении через Pangolin Pooler, каждый сеанс сопровождается двойной аутентификацией: сначала в Pooler, затем в Pangolin. Это увеличивает нагрузку и задержки при установлении соединений, особенно при большом числе подключений.

Для оптимизации процесса предлагается централизовать аутентификацию на стороне Pangolin. Для этого Pooler настраивается в режиме проксирования аутентификации (auth_proxy = on), при котором он перенаправляет запросы на специальный порт Pangolin (auth_port). Обмен данными аутентификации идет по отдельному сетевому каналу, зависит от методов аутентификации, и может состоять из нескольких итераций. Pangolin Pooler должен быть подключен к порту аутентификации Pangolin (параметр auth_port). При подключении клиента по TLS Pangolin Pooler должен передать в СУБД Pangolin определенный набор данных, содержащий следующую информацию:

• информацию о сертификате (необходимо при двухфакторной аутентификации);
• информацию об IP-адресе подключающегося клиента.

Pangolin запускает специализированный процесс AuthProc, слушающий порт аутентификации. При подключении к базе данных инициируется отдельный процесс AuthWorker, который обрабатывает аутентификацию пользователей этой конкретной базы. В зависимости от метода аутентификации возможны несколько итераций обмена сообщениями между клиентом и сервером. По завершении аутентификации формируется ответ AuthStatus, содержащий статус, токен и дополнительные параметры, необходимые для дальнейшей работы.

Количество итераций обмена аутентификационными данными для конкретного пользователя зависит от определенных в файле pg_hba.conf методов аутентификации. Обмен данными аутентификации между Pangolin Pooler и Pangolin выполняется по отдельным сетевым каналам, их количество зависит от количества баз данных, к которым выполняется подключение пользователей.

При успешной аутентификации Pangolin передает на Pangolin Pooler контекст аутентификации, состоящий из:

• token — ключ, который создается при каждом успешном выполнении аутентификации и используется для поднятия соединения или пула соединений между Pangolin Pooler и Pangolin;
• verifier — данные верификации, используются для оптимизации аутентификации и позволяют не выполнять повторную аутентификацию новых соединений клиента в Pangolin в течении определенного интервала времени (интервал (параметр auth_activity_period) задается в конфигурации Pangolin).

Контекст аутентификации позволяет не выполнять повторную аутентификацию для новых соединений клиента. Поиск контекста выполняется по параметрам аутентификации. Новые соединения ранее аутентифицированного клиента сразу начинают проксировать от Pangolin Pooler на Pangolin.

Для повышения производительности сквозной аутентификации в Pangolin Pooler добавлена возможность поднятия пула соединений аутентификаций в рамках одной БД.

Процесс аутентификации также сопровождается таймером (authentication_timeout), превышение которого приводит к разрыву соединения. Это предотвращает зависание системы при медленной или неудачной аутентификации. При изменении данных пользователя (например, пароля) контекст аутентификации сбрасывается. Существующие соединения остаются активными, однако новые попытки подключения с устаревшими данными будут отвергнуты. В этом случае Pangolin Pooler получает отказ от Pangolin, сбрасывает контекст и токен, и уведомляет клиента об ошибке аутентификации. Клиент должен переподключиться с актуальными учетными данными.

Сведения

Для пользователей, указанных в файле userlist.txt, сквозная аутентификация не выполняется.

Конфигурирование сквозной аутентификации в Pangolin Pooler

Настроить сквозную аутентификацию в Pangolin Pooler можно с помощью конфигурационных параметров, описанных в данном разделе.

Параметры аутентификации:

Параметр	Описание	Значение
auth_proxy (string)	Параметр включает/выключает режим сквозной аутентификации	Возможные значения: - off — режим сквозной аутентификации выключен, выполняется локальная аутентификация пользователя (значение по умолчанию); - on — режим сквозной аутентификации включен, выполняется аутентификация пользователя только на Pangolin
auth_failure_threshold (integer)	Параметр задает максимальное число не аутентифицированного N раз подряд клиента с идентичными параметрами (тип соединения, адрес клиента, база данных и имя пользователя), при котором будет взведен таймер неактивности аутентификации для этого клиента	Значение по умолчанию 0 (выключено)
auth_inactivity_period (integer)	Параметр определяет период неактивности аутентификации (в секундах). Это время, в течение которого ранее не аутентифицированному более N раз подряд клиенту при подключении с идентичными параметрами (тип соединения, адрес клиента, база данных и имя пользователя), Pangolin Pooler откажет в обслуживании	Значение по умолчанию 0 (выключено)
auth_last_size (integer)	Параметр задает максимальное число кешируемых записей о последних аутентификациях пользователей. Информацию о последних аутентификациях пользователей можно получить с помощью команды SHOW LAST (см. подробнее в подразделе «Команды вывода информации»)	Значение по умолчанию 10
log_audit (integer)	Включает/выключает аудит	Значение по умолчанию - 0 (выключено)

Примечание

Увеличение значения auth_failure_threshold потенциально увеличит количество обработок отказов в подключении и соответствующих записей в логах, при обычных условиях эксплуатации это не должно приводить к отказу Pangolin Pooler.

Увеличение auth_inactivity_period позволяет избежать увеличения обработок отказов в подключении на указанное время.

Одной единицей подключения (клиентом) считается соединение с определенным набором (сочетанием) параметров: логин/пароль пользователя, имя БД для подключения, IP-адрес клиента, тип соединения. Клиент считается ранее пытавшимся подключиться, по этому же сочетанию, только без передачи пароля. Блокировка пользователя происходит по этим учетным данным подключения, то есть любое изменение данного сочетания будет считаться попыткой соединения нового пользователя.

Параметры подключений:

Параметр	Описание	Значение
auth_port (integer)	Номер порта, к которому нужно подключиться для выполнения аутентификации пользователей	Значение по умолчанию 5544. Параметр раздела базы данных [databases]
auth_pool_size (integer)	Параметр задает максимальное количество соединений для выполнения аутентификации пользователей	Значение по умолчанию 1. Параметр раздела базы данных [databases]

примечание

Общее количество соединений не должно превышать значения authentication_max_workers, раздел «Конфигурирование сквозной аутентификации в Pangolin DBMS».

Пример конфигурации компонента Pangolin Pooler при активной сквозной аутентификации:

[databases]
* = host=<IP-адрес> port=5433 auth_port=5434

[pgbouncer]
 listen_addr = *
 listen_port = 6544
; включена сквозная аутентификация
 auth_proxy = on
; включен audit
 log_audit = 1
; выставлено время выполнения аутентификации
 client_login_timeout = 10
; выставлен порог, по превышению которого пользователь временно блокируется
 auth_failure_threshold = 3
; выставлен период неактивности аутентификации
 auth_inactivity_period = 30
; выставлен размер кешируемых записей о последних аутентификациях пользователей
 auth_last_size = 20

; пользователи, прописанные в userlist, будут выполнять аутентификацию, используя данный метод
 auth_type = scram-sha-256
; в файле userlist содержатся пользователи, выполняющие действия администратора или мониторинг
 auth_file = ./userlist.txt
 admin_users = pgbouncer
 stats_users = stat

Если на сервере используется TLS/SSL-соединение, то в pgbouncer.ini необходимо дополнительно прописать настройки TLS. Пример заполнения:

# TLS settings
 server_tls_protocols = all
 server_tls_sslmode = verify-ca
 server_tls_ca_file = /pg_ssl/root.crt
 server_tls_cert_file = /pg_ssl/pgbouncer.crt
 server_tls_key_file = /pg_ssl/pgbouncer.key
 server_tls_ciphers = normal
 client_tls_protocols = all
 client_tls_sslmode = verify-full
 client_tls_ca_file = /pg_ssl/root.crt
 client_tls_cert_file = /pg_ssl/server.crt
 client_tls_key_file = /pg_ssl/server.key

Внимание!

Сквозная аутентификация не работает для пользователей, которые указаны в секции [users] конфигурационного файла Pangolin Pooler.

Раздел [users] содержит пары ключ=значение, где в качестве ключа принимается имя пользователя, а в качестве значения — переопределяемые для него параметры конфигурации (в формате строк подключения libpq):

• pool_mode – задает режим пула для всех подключений данного пользователя;
• max_user_connections – задает максимум подключений для пользователя.

Пользователь, для которого переопределен один или оба параметра:

• должен быть указан в параметре stats_users или admin_users;
• должен присутствовать в списке userlist.txt (параметр auth_file) в виде "имя_пользователя" "хеш_пароля_пользователя".

Пример конфигурации (содержит параметры, связанные с использованием секции [users] файла /etc/pangolin-pooler/pangolin-pooler.ini):

[pgbouncer]
; в файле userlist содержатся пользователи, выполняющие действия администратора или мониторинг
auth_file = ./userlist.txt
admin_users = pgbouncer
stats_users = user1
[users]
; раздел содержит имя пользователя и переопределяемые для него параметры конфигурации
user1 = pool_mode=session max_user_connections=1

Пользователю user1 при таких настройках будут применены персональные параметры pool_mode и max_user_connections, а аутентификация в базе данных будет выполняться только после аутентификации его в Pangolin Pooler.

Сведения

Данные настройки также влияют на подключение к интерфейсу администрирования Pangolin Pooler.

Сброс контекста сквозной аутентификации пользователей в состояние по умолчанию

В административной консоли Pangolin Pooler реализована команда RESET_AUTH, которая сбрасывает сквозную аутентификацию пользователей в состояние по умолчанию. В качестве аргумента передается строка, содержащая параметры для выборки пользователей, для которых будет сброшен (приведен в состояние по умолчанию) контекст сквозной аутентификации.

Параметры выборки пользователя передаются в формате: "[<user>[|<db>[|<addr>[|ssl]]]]", где:

• <user> – имя пользователя;
• <db> – наименование базы данных;
• <addr> – адрес хоста, с которого аутентифицировался пользователь;
• ssl – признак того, что пользователь аутентифицировался по защищенному соединению;
• * в качестве значения параметра выборки обозначает, что в выборку попадут пользователи с любым значением данного параметра.

Примеры использования:

• RESET_AUTH; – состояние сквозной аутентификации будет сброшено у всех пользователей;
• RESET_AUTH user1; – состояние сквозной аутентификации будет сброшено у пользователя user1, подключенного к любой базе данных, с любого адреса, по любому типу соединения;
• RESET_AUTH "*|db_name"; – состояние сквозной аутентификации будет сброшено у любого пользователя, подключенного к базе данных с именем db_name, с любого адреса, по любому типу соединения;
• RESET_AUTH "*|*|127.0.0.1"; – состояние сквозной аутентификации будет сброшено у любого пользователя, подключенного к любой базе данных с хоста с адресом 127.0.0.1 по любому типу соединения;
• RESET_AUTH "*|*|*|yes"; – состояние сквозной аутентификации будет сброшено у любого пользователя, подключенного к любой базе данных с любого адреса по защищенному соединению;
• RESET_AUTH "user1|*|127.0.0.1"; – состояние сквозной аутентификации будет сброшено у пользователя user1, подключенного к любой базе данных с хоста с адресом 127.0.0.1 по любому типу соединения.

Пример работы команды сброса состояния аутентификация для всех пользователей:

postgres$ PGPASSWORD='<password3>' psql -p 6544 -d pgbouncer -U pgbouncer -c "RESET_AUTH"

RESET_AUTH

Конфигурирование сквозной аутентификации в Pangolin DBMS

Настроить сквозную аутентификацию в СУБД Pangolin можно с помощью конфигурационных параметров, описанных в данном разделе.

Параметры аутентификации:

Параметр	Описание	Значение
authentication_proxy (integer)	Параметр включает/выключает режим сквозной аутентификации	Возможные значения: - 0 — режим сквозной аутентификации выключен, не позволяет выполнять аутентификацию пользователей конкретной БД в отдельном потоке (значение по умолчанию); - 1 — режим сквозной аутентификации включен, позволяет выполнять аутентификацию пользователей конкретной БД в отдельном потоке
authentication_max_workers (integer)	Параметр определяет максимальное число одновременных подключений для выполнения аутентификации пользователей	Значение по умолчанию 16. При значении, равном 0, сквозная аутентификация выполняться не будет. Параметр authentication_max_workers можно задать только при запуске сервера
auth_handshake_timeout (integer)	Параметр определяет максимальное время, за которое должно произойти подтверждение аутентификации (в секундах). Если потенциальный клиент не сможет выполнить подтверждение аутентификации (рукопожатие) за это время, сервер закроет соединение	Значение по умолчанию 10 секунд
auth_activity_period (integer)	Параметр определяет период активности аутентификации (в секундах). Это время, в течение которого ранее аутентифицированный клиент при подключении с идентичными параметрами (тип соединения, адрес клиента, база данных и имя пользователя), выполнит аутентификацию по token	Значение по умолчанию 60 Значение передается на Pangolin Pooler и используется для проведения более быстрой аутентификации. Возможные значения: - -1 — не используется период активности аутентификации; - 0 — период активности аутентификации не имеет ограничений по времени; - > 0 — имеет ограничение по времени
auth_idle_period (integer)	Параметр определяет период простоя процесса сквозной аутентификации (в секундах). Отсчет периода начинается после обработки последнего полученного пакета. После окончания периода будет проверено, нужно ли продолжать работу процесса сквозной аутентификации. Процесс будет прерван, если связанной с ним базы данных нет, или она была удалена или переименована	Значение по умолчанию 60
auth_ete_cache_size (integet)	Параметр определяет размер кеша ключей засекречивания токенов аутентификации. При достижении максимального значения из кеша удаляется самая редко используемая запись.	Значение по умолчанию 1024. Параметр auth_ete_cache_size можно задать только при запуске сервера

примечание

Не рекомендуется выставлять значение auth_activity_period = 0, так как его нельзя сбросить в Pangolin Pooler без перезагрузки. Выставляемого значения должно хватить, чтобы запустить пул соединений между Pangolin Pooler и Pangolin DBMS.

Параметры подключений:

Параметр	Описание	Значение
authentication_port (integer)	TCP-порт, открываемый сервером для выполнения аутентификации пользователей	По умолчанию порт — 5433. Параметр authentication_port (integer) можно задать только при запуске сервера

Пример конфигурации (содержит параметры, связанные со сквозной аутентификацией):

port = 5433
...
authentication_port = 5434
authentication_timeout 60 # sec
auth_activity_period = 60 # sec

Функция очистки контекста аутентификации

Реализована функция auth_reset_context для сброса\очистки контекстов аутентификаций в СУБД Pangolin. У функции нет возвращаемого значения. Пример вызова функции:

SELECT auth_reset_context();
 
 auth_reset_context
--------------------
  
(1 row)

Команды вывода информации

Для получения информации о статусе или результатах работы механизма сквозной аутентификации были добавлены следующие команды:

• SHOW AUTHSERVERS — показывает информацию о соединениях с сервером аутентификации;

• SHOW AUTHPOOLS — показывает информацию по пулам аутентификации;

  примечание

  Новый пул аутентификации создается для каждой базы данных.

• SHOW AUTHUSERS — показывает информацию о пользователях. В Pangolin 6.4.0 добавлено новое поле auth_state, в котором отображается состояния сквозной аутентификации пользователя:

  • none – пользователь не аутентифицирован;
  • in progress – пользователь в процессе аутентификации;
  • done – пользователь аутентифицирован;

• SHOW LAST — показывает информацию об аутентификации последних N пользователей;

  примечание

  N задается параметром auth_last_size в конфигурационном файле Pangolin Pooler. По умолчанию имеет значение 10.

  При превышении этого значения первые записи удаляются, а новые добавляются в конец. Ошибка аутентификации указана в логах Pangolin или Pangolin Pooler. В каком логе и в какое время — зависит от значений параметров place и connect_time/auth_time.

• SHOW LOCKED_USERS — показывает информацию о временно заблокированных пользователях. Это пользователи с идентичными параметрами: тип соединения, адрес клиента, база данных и имя пользователя, которые не смогли аутентифицироваться N раз подряд (N определяет конфигурационный параметр auth_failure_threshold). Длительность блокировки пользователя определяется конфигурационным параметром auth_inactivity_period.

Расширены существующие команды, предоставляемые ядром компонента Pangolin Pooler - pgBouncer:

• SHOW SERVERS — показывает информацию о соединениях с сервером Pangolin;
• SHOW POOLS — показывает информацию по пулам. Новый пул создается для каждой пары сущностей (база данных, пользователь);
• SHOW LISTS — показывает различные внутренние сведения.

Подробное описание полей вывода данных команд представлено в разделе «Администрирование Pangolin Pooler» документа «Руководство администратора».

Ограничения

К ограничениям сквозной аутентификации относятся:

• пользователь со старым паролем сможет выполнить запрос к БД в период актуальности контекста аутентификации, если будут выполнены следующие условия:

  • на Pangolin Pooler включен период активности аутентификации;
  • в период активности аутентификации произошла смена пароля;
  • существует открытое соединение к БД;

• смена пароля пользователя приведет к отказу в выполняющемся подключении клиента, поэтому клиенту будет необходимо переподключиться;

• не выполняется сквозная аутентификация для пользователей, указанных в файле userlist;

• userlist.txt содержит список пользователей, прописанных в конфигурационных параметрах: admin_users и stat_users. Этим пользователям разрешается подключаться к Pangolin Pooler для выполнения команд администрирования и мониторинга, однако к Pangolin они доступа не имеют;

• игнорируются пользователи, прописанные в userlist.txt, но не указанные в admin_users и stat_users;

• аудит действий клиента выводится в лог Pangolin Pooler. Фиксируется подключение и отключение клиента, выполнение аутентификации клиента.

Типовые сценарии подключений при сквозной аутентификации

Среди множества поддерживаемых Pangolin Pooler от Pangolin методов аутентификации пользователя на сервере СУБД Pangolin выделим следующие варианты аутентификации:

• по паролю (тип password). Этот метод включает в себя несколько методов аутентификации (password, md5, scram-sha-256). Они различаются между собой разными способами хранения паролей на сервере, но все они требуют ввода пароля пользователем.
• по сертификату (тип cert). Для аутентификации в рамках этого метода используется клиентский сертификат SSL, поэтому данный способ применим только для TLS-подключений. Не требует ввода пароля.
• по LDAP (тип LDAP). Этот метод аутентификации использует LDAP только для подтверждения пары «пользователь/пароль». Требует ввода пароля пользователем.

В таблице сведены основные результаты поведения Pangolin при сквозной аутентификации, в зависимости от методов аутентификации пользователя:

Тип аутентификации	Pangolin Pooler (настройка TLS в обе стороны)	Соединение по порту 5432	Соединение по порту 6544
password	OFF	TLSv1.2	Незашифрованное
password	ON	TLSv1.2	TLSv1.2
cert	OFF	TLSv1.2	Не поддерживается
cert	ON	TLSv1.2	TLSv1.2
LDAP	OFF	TLSv1.2	Незашифрованное
LDAP	ON	TLSv1.2	TLSv1.2

Настройка подключения через Pangolin Pooler к Pangolin, используя сквозную аутентификацию

Для подключения через Pangolin Pooler к Pangolin, используя сквозную аутентификацию, необходимо:

1. В конфигурационном файле СУБД Pangolin (postgresql.conf/postgres.yaml) указать:

   • authentication_proxy = on;
   • authentication_port = {AUTHPORT};

   Пример:

   port = 5432
   ...
   authentication_port = 5544
   authentication_timeout = 60 # sec
   auth_activity_period = 10 # sec

2. В конфигурационном файле pg_hba.conf (или секции pg_hba) прописать настройки, позволяющие принимать и отклонять соединения, параметры для аутентификации пользователей. Например:

   # TYPE   DATABASE         USER              ADDRESS             METHOD
   host     all              postgres          127.0.0.1/32        scram-sha-256

3. В конфигурационном файле Pangolin Pooler указать:

   • auth_port={AUTHPORT};
   • auth_proxy = on.

   Пример:

   [pgbouncer]
    listen_port = 6544
    auth_proxy = on
    ...
   
   [databases]
   * = host=localhost port=5432 auth_port=5544 auth_pool_size=1

4. Инициируйте подключение. Пример команды:

   psql -h 127.0.0.1 -p 6544 -U postgres

   Введите корректный пароль при возникновении запроса:

   Password for user postgres: 

   Ожидаемый результат:

   psql (17.5)
   SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
   Type "help" for help.
   
   postgres=> 

5. Проверьте лог-файл Pangolin Pooler на наличие записей об обмене данными аутентификации между клиентом, Pangolin Pooler и СУБД Pangolin.

   2025-07-07 16:53:48.587 MSK AUDIT postgres/postgres@<IP-Address> connection received
   2025-07-07 16:53:48.587 MSK AUDIT postgres/postgres@<IP-Address> login attempt tls=TLSv1.3/TLS_AES_256_GCM_SHA384
   2025-07-07 16:53:48.587 MSK AUDIT postgres/postgres@<IP-Address> send auth startup packet
   2025-07-07 16:53:48.592 MSK AUDIT postgres/postgres@<IP-Address> auth server login ok25

   При наличии записи в логе формата closing because: client unexpected eof, возможно происходит потеря соединений с БД. Для решения данной проблемы обратитесь к разделу «Часто встречающиеся проблемы и пути их устранения».

6. Проверьте лог-файл Pangolin на наличие записи о выполнении аутентификации и подключении пользователя:

   2025-07-07 16:53:48 MSK [3217942]: [7-1] app=authworker,user=postgres,db=postgres,client=<IP-Address>,type=authworker LOG:  AUTH: connection authorized: user=postgres database=postgres remote_host=<IP-Address> cn="(null)" SSL enabled (protocol=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384, bits=256)