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);