适用于 PostgreSQL 18 及更高版本。

在内置的设备授权客户端流程期间，替换默认的用户提示。data 指向一个 PGpromptOAuthDevice 实例：

typedef struct _PGpromptOAuthDevice
{
    const char *verification_uri;   /* 要访问的验证 URI */
    const char *user_code;          /* 要输入的用户代码 */
    const char *verification_uri_complete;  /* 可选的 URI 与代码组合，
                                             * 或为 NULL */
    int         expires_in;         /* 距用户代码过期的秒数 */
} PGpromptOAuthDevice;

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

该回调只会在内置设备授权流程中被调用。如果应用程序安装了自定义 OAuth 流程，或者 libpq 构建时未启用内置流程支持，则不会使用这种 authdata 类型。

如果提供了不为 NULL 的 verification_uri_complete，则可以选择把它用于非文本形式的验证（例如显示二维码）。在这种情况下，仍应向最终用户显示 URL 和用户代码，因为该代码需要由提供者手工确认，而 URL 也使得用户在无法使用非文本方式时仍可继续。更多信息见 RFC 8628 第 3.3.1 节。

适用于 PostgreSQL 18 及更高版本。

添加一个自定义流程实现；如果内置流程已安装，则用它替换内置流程。该钩子应当要么直接返回一个适用于当前用户、签发者及授权范围组合的 Bearer 令牌（如果能在不阻塞的情况下获得），要么设置一个异步回调来获取令牌。

data 指向一个 PGoauthBearerRequest 实例，应该由实现填充：

typedef struct PGoauthBearerRequest
{
    /* 钩子输入（在所有调用中保持不变） */
    const char *openid_configuration; /* OIDC 发现 URL */
    const char *scope;                /* 所需的授权范围，或为 NULL */

    /* 钩子输出 */

    /*
     * 实现自定义异步 OAuth 流程的回调。签名与平台有关：
     * 在 Windows 上，PQ_SOCKTYPE 是 SOCKET；在其他平台上则为 int。
     */
    PostgresPollingStatusType (*async) (PGconn *conn,
                                        struct PGoauthBearerRequest *request,
                                        PQ_SOCKTYPE *altsock);

    /* 清理自定义分配内存的回调。 */
    void        (*cleanup) (PGconn *conn, struct PGoauthBearerRequest *request);

    char       *token;   /* 获取的 Bearer 令牌 */
    void       *user;    /* 钩子定义并分配的数据 */
} PGoauthBearerRequest;

libpq 会向该钩子提供两项信息：openid_configuration 包含描述授权服务器所支持流程的 OAuth 发现文档 URL，而 scope 包含访问服务器所需的 OAuth 授权范围列表（以空格分隔，可以为空）。两者中的任意一个或两个都可能为 NULL，表示无法发现该信息。（在这种情况下，实现可以通过其他预先配置的知识来确定要求，或者选择失败。）

该钩子的最终输出是 token，它必须指向一个可在该连接上使用的有效 Bearer 令牌。（该令牌应由 oauth_issuer 所指定的签发者签发，并持有所请求的授权范围，否则连接会被服务器的验证器模块拒绝。）分配得到的令牌字符串必须在 libpq 完成连接之前始终有效；该钩子应设置 cleanup 回调，以便在 libpq 不再需要该令牌时调用。

如果实现在首次调用钩子时无法立即生成 token，应设置 async 回调，以处理与授权服务器之间的非阻塞通信。^[16] 从钩子返回后，会立即调用该回调以启动流程。当回调无法在不阻塞的情况下继续时，应先将 *altsock 设为一个文件描述符，该描述符会在可以继续时被标记为可读或可写，然后返回 PGRES_POLLING_READING 或 PGRES_POLLING_WRITING。（该描述符随后会通过 PQsocket() 提供给顶层轮询循环。）流程完成时，应先设置 token，再返回 PGRES_POLLING_OK；返回 PGRES_POLLING_FAILED 表示失败。

实现可能希望在多次调用 async 和 cleanup 回调之间保存额外的数据用于记录状态。为此提供了 user 指针；libpq 不会触碰其内容，应用程序可以按自己的需要使用它。（记得在令牌清理时释放相关分配。）

适用于 PostgreSQL 19 及更高版本。

提供 PQAUTHDATA_OAUTH_BEARER_TOKEN 的全部功能，并且还允许设置自定义错误消息以及获取客户端已信任的 OAuth 签发者 ID。

data 指向一个 PGoauthBearerRequestV2 实例：

typedef struct
{
    PGoauthBearerRequest v1;    /* 参见上面的 PGoauthBearerRequest 结构体 */

    /* 钩子输入（在所有调用中保持不变） */
    const char *issuer;            /* 使用中的签发者标识符（RFC 9207） */

    /* 钩子输出 */
    const char *error;             /* 钩子定义的错误消息 */
} PGoauthBearerRequestV2;

应用程序必须首先使用 v1 结构体成员来实现基础 API，如上面的说明所述。libpq 还保证，传给 v1.async 和 v1.cleanup 回调的 request 指针可以安全地强制转换为 (PGoauthBearerRequestV2 *)，以便使用下面描述的附加成员。

除版本 1 API 的功能外，v2 结构体还为该钩子提供了一个额外输入和一个额外输出：

issuer 包含当前连接所使用的签发者标识符（issuer identifier），定义见 RFC 9207。该标识符来自 oauth_issuer。为避免混淆攻击，自定义流程应确保授权服务器提供的任何发现元数据都与该签发者 ID 一致。

当流程失败时，error 可以被设置为指向一条自定义错误消息。该消息会作为 PQerrorMessage 的一部分包含进去。钩子必须在 v1.cleanup 回调期间释放为错误消息分配的所有内存。