50.3. Обработчики модуля проверки OAuth #
Модули проверки OAuth реализуют свою функциональность путём определения набора обработчиков. Сервер вызывает их по мере необходимости для обработки запроса аутентификации от пользователя.
50.3.1. Обработчик запуска #
Обработчик startup_cb
выполняется непосредственно после загрузки модуля. Его можно использовать для настройки локального состояния и выполнения дополнительной инициализации при необходимости. Если есть данные о состоянии модуля проверки, обработчик может использовать state->private_data
для их хранения.
typedef void (*ValidatorStartupCB) (ValidatorModuleState *state);
50.3.2. Обработчик проверки #
Обработчик validate_cb
выполняется во время OAuth-обмена, когда пользователь пытается аутентифицироваться с помощью OAuth. Любое состояние, установленное во время предыдущих вызовов, будет доступно в state->private_data
.
typedef bool (*ValidatorValidateCB) (const ValidatorModuleState *state, const char *token, const char *role, ValidatorModuleResult *result);
token
содержит токен типа bearer, который необходимо проверить. Ранее в PostgreSQL проверялась синтаксическая корректность токена, однако никакой другой проверки не проводилось. role
содержит роль, под которой пользователь пытается войти. Обработчик должен установить выходные параметры в структуре result
, определённой следующим образом:
typedef struct ValidatorModuleResult { bool authorized; char *authn_id; } ValidatorModuleResult;
. Подключение будет продолжено, только если модуль установит result->authorized
в значение true
. Имя аутентифицированного пользователя (определяемое с помощью токена) должно быть выделено с помощью palloc и возвращено в поле result->authn_id
для аутентификации пользователя. Кроме того, поле result->authn_id
может содержать NULL, если токен действителен, но связанный с ним идентификатор пользователя не может быть определён.
Модуль проверки может возвращать значение false
, что сигнализирует о внутренней ошибке. В этом случае все параметры результата игнорируются, а подключение прерывается. В остальных случаях модуль проверки должен возвращать true
, указывая, что он обработал токен и принял решение об авторизации.
Поведение после возврата из функции validate_cb
зависит от конкретной настройки HBA. Обычно имя пользователя в result->authn_id
должно точно совпадать с ролью, под которой пользователь пытается войти (это поведение может быть изменено с помощью файла сопоставления пользователей). Однако при аутентификации по правилу HBA с включённым параметром delegate_ident_mapping
в PostgreSQL не выполняются никакие проверки значения result->authn_id
. В этом случае модуль проверки должен самостоятельно гарантировать, что токен содержит достаточные права для входа под ролью, указанной в role
.
50.3.3. Обработчик выключения #
Обработчик shutdown_cb
выполняется, когда завершается обслуживающий процесс, связанный с подключением. Если есть какие-либо сохранённые данные о состоянии модуля проверки, этот обработчик должен удалить их во избежание утечек ресурсов.
typedef void (*ValidatorShutdownCB) (ValidatorModuleState *state);