Обратные вызовы валидатора OAuth

Модули валидатора OAuth реализуют свою функциональность, определяя набор обратных вызовов. Сервер будет вызывать их по мере необходимости для обработки запроса аутентификации от пользователя.

Обратный вызов при запуске

Обратный вызов startup_cb выполняется непосредственно после загрузки модуля. Этот обратный вызов может использоваться для установки локального состояния и выполнения дополнительной инициализации при необходимости. Если модуль валидатора имеет состояние, он может использовать state->private_data для его хранения.

typedef void (*ValidatorStartupCB) (ValidatorModuleState *state);

Обратный вызов проверки

Обратный вызов validate_cb выполняется во время обмена данными OAuth, когда пользователь пытается пройти аутентификацию с помощью OAuth. Любое состояние, установленное в предыдущих вызовах, будет доступно в state->private_data.

typedef bool (*ValidatorValidateCB) (const ValidatorModuleState *state,
                                    const char *token, const char *role,
                                    ValidatorModuleResult *result);

token будет содержать токен носителя для проверки. PostgreSQL гарантирует корректность синтаксического формата токена, но никаких других проверок не проводилось. role будет содержать роль, которую пользователь запросил для входа в систему. Функция обратного вызова должна установить выходные параметры в структуре результата, которая определена следующим образом:

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 должно точно соответствовать роли, под которой пользователь входит в систему. Это поведение может быть изменено с помощью usermap. Но при аутентификации по правилу HBA с включенным delegate_ident_mapping PostgreSQL вообще не будет выполнять никаких проверок значения result->authn_id, в этом случае валидатор должен убедиться, что токен обладает достаточными привилегиями для входа пользователя в систему под указанной ролью.

Функция обратного вызова завершения работы

Функция обратного вызова shutdown_cb выполняется при завершении работы процесса бэкэнда, связанного с соединением. Если модуль валидатора имеет какое-либо выделенное состояние, эта функция обратного вызова должна освободить его, чтобы избежать утечек ресурсов.

typedef void (*ValidatorShutdownCB) (ValidatorModuleState *state);