Available in PostgreSQL 18 and later.

Replaces the default user prompt during the builtin device authorization client flow. data points to an instance of 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;

The OAuth Device Authorization flow which can be included in libpq requires the end user to visit a URL with a browser, then enter a code which permits libpq to connect to the server on their behalf. The default prompt simply prints the verification_uri and user_code on standard error. Replacement implementations may display this information using any preferred method, for example with a GUI.

This callback is only invoked during the builtin device authorization flow. If the application installs a custom OAuth flow, or libpq was not built with support for the builtin flow, this authdata type will not be used.

If a non-NULL verification_uri_complete is provided, it may optionally be used for non-textual verification (for example, by displaying a QR code). The URL and user code should still be displayed to the end user in this case, because the code will be manually confirmed by the provider, and the URL lets users continue even if they can't use the non-textual method. For more information, see section 3.3.1 in RFC 8628.

Available in PostgreSQL 18 and later.

Adds a custom implementation of a flow, replacing the builtin flow if it is installed. The hook should either directly return a Bearer token for the current user/issuer/scope combination, if one is available without blocking, or else set up an asynchronous callback to retrieve one.

data points to an instance of PGoauthBearerRequest, which should be filled in by the implementation:

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;

Two pieces of information are provided to the hook by libpq: openid_configuration contains the URL of an OAuth discovery document describing the authorization server's supported flows, and scope contains a (possibly empty) space-separated list of OAuth scopes which are required to access the server. Either or both may be NULL to indicate that the information was not discoverable. (In this case, implementations may be able to establish the requirements using some other preconfigured knowledge, or they may choose to fail.)

The final output of the hook is token, which must point to a valid Bearer token for use on the connection. (This token should be issued by the oauth_issuer and hold the requested scopes, or the connection will be rejected by the server's validator module.) The allocated token string must remain valid until libpq is finished connecting; the hook should set a cleanup callback which will be called when libpq no longer requires it.

If an implementation cannot immediately produce a token during the initial call to the hook, it should set the async callback to handle nonblocking communication with the authorization server. ^[16] This will be called to begin the flow immediately upon return from the hook. When the callback cannot make further progress without blocking, it should return either PGRES_POLLING_READING or PGRES_POLLING_WRITING after setting *altsock to the file descriptor that will be marked ready to read/write when progress can be made again. (This descriptor is then provided to the top-level polling loop via PQsocket().) Return PGRES_POLLING_OK after setting token when the flow is complete, or PGRES_POLLING_FAILED to indicate failure.

Implementations may wish to store additional data for bookkeeping across calls to the async and cleanup callbacks. The user pointer is provided for this purpose; libpq will not touch its contents and the application may use it at its convenience. (Remember to free any allocations during token cleanup.)

Available in PostgreSQL 19 and later.

Provides all the functionality of PQAUTHDATA_OAUTH_BEARER_TOKEN, as well as the ability to set custom error messages and retrieve the OAuth issuer ID that the client has trusted.

data points to an instance of PGoauthBearerRequestV2:

typedef struct
{
    PGoauthBearerRequest v1;    /* see the PGoauthBearerRequest struct, above */

    /* Hook inputs (constant across all calls) */
    const char *issuer;            /* the issuer identifier (RFC 9207) in use */

    /* Hook outputs */
    const char *error;             /* hook-defined error message */
} PGoauthBearerRequestV2;

Applications must first use the v1 struct member to implement the base API, as described above. libpq additionally guarantees that the request pointer passed to the v1.async and v1.cleanup callbacks may be safely cast to (PGoauthBearerRequestV2 *), to make use of the additional members described below.

In addition to the functionality of the version 1 API, the v2 struct provides an additional input and output for the hook:

issuer contains the issuer identifier, as defined in RFC 9207, that is in use for the current connection. This identifier is derived from oauth_issuer. To avoid mix-up attacks, custom flows should ensure that any discovery metadata provided by the authorization server matches this issuer ID.

error may be set to point to a custom error message when a flow fails. The message will be included as part of PQerrorMessage . Hooks must free any error message allocations during the v1.cleanup callback.