Заменяет приглашение пользователя по умолчанию во время встроенного клиентского потока авторизации устройства. 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;

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

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

Если предоставлено ненулевое значение 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. */
    PostgresPollingStatusType (*async) (PGconn *conn,
                                        struct PGoauthBearerRequest *request,
                                        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 после установки *pgsocket в файловый дескриптор, который будет помечен готовым для чтения/записи, когда выполнение может быть продолжено. (Этот дескриптор затем предоставляется в цикл опроса верхнего уровня через PQsocket().) Верните PGRES_POLLING_OK после установки token, когда поток завершен, или PGRES_POLLING_FAILED для указания на неудачу.

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