在内建设备授权客户端流程期间取代默认的用户提示。 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;

可以 被包含在 libpq 中的 OAuth 设备授权流程要求最终用户用浏览器访问一个 URL， 然后输入一个允许 libpq 代表他们连接到服务器的码。 默认的提示只是把 verification_uri 和 user_code 打印到标准错误。 替换实现可以用任何偏好的方式显示这些信息， 例如用 GUI。

这个回调只在内建设备授权流程期间被调用。 如果应用程序安装了一个 自定义 OAuth 流程， 或者 libpq 构建时没有带内建流程的支持， 这个 authdata 类型将不会被使用。

如果提供了一个非 NULL 的 verification_uri_complete， 它可以选择性地用于非文本的验证 （例如通过显示一个二维码）。 在这种情况下， 仍然应当向最终用户显示该 URL 和用户码， 因为该码会由提供方手动确认， 而这个 URL 让用户在无法使用非文本方法的情况下也能继续。 更多信息请参见 RFC 8628 的 3.3.1 节。

添加一个流程的自定义实现， 如果该流程 已安装， 则替换内建的流程。 如果当前用户/颁发者/作用域组合的 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 包含一份描述授权服务器所支持流程的 OAuth 发现文档的 URL， 而 scope 包含访问服务器所需的 OAuth 作用域的一个 （可能为空的） 以空格分隔的列表。 其中任何一个或两者都可以是 NULL， 表示无法发现该信息。 （在这种情况下， 实现也许能够使用某些其他预先配置的知识来确定这些要求， 或者它们可能选择失败。）

钩子的最终输出是 token， 它必须指向一个有效的 Bearer 令牌供连接使用。 （这个令牌应当由 oauth_issuer 颁发， 并且持有所需的作用域， 否则连接将被服务器的验证器模块拒绝。） 被分配的令牌字符串必须在 libpq 完成连接之前保持有效； 钩子应当设置一个 cleanup 回调， 当 libpq 不再需要它时该回调会被调用。

如果一个实现无法在钩子的初始调用期间立即产生一个 token， 它应当设置 async 回调来处理与授权服务器的非阻塞通信。 ^[11] 这个回调会在从钩子返回之后被立即调用， 以开始该流程。 当回调在不阻塞的情况下无法取得进一步进展时， 它应当在把 *altsock 设置为将来可以再次取得进展时会被标记为可读/可写的文件描述符 之后， 返回 PGRES_POLLING_READING 或 PGRES_POLLING_WRITING。 （这个描述符随后会通过 PQsocket() 提供给顶层轮询循环。） 当流程完成时， 在设置好 token 之后返回 PGRES_POLLING_OK； 若要指示失败， 则返回 PGRES_POLLING_FAILED。

实现可能希望在多次调用 async 和 cleanup 回调之间存储一些额外的数据用于簿记。 为此提供了 user 指针； libpq 不会触碰它的内容， 应用程序可以在方便时使用它。 （记住在令牌清理期间释放任何分配。）