53.3. Обработчики модуля проверки OAuth #
Модули проверки OAuth реализуют свою функциональность путём определения набора обработчиков. Сервер вызывает их по мере необходимости для обработки запроса аутентификации от пользователя.
53.3.1. Обработчик запуска #
Обработчик startup_cb выполняется непосредственно после загрузки модуля. Его можно использовать для настройки локального состояния и выполнения дополнительной инициализации при необходимости. Если есть данные о состоянии модуля проверки, обработчик может использовать state->private_data для их хранения.
typedef void (*ValidatorStartupCB) (ValidatorModuleState *state);
53.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, который необходимо проверить. Ранее в Postgres Pro Shardman проверялась синтаксическая корректность токена, однако никакой другой проверки не проводилось. 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 в Postgres Pro Shardman не выполняются никакие проверки значения result->authn_id. В этом случае модуль проверки должен самостоятельно гарантировать, что токен содержит достаточные права для входа под ролью, указанной в role.
53.3.3. Обработчик выключения #
Обработчик shutdown_cb выполняется, когда завершается обслуживающий процесс, связанный с подключением. Если есть какие-либо сохранённые данные о состоянии модуля проверки, этот обработчик должен удалить их во избежание утечек ресурсов.
typedef void (*ValidatorShutdownCB) (ValidatorModuleState *state);
53.3. OAuth Validator Callbacks #
OAuth validator modules implement their functionality by defining a set of callbacks. The server will call them as required to process the authentication request from the user.
53.3.1. Startup Callback #
The startup_cb callback is executed directly after loading the module. This callback can be used to set up local state and perform additional initialization if required. If the validator module has state it can use state->private_data to store it.
typedef void (*ValidatorStartupCB) (ValidatorModuleState *state);
53.3.2. Validate Callback #
The validate_cb callback is executed during the OAuth exchange when a user attempts to authenticate using OAuth. Any state set in previous calls will be available in state->private_data.
typedef bool (*ValidatorValidateCB) (const ValidatorModuleState *state,
const char *token, const char *role,
ValidatorModuleResult *result);
token will contain the bearer token to validate. Postgres Pro Shardman has ensured that the token is well-formed syntactically, but no other validation has been performed. role will contain the role the user has requested to log in as. The callback must set output parameters in the result struct, which is defined as below:
typedef struct ValidatorModuleResult
{
bool authorized;
char *authn_id;
} ValidatorModuleResult;
The connection will only proceed if the module sets result->authorized to true. To authenticate the user, the authenticated user name (as determined using the token) shall be palloc'd and returned in the result->authn_id field. Alternatively, result->authn_id may be set to NULL if the token is valid but the associated user identity cannot be determined.
A validator may return false to signal an internal error, in which case any result parameters are ignored and the connection fails. Otherwise the validator should return true to indicate that it has processed the token and made an authorization decision.
The behavior after validate_cb returns depends on the specific HBA setup. Normally, the result->authn_id user name must exactly match the role that the user is logging in as. (This behavior may be modified with a usermap.) But when authenticating against an HBA rule with delegate_ident_mapping turned on, Postgres Pro Shardman will not perform any checks on the value of result->authn_id at all; in this case it is up to the validator to ensure that the token carries enough privileges for the user to log in under the indicated role.
53.3.3. Shutdown Callback #
The shutdown_cb callback is executed when the backend process associated with the connection exits. If the validator module has any allocated state, this callback should free it to avoid resource leaks.
typedef void (*ValidatorShutdownCB) (ValidatorModuleState *state);
