Заменяет стандартное приглашение пользователя во встроенном клиентском потоке авторизации устройства. data указывает на экземпляр PGpromptOAuthDevice:

typedef struct _PGpromptOAuthDevice
{
    const char *verification_uri;   /* verification URI to visit */
    const char *user_code;          /* user code to enter */
    const char *verification_uri_complete;  /* optional combination of URI and
                                             * code, or NULL */
    int         expires_in;         /* seconds until user code expires */
} PGpromptOAuthDevice;

Поток авторизации устройства OAuth, который можно включить в libpq, требует, чтобы конечный пользователь перешел по URL-адресу в браузере, а затем ввел код, который разрешает libpq подключиться к серверу от его имени. Приглашение по умолчанию просто выводит verification_uri и user_code в стандартный поток ошибок. Альтернативные реализации могут отображать эту информацию любым предпочтительным способом, например, с помощью графического интерфейса.

Этот обработчик вызывается только во встроенном потоке авторизации устройства. Если в приложении установлен пользовательский поток OAuth или если libpq был собран без поддержки встроенного потока, то этот тип данных аутентификации использоваться не будет.

Ненулевой verification_uri_complete может использоваться для вывода нетекстовой проверки (например, QR-кода). В таком случае URL-адрес и код пользователя должны быть видны конечному пользователю, поскольку код вручную подтверждается поставщиком, а URL-адрес позволяет пользователям продолжить, даже если они не могут использовать нетекстовый метод. Более подробная информация предоставлена в разделе 3.3.1 RFC 8628.

Добавляет пользовательскую реализацию потока, заменяя встроенный поток, если он установлен. Обработчик должен либо напрямую вернуть токен типа bearer для комбинации текущего пользователя/издателя/области доступа, если он доступен без блокировки, либо установить асинхронный обработчик для его получения.

data указывает на экземпляр PGoauthBearerRequest, который должен быть заполнен реализацией:

typedef struct PGoauthBearerRequest
{
    /* Hook inputs (constant across all calls) */
    const char *openid_configuration; /* OIDC discovery URL */
    const char *scope;                /* required scope(s), or NULL */

    /* Hook outputs */

    /*
     * Callback implementing a custom asynchronous OAuth flow. The signature is
     * platform-dependent: PQ_SOCKTYPE is SOCKET on Windows, and int everywhere
     * else.
     */
    PostgresPollingStatusType (*async) (PGconn *conn,
                                        struct PGoauthBearerRequest *request,
                                        PQ_SOCKTYPE *altsock);

    /* Callback to clean up custom allocations. */
    void        (*cleanup) (PGconn *conn, struct PGoauthBearerRequest *request);

    char       *token;   /* acquired Bearer token */
    void       *user;    /* hook-defined allocated data */
} PGoauthBearerRequest;

libpq передаёт обработчику два элемента информации: openid_configuration содержит URL-адрес документа обнаружения OAuth, где перечисляются потоки, поддерживаемые сервером авторизации, а scope содержит (возможно, пустой) список необходимых для доступа к серверу идентификаторов областей доступа OAuth, разделённых пробелами. Один из параметров или оба могут иметь значение NULL, что указывает на то, что информацию не удалось обнаружить. (В таком случае реализации могут попытаться установить требования, используя другую предварительно настроенную информацию, или могут выбрать завершение с ошибкой.)

Финальным результатом работы обработчика является параметр token, который должен указывать на действительный токен типа bearer для использования при подключении. (Этот токен должен быть выпущен oauth_issuer и содержать запрашиваемые области доступа, иначе запрос на соединение будет отклонён модулем проверки сервера.) Выделенная строка токена должна оставаться действительной до завершения подключения libpq. Обработчик должен установить функцию-обработчик cleanup, которая будет вызвана, когда токен больше не будет нужен libpq.

Если реализация не может немедленно предоставить token при первоначальном вызове обработчика, то обрабатывать неблокирующие операции с сервером авторизации должна функция-обработчик async. ^[16] Эта функция будет вызвана для начала потока сразу после возврата из обработчика. Когда функции-обработчику не удаётся продолжить выполнение без блокировки, она должна вернуть либо PGRES_POLLING_READING, либо PGRES_POLLING_WRITING, предварительно установив *altsock в значение файлового дескриптора, который будет помечен как готовый к чтению и записи, когда выполнение можно будет продолжить. (Этот дескриптор затем передаётся в главный цикл опроса через PQsocket().) После установки token при успешном завершении потока возвращается PGRES_POLLING_OK или PGRES_POLLING_FAILED при ошибке.

Реализации может потребоваться сохранять дополнительные данные для ведения учёта между вызовами функций-обработчиков async и cleanup. Указатель user предоставляется для этой цели; libpq не будет изменять его содержимое, и приложение может использовать его по своему усмотрению. (Не забывайте освобождать выделенные ресурсы во время очистки токена.)