Add support for OAUTHBEARER SASL mechanism

This commit implements OAUTHBEARER, RFC 7628, and OAuth 2.0 Device
Authorization Grants, RFC 8628.  In order to use this there is a
new pg_hba auth method called oauth.  When speaking to a OAuth-
enabled server, it looks a bit like this:

  $ psql 'host=example.org oauth_issuer=... oauth_client_id=...'
  Visit https://oauth.example.org/login and enter the code: FPQ2-M4BG

Device authorization is currently the only supported flow so the
OAuth issuer must support that in order for users to authenticate.
Third-party clients may however extend this and provide their own
flows.  The built-in device authorization flow is currently not
supported on Windows.

In order for validation to happen server side a new framework for
plugging in OAuth validation modules is added.  As validation is
implementation specific, with no default specified in the standard,
PostgreSQL does not ship with one built-in.  Each pg_hba entry can
specify a specific validator or be left blank for the validator
installed as default.

This adds a requirement on libcurl for the client side support,
which is optional to build, but the server side has no additional
build requirements.  In order to run the tests, Python is required
as this adds a https server written in Python.  Tests are gated
behind PG_TEST_EXTRA as they open ports.

This patch has been a multi-year project with many contributors
involved with reviews and in-depth discussions:  Michael Paquier,
Heikki Linnakangas, Zhihong Yu, Mahendrakar Srinivasarao, Andrey
Chudnovsky and Stephen Frost to name a few.  While Jacob Champion
is the main author there have been some levels of hacking by others.
Daniel Gustafsson contributed the validation module and various bits
and pieces; Thomas Munro wrote the client side support for kqueue.

Author: Jacob Champion <jacob.champion@enterprisedb.com>
Co-authored-by: Daniel Gustafsson <daniel@yesql.se>
Co-authored-by: Thomas Munro <thomas.munro@gmail.com>
Reviewed-by: Daniel Gustafsson <daniel@yesql.se>
Reviewed-by: Peter Eisentraut <peter@eisentraut.org>
Reviewed-by: Antonin Houska <ah@cybertec.at>
Reviewed-by: Kashif Zeeshan <kashi.zeeshan@gmail.com>
Discussion: https://postgr.es/m/d1b467a78e0e36ed85a09adf979d04cf124a9d4b.camel@vmware.com

11 files changed, 4285 insertions, 11 deletions

diff --git a/src/interfaces/libpq/Makefile b/src/interfaces/libpq/Makefile
index 701810a272a..90b0b65db6f 100644
--- a/src/interfaces/libpq/Makefile
+++ b/src/interfaces/libpq/Makefile
@@ -31,6 +31,7 @@ endif
 
 OBJS = \
 	$(WIN32RES) \
+	fe-auth-oauth.o \
 	fe-auth-scram.o \
 	fe-cancel.o \
 	fe-connect.o \
@@ -63,6 +64,10 @@ OBJS += \
 	fe-secure-gssapi.o
 endif
 
+ifeq ($(with_libcurl),yes)
+OBJS += fe-auth-oauth-curl.o
+endif
+
 ifeq ($(PORTNAME), cygwin)
 override shlib = cyg$(NAME)$(DLSUFFIX)
 endif
@@ -81,7 +86,7 @@ endif
 # that are built correctly for use in a shlib.
 SHLIB_LINK_INTERNAL = -lpgcommon_shlib -lpgport_shlib
 ifneq ($(PORTNAME), win32)
-SHLIB_LINK += $(filter -lcrypt -ldes -lcom_err -lcrypto -lk5crypto -lkrb5 -lgssapi_krb5 -lgss -lgssapi -lssl -lsocket -lnsl -lresolv -lintl -lm, $(LIBS)) $(LDAP_LIBS_FE) $(PTHREAD_LIBS)
+SHLIB_LINK += $(filter -lcrypt -ldes -lcom_err -lcrypto -lk5crypto -lkrb5 -lgssapi_krb5 -lgss -lgssapi -lssl -lcurl -lsocket -lnsl -lresolv -lintl -lm, $(LIBS)) $(LDAP_LIBS_FE) $(PTHREAD_LIBS)
 else
 SHLIB_LINK += $(filter -lcrypt -ldes -lcom_err -lcrypto -lk5crypto -lkrb5 -lgssapi32 -lssl -lsocket -lnsl -lresolv -lintl -lm $(PTHREAD_LIBS), $(LIBS)) $(LDAP_LIBS_FE)
 endif
@@ -110,6 +115,8 @@ backend_src = $(top_srcdir)/src/backend
 # which seems to insert references to that even in pure C code. Excluding
 # __tsan_func_exit is necessary when using ThreadSanitizer data race detector
 # which use this function for instrumentation of function exit.
+# libcurl registers an exit handler in the memory debugging code when running
+# with LeakSanitizer.
 # Skip the test when profiling, as gcc may insert exit() calls for that.
 # Also skip the test on platforms where libpq infrastructure may be provided
 # by statically-linked libraries, as we can't expect them to honor this
@@ -117,7 +124,7 @@ backend_src = $(top_srcdir)/src/backend
 libpq-refs-stamp: $(shlib)
 ifneq ($(enable_coverage), yes)
 ifeq (,$(filter solaris,$(PORTNAME)))
-	@if nm -A -u $< 2>/dev/null | grep -v -e __cxa_atexit -e __tsan_func_exit | grep exit; then \
+	@if nm -A -u $< 2>/dev/null | grep -v -e __cxa_atexit -e __tsan_func_exit -e _atexit | grep exit; then \
 		echo 'libpq must not be calling any function which invokes exit'; exit 1; \
 	fi
 endif
diff --git a/src/interfaces/libpq/exports.txt b/src/interfaces/libpq/exports.txt
index 2ad2cbf5ca3..9b789cbec0b 100644
--- a/src/interfaces/libpq/exports.txt
+++ b/src/interfaces/libpq/exports.txt
@@ -206,3 +206,6 @@ PQsocketPoll              203
 PQsetChunkedRowsMode      204
 PQgetCurrentTimeUSec      205
 PQservice                 206
+PQsetAuthDataHook         207
+PQgetAuthDataHook         208
+PQdefaultAuthDataHook     209
diff --git a/src/interfaces/libpq/fe-auth-oauth-curl.c b/src/interfaces/libpq/fe-auth-oauth-curl.c
new file mode 100644
index 00000000000..a80e2047bb7
--- /dev/null
+++ b/src/interfaces/libpq/fe-auth-oauth-curl.c
@@ -0,0 +1,2883 @@
+/*-------------------------------------------------------------------------
+ *
+ * fe-auth-oauth-curl.c
+ *	   The libcurl implementation of OAuth/OIDC authentication, using the
+ *	   OAuth Device Authorization Grant (RFC 8628).
+ *
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1994, Regents of the University of California
+ *
+ * IDENTIFICATION
+ *	  src/interfaces/libpq/fe-auth-oauth-curl.c
+ *
+ *-------------------------------------------------------------------------
+ */
+
+#include "postgres_fe.h"
+
+#include <curl/curl.h>
+#include <math.h>
+#ifdef HAVE_SYS_EPOLL_H
+#include <sys/epoll.h>
+#include <sys/timerfd.h>
+#endif
+#ifdef HAVE_SYS_EVENT_H
+#include <sys/event.h>
+#endif
+#include <unistd.h>
+
+#include "common/jsonapi.h"
+#include "fe-auth.h"
+#include "fe-auth-oauth.h"
+#include "libpq-int.h"
+#include "mb/pg_wchar.h"
+
+/*
+ * It's generally prudent to set a maximum response size to buffer in memory,
+ * but it's less clear what size to choose. The biggest of our expected
+ * responses is the server metadata JSON, which will only continue to grow in
+ * size; the number of IANA-registered parameters in that document is up to 78
+ * as of February 2025.
+ *
+ * Even if every single parameter were to take up 2k on average (a previously
+ * common limit on the size of a URL), 256k gives us 128 parameter values before
+ * we give up. (That's almost certainly complete overkill in practice; 2-4k
+ * appears to be common among popular providers at the moment.)
+ */
+#define MAX_OAUTH_RESPONSE_SIZE (256 * 1024)
+
+/*
+ * Parsed JSON Representations
+ *
+ * As a general rule, we parse and cache only the fields we're currently using.
+ * When adding new fields, ensure the corresponding free_*() function is updated
+ * too.
+ */
+
+/*
+ * The OpenID Provider configuration (alternatively named "authorization server
+ * metadata") jointly described by OpenID Connect Discovery 1.0 and RFC 8414:
+ *
+ *     https://openid.net/specs/openid-connect-discovery-1_0.html
+ *     https://www.rfc-editor.org/rfc/rfc8414#section-3.2
+ */
+struct provider
+{
+	char	   *issuer;
+	char	   *token_endpoint;
+	char	   *device_authorization_endpoint;
+	struct curl_slist *grant_types_supported;
+};
+
+static void
+free_provider(struct provider *provider)
+{
+	free(provider->issuer);
+	free(provider->token_endpoint);
+	free(provider->device_authorization_endpoint);
+	curl_slist_free_all(provider->grant_types_supported);
+}
+
+/*
+ * The Device Authorization response, described by RFC 8628:
+ *
+ *     https://www.rfc-editor.org/rfc/rfc8628#section-3.2
+ */
+struct device_authz
+{
+	char	   *device_code;
+	char	   *user_code;
+	char	   *verification_uri;
+	char	   *verification_uri_complete;
+	char	   *expires_in_str;
+	char	   *interval_str;
+
+	/* Fields below are parsed from the corresponding string above. */
+	int			expires_in;
+	int			interval;
+};
+
+static void
+free_device_authz(struct device_authz *authz)
+{
+	free(authz->device_code);
+	free(authz->user_code);
+	free(authz->verification_uri);
+	free(authz->verification_uri_complete);
+	free(authz->expires_in_str);
+	free(authz->interval_str);
+}
+
+/*
+ * The Token Endpoint error response, as described by RFC 6749:
+ *
+ *     https://www.rfc-editor.org/rfc/rfc6749#section-5.2
+ *
+ * Note that this response type can also be returned from the Device
+ * Authorization Endpoint.
+ */
+struct token_error
+{
+	char	   *error;
+	char	   *error_description;
+};
+
+static void
+free_token_error(struct token_error *err)
+{
+	free(err->error);
+	free(err->error_description);
+}
+
+/*
+ * The Access Token response, as described by RFC 6749:
+ *
+ *     https://www.rfc-editor.org/rfc/rfc6749#section-4.1.4
+ *
+ * During the Device Authorization flow, several temporary errors are expected
+ * as part of normal operation. To make it easy to handle these in the happy
+ * path, this contains an embedded token_error that is filled in if needed.
+ */
+struct token
+{
+	/* for successful responses */
+	char	   *access_token;
+	char	   *token_type;
+
+	/* for error responses */
+	struct token_error err;
+};
+
+static void
+free_token(struct token *tok)
+{
+	free(tok->access_token);
+	free(tok->token_type);
+	free_token_error(&tok->err);
+}
+
+/*
+ * Asynchronous State
+ */
+
+/* States for the overall async machine. */
+enum OAuthStep
+{
+	OAUTH_STEP_INIT = 0,
+	OAUTH_STEP_DISCOVERY,
+	OAUTH_STEP_DEVICE_AUTHORIZATION,
+	OAUTH_STEP_TOKEN_REQUEST,
+	OAUTH_STEP_WAIT_INTERVAL,
+};
+
+/*
+ * The async_ctx holds onto state that needs to persist across multiple calls
+ * to pg_fe_run_oauth_flow(). Almost everything interacts with this in some
+ * way.
+ */
+struct async_ctx
+{
+	enum OAuthStep step;		/* where are we in the flow? */
+
+	int			timerfd;		/* descriptor for signaling async timeouts */
+	pgsocket	mux;			/* the multiplexer socket containing all
+								 * descriptors tracked by libcurl, plus the
+								 * timerfd */
+	CURLM	   *curlm;			/* top-level multi handle for libcurl
+								 * operations */
+	CURL	   *curl;			/* the (single) easy handle for serial
+								 * requests */
+
+	struct curl_slist *headers; /* common headers for all requests */
+	PQExpBufferData work_data;	/* scratch buffer for general use (remember to
+								 * clear out prior contents first!) */
+
+	/*------
+	 * Since a single logical operation may stretch across multiple calls to
+	 * our entry point, errors have three parts:
+	 *
+	 * - errctx:	an optional static string, describing the global operation
+	 *				currently in progress. It'll be translated for you.
+	 *
+	 * - errbuf:	contains the actual error message. Generally speaking, use
+	 *				actx_error[_str] to manipulate this. This must be filled
+	 *				with something useful on an error.
+	 *
+	 * - curl_err:	an optional static error buffer used by libcurl to put
+	 *				detailed information about failures. Unfortunately
+	 *				untranslatable.
+	 *
+	 * These pieces will be combined into a single error message looking
+	 * something like the following, with errctx and/or curl_err omitted when
+	 * absent:
+	 *
+	 *     connection to server ... failed: errctx: errbuf (libcurl: curl_err)
+	 */
+	const char *errctx;			/* not freed; must point to static allocation */
+	PQExpBufferData errbuf;
+	char		curl_err[CURL_ERROR_SIZE];
+
+	/*
+	 * These documents need to survive over multiple calls, and are therefore
+	 * cached directly in the async_ctx.
+	 */
+	struct provider provider;
+	struct device_authz authz;
+
+	int			running;		/* is asynchronous work in progress? */
+	bool		user_prompted;	/* have we already sent the authz prompt? */
+	bool		used_basic_auth;	/* did we send a client secret? */
+	bool		debugging;		/* can we give unsafe developer assistance? */
+};
+
+/*
+ * Tears down the Curl handles and frees the async_ctx.
+ */
+static void
+free_async_ctx(PGconn *conn, struct async_ctx *actx)
+{
+	/*
+	 * In general, none of the error cases below should ever happen if we have
+	 * no bugs above. But if we do hit them, surfacing those errors somehow
+	 * might be the only way to have a chance to debug them.
+	 *
+	 * TODO: At some point it'd be nice to have a standard way to warn about
+	 * teardown failures. Appending to the connection's error message only
+	 * helps if the bug caused a connection failure; otherwise it'll be
+	 * buried...
+	 */
+
+	if (actx->curlm && actx->curl)
+	{
+		CURLMcode	err = curl_multi_remove_handle(actx->curlm, actx->curl);
+
+		if (err)
+			libpq_append_conn_error(conn,
+									"libcurl easy handle removal failed: %s",
+									curl_multi_strerror(err));
+	}
+
+	if (actx->curl)
+	{
+		/*
+		 * curl_multi_cleanup() doesn't free any associated easy handles; we
+		 * need to do that separately. We only ever have one easy handle per
+		 * multi handle.
+		 */
+		curl_easy_cleanup(actx->curl);
+	}
+
+	if (actx->curlm)
+	{
+		CURLMcode	err = curl_multi_cleanup(actx->curlm);
+
+		if (err)
+			libpq_append_conn_error(conn,
+									"libcurl multi handle cleanup failed: %s",
+									curl_multi_strerror(err));
+	}
+
+	free_provider(&actx->provider);
+	free_device_authz(&actx->authz);
+
+	curl_slist_free_all(actx->headers);
+	termPQExpBuffer(&actx->work_data);
+	termPQExpBuffer(&actx->errbuf);
+
+	if (actx->mux != PGINVALID_SOCKET)
+		close(actx->mux);
+	if (actx->timerfd >= 0)
+		close(actx->timerfd);
+
+	free(actx);
+}
+
+/*
+ * Release resources used for the asynchronous exchange and disconnect the
+ * altsock.
+ *
+ * This is called either at the end of a successful authentication, or during
+ * pqDropConnection(), so we won't leak resources even if PQconnectPoll() never
+ * calls us back.
+ */
+void
+pg_fe_cleanup_oauth_flow(PGconn *conn)
+{
+	fe_oauth_state *state = conn->sasl_state;
+
+	if (state->async_ctx)
+	{
+		free_async_ctx(conn, state->async_ctx);
+		state->async_ctx = NULL;
+	}
+
+	conn->altsock = PGINVALID_SOCKET;
+}
+
+/*
+ * Macros for manipulating actx->errbuf. actx_error() translates and formats a
+ * string for you; actx_error_str() appends a string directly without
+ * translation.
+ */
+
+#define actx_error(ACTX, FMT, ...) \
+	appendPQExpBuffer(&(ACTX)->errbuf, libpq_gettext(FMT), ##__VA_ARGS__)
+
+#define actx_error_str(ACTX, S) \
+	appendPQExpBufferStr(&(ACTX)->errbuf, S)
+
+/*
+ * Macros for getting and setting state for the connection's two libcurl
+ * handles, so you don't have to write out the error handling every time.
+ */
+
+#define CHECK_MSETOPT(ACTX, OPT, VAL, FAILACTION) \
+	do { \
+		struct async_ctx *_actx = (ACTX); \
+		CURLMcode	_setopterr = curl_multi_setopt(_actx->curlm, OPT, VAL); \
+		if (_setopterr) { \
+			actx_error(_actx, "failed to set %s on OAuth connection: %s",\
+					   #OPT, curl_multi_strerror(_setopterr)); \
+			FAILACTION; \
+		} \
+	} while (0)
+
+#define CHECK_SETOPT(ACTX, OPT, VAL, FAILACTION) \
+	do { \
+		struct async_ctx *_actx = (ACTX); \
+		CURLcode	_setopterr = curl_easy_setopt(_actx->curl, OPT, VAL); \
+		if (_setopterr) { \
+			actx_error(_actx, "failed to set %s on OAuth connection: %s",\
+					   #OPT, curl_easy_strerror(_setopterr)); \
+			FAILACTION; \
+		} \
+	} while (0)
+
+#define CHECK_GETINFO(ACTX, INFO, OUT, FAILACTION) \
+	do { \
+		struct async_ctx *_actx = (ACTX); \
+		CURLcode	_getinfoerr = curl_easy_getinfo(_actx->curl, INFO, OUT); \
+		if (_getinfoerr) { \
+			actx_error(_actx, "failed to get %s from OAuth response: %s",\
+					   #INFO, curl_easy_strerror(_getinfoerr)); \
+			FAILACTION; \
+		} \
+	} while (0)
+
+/*
+ * General JSON Parsing for OAuth Responses
+ */
+
+/*
+ * Represents a single name/value pair in a JSON object. This is the primary
+ * interface to parse_oauth_json().
+ *
+ * All fields are stored internally as strings or lists of strings, so clients
+ * have to explicitly parse other scalar types (though they will have gone
+ * through basic lexical validation). Storing nested objects is not currently
+ * supported, nor is parsing arrays of anything other than strings.
+ */
+struct json_field
+{
+	const char *name;			/* name (key) of the member */
+
+	JsonTokenType type;			/* currently supports JSON_TOKEN_STRING,
+								 * JSON_TOKEN_NUMBER, and
+								 * JSON_TOKEN_ARRAY_START */
+	union
+	{
+		char	  **scalar;		/* for all scalar types */
+		struct curl_slist **array;	/* for type == JSON_TOKEN_ARRAY_START */
+	}			target;
+
+	bool		required;		/* REQUIRED field, or just OPTIONAL? */
+};
+
+/* Documentation macros for json_field.required. */
+#define REQUIRED true
+#define OPTIONAL false
+
+/* Parse state for parse_oauth_json(). */
+struct oauth_parse
+{
+	PQExpBuffer errbuf;			/* detail message for JSON_SEM_ACTION_FAILED */
+	int			nested;			/* nesting level (zero is the top) */
+
+	const struct json_field *fields;	/* field definition array */
+	const struct json_field *active;	/* points inside the fields array */
+};
+
+#define oauth_parse_set_error(ctx, fmt, ...) \
+	appendPQExpBuffer((ctx)->errbuf, libpq_gettext(fmt), ##__VA_ARGS__)
+
+static void
+report_type_mismatch(struct oauth_parse *ctx)
+{
+	char	   *msgfmt;
+
+	Assert(ctx->active);
+
+	/*
+	 * At the moment, the only fields we're interested in are strings,
+	 * numbers, and arrays of strings.
+	 */
+	switch (ctx->active->type)
+	{
+		case JSON_TOKEN_STRING:
+			msgfmt = "field \"%s\" must be a string";
+			break;
+
+		case JSON_TOKEN_NUMBER:
+			msgfmt = "field \"%s\" must be a number";
+			break;
+
+		case JSON_TOKEN_ARRAY_START:
+			msgfmt = "field \"%s\" must be an array of strings";
+			break;
+
+		default:
+			Assert(false);
+			msgfmt = "field \"%s\" has unexpected type";
+	}
+
+	oauth_parse_set_error(ctx, msgfmt, ctx->active->name);
+}
+
+static JsonParseErrorType
+oauth_json_object_start(void *state)
+{
+	struct oauth_parse *ctx = state;
+
+	if (ctx->active)
+	{
+		/*
+		 * Currently, none of the fields we're interested in can be or contain
+		 * objects, so we can reject this case outright.
+		 */
+		report_type_mismatch(ctx);
+		return JSON_SEM_ACTION_FAILED;
+	}
+
+	++ctx->nested;
+	return JSON_SUCCESS;
+}
+
+static JsonParseErrorType
+oauth_json_object_field_start(void *state, char *name, bool isnull)
+{
+	struct oauth_parse *ctx = state;
+
+	/* We care only about the top-level fields. */
+	if (ctx->nested == 1)
+	{
+		const struct json_field *field = ctx->fields;
+
+		/*
+		 * We should never start parsing a new field while a previous one is
+		 * still active.
+		 */
+		if (ctx->active)
+		{
+			Assert(false);
+			oauth_parse_set_error(ctx,
+								  "internal error: started field '%s' before field '%s' was finished",
+								  name, ctx->active->name);
+			return JSON_SEM_ACTION_FAILED;
+		}
+
+		while (field->name)
+		{
+			if (strcmp(name, field->name) == 0)
+			{
+				ctx->active = field;
+				break;
+			}
+
+			++field;
+		}
+
+		/*
+		 * We don't allow duplicate field names; error out if the target has
+		 * already been set.
+		 */
+		if (ctx->active)
+		{
+			field = ctx->active;
+
+			if ((field->type == JSON_TOKEN_ARRAY_START && *field->target.array)
+				|| (field->type != JSON_TOKEN_ARRAY_START && *field->target.scalar))
+			{
+				oauth_parse_set_error(ctx, "field \"%s\" is duplicated",
+									  field->name);
+				return JSON_SEM_ACTION_FAILED;
+			}
+		}
+	}
+
+	return JSON_SUCCESS;
+}
+
+static JsonParseErrorType
+oauth_json_object_end(void *state)
+{
+	struct oauth_parse *ctx = state;
+
+	--ctx->nested;
+
+	/*
+	 * All fields should be fully processed by the end of the top-level
+	 * object.
+	 */
+	if (!ctx->nested && ctx->active)
+	{
+		Assert(false);
+		oauth_parse_set_error(ctx,
+							  "internal error: field '%s' still active at end of object",
+							  ctx->active->name);
+		return JSON_SEM_ACTION_FAILED;
+	}
+
+	return JSON_SUCCESS;
+}
+
+static JsonParseErrorType
+oauth_json_array_start(void *state)
+{
+	struct oauth_parse *ctx = state;
+
+	if (!ctx->nested)
+	{
+		oauth_parse_set_error(ctx, "top-level element must be an object");
+		return JSON_SEM_ACTION_FAILED;
+	}
+
+	if (ctx->active)
+	{
+		if (ctx->active->type != JSON_TOKEN_ARRAY_START
+		/* The arrays we care about must not have arrays as values. */
+			|| ctx->nested > 1)
+		{
+			report_type_mismatch(ctx);
+			return JSON_SEM_ACTION_FAILED;
+		}
+	}
+
+	++ctx->nested;
+	return JSON_SUCCESS;
+}
+
+static JsonParseErrorType
+oauth_json_array_end(void *state)
+{
+	struct oauth_parse *ctx = state;
+
+	if (ctx->active)
+	{
+		/*
+		 * Clear the target (which should be an array inside the top-level
+		 * object). For this to be safe, no target arrays can contain other
+		 * arrays; we check for that in the array_start callback.
+		 */
+		if (ctx->nested != 2 || ctx->active->type != JSON_TOKEN_ARRAY_START)
+		{
+			Assert(false);
+			oauth_parse_set_error(ctx,
+								  "internal error: found unexpected array end while parsing field '%s'",
+								  ctx->active->name);
+			return JSON_SEM_ACTION_FAILED;
+		}
+
+		ctx->active = NULL;
+	}
+
+	--ctx->nested;
+	return JSON_SUCCESS;
+}
+
+static JsonParseErrorType
+oauth_json_scalar(void *state, char *token, JsonTokenType type)
+{
+	struct oauth_parse *ctx = state;
+
+	if (!ctx->nested)
+	{
+		oauth_parse_set_error(ctx, "top-level element must be an object");
+		return JSON_SEM_ACTION_FAILED;
+	}
+
+	if (ctx->active)
+	{
+		const struct json_field *field = ctx->active;
+		JsonTokenType expected = field->type;
+
+		/* Make sure this matches what the active field expects. */
+		if (expected == JSON_TOKEN_ARRAY_START)
+		{
+			/* Are we actually inside an array? */
+			if (ctx->nested < 2)
+			{
+				report_type_mismatch(ctx);
+				return JSON_SEM_ACTION_FAILED;
+			}
+
+			/* Currently, arrays can only contain strings. */
+			expected = JSON_TOKEN_STRING;
+		}
+
+		if (type != expected)
+		{
+			report_type_mismatch(ctx);
+			return JSON_SEM_ACTION_FAILED;
+		}
+
+		if (field->type != JSON_TOKEN_ARRAY_START)
+		{
+			/* Ensure that we're parsing the top-level keys... */
+			if (ctx->nested != 1)
+			{
+				Assert(false);
+				oauth_parse_set_error(ctx,
+									  "internal error: scalar target found at nesting level %d",
+									  ctx->nested);
+				return JSON_SEM_ACTION_FAILED;
+			}
+
+			/* ...and that a result has not already been set. */
+			if (*field->target.scalar)
+			{
+				Assert(false);
+				oauth_parse_set_error(ctx,
+									  "internal error: scalar field '%s' would be assigned twice",
+									  ctx->active->name);
+				return JSON_SEM_ACTION_FAILED;
+			}
+
+			*field->target.scalar = strdup(token);
+			if (!*field->target.scalar)
+				return JSON_OUT_OF_MEMORY;
+
+			ctx->active = NULL;
+
+			return JSON_SUCCESS;
+		}
+		else
+		{
+			struct curl_slist *temp;
+
+			/* The target array should be inside the top-level object. */
+			if (ctx->nested != 2)
+			{
+				Assert(false);
+				oauth_parse_set_error(ctx,
+									  "internal error: array member found at nesting level %d",
+									  ctx->nested);
+				return JSON_SEM_ACTION_FAILED;
+			}
+
+			/* Note that curl_slist_append() makes a copy of the token. */
+			temp = curl_slist_append(*field->target.array, token);
+			if (!temp)
+				return JSON_OUT_OF_MEMORY;
+
+			*field->target.array = temp;
+		}
+	}
+	else
+	{
+		/* otherwise we just ignore it */
+	}
+
+	return JSON_SUCCESS;
+}
+
+/*
+ * Checks the Content-Type header against the expected type. Parameters are
+ * allowed but ignored.
+ */
+static bool
+check_content_type(struct async_ctx *actx, const char *type)
+{
+	const size_t type_len = strlen(type);
+	char	   *content_type;
+
+	CHECK_GETINFO(actx, CURLINFO_CONTENT_TYPE, &content_type, return false);
+
+	if (!content_type)
+	{
+		actx_error(actx, "no content type was provided");
+		return false;
+	}
+
+	/*
+	 * We need to perform a length limited comparison and not compare the
+	 * whole string.
+	 */
+	if (pg_strncasecmp(content_type, type, type_len) != 0)
+		goto fail;
+
+	/* On an exact match, we're done. */
+	Assert(strlen(content_type) >= type_len);
+	if (content_type[type_len] == '\0')
+		return true;
+
+	/*
+	 * Only a semicolon (optionally preceded by HTTP optional whitespace) is
+	 * acceptable after the prefix we checked. This marks the start of media
+	 * type parameters, which we currently have no use for.
+	 */
+	for (size_t i = type_len; content_type[i]; ++i)
+	{
+		switch (content_type[i])
+		{
+			case ';':
+				return true;	/* success! */
+
+			case ' ':
+			case '\t':
+				/* HTTP optional whitespace allows only spaces and htabs. */
+				break;
+
+			default:
+				goto fail;
+		}
+	}
+
+fail:
+	actx_error(actx, "unexpected content type: \"%s\"", content_type);
+	return false;
+}
+
+/*
+ * A helper function for general JSON parsing. fields is the array of field
+ * definitions with their backing pointers. The response will be parsed from
+ * actx->curl and actx->work_data (as set up by start_request()), and any
+ * parsing errors will be placed into actx->errbuf.
+ */
+static bool
+parse_oauth_json(struct async_ctx *actx, const struct json_field *fields)
+{
+	PQExpBuffer resp = &actx->work_data;
+	JsonLexContext lex = {0};
+	JsonSemAction sem = {0};
+	JsonParseErrorType err;
+	struct oauth_parse ctx = {0};
+	bool		success = false;
+
+	if (!check_content_type(actx, "application/json"))
+		return false;
+
+	if (strlen(resp->data) != resp->len)
+	{
+		actx_error(actx, "response contains embedded NULLs");
+		return false;
+	}
+
+	/*
+	 * pg_parse_json doesn't validate the incoming UTF-8, so we have to check
+	 * that up front.
+	 */
+	if (pg_encoding_verifymbstr(PG_UTF8, resp->data, resp->len) != resp->len)
+	{
+		actx_error(actx, "response is not valid UTF-8");
+		return false;
+	}
+
+	makeJsonLexContextCstringLen(&lex, resp->data, resp->len, PG_UTF8, true);
+	setJsonLexContextOwnsTokens(&lex, true);	/* must not leak on error */
+
+	ctx.errbuf = &actx->errbuf;
+	ctx.fields = fields;
+	sem.semstate = &ctx;
+
+	sem.object_start = oauth_json_object_start;
+	sem.object_field_start = oauth_json_object_field_start;
+	sem.object_end = oauth_json_object_end;
+	sem.array_start = oauth_json_array_start;
+	sem.array_end = oauth_json_array_end;
+	sem.scalar = oauth_json_scalar;
+
+	err = pg_parse_json(&lex, &sem);
+
+	if (err != JSON_SUCCESS)
+	{
+		/*
+		 * For JSON_SEM_ACTION_FAILED, we've already written the error
+		 * message. Other errors come directly from pg_parse_json(), already
+		 * translated.
+		 */
+		if (err != JSON_SEM_ACTION_FAILED)
+			actx_error_str(actx, json_errdetail(err, &lex));
+
+		goto cleanup;
+	}
+
+	/* Check all required fields. */
+	while (fields->name)
+	{
+		if (fields->required
+			&& !*fields->target.scalar
+			&& !*fields->target.array)
+		{
+			actx_error(actx, "field \"%s\" is missing", fields->name);
+			goto cleanup;
+		}
+
+		fields++;
+	}
+
+	success = true;
+
+cleanup:
+	freeJsonLexContext(&lex);
+	return success;
+}
+
+/*
+ * JSON Parser Definitions
+ */
+
+/*
+ * Parses authorization server metadata. Fields are defined by OIDC Discovery
+ * 1.0 and RFC 8414.
+ */
+static bool
+parse_provider(struct async_ctx *actx, struct provider *provider)
+{
+	struct json_field fields[] = {
+		{"issuer", JSON_TOKEN_STRING, {&provider->issuer}, REQUIRED},
+		{"token_endpoint", JSON_TOKEN_STRING, {&provider->token_endpoint}, REQUIRED},
+
+		/*----
+		 * The following fields are technically REQUIRED, but we don't use
+		 * them anywhere yet:
+		 *
+		 * - jwks_uri
+		 * - response_types_supported
+		 * - subject_types_supported
+		 * - id_token_signing_alg_values_supported
+		 */
+
+		{"device_authorization_endpoint", JSON_TOKEN_STRING, {&provider->device_authorization_endpoint}, OPTIONAL},
+		{"grant_types_supported", JSON_TOKEN_ARRAY_START, {.array = &provider->grant_types_supported}, OPTIONAL},
+
+		{0},
+	};
+
+	return parse_oauth_json(actx, fields);
+}
+
+/*
+ * Parses a valid JSON number into a double. The input must have come from
+ * pg_parse_json(), so that we know the lexer has validated it; there's no
+ * in-band signal for invalid formats.
+ */
+static double
+parse_json_number(const char *s)
+{
+	double		parsed;
+	int			cnt;
+
+	/*
+	 * The JSON lexer has already validated the number, which is stricter than
+	 * the %f format, so we should be good to use sscanf().
+	 */
+	cnt = sscanf(s, "%lf", &parsed);
+
+	if (cnt != 1)
+	{
+		/*
+		 * Either the lexer screwed up or our assumption above isn't true, and
+		 * either way a developer needs to take a look.
+		 */
+		Assert(false);
+		return 0;
+	}
+
+	return parsed;
+}
+
+/*
+ * Parses the "interval" JSON number, corresponding to the number of seconds to
+ * wait between token endpoint requests.
+ *
+ * RFC 8628 is pretty silent on sanity checks for the interval. As a matter of
+ * practicality, round any fractional intervals up to the next second, and clamp
+ * the result at a minimum of one. (Zero-second intervals would result in an
+ * expensive network polling loop.) Tests may remove the lower bound with
+ * PGOAUTHDEBUG, for improved performance.
+ */
+static int
+parse_interval(struct async_ctx *actx, const char *interval_str)
+{
+	double		parsed;
+
+	parsed = parse_json_number(interval_str);
+	parsed = ceil(parsed);
+
+	if (parsed < 1)
+		return actx->debugging ? 0 : 1;
+
+	else if (parsed >= INT_MAX)
+		return INT_MAX;
+
+	return parsed;
+}
+
+/*
+ * Parses the "expires_in" JSON number, corresponding to the number of seconds
+ * remaining in the lifetime of the device code request.
+ *
+ * Similar to parse_interval, but we have even fewer requirements for reasonable
+ * values since we don't use the expiration time directly (it's passed to the
+ * PQAUTHDATA_PROMPT_OAUTH_DEVICE hook, in case the application wants to do
+ * something with it). We simply round down and clamp to int range.
+ */
+static int
+parse_expires_in(struct async_ctx *actx, const char *expires_in_str)
+{
+	double		parsed;
+
+	parsed = parse_json_number(expires_in_str);
+	parsed = floor(parsed);
+
+	if (parsed >= INT_MAX)
+		return INT_MAX;
+	else if (parsed <= INT_MIN)
+		return INT_MIN;
+
+	return parsed;
+}
+
+/*
+ * Parses the Device Authorization Response (RFC 8628, Sec. 3.2).
+ */
+static bool
+parse_device_authz(struct async_ctx *actx, struct device_authz *authz)
+{
+	struct json_field fields[] = {
+		{"device_code", JSON_TOKEN_STRING, {&authz->device_code}, REQUIRED},
+		{"user_code", JSON_TOKEN_STRING, {&authz->user_code}, REQUIRED},
+		{"verification_uri", JSON_TOKEN_STRING, {&authz->verification_uri}, REQUIRED},
+		{"expires_in", JSON_TOKEN_NUMBER, {&authz->expires_in_str}, REQUIRED},
+
+		/*
+		 * Some services (Google, Azure) spell verification_uri differently.
+		 * We accept either.
+		 */
+		{"verification_url", JSON_TOKEN_STRING, {&authz->verification_uri}, REQUIRED},
+
+		/*
+		 * There is no evidence of verification_uri_complete being spelled
+		 * with "url" instead with any service provider, so only support
+		 * "uri".
+		 */
+		{"verification_uri_complete", JSON_TOKEN_STRING, {&authz->verification_uri_complete}, OPTIONAL},
+		{"interval", JSON_TOKEN_NUMBER, {&authz->interval_str}, OPTIONAL},
+
+		{0},
+	};
+
+	if (!parse_oauth_json(actx, fields))
+		return false;
+
+	/*
+	 * Parse our numeric fields. Lexing has already completed by this time, so
+	 * we at least know they're valid JSON numbers.
+	 */
+	if (authz->interval_str)
+		authz->interval = parse_interval(actx, authz->interval_str);
+	else
+	{
+		/*
+		 * RFC 8628 specifies 5 seconds as the default value if the server
+		 * doesn't provide an interval.
+		 */
+		authz->interval = 5;
+	}
+
+	Assert(authz->expires_in_str);	/* ensured by parse_oauth_json() */
+	authz->expires_in = parse_expires_in(actx, authz->expires_in_str);
+
+	return true;
+}
+
+/*
+ * Parses the device access token error response (RFC 8628, Sec. 3.5, which
+ * uses the error response defined in RFC 6749, Sec. 5.2).
+ */
+static bool
+parse_token_error(struct async_ctx *actx, struct token_error *err)
+{
+	bool		result;
+	struct json_field fields[] = {
+		{"error", JSON_TOKEN_STRING, {&err->error}, REQUIRED},
+
+		{"error_description", JSON_TOKEN_STRING, {&err->error_description}, OPTIONAL},
+
+		{0},
+	};
+
+	result = parse_oauth_json(actx, fields);
+
+	/*
+	 * Since token errors are parsed during other active error paths, only
+	 * override the errctx if parsing explicitly fails.
+	 */
+	if (!result)
+		actx->errctx = "failed to parse token error response";
+
+	return result;
+}
+
+/*
+ * Constructs a message from the token error response and puts it into
+ * actx->errbuf.
+ */
+static void
+record_token_error(struct async_ctx *actx, const struct token_error *err)
+{
+	if (err->error_description)
+		appendPQExpBuffer(&actx->errbuf, "%s ", err->error_description);
+	else
+	{
+		/*
+		 * Try to get some more helpful detail into the error string. A 401
+		 * status in particular implies that the oauth_client_secret is
+		 * missing or wrong.
+		 */
+		long		response_code;
+
+		CHECK_GETINFO(actx, CURLINFO_RESPONSE_CODE, &response_code, response_code = 0);
+
+		if (response_code == 401)
+		{
+			actx_error(actx, actx->used_basic_auth
+					   ? "provider rejected the oauth_client_secret"
+					   : "provider requires client authentication, and no oauth_client_secret is set");
+			actx_error_str(actx, " ");
+		}
+	}
+
+	appendPQExpBuffer(&actx->errbuf, "(%s)", err->error);
+}
+
+/*
+ * Parses the device access token response (RFC 8628, Sec. 3.5, which uses the
+ * success response defined in RFC 6749, Sec. 5.1).
+ */
+static bool
+parse_access_token(struct async_ctx *actx, struct token *tok)
+{
+	struct json_field fields[] = {
+		{"access_token", JSON_TOKEN_STRING, {&tok->access_token}, REQUIRED},
+		{"token_type", JSON_TOKEN_STRING, {&tok->token_type}, REQUIRED},
+
+		/*---
+		 * We currently have no use for the following OPTIONAL fields:
+		 *
+		 * - expires_in: This will be important for maintaining a token cache,
+		 *               but we do not yet implement one.
+		 *
+		 * - refresh_token: Ditto.
+		 *
+		 * - scope: This is only sent when the authorization server sees fit to
+		 *          change our scope request. It's not clear what we should do
+		 *          about this; either it's been done as a matter of policy, or
+		 *          the user has explicitly denied part of the authorization,
+		 *          and either way the server-side validator is in a better
+		 *          place to complain if the change isn't acceptable.
+		 */
+
+		{0},
+	};
+
+	return parse_oauth_json(actx, fields);
+}
+
+/*
+ * libcurl Multi Setup/Callbacks
+ */
+
+/*
+ * Sets up the actx->mux, which is the altsock that PQconnectPoll clients will
+ * select() on instead of the Postgres socket during OAuth negotiation.
+ *
+ * This is just an epoll set or kqueue abstracting multiple other descriptors.
+ * For epoll, the timerfd is always part of the set; it's just disabled when
+ * we're not using it. For kqueue, the "timerfd" is actually a second kqueue
+ * instance which is only added to the set when needed.
+ */
+static bool
+setup_multiplexer(struct async_ctx *actx)
+{
+#ifdef HAVE_SYS_EPOLL_H
+	struct epoll_event ev = {.events = EPOLLIN};
+
+	actx->mux = epoll_create1(EPOLL_CLOEXEC);
+	if (actx->mux < 0)
+	{
+		actx_error(actx, "failed to create epoll set: %m");
+		return false;
+	}
+
+	actx->timerfd = timerfd_create(CLOCK_MONOTONIC, TFD_CLOEXEC);
+	if (actx->timerfd < 0)
+	{
+		actx_error(actx, "failed to create timerfd: %m");
+		return false;
+	}
+
+	if (epoll_ctl(actx->mux, EPOLL_CTL_ADD, actx->timerfd, &ev) < 0)
+	{
+		actx_error(actx, "failed to add timerfd to epoll set: %m");
+		return false;
+	}
+
+	return true;
+#endif
+#ifdef HAVE_SYS_EVENT_H
+	actx->mux = kqueue();
+	if (actx->mux < 0)
+	{
+		/*- translator: the term "kqueue" (kernel queue) should not be translated */
+		actx_error(actx, "failed to create kqueue: %m");
+		return false;
+	}
+
+	/*
+	 * Originally, we set EVFILT_TIMER directly on the top-level multiplexer.
+	 * This makes it difficult to implement timer_expired(), though, so now we
+	 * set EVFILT_TIMER on a separate actx->timerfd, which is chained to
+	 * actx->mux while the timer is active.
+	 */
+	actx->timerfd = kqueue();
+	if (actx->timerfd < 0)
+	{
+		actx_error(actx, "failed to create timer kqueue: %m");
+		return false;
+	}
+
+	return true;
+#endif
+
+	actx_error(actx, "libpq does not support the Device Authorization flow on this platform");
+	return false;
+}
+
+/*
+ * Adds and removes sockets from the multiplexer set, as directed by the
+ * libcurl multi handle.
+ */
+static int
+register_socket(CURL *curl, curl_socket_t socket, int what, void *ctx,
+				void *socketp)
+{
+#ifdef HAVE_SYS_EPOLL_H
+	struct async_ctx *actx = ctx;
+	struct epoll_event ev = {0};
+	int			res;
+	int			op = EPOLL_CTL_ADD;
+
+	switch (what)
+	{
+		case CURL_POLL_IN:
+			ev.events = EPOLLIN;
+			break;
+
+		case CURL_POLL_OUT:
+			ev.events = EPOLLOUT;
+			break;
+
+		case CURL_POLL_INOUT:
+			ev.events = EPOLLIN | EPOLLOUT;
+			break;
+
+		case CURL_POLL_REMOVE:
+			op = EPOLL_CTL_DEL;
+			break;
+
+		default:
+			actx_error(actx, "unknown libcurl socket operation: %d", what);
+			return -1;
+	}
+
+	res = epoll_ctl(actx->mux, op, socket, &ev);
+	if (res < 0 && errno == EEXIST)
+	{
+		/* We already had this socket in the pollset. */
+		op = EPOLL_CTL_MOD;
+		res = epoll_ctl(actx->mux, op, socket, &ev);
+	}
+
+	if (res < 0)
+	{
+		switch (op)
+		{
+			case EPOLL_CTL_ADD:
+				actx_error(actx, "could not add to epoll set: %m");
+				break;
+
+			case EPOLL_CTL_DEL:
+				actx_error(actx, "could not delete from epoll set: %m");
+				break;
+
+			default:
+				actx_error(actx, "could not update epoll set: %m");
+		}
+
+		return -1;
+	}
+
+	return 0;
+#endif
+#ifdef HAVE_SYS_EVENT_H
+	struct async_ctx *actx = ctx;
+	struct kevent ev[2] = {{0}};
+	struct kevent ev_out[2];
+	struct timespec timeout = {0};
+	int			nev = 0;
+	int			res;
+
+	switch (what)
+	{
+		case CURL_POLL_IN:
+			EV_SET(&ev[nev], socket, EVFILT_READ, EV_ADD | EV_RECEIPT, 0, 0, 0);
+			nev++;
+			break;
+
+		case CURL_POLL_OUT:
+			EV_SET(&ev[nev], socket, EVFILT_WRITE, EV_ADD | EV_RECEIPT, 0, 0, 0);
+			nev++;
+			break;
+
+		case CURL_POLL_INOUT:
+			EV_SET(&ev[nev], socket, EVFILT_READ, EV_ADD | EV_RECEIPT, 0, 0, 0);
+			nev++;
+			EV_SET(&ev[nev], socket, EVFILT_WRITE, EV_ADD | EV_RECEIPT, 0, 0, 0);
+			nev++;
+			break;
+
+		case CURL_POLL_REMOVE:
+
+			/*
+			 * We don't know which of these is currently registered, perhaps
+			 * both, so we try to remove both.  This means we need to tolerate
+			 * ENOENT below.
+			 */
+			EV_SET(&ev[nev], socket, EVFILT_READ, EV_DELETE | EV_RECEIPT, 0, 0, 0);
+			nev++;
+			EV_SET(&ev[nev], socket, EVFILT_WRITE, EV_DELETE | EV_RECEIPT, 0, 0, 0);
+			nev++;
+			break;
+
+		default:
+			actx_error(actx, "unknown libcurl socket operation: %d", what);
+			return -1;
+	}
+
+	res = kevent(actx->mux, ev, nev, ev_out, lengthof(ev_out), &timeout);
+	if (res < 0)
+	{
+		actx_error(actx, "could not modify kqueue: %m");
+		return -1;
+	}
+
+	/*
+	 * We can't use the simple errno version of kevent, because we need to
+	 * skip over ENOENT while still allowing a second change to be processed.
+	 * So we need a longer-form error checking loop.
+	 */
+	for (int i = 0; i < res; ++i)
+	{
+		/*
+		 * EV_RECEIPT should guarantee one EV_ERROR result for every change,
+		 * whether successful or not. Failed entries contain a non-zero errno
+		 * in the data field.
+		 */
+		Assert(ev_out[i].flags & EV_ERROR);
+
+		errno = ev_out[i].data;
+		if (errno && errno != ENOENT)
+		{
+			switch (what)
+			{
+				case CURL_POLL_REMOVE:
+					actx_error(actx, "could not delete from kqueue: %m");
+					break;
+				default:
+					actx_error(actx, "could not add to kqueue: %m");
+			}
+			return -1;
+		}
+	}
+
+	return 0;
+#endif
+
+	actx_error(actx, "libpq does not support multiplexer sockets on this platform");
+	return -1;
+}
+
+/*
+ * Enables or disables the timer in the multiplexer set. The timeout value is
+ * in milliseconds (negative values disable the timer).
+ *
+ * For epoll, rather than continually adding and removing the timer, we keep it
+ * in the set at all times and just disarm it when it's not needed. For kqueue,
+ * the timer is removed completely when disabled to prevent stale timeouts from
+ * remaining in the queue.
+ */
+static bool
+set_timer(struct async_ctx *actx, long timeout)
+{
+#if HAVE_SYS_EPOLL_H
+	struct itimerspec spec = {0};
+
+	if (timeout < 0)
+	{
+		/* the zero itimerspec will disarm the timer below */
+	}
+	else if (timeout == 0)
+	{
+		/*
+		 * A zero timeout means libcurl wants us to call back immediately.
+		 * That's not technically an option for timerfd, but we can make the
+		 * timeout ridiculously short.
+		 */
+		spec.it_value.tv_nsec = 1;
+	}
+	else
+	{
+		spec.it_value.tv_sec = timeout / 1000;
+		spec.it_value.tv_nsec = (timeout % 1000) * 1000000;
+	}
+
+	if (timerfd_settime(actx->timerfd, 0 /* no flags */ , &spec, NULL) < 0)
+	{
+		actx_error(actx, "setting timerfd to %ld: %m", timeout);
+		return false;
+	}
+
+	return true;
+#endif
+#ifdef HAVE_SYS_EVENT_H
+	struct kevent ev;
+
+	/* Enable/disable the timer itself. */
+	EV_SET(&ev, 1, EVFILT_TIMER, timeout < 0 ? EV_DELETE : (EV_ADD | EV_ONESHOT),
+		   0, timeout, 0);
+	if (kevent(actx->timerfd, &ev, 1, NULL, 0, NULL) < 0 && errno != ENOENT)
+	{
+		actx_error(actx, "setting kqueue timer to %ld: %m", timeout);
+		return false;
+	}
+
+	/*
+	 * Add/remove the timer to/from the mux. (In contrast with epoll, if we
+	 * allowed the timer to remain registered here after being disabled, the
+	 * mux queue would retain any previous stale timeout notifications and
+	 * remain readable.)
+	 */
+	EV_SET(&ev, actx->timerfd, EVFILT_READ, timeout < 0 ? EV_DELETE : EV_ADD,
+		   0, 0, 0);
+	if (kevent(actx->mux, &ev, 1, NULL, 0, NULL) < 0 && errno != ENOENT)
+	{
+		actx_error(actx, "could not update timer on kqueue: %m");
+		return false;
+	}
+
+	return true;
+#endif
+
+	actx_error(actx, "libpq does not support timers on this platform");
+	return false;
+}
+
+/*
+ * Returns 1 if the timeout in the multiplexer set has expired since the last
+ * call to set_timer(), 0 if the timer is still running, or -1 (with an
+ * actx_error() report) if the timer cannot be queried.
+ */
+static int
+timer_expired(struct async_ctx *actx)
+{
+#if HAVE_SYS_EPOLL_H
+	struct itimerspec spec = {0};
+
+	if (timerfd_gettime(actx->timerfd, &spec) < 0)
+	{
+		actx_error(actx, "getting timerfd value: %m");
+		return -1;
+	}
+
+	/*
+	 * This implementation assumes we're using single-shot timers. If you
+	 * change to using intervals, you'll need to reimplement this function
+	 * too, possibly with the read() or select() interfaces for timerfd.
+	 */
+	Assert(spec.it_interval.tv_sec == 0
+		   && spec.it_interval.tv_nsec == 0);
+
+	/* If the remaining time to expiration is zero, we're done. */
+	return (spec.it_value.tv_sec == 0
+			&& spec.it_value.tv_nsec == 0);
+#endif
+#ifdef HAVE_SYS_EVENT_H
+	int			res;
+
+	/* Is the timer queue ready? */
+	res = PQsocketPoll(actx->timerfd, 1 /* forRead */ , 0, 0);
+	if (res < 0)
+	{
+		actx_error(actx, "checking kqueue for timeout: %m");
+		return -1;
+	}
+
+	return (res > 0);
+#endif
+
+	actx_error(actx, "libpq does not support timers on this platform");
+	return -1;
+}
+
+/*
+ * Adds or removes timeouts from the multiplexer set, as directed by the
+ * libcurl multi handle.
+ */
+static int
+register_timer(CURLM *curlm, long timeout, void *ctx)
+{
+	struct async_ctx *actx = ctx;
+
+	/*
+	 * There might be an optimization opportunity here: if timeout == 0, we
+	 * could signal drive_request to immediately call
+	 * curl_multi_socket_action, rather than returning all the way up the
+	 * stack only to come right back. But it's not clear that the additional
+	 * code complexity is worth it.
+	 */
+	if (!set_timer(actx, timeout))
+		return -1;				/* actx_error already called */
+
+	return 0;
+}
+
+/*
+ * Prints Curl request debugging information to stderr.
+ *
+ * Note that this will expose a number of critical secrets, so users have to opt
+ * into this (see PGOAUTHDEBUG).
+ */
+static int
+debug_callback(CURL *handle, curl_infotype type, char *data, size_t size,
+			   void *clientp)
+{
+	const char *prefix;
+	bool		printed_prefix = false;
+	PQExpBufferData buf;
+
+	/* Prefixes are modeled off of the default libcurl debug output. */
+	switch (type)
+	{
+		case CURLINFO_TEXT:
+			prefix = "*";
+			break;
+
+		case CURLINFO_HEADER_IN:	/* fall through */
+		case CURLINFO_DATA_IN:
+			prefix = "<";
+			break;
+
+		case CURLINFO_HEADER_OUT:	/* fall through */
+		case CURLINFO_DATA_OUT:
+			prefix = ">";
+			break;
+
+		default:
+			return 0;
+	}
+
+	initPQExpBuffer(&buf);
+
+	/*
+	 * Split the output into lines for readability; sometimes multiple headers
+	 * are included in a single call. We also don't allow unprintable ASCII
+	 * through without a basic <XX> escape.
+	 */
+	for (int i = 0; i < size; i++)
+	{
+		char		c = data[i];
+
+		if (!printed_prefix)
+		{
+			appendPQExpBuffer(&buf, "[libcurl] %s ", prefix);
+			printed_prefix = true;
+		}
+
+		if (c >= 0x20 && c <= 0x7E)
+			appendPQExpBufferChar(&buf, c);
+		else if ((type == CURLINFO_HEADER_IN
+				  || type == CURLINFO_HEADER_OUT
+				  || type == CURLINFO_TEXT)
+				 && (c == '\r' || c == '\n'))
+		{
+			/*
+			 * Don't bother emitting <0D><0A> for headers and text; it's not
+			 * helpful noise.
+			 */
+		}
+		else
+			appendPQExpBuffer(&buf, "<%02X>", c);
+
+		if (c == '\n')
+		{
+			appendPQExpBufferChar(&buf, c);
+			printed_prefix = false;
+		}
+	}
+
+	if (printed_prefix)
+		appendPQExpBufferChar(&buf, '\n');	/* finish the line */
+
+	fprintf(stderr, "%s", buf.data);
+	termPQExpBuffer(&buf);
+	return 0;
+}
+
+/*
+ * Initializes the two libcurl handles in the async_ctx. The multi handle,
+ * actx->curlm, is what drives the asynchronous engine and tells us what to do
+ * next. The easy handle, actx->curl, encapsulates the state for a single
+ * request/response. It's added to the multi handle as needed, during
+ * start_request().
+ */
+static bool
+setup_curl_handles(struct async_ctx *actx)
+{
+	/*
+	 * Create our multi handle. This encapsulates the entire conversation with
+	 * libcurl for this connection.
+	 */
+	actx->curlm = curl_multi_init();
+	if (!actx->curlm)
+	{
+		/* We don't get a lot of feedback on the failure reason. */
+		actx_error(actx, "failed to create libcurl multi handle");
+		return false;
+	}
+
+	/*
+	 * The multi handle tells us what to wait on using two callbacks. These
+	 * will manipulate actx->mux as needed.
+	 */
+	CHECK_MSETOPT(actx, CURLMOPT_SOCKETFUNCTION, register_socket, return false);
+	CHECK_MSETOPT(actx, CURLMOPT_SOCKETDATA, actx, return false);
+	CHECK_MSETOPT(actx, CURLMOPT_TIMERFUNCTION, register_timer, return false);
+	CHECK_MSETOPT(actx, CURLMOPT_TIMERDATA, actx, return false);
+
+	/*
+	 * Set up an easy handle. All of our requests are made serially, so we
+	 * only ever need to keep track of one.
+	 */
+	actx->curl = curl_easy_init();
+	if (!actx->curl)
+	{
+		actx_error(actx, "failed to create libcurl handle");
+		return false;
+	}
+
+	/*
+	 * Multi-threaded applications must set CURLOPT_NOSIGNAL. This requires us
+	 * to handle the possibility of SIGPIPE ourselves using pq_block_sigpipe;
+	 * see pg_fe_run_oauth_flow().
+	 *
+	 * NB: If libcurl is not built against a friendly DNS resolver (c-ares or
+	 * threaded), setting this option prevents DNS lookups from timing out
+	 * correctly. We warn about this situation at configure time.
+	 *
+	 * TODO: Perhaps there's a clever way to warn the user about synchronous
+	 * DNS at runtime too? It's not immediately clear how to do that in a
+	 * helpful way: for many standard single-threaded use cases, the user
+	 * might not care at all, so spraying warnings to stderr would probably do
+	 * more harm than good.
+	 */
+	CHECK_SETOPT(actx, CURLOPT_NOSIGNAL, 1L, return false);
+
+	if (actx->debugging)
+	{
+		/*
+		 * Set a callback for retrieving error information from libcurl, the
+		 * function only takes effect when CURLOPT_VERBOSE has been set so
+		 * make sure the order is kept.
+		 */
+		CHECK_SETOPT(actx, CURLOPT_DEBUGFUNCTION, debug_callback, return false);
+		CHECK_SETOPT(actx, CURLOPT_VERBOSE, 1L, return false);
+	}
+
+	CHECK_SETOPT(actx, CURLOPT_ERRORBUFFER, actx->curl_err, return false);
+
+	/*
+	 * Only HTTPS is allowed. (Debug mode additionally allows HTTP; this is
+	 * intended for testing only.)
+	 *
+	 * There's a bit of unfortunate complexity around the choice of
+	 * CURLoption. CURLOPT_PROTOCOLS is deprecated in modern Curls, but its
+	 * replacement didn't show up until relatively recently.
+	 */
+	{
+#if CURL_AT_LEAST_VERSION(7, 85, 0)
+		const CURLoption popt = CURLOPT_PROTOCOLS_STR;
+		const char *protos = "https";
+		const char *const unsafe = "https,http";
+#else
+		const CURLoption popt = CURLOPT_PROTOCOLS;
+		long		protos = CURLPROTO_HTTPS;
+		const long	unsafe = CURLPROTO_HTTPS | CURLPROTO_HTTP;
+#endif
+
+		if (actx->debugging)
+			protos = unsafe;
+
+		CHECK_SETOPT(actx, popt, protos, return false);
+	}
+
+	/*
+	 * If we're in debug mode, allow the developer to change the trusted CA
+	 * list. For now, this is not something we expose outside of the UNSAFE
+	 * mode, because it's not clear that it's useful in production: both libpq
+	 * and the user's browser must trust the same authorization servers for
+	 * the flow to work at all, so any changes to the roots are likely to be
+	 * done system-wide.
+	 */
+	if (actx->debugging)
+	{
+		const char *env;
+
+		if ((env = getenv("PGOAUTHCAFILE")) != NULL)
+			CHECK_SETOPT(actx, CURLOPT_CAINFO, env, return false);
+	}
+
+	/*
+	 * Suppress the Accept header to make our request as minimal as possible.
+	 * (Ideally we would set it to "application/json" instead, but OpenID is
+	 * pretty strict when it comes to provider behavior, so we have to check
+	 * what comes back anyway.)
+	 */
+	actx->headers = curl_slist_append(actx->headers, "Accept:");
+	if (actx->headers == NULL)
+	{
+		actx_error(actx, "out of memory");
+		return false;
+	}
+	CHECK_SETOPT(actx, CURLOPT_HTTPHEADER, actx->headers, return false);
+
+	return true;
+}
+
+/*
+ * Generic HTTP Request Handlers
+ */
+
+/*
+ * Response callback from libcurl which appends the response body into
+ * actx->work_data (see start_request()). The maximum size of the data is
+ * defined by CURL_MAX_WRITE_SIZE which by default is 16kb (and can only be
+ * changed by recompiling libcurl).
+ */
+static size_t
+append_data(char *buf, size_t size, size_t nmemb, void *userdata)
+{
+	struct async_ctx *actx = userdata;
+	PQExpBuffer resp = &actx->work_data;
+	size_t		len = size * nmemb;
+
+	/* In case we receive data over the threshold, abort the transfer */
+	if ((resp->len + len) > MAX_OAUTH_RESPONSE_SIZE)
+	{
+		actx_error(actx, "response is too large");
+		return 0;
+	}
+
+	/* The data passed from libcurl is not null-terminated */
+	appendBinaryPQExpBuffer(resp, buf, len);
+
+	/*
+	 * Signal an error in order to abort the transfer in case we ran out of
+	 * memory in accepting the data.
+	 */
+	if (PQExpBufferBroken(resp))
+	{
+		actx_error(actx, "out of memory");
+		return 0;
+	}
+
+	return len;
+}
+
+/*
+ * Begins an HTTP request on the multi handle. The caller should have set up all
+ * request-specific options on actx->curl first. The server's response body will
+ * be accumulated in actx->work_data (which will be reset, so don't store
+ * anything important there across this call).
+ *
+ * Once a request is queued, it can be driven to completion via drive_request().
+ * If actx->running is zero upon return, the request has already finished and
+ * drive_request() can be called without returning control to the client.
+ */
+static bool
+start_request(struct async_ctx *actx)
+{
+	CURLMcode	err;
+
+	resetPQExpBuffer(&actx->work_data);
+	CHECK_SETOPT(actx, CURLOPT_WRITEFUNCTION, append_data, return false);
+	CHECK_SETOPT(actx, CURLOPT_WRITEDATA, actx, return false);
+
+	err = curl_multi_add_handle(actx->curlm, actx->curl);
+	if (err)
+	{
+		actx_error(actx, "failed to queue HTTP request: %s",
+				   curl_multi_strerror(err));
+		return false;
+	}
+
+	/*
+	 * actx->running tracks the number of running handles, so we can
+	 * immediately call back if no waiting is needed.
+	 *
+	 * Even though this is nominally an asynchronous process, there are some
+	 * operations that can synchronously fail by this point (e.g. connections
+	 * to closed local ports) or even synchronously succeed if the stars align
+	 * (all the libcurl connection caches hit and the server is fast).
+	 */
+	err = curl_multi_socket_action(actx->curlm, CURL_SOCKET_TIMEOUT, 0, &actx->running);
+	if (err)
+	{
+		actx_error(actx, "asynchronous HTTP request failed: %s",
+				   curl_multi_strerror(err));
+		return false;
+	}
+
+	return true;
+}
+
+/*
+ * CURL_IGNORE_DEPRECATION was added in 7.87.0. If it's not defined, we can make
+ * it a no-op.
+ */
+#ifndef CURL_IGNORE_DEPRECATION
+#define CURL_IGNORE_DEPRECATION(x) x
+#endif
+
+/*
+ * Drives the multi handle towards completion. The caller should have already
+ * set up an asynchronous request via start_request().
+ */
+static PostgresPollingStatusType
+drive_request(struct async_ctx *actx)
+{
+	CURLMcode	err;
+	CURLMsg    *msg;
+	int			msgs_left;
+	bool		done;
+
+	if (actx->running)
+	{
+		/*---
+		 * There's an async request in progress. Pump the multi handle.
+		 *
+		 * curl_multi_socket_all() is officially deprecated, because it's
+		 * inefficient and pointless if your event loop has already handed you
+		 * the exact sockets that are ready. But that's not our use case --
+		 * our client has no way to tell us which sockets are ready. (They
+		 * don't even know there are sockets to begin with.)
+		 *
+		 * We can grab the list of triggered events from the multiplexer
+		 * ourselves, but that's effectively what curl_multi_socket_all() is
+		 * going to do. And there are currently no plans for the Curl project
+		 * to remove or break this API, so ignore the deprecation. See
+		 *
+		 *    https://curl.se/mail/lib-2024-11/0028.html
+		 *
+		 */
+		CURL_IGNORE_DEPRECATION(
+			err = curl_multi_socket_all(actx->curlm, &actx->running);
+		)
+
+		if (err)
+		{
+			actx_error(actx, "asynchronous HTTP request failed: %s",
+					   curl_multi_strerror(err));
+			return PGRES_POLLING_FAILED;
+		}
+
+		if (actx->running)
+		{
+			/* We'll come back again. */
+			return PGRES_POLLING_READING;
+		}
+	}
+
+	done = false;
+	while ((msg = curl_multi_info_read(actx->curlm, &msgs_left)) != NULL)
+	{
+		if (msg->msg != CURLMSG_DONE)
+		{
+			/*
+			 * Future libcurl versions may define new message types; we don't
+			 * know how to handle them, so we'll ignore them.
+			 */
+			continue;
+		}
+
+		/* First check the status of the request itself. */
+		if (msg->data.result != CURLE_OK)
+		{
+			/*
+			 * If a more specific error hasn't already been reported, use
+			 * libcurl's description.
+			 */
+			if (actx->errbuf.len == 0)
+				actx_error_str(actx, curl_easy_strerror(msg->data.result));
+
+			return PGRES_POLLING_FAILED;
+		}
+
+		/* Now remove the finished handle; we'll add it back later if needed. */
+		err = curl_multi_remove_handle(actx->curlm, msg->easy_handle);
+		if (err)
+		{
+			actx_error(actx, "libcurl easy handle removal failed: %s",
+					   curl_multi_strerror(err));
+			return PGRES_POLLING_FAILED;
+		}
+
+		done = true;
+	}
+
+	/* Sanity check. */
+	if (!done)
+	{
+		actx_error(actx, "no result was retrieved for the finished handle");
+		return PGRES_POLLING_FAILED;
+	}
+
+	return PGRES_POLLING_OK;
+}
+
+/*
+ * URL-Encoding Helpers
+ */
+
+/*
+ * Encodes a string using the application/x-www-form-urlencoded format, and
+ * appends it to the given buffer.
+ */
+static void
+append_urlencoded(PQExpBuffer buf, const char *s)
+{
+	char	   *escaped;
+	char	   *haystack;
+	char	   *match;
+
+	/* The first parameter to curl_easy_escape is deprecated by Curl */
+	escaped = curl_easy_escape(NULL, s, 0);
+	if (!escaped)
+	{
+		termPQExpBuffer(buf);	/* mark the buffer broken */
+		return;
+	}
+
+	/*
+	 * curl_easy_escape() almost does what we want, but we need the
+	 * query-specific flavor which uses '+' instead of '%20' for spaces. The
+	 * Curl command-line tool does this with a simple search-and-replace, so
+	 * follow its lead.
+	 */
+	haystack = escaped;
+
+	while ((match = strstr(haystack, "%20")) != NULL)
+	{
+		/* Append the unmatched portion, followed by the plus sign. */
+		appendBinaryPQExpBuffer(buf, haystack, match - haystack);
+		appendPQExpBufferChar(buf, '+');
+
+		/* Keep searching after the match. */
+		haystack = match + 3 /* strlen("%20") */ ;
+	}
+
+	/* Push the remainder of the string onto the buffer. */
+	appendPQExpBufferStr(buf, haystack);
+
+	curl_free(escaped);
+}
+
+/*
+ * Convenience wrapper for encoding a single string. Returns NULL on allocation
+ * failure.
+ */
+static char *
+urlencode(const char *s)
+{
+	PQExpBufferData buf;
+
+	initPQExpBuffer(&buf);
+	append_urlencoded(&buf, s);
+
+	return PQExpBufferDataBroken(buf) ? NULL : buf.data;
+}
+
+/*
+ * Appends a key/value pair to the end of an application/x-www-form-urlencoded
+ * list.
+ */
+static void
+build_urlencoded(PQExpBuffer buf, const char *key, const char *value)
+{
+	if (buf->len)
+		appendPQExpBufferChar(buf, '&');
+
+	append_urlencoded(buf, key);
+	appendPQExpBufferChar(buf, '=');
+	append_urlencoded(buf, value);
+}
+
+/*
+ * Specific HTTP Request Handlers
+ *
+ * This is finally the beginning of the actual application logic. Generally
+ * speaking, a single request consists of a start_* and a finish_* step, with
+ * drive_request() pumping the machine in between.
+ */
+
+/*
+ * Queue an OpenID Provider Configuration Request:
+ *
+ *     https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest
+ *     https://www.rfc-editor.org/rfc/rfc8414#section-3.1
+ *
+ * This is done first to get the endpoint URIs we need to contact and to make
+ * sure the provider provides a device authorization flow. finish_discovery()
+ * will fill in actx->provider.
+ */
+static bool
+start_discovery(struct async_ctx *actx, const char *discovery_uri)
+{
+	CHECK_SETOPT(actx, CURLOPT_HTTPGET, 1L, return false);
+	CHECK_SETOPT(actx, CURLOPT_URL, discovery_uri, return false);
+
+	return start_request(actx);
+}
+
+static bool
+finish_discovery(struct async_ctx *actx)
+{
+	long		response_code;
+
+	/*----
+	 * Now check the response. OIDC Discovery 1.0 is pretty strict:
+	 *
+	 *     A successful response MUST use the 200 OK HTTP status code and
+	 *     return a JSON object using the application/json content type that
+	 *     contains a set of Claims as its members that are a subset of the
+	 *     Metadata values defined in Section 3.
+	 *
+	 * Compared to standard HTTP semantics, this makes life easy -- we don't
+	 * need to worry about redirections (which would call the Issuer host
+	 * validation into question), or non-authoritative responses, or any other
+	 * complications.
+	 */
+	CHECK_GETINFO(actx, CURLINFO_RESPONSE_CODE, &response_code, return false);
+
+	if (response_code != 200)
+	{
+		actx_error(actx, "unexpected response code %ld", response_code);
+		return false;
+	}
+
+	/*
+	 * Pull the fields we care about from the document.
+	 */
+	actx->errctx = "failed to parse OpenID discovery document";
+	if (!parse_provider(actx, &actx->provider))
+		return false;			/* error message already set */
+
+	/*
+	 * Fill in any defaults for OPTIONAL/RECOMMENDED fields we care about.
+	 */
+	if (!actx->provider.grant_types_supported)
+	{
+		/*
+		 * Per Section 3, the default is ["authorization_code", "implicit"].
+		 */
+		struct curl_slist *temp = actx->provider.grant_types_supported;
+
+		temp = curl_slist_append(temp, "authorization_code");
+		if (temp)
+		{
+			temp = curl_slist_append(temp, "implicit");
+		}
+
+		if (!temp)
+		{
+			actx_error(actx, "out of memory");
+			return false;
+		}
+
+		actx->provider.grant_types_supported = temp;
+	}
+
+	return true;
+}
+
+/*
+ * Ensure that the discovery document is provided by the expected issuer.
+ * Currently, issuers are statically configured in the connection string.
+ */
+static bool
+check_issuer(struct async_ctx *actx, PGconn *conn)
+{
+	const struct provider *provider = &actx->provider;
+
+	Assert(conn->oauth_issuer_id);	/* ensured by setup_oauth_parameters() */
+	Assert(provider->issuer);	/* ensured by parse_provider() */
+
+	/*---
+	 * We require strict equality for issuer identifiers -- no path or case
+	 * normalization, no substitution of default ports and schemes, etc. This
+	 * is done to match the rules in OIDC Discovery Sec. 4.3 for config
+	 * validation:
+	 *
+	 *    The issuer value returned MUST be identical to the Issuer URL that
+	 *    was used as the prefix to /.well-known/openid-configuration to
+	 *    retrieve the configuration information.
+	 *
+	 * as well as the rules set out in RFC 9207 for avoiding mix-up attacks:
+	 *
+	 *    Clients MUST then [...] compare the result to the issuer identifier
+	 *    of the authorization server where the authorization request was
+	 *    sent to. This comparison MUST use simple string comparison as defined
+	 *    in Section 6.2.1 of [RFC3986].
+	 */
+	if (strcmp(conn->oauth_issuer_id, provider->issuer) != 0)
+	{
+		actx_error(actx,
+				   "the issuer identifier (%s) does not match oauth_issuer (%s)",
+				   provider->issuer, conn->oauth_issuer_id);
+		return false;
+	}
+
+	return true;
+}
+
+#define HTTPS_SCHEME "https://"
+#define OAUTH_GRANT_TYPE_DEVICE_CODE "urn:ietf:params:oauth:grant-type:device_code"
+
+/*
+ * Ensure that the provider supports the Device Authorization flow (i.e. it
+ * provides an authorization endpoint, and both the token and authorization
+ * endpoint URLs seem reasonable).
+ */
+static bool
+check_for_device_flow(struct async_ctx *actx)
+{
+	const struct provider *provider = &actx->provider;
+
+	Assert(provider->issuer);	/* ensured by parse_provider() */
+	Assert(provider->token_endpoint);	/* ensured by parse_provider() */
+
+	if (!provider->device_authorization_endpoint)
+	{
+		actx_error(actx,
+				   "issuer \"%s\" does not provide a device authorization endpoint",
+				   provider->issuer);
+		return false;
+	}
+
+	/*
+	 * The original implementation checked that OAUTH_GRANT_TYPE_DEVICE_CODE
+	 * was present in the discovery document's grant_types_supported list. MS
+	 * Entra does not advertise this grant type, though, and since it doesn't
+	 * make sense to stand up a device_authorization_endpoint without also
+	 * accepting device codes at the token_endpoint, that's the only thing we
+	 * currently require.
+	 */
+
+	/*
+	 * Although libcurl will fail later if the URL contains an unsupported
+	 * scheme, that error message is going to be a bit opaque. This is a
+	 * decent time to bail out if we're not using HTTPS for the endpoints
+	 * we'll use for the flow.
+	 */
+	if (!actx->debugging)
+	{
+		if (pg_strncasecmp(provider->device_authorization_endpoint,
+						   HTTPS_SCHEME, strlen(HTTPS_SCHEME)) != 0)
+		{
+			actx_error(actx,
+					   "device authorization endpoint \"%s\" must use HTTPS",
+					   provider->device_authorization_endpoint);
+			return false;
+		}
+
+		if (pg_strncasecmp(provider->token_endpoint,
+						   HTTPS_SCHEME, strlen(HTTPS_SCHEME)) != 0)
+		{
+			actx_error(actx,
+					   "token endpoint \"%s\" must use HTTPS",
+					   provider->token_endpoint);
+			return false;
+		}
+	}
+
+	return true;
+}
+
+/*
+ * Adds the client ID (and secret, if provided) to the current request, using
+ * either HTTP headers or the request body.
+ */
+static bool
+add_client_identification(struct async_ctx *actx, PQExpBuffer reqbody, PGconn *conn)
+{
+	bool		success = false;
+	char	   *username = NULL;
+	char	   *password = NULL;
+
+	if (conn->oauth_client_secret)	/* Zero-length secrets are permitted! */
+	{
+		/*----
+		 * Use HTTP Basic auth to send the client_id and secret. Per RFC 6749,
+		 * Sec. 2.3.1,
+		 *
+		 *   Including the client credentials in the request-body using the
+		 *   two parameters is NOT RECOMMENDED and SHOULD be limited to
+		 *   clients unable to directly utilize the HTTP Basic authentication
+		 *   scheme (or other password-based HTTP authentication schemes).
+		 *
+		 * Additionally:
+		 *
+		 *   The client identifier is encoded using the
+		 *   "application/x-www-form-urlencoded" encoding algorithm per Appendix
+		 *   B, and the encoded value is used as the username; the client
+		 *   password is encoded using the same algorithm and used as the
+		 *   password.
+		 *
+		 * (Appendix B modifies application/x-www-form-urlencoded by requiring
+		 * an initial UTF-8 encoding step. Since the client ID and secret must
+		 * both be 7-bit ASCII -- RFC 6749 Appendix A -- we don't worry about
+		 * that in this function.)
+		 *
+		 * client_id is not added to the request body in this case. Not only
+		 * would it be redundant, but some providers in the wild (e.g. Okta)
+		 * refuse to accept it.
+		 */
+		username = urlencode(conn->oauth_client_id);
+		password = urlencode(conn->oauth_client_secret);
+
+		if (!username || !password)
+		{
+			actx_error(actx, "out of memory");
+			goto cleanup;
+		}
+
+		CHECK_SETOPT(actx, CURLOPT_HTTPAUTH, CURLAUTH_BASIC, goto cleanup);
+		CHECK_SETOPT(actx, CURLOPT_USERNAME, username, goto cleanup);
+		CHECK_SETOPT(actx, CURLOPT_PASSWORD, password, goto cleanup);
+
+		actx->used_basic_auth = true;
+	}
+	else
+	{
+		/*
+		 * If we're not otherwise authenticating, client_id is REQUIRED in the
+		 * request body.
+		 */
+		build_urlencoded(reqbody, "client_id", conn->oauth_client_id);
+
+		CHECK_SETOPT(actx, CURLOPT_HTTPAUTH, CURLAUTH_NONE, goto cleanup);
+		actx->used_basic_auth = false;
+	}
+
+	success = true;
+
+cleanup:
+	free(username);
+	free(password);
+
+	return success;
+}
+
+/*
+ * Queue a Device Authorization Request:
+ *
+ *     https://www.rfc-editor.org/rfc/rfc8628#section-3.1
+ *
+ * This is the second step. We ask the provider to verify the end user out of
+ * band and authorize us to act on their behalf; it will give us the required
+ * nonces for us to later poll the request status, which we'll grab in
+ * finish_device_authz().
+ */
+static bool
+start_device_authz(struct async_ctx *actx, PGconn *conn)
+{
+	const char *device_authz_uri = actx->provider.device_authorization_endpoint;
+	PQExpBuffer work_buffer = &actx->work_data;
+
+	Assert(conn->oauth_client_id);	/* ensured by setup_oauth_parameters() */
+	Assert(device_authz_uri);	/* ensured by check_for_device_flow() */
+
+	/* Construct our request body. */
+	resetPQExpBuffer(work_buffer);
+	if (conn->oauth_scope && conn->oauth_scope[0])
+		build_urlencoded(work_buffer, "scope", conn->oauth_scope);
+
+	if (!add_client_identification(actx, work_buffer, conn))
+		return false;
+
+	if (PQExpBufferBroken(work_buffer))
+	{
+		actx_error(actx, "out of memory");
+		return false;
+	}
+
+	/* Make our request. */
+	CHECK_SETOPT(actx, CURLOPT_URL, device_authz_uri, return false);
+	CHECK_SETOPT(actx, CURLOPT_COPYPOSTFIELDS, work_buffer->data, return false);
+
+	return start_request(actx);
+}
+
+static bool
+finish_device_authz(struct async_ctx *actx)
+{
+	long		response_code;
+
+	CHECK_GETINFO(actx, CURLINFO_RESPONSE_CODE, &response_code, return false);
+
+	/*
+	 * Per RFC 8628, Section 3, a successful device authorization response
+	 * uses 200 OK.
+	 */
+	if (response_code == 200)
+	{
+		actx->errctx = "failed to parse device authorization";
+		if (!parse_device_authz(actx, &actx->authz))
+			return false;		/* error message already set */
+
+		return true;
+	}
+
+	/*
+	 * The device authorization endpoint uses the same error response as the
+	 * token endpoint, so the error handling roughly follows
+	 * finish_token_request(). The key difference is that an error here is
+	 * immediately fatal.
+	 */
+	if (response_code == 400 || response_code == 401)
+	{
+		struct token_error err = {0};
+
+		if (!parse_token_error(actx, &err))
+		{
+			free_token_error(&err);
+			return false;
+		}
+
+		/* Copy the token error into the context error buffer */
+		record_token_error(actx, &err);
+
+		free_token_error(&err);
+		return false;
+	}
+
+	/* Any other response codes are considered invalid */
+	actx_error(actx, "unexpected response code %ld", response_code);
+	return false;
+}
+
+/*
+ * Queue an Access Token Request:
+ *
+ *     https://www.rfc-editor.org/rfc/rfc6749#section-4.1.3
+ *
+ * This is the final step. We continually poll the token endpoint to see if the
+ * user has authorized us yet. finish_token_request() will pull either the token
+ * or a (ideally temporary) error status from the provider.
+ */
+static bool
+start_token_request(struct async_ctx *actx, PGconn *conn)
+{
+	const char *token_uri = actx->provider.token_endpoint;
+	const char *device_code = actx->authz.device_code;
+	PQExpBuffer work_buffer = &actx->work_data;
+
+	Assert(conn->oauth_client_id);	/* ensured by setup_oauth_parameters() */
+	Assert(token_uri);			/* ensured by parse_provider() */
+	Assert(device_code);		/* ensured by parse_device_authz() */
+
+	/* Construct our request body. */
+	resetPQExpBuffer(work_buffer);
+	build_urlencoded(work_buffer, "device_code", device_code);
+	build_urlencoded(work_buffer, "grant_type", OAUTH_GRANT_TYPE_DEVICE_CODE);
+
+	if (!add_client_identification(actx, work_buffer, conn))
+		return false;
+
+	if (PQExpBufferBroken(work_buffer))
+	{
+		actx_error(actx, "out of memory");
+		return false;
+	}
+
+	/* Make our request. */
+	CHECK_SETOPT(actx, CURLOPT_URL, token_uri, return false);
+	CHECK_SETOPT(actx, CURLOPT_COPYPOSTFIELDS, work_buffer->data, return false);
+
+	return start_request(actx);
+}
+
+static bool
+finish_token_request(struct async_ctx *actx, struct token *tok)
+{
+	long		response_code;
+
+	CHECK_GETINFO(actx, CURLINFO_RESPONSE_CODE, &response_code, return false);
+
+	/*
+	 * Per RFC 6749, Section 5, a successful response uses 200 OK.
+	 */
+	if (response_code == 200)
+	{
+		actx->errctx = "failed to parse access token response";
+		if (!parse_access_token(actx, tok))
+			return false;		/* error message already set */
+
+		return true;
+	}
+
+	/*
+	 * An error response uses either 400 Bad Request or 401 Unauthorized.
+	 * There are references online to implementations using 403 for error
+	 * return which would violate the specification. For now we stick to the
+	 * specification but we might have to revisit this.
+	 */
+	if (response_code == 400 || response_code == 401)
+	{
+		if (!parse_token_error(actx, &tok->err))
+			return false;
+
+		return true;
+	}
+
+	/* Any other response codes are considered invalid */
+	actx_error(actx, "unexpected response code %ld", response_code);
+	return false;
+}
+
+/*
+ * Finishes the token request and examines the response. If the flow has
+ * completed, a valid token will be returned via the parameter list. Otherwise,
+ * the token parameter remains unchanged, and the caller needs to wait for
+ * another interval (which will have been increased in response to a slow_down
+ * message from the server) before starting a new token request.
+ *
+ * False is returned only for permanent error conditions.
+ */
+static bool
+handle_token_response(struct async_ctx *actx, char **token)
+{
+	bool		success = false;
+	struct token tok = {0};
+	const struct token_error *err;
+
+	if (!finish_token_request(actx, &tok))
+		goto token_cleanup;
+
+	/* A successful token request gives either a token or an in-band error. */
+	Assert(tok.access_token || tok.err.error);
+
+	if (tok.access_token)
+	{
+		*token = tok.access_token;
+		tok.access_token = NULL;
+
+		success = true;
+		goto token_cleanup;
+	}
+
+	/*
+	 * authorization_pending and slow_down are the only acceptable errors;
+	 * anything else and we bail. These are defined in RFC 8628, Sec. 3.5.
+	 */
+	err = &tok.err;
+	if (strcmp(err->error, "authorization_pending") != 0 &&
+		strcmp(err->error, "slow_down") != 0)
+	{
+		record_token_error(actx, err);
+		goto token_cleanup;
+	}
+
+	/*
+	 * A slow_down error requires us to permanently increase our retry
+	 * interval by five seconds.
+	 */
+	if (strcmp(err->error, "slow_down") == 0)
+	{
+		int			prev_interval = actx->authz.interval;
+
+		actx->authz.interval += 5;
+		if (actx->authz.interval < prev_interval)
+		{
+			actx_error(actx, "slow_down interval overflow");
+			goto token_cleanup;
+		}
+	}
+
+	success = true;
+
+token_cleanup:
+	free_token(&tok);
+	return success;
+}
+
+/*
+ * Displays a device authorization prompt for action by the end user, either via
+ * the PQauthDataHook, or by a message on standard error if no hook is set.
+ */
+static bool
+prompt_user(struct async_ctx *actx, PGconn *conn)
+{
+	int			res;
+	PGpromptOAuthDevice prompt = {
+		.verification_uri = actx->authz.verification_uri,
+		.user_code = actx->authz.user_code,
+		.verification_uri_complete = actx->authz.verification_uri_complete,
+		.expires_in = actx->authz.expires_in,
+	};
+
+	res = PQauthDataHook(PQAUTHDATA_PROMPT_OAUTH_DEVICE, conn, &prompt);
+
+	if (!res)
+	{
+		/*
+		 * translator: The first %s is a URL for the user to visit in a
+		 * browser, and the second %s is a code to be copy-pasted there.
+		 */
+		fprintf(stderr, libpq_gettext("Visit %s and enter the code: %s\n"),
+				prompt.verification_uri, prompt.user_code);
+	}
+	else if (res < 0)
+	{
+		actx_error(actx, "device prompt failed");
+		return false;
+	}
+
+	return true;
+}
+
+/*
+ * Calls curl_global_init() in a thread-safe way.
+ *
+ * libcurl has stringent requirements for the thread context in which you call
+ * curl_global_init(), because it's going to try initializing a bunch of other
+ * libraries (OpenSSL, Winsock, etc). Recent versions of libcurl have improved
+ * the thread-safety situation, but there's a chicken-and-egg problem at
+ * runtime: you can't check the thread safety until you've initialized libcurl,
+ * which you can't do from within a thread unless you know it's thread-safe...
+ *
+ * Returns true if initialization was successful. Successful or not, this
+ * function will not try to reinitialize Curl on successive calls.
+ */
+static bool
+initialize_curl(PGconn *conn)
+{
+	/*
+	 * Don't let the compiler play tricks with this variable. In the
+	 * HAVE_THREADSAFE_CURL_GLOBAL_INIT case, we don't care if two threads
+	 * enter simultaneously, but we do care if this gets set transiently to
+	 * PG_BOOL_YES/NO in cases where that's not the final answer.
+	 */
+	static volatile PGTernaryBool init_successful = PG_BOOL_UNKNOWN;
+#if HAVE_THREADSAFE_CURL_GLOBAL_INIT
+	curl_version_info_data *info;
+#endif
+
+#if !HAVE_THREADSAFE_CURL_GLOBAL_INIT
+
+	/*
+	 * Lock around the whole function. If a libpq client performs its own work
+	 * with libcurl, it must either ensure that Curl is initialized safely
+	 * before calling us (in which case our call will be a no-op), or else it
+	 * must guard its own calls to curl_global_init() with a registered
+	 * threadlock handler. See PQregisterThreadLock().
+	 */
+	pglock_thread();
+#endif
+
+	/*
+	 * Skip initialization if we've already done it. (Curl tracks the number
+	 * of calls; there's no point in incrementing the counter every time we
+	 * connect.)
+	 */
+	if (init_successful == PG_BOOL_YES)
+		goto done;
+	else if (init_successful == PG_BOOL_NO)
+	{
+		libpq_append_conn_error(conn,
+								"curl_global_init previously failed during OAuth setup");
+		goto done;
+	}
+
+	/*
+	 * We know we've already initialized Winsock by this point (see
+	 * pqMakeEmptyPGconn()), so we should be able to safely skip that bit. But
+	 * we have to tell libcurl to initialize everything else, because other
+	 * pieces of our client executable may already be using libcurl for their
+	 * own purposes. If we initialize libcurl with only a subset of its
+	 * features, we could break those other clients nondeterministically, and
+	 * that would probably be a nightmare to debug.
+	 *
+	 * If some other part of the program has already called this, it's a
+	 * no-op.
+	 */
+	if (curl_global_init(CURL_GLOBAL_ALL & ~CURL_GLOBAL_WIN32) != CURLE_OK)
+	{
+		libpq_append_conn_error(conn,
+								"curl_global_init failed during OAuth setup");
+		init_successful = PG_BOOL_NO;
+		goto done;
+	}
+
+#if HAVE_THREADSAFE_CURL_GLOBAL_INIT
+
+	/*
+	 * If we determined at configure time that the Curl installation is
+	 * thread-safe, our job here is much easier. We simply initialize above
+	 * without any locking (concurrent or duplicated calls are fine in that
+	 * situation), then double-check to make sure the runtime setting agrees,
+	 * to try to catch silent downgrades.
+	 */
+	info = curl_version_info(CURLVERSION_NOW);
+	if (!(info->features & CURL_VERSION_THREADSAFE))
+	{
+		/*
+		 * In a downgrade situation, the damage is already done. Curl global
+		 * state may be corrupted. Be noisy.
+		 */
+		libpq_append_conn_error(conn, "libcurl is no longer thread-safe\n"
+								"\tCurl initialization was reported thread-safe when libpq\n"
+								"\twas compiled, but the currently installed version of\n"
+								"\tlibcurl reports that it is not. Recompile libpq against\n"
+								"\tthe installed version of libcurl.");
+		init_successful = PG_BOOL_NO;
+		goto done;
+	}
+#endif
+
+	init_successful = PG_BOOL_YES;
+
+done:
+#if !HAVE_THREADSAFE_CURL_GLOBAL_INIT
+	pgunlock_thread();
+#endif
+	return (init_successful == PG_BOOL_YES);
+}
+
+/*
+ * The core nonblocking libcurl implementation. This will be called several
+ * times to pump the async engine.
+ *
+ * The architecture is based on PQconnectPoll(). The first half drives the
+ * connection state forward as necessary, returning if we're not ready to
+ * proceed to the next step yet. The second half performs the actual transition
+ * between states.
+ *
+ * You can trace the overall OAuth flow through the second half. It's linear
+ * until we get to the end, where we flip back and forth between
+ * OAUTH_STEP_TOKEN_REQUEST and OAUTH_STEP_WAIT_INTERVAL to regularly ping the
+ * provider.
+ */
+static PostgresPollingStatusType
+pg_fe_run_oauth_flow_impl(PGconn *conn)
+{
+	fe_oauth_state *state = conn->sasl_state;
+	struct async_ctx *actx;
+
+	if (!initialize_curl(conn))
+		return PGRES_POLLING_FAILED;
+
+	if (!state->async_ctx)
+	{
+		/*
+		 * Create our asynchronous state, and hook it into the upper-level
+		 * OAuth state immediately, so any failures below won't leak the
+		 * context allocation.
+		 */
+		actx = calloc(1, sizeof(*actx));
+		if (!actx)
+		{
+			libpq_append_conn_error(conn, "out of memory");
+			return PGRES_POLLING_FAILED;
+		}
+
+		actx->mux = PGINVALID_SOCKET;
+		actx->timerfd = -1;
+
+		/* Should we enable unsafe features? */
+		actx->debugging = oauth_unsafe_debugging_enabled();
+
+		state->async_ctx = actx;
+
+		initPQExpBuffer(&actx->work_data);
+		initPQExpBuffer(&actx->errbuf);
+
+		if (!setup_multiplexer(actx))
+			goto error_return;
+
+		if (!setup_curl_handles(actx))
+			goto error_return;
+	}
+
+	actx = state->async_ctx;
+
+	do
+	{
+		/* By default, the multiplexer is the altsock. Reassign as desired. */
+		conn->altsock = actx->mux;
+
+		switch (actx->step)
+		{
+			case OAUTH_STEP_INIT:
+				break;
+
+			case OAUTH_STEP_DISCOVERY:
+			case OAUTH_STEP_DEVICE_AUTHORIZATION:
+			case OAUTH_STEP_TOKEN_REQUEST:
+				{
+					PostgresPollingStatusType status;
+
+					status = drive_request(actx);
+
+					if (status == PGRES_POLLING_FAILED)
+						goto error_return;
+					else if (status != PGRES_POLLING_OK)
+					{
+						/* not done yet */
+						return status;
+					}
+
+					break;
+				}
+
+			case OAUTH_STEP_WAIT_INTERVAL:
+
+				/*
+				 * The client application is supposed to wait until our timer
+				 * expires before calling PQconnectPoll() again, but that
+				 * might not happen. To avoid sending a token request early,
+				 * check the timer before continuing.
+				 */
+				if (!timer_expired(actx))
+				{
+					conn->altsock = actx->timerfd;
+					return PGRES_POLLING_READING;
+				}
+
+				/* Disable the expired timer. */
+				if (!set_timer(actx, -1))
+					goto error_return;
+
+				break;
+		}
+
+		/*
+		 * Each case here must ensure that actx->running is set while we're
+		 * waiting on some asynchronous work. Most cases rely on
+		 * start_request() to do that for them.
+		 */
+		switch (actx->step)
+		{
+			case OAUTH_STEP_INIT:
+				actx->errctx = "failed to fetch OpenID discovery document";
+				if (!start_discovery(actx, conn->oauth_discovery_uri))
+					goto error_return;
+
+				actx->step = OAUTH_STEP_DISCOVERY;
+				break;
+
+			case OAUTH_STEP_DISCOVERY:
+				if (!finish_discovery(actx))
+					goto error_return;
+
+				if (!check_issuer(actx, conn))
+					goto error_return;
+
+				actx->errctx = "cannot run OAuth device authorization";
+				if (!check_for_device_flow(actx))
+					goto error_return;
+
+				actx->errctx = "failed to obtain device authorization";
+				if (!start_device_authz(actx, conn))
+					goto error_return;
+
+				actx->step = OAUTH_STEP_DEVICE_AUTHORIZATION;
+				break;
+
+			case OAUTH_STEP_DEVICE_AUTHORIZATION:
+				if (!finish_device_authz(actx))
+					goto error_return;
+
+				actx->errctx = "failed to obtain access token";
+				if (!start_token_request(actx, conn))
+					goto error_return;
+
+				actx->step = OAUTH_STEP_TOKEN_REQUEST;
+				break;
+
+			case OAUTH_STEP_TOKEN_REQUEST:
+				if (!handle_token_response(actx, &conn->oauth_token))
+					goto error_return;
+
+				if (!actx->user_prompted)
+				{
+					/*
+					 * Now that we know the token endpoint isn't broken, give
+					 * the user the login instructions.
+					 */
+					if (!prompt_user(actx, conn))
+						goto error_return;
+
+					actx->user_prompted = true;
+				}
+
+				if (conn->oauth_token)
+					break;		/* done! */
+
+				/*
+				 * Wait for the required interval before issuing the next
+				 * request.
+				 */
+				if (!set_timer(actx, actx->authz.interval * 1000))
+					goto error_return;
+
+				/*
+				 * No Curl requests are running, so we can simplify by having
+				 * the client wait directly on the timerfd rather than the
+				 * multiplexer.
+				 */
+				conn->altsock = actx->timerfd;
+
+				actx->step = OAUTH_STEP_WAIT_INTERVAL;
+				actx->running = 1;
+				break;
+
+			case OAUTH_STEP_WAIT_INTERVAL:
+				actx->errctx = "failed to obtain access token";
+				if (!start_token_request(actx, conn))
+					goto error_return;
+
+				actx->step = OAUTH_STEP_TOKEN_REQUEST;
+				break;
+		}
+
+		/*
+		 * The vast majority of the time, if we don't have a token at this
+		 * point, actx->running will be set. But there are some corner cases
+		 * where we can immediately loop back around; see start_request().
+		 */
+	} while (!conn->oauth_token && !actx->running);
+
+	/* If we've stored a token, we're done. Otherwise come back later. */
+	return conn->oauth_token ? PGRES_POLLING_OK : PGRES_POLLING_READING;
+
+error_return:
+
+	/*
+	 * Assemble the three parts of our error: context, body, and detail. See
+	 * also the documentation for struct async_ctx.
+	 */
+	if (actx->errctx)
+	{
+		appendPQExpBufferStr(&conn->errorMessage,
+							 libpq_gettext(actx->errctx));
+		appendPQExpBufferStr(&conn->errorMessage, ": ");
+	}
+
+	if (PQExpBufferDataBroken(actx->errbuf))
+		appendPQExpBufferStr(&conn->errorMessage,
+							 libpq_gettext("out of memory"));
+	else
+		appendPQExpBufferStr(&conn->errorMessage, actx->errbuf.data);
+
+	if (actx->curl_err[0])
+	{
+		size_t		len;
+
+		appendPQExpBuffer(&conn->errorMessage,
+						  " (libcurl: %s)", actx->curl_err);
+
+		/* Sometimes libcurl adds a newline to the error buffer. :( */
+		len = conn->errorMessage.len;
+		if (len >= 2 && conn->errorMessage.data[len - 2] == '\n')
+		{
+			conn->errorMessage.data[len - 2] = ')';
+			conn->errorMessage.data[len - 1] = '\0';
+			conn->errorMessage.len--;
+		}
+	}
+
+	appendPQExpBufferStr(&conn->errorMessage, "\n");
+
+	return PGRES_POLLING_FAILED;
+}
+
+/*
+ * The top-level entry point. This is a convenient place to put necessary
+ * wrapper logic before handing off to the true implementation, above.
+ */
+PostgresPollingStatusType
+pg_fe_run_oauth_flow(PGconn *conn)
+{
+	PostgresPollingStatusType result;
+#ifndef WIN32
+	sigset_t	osigset;
+	bool		sigpipe_pending;
+	bool		masked;
+
+	/*---
+	 * Ignore SIGPIPE on this thread during all Curl processing.
+	 *
+	 * Because we support multiple threads, we have to set up libcurl with
+	 * CURLOPT_NOSIGNAL, which disables its default global handling of
+	 * SIGPIPE. From the Curl docs:
+	 *
+	 *     libcurl makes an effort to never cause such SIGPIPE signals to
+	 *     trigger, but some operating systems have no way to avoid them and
+	 *     even on those that have there are some corner cases when they may
+	 *     still happen, contrary to our desire.
+	 *
+	 * Note that libcurl is also at the mercy of its DNS resolution and SSL
+	 * libraries; if any of them forget a MSG_NOSIGNAL then we're in trouble.
+	 * Modern platforms and libraries seem to get it right, so this is a
+	 * difficult corner case to exercise in practice, and unfortunately it's
+	 * not really clear whether it's necessary in all cases.
+	 */
+	masked = (pq_block_sigpipe(&osigset, &sigpipe_pending) == 0);
+#endif
+
+	result = pg_fe_run_oauth_flow_impl(conn);
+
+#ifndef WIN32
+	if (masked)
+	{
+		/*
+		 * Undo the SIGPIPE mask. Assume we may have gotten EPIPE (we have no
+		 * way of knowing at this level).
+		 */
+		pq_reset_sigpipe(&osigset, sigpipe_pending, true /* EPIPE, maybe */ );
+	}
+#endif
+
+	return result;
+}
diff --git a/src/interfaces/libpq/fe-auth-oauth.c b/src/interfaces/libpq/fe-auth-oauth.c
new file mode 100644
index 00000000000..fb1e9a1a8aa
--- /dev/null
+++ b/src/interfaces/libpq/fe-auth-oauth.c
@@ -0,0 +1,1163 @@
+/*-------------------------------------------------------------------------
+ *
+ * fe-auth-oauth.c
+ *	   The front-end (client) implementation of OAuth/OIDC authentication
+ *	   using the SASL OAUTHBEARER mechanism.
+ *
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1994, Regents of the University of California
+ *
+ * IDENTIFICATION
+ *	  src/interfaces/libpq/fe-auth-oauth.c
+ *
+ *-------------------------------------------------------------------------
+ */
+
+#include "postgres_fe.h"
+
+#include "common/base64.h"
+#include "common/hmac.h"
+#include "common/jsonapi.h"
+#include "common/oauth-common.h"
+#include "fe-auth.h"
+#include "fe-auth-oauth.h"
+#include "mb/pg_wchar.h"
+
+/* The exported OAuth callback mechanism. */
+static void *oauth_init(PGconn *conn, const char *password,
+						const char *sasl_mechanism);
+static SASLStatus oauth_exchange(void *opaq, bool final,
+								 char *input, int inputlen,
+								 char **output, int *outputlen);
+static bool oauth_channel_bound(void *opaq);
+static void oauth_free(void *opaq);
+
+const pg_fe_sasl_mech pg_oauth_mech = {
+	oauth_init,
+	oauth_exchange,
+	oauth_channel_bound,
+	oauth_free,
+};
+
+/*
+ * Initializes mechanism state for OAUTHBEARER.
+ *
+ * For a full description of the API, see libpq/fe-auth-sasl.h.
+ */
+static void *
+oauth_init(PGconn *conn, const char *password,
+		   const char *sasl_mechanism)
+{
+	fe_oauth_state *state;
+
+	/*
+	 * We only support one SASL mechanism here; anything else is programmer
+	 * error.
+	 */
+	Assert(sasl_mechanism != NULL);
+	Assert(strcmp(sasl_mechanism, OAUTHBEARER_NAME) == 0);
+
+	state = calloc(1, sizeof(*state));
+	if (!state)
+		return NULL;
+
+	state->step = FE_OAUTH_INIT;
+	state->conn = conn;
+
+	return state;
+}
+
+/*
+ * Frees the state allocated by oauth_init().
+ *
+ * This handles only mechanism state tied to the connection lifetime; state
+ * stored in state->async_ctx is freed up either immediately after the
+ * authentication handshake succeeds, or before the mechanism is cleaned up on
+ * failure. See pg_fe_cleanup_oauth_flow() and cleanup_user_oauth_flow().
+ */
+static void
+oauth_free(void *opaq)
+{
+	fe_oauth_state *state = opaq;
+
+	/* Any async authentication state should have been cleaned up already. */
+	Assert(!state->async_ctx);
+
+	free(state);
+}
+
+#define kvsep "\x01"
+
+/*
+ * Constructs an OAUTHBEARER client initial response (RFC 7628, Sec. 3.1).
+ *
+ * If discover is true, the initial response will contain a request for the
+ * server's required OAuth parameters (Sec. 4.3). Otherwise, conn->token must
+ * be set; it will be sent as the connection's bearer token.
+ *
+ * Returns the response as a null-terminated string, or NULL on error.
+ */
+static char *
+client_initial_response(PGconn *conn, bool discover)
+{
+	static const char *const resp_format = "n,," kvsep "auth=%s%s" kvsep kvsep;
+
+	PQExpBufferData buf;
+	const char *authn_scheme;
+	char	   *response = NULL;
+	const char *token = conn->oauth_token;
+
+	if (discover)
+	{
+		/* Parameter discovery uses a completely empty auth value. */
+		authn_scheme = token = "";
+	}
+	else
+	{
+		/*
+		 * Use a Bearer authentication scheme (RFC 6750, Sec. 2.1). A trailing
+		 * space is used as a separator.
+		 */
+		authn_scheme = "Bearer ";
+
+		/* conn->token must have been set in this case. */
+		if (!token)
+		{
+			Assert(false);
+			libpq_append_conn_error(conn,
+									"internal error: no OAuth token was set for the connection");
+			return NULL;
+		}
+	}
+
+	initPQExpBuffer(&buf);
+	appendPQExpBuffer(&buf, resp_format, authn_scheme, token);
+
+	if (!PQExpBufferDataBroken(buf))
+		response = strdup(buf.data);
+	termPQExpBuffer(&buf);
+
+	if (!response)
+		libpq_append_conn_error(conn, "out of memory");
+
+	return response;
+}
+
+/*
+ * JSON Parser (for the OAUTHBEARER error result)
+ */
+
+/* Relevant JSON fields in the error result object. */
+#define ERROR_STATUS_FIELD "status"
+#define ERROR_SCOPE_FIELD "scope"
+#define ERROR_OPENID_CONFIGURATION_FIELD "openid-configuration"
+
+struct json_ctx
+{
+	char	   *errmsg;			/* any non-NULL value stops all processing */
+	PQExpBufferData errbuf;		/* backing memory for errmsg */
+	int			nested;			/* nesting level (zero is the top) */
+
+	const char *target_field_name;	/* points to a static allocation */
+	char	  **target_field;	/* see below */
+
+	/* target_field, if set, points to one of the following: */
+	char	   *status;
+	char	   *scope;
+	char	   *discovery_uri;
+};
+
+#define oauth_json_has_error(ctx) \
+	(PQExpBufferDataBroken((ctx)->errbuf) || (ctx)->errmsg)
+
+#define oauth_json_set_error(ctx, ...) \
+	do { \
+		appendPQExpBuffer(&(ctx)->errbuf, __VA_ARGS__); \
+		(ctx)->errmsg = (ctx)->errbuf.data; \
+	} while (0)
+
+static JsonParseErrorType
+oauth_json_object_start(void *state)
+{
+	struct json_ctx *ctx = state;
+
+	if (ctx->target_field)
+	{
+		Assert(ctx->nested == 1);
+
+		oauth_json_set_error(ctx,
+							 libpq_gettext("field \"%s\" must be a string"),
+							 ctx->target_field_name);
+	}
+
+	++ctx->nested;
+	return oauth_json_has_error(ctx) ? JSON_SEM_ACTION_FAILED : JSON_SUCCESS;
+}
+
+static JsonParseErrorType
+oauth_json_object_end(void *state)
+{
+	struct json_ctx *ctx = state;
+
+	--ctx->nested;
+	return JSON_SUCCESS;
+}
+
+static JsonParseErrorType
+oauth_json_object_field_start(void *state, char *name, bool isnull)
+{
+	struct json_ctx *ctx = state;
+
+	/* Only top-level keys are considered. */
+	if (ctx->nested == 1)
+	{
+		if (strcmp(name, ERROR_STATUS_FIELD) == 0)
+		{
+			ctx->target_field_name = ERROR_STATUS_FIELD;
+			ctx->target_field = &ctx->status;
+		}
+		else if (strcmp(name, ERROR_SCOPE_FIELD) == 0)
+		{
+			ctx->target_field_name = ERROR_SCOPE_FIELD;
+			ctx->target_field = &ctx->scope;
+		}
+		else if (strcmp(name, ERROR_OPENID_CONFIGURATION_FIELD) == 0)
+		{
+			ctx->target_field_name = ERROR_OPENID_CONFIGURATION_FIELD;
+			ctx->target_field = &ctx->discovery_uri;
+		}
+	}
+
+	return JSON_SUCCESS;
+}
+
+static JsonParseErrorType
+oauth_json_array_start(void *state)
+{
+	struct json_ctx *ctx = state;
+
+	if (!ctx->nested)
+	{
+		ctx->errmsg = libpq_gettext("top-level element must be an object");
+	}
+	else if (ctx->target_field)
+	{
+		Assert(ctx->nested == 1);
+
+		oauth_json_set_error(ctx,
+							 libpq_gettext("field \"%s\" must be a string"),
+							 ctx->target_field_name);
+	}
+
+	return oauth_json_has_error(ctx) ? JSON_SEM_ACTION_FAILED : JSON_SUCCESS;
+}
+
+static JsonParseErrorType
+oauth_json_scalar(void *state, char *token, JsonTokenType type)
+{
+	struct json_ctx *ctx = state;
+
+	if (!ctx->nested)
+	{
+		ctx->errmsg = libpq_gettext("top-level element must be an object");
+		return JSON_SEM_ACTION_FAILED;
+	}
+
+	if (ctx->target_field)
+	{
+		if (ctx->nested != 1)
+		{
+			/*
+			 * ctx->target_field should not have been set for nested keys.
+			 * Assert and don't continue any further for production builds.
+			 */
+			Assert(false);
+			oauth_json_set_error(ctx,
+								 "internal error: target scalar found at nesting level %d during OAUTHBEARER parsing",
+								 ctx->nested);
+			return JSON_SEM_ACTION_FAILED;
+		}
+
+		/*
+		 * We don't allow duplicate field names; error out if the target has
+		 * already been set.
+		 */
+		if (*ctx->target_field)
+		{
+			oauth_json_set_error(ctx,
+								 libpq_gettext("field \"%s\" is duplicated"),
+								 ctx->target_field_name);
+			return JSON_SEM_ACTION_FAILED;
+		}
+
+		/* The only fields we support are strings. */
+		if (type != JSON_TOKEN_STRING)
+		{
+			oauth_json_set_error(ctx,
+								 libpq_gettext("field \"%s\" must be a string"),
+								 ctx->target_field_name);
+			return JSON_SEM_ACTION_FAILED;
+		}
+
+		*ctx->target_field = strdup(token);
+		if (!*ctx->target_field)
+			return JSON_OUT_OF_MEMORY;
+
+		ctx->target_field = NULL;
+		ctx->target_field_name = NULL;
+	}
+	else
+	{
+		/* otherwise we just ignore it */
+	}
+
+	return JSON_SUCCESS;
+}
+
+#define HTTPS_SCHEME "https://"
+#define HTTP_SCHEME "http://"
+
+/* We support both well-known suffixes defined by RFC 8414. */
+#define WK_PREFIX "/.well-known/"
+#define OPENID_WK_SUFFIX "openid-configuration"
+#define OAUTH_WK_SUFFIX "oauth-authorization-server"
+
+/*
+ * Derives an issuer identifier from one of our recognized .well-known URIs,
+ * using the rules in RFC 8414.
+ */
+static char *
+issuer_from_well_known_uri(PGconn *conn, const char *wkuri)
+{
+	const char *authority_start = NULL;
+	const char *wk_start;
+	const char *wk_end;
+	char	   *issuer;
+	ptrdiff_t	start_offset,
+				end_offset;
+	size_t		end_len;
+
+	/*
+	 * https:// is required for issuer identifiers (RFC 8414, Sec. 2; OIDC
+	 * Discovery 1.0, Sec. 3). This is a case-insensitive comparison at this
+	 * level (but issuer identifier comparison at the level above this is
+	 * case-sensitive, so in practice it's probably moot).
+	 */
+	if (pg_strncasecmp(wkuri, HTTPS_SCHEME, strlen(HTTPS_SCHEME)) == 0)
+		authority_start = wkuri + strlen(HTTPS_SCHEME);
+
+	if (!authority_start
+		&& oauth_unsafe_debugging_enabled()
+		&& pg_strncasecmp(wkuri, HTTP_SCHEME, strlen(HTTP_SCHEME)) == 0)
+	{
+		/* Allow http:// for testing only. */
+		authority_start = wkuri + strlen(HTTP_SCHEME);
+	}
+
+	if (!authority_start)
+	{
+		libpq_append_conn_error(conn,
+								"OAuth discovery URI \"%s\" must use HTTPS",
+								wkuri);
+		return NULL;
+	}
+
+	/*
+	 * Well-known URIs in general may support queries and fragments, but the
+	 * two types we support here do not. (They must be constructed from the
+	 * components of issuer identifiers, which themselves may not contain any
+	 * queries or fragments.)
+	 *
+	 * It's important to check this first, to avoid getting tricked later by a
+	 * prefix buried inside a query or fragment.
+	 */
+	if (strpbrk(authority_start, "?#") != NULL)
+	{
+		libpq_append_conn_error(conn,
+								"OAuth discovery URI \"%s\" must not contain query or fragment components",
+								wkuri);
+		return NULL;
+	}
+
+	/*
+	 * Find the start of the .well-known prefix. IETF rules (RFC 8615) state
+	 * this must be at the beginning of the path component, but OIDC defined
+	 * it at the end instead (OIDC Discovery 1.0, Sec. 4), so we have to
+	 * search for it anywhere.
+	 */
+	wk_start = strstr(authority_start, WK_PREFIX);
+	if (!wk_start)
+	{
+		libpq_append_conn_error(conn,
+								"OAuth discovery URI \"%s\" is not a .well-known URI",
+								wkuri);
+		return NULL;
+	}
+
+	/*
+	 * Now find the suffix type. We only support the two defined in OIDC
+	 * Discovery 1.0 and RFC 8414.
+	 */
+	wk_end = wk_start + strlen(WK_PREFIX);
+
+	if (strncmp(wk_end, OPENID_WK_SUFFIX, strlen(OPENID_WK_SUFFIX)) == 0)
+		wk_end += strlen(OPENID_WK_SUFFIX);
+	else if (strncmp(wk_end, OAUTH_WK_SUFFIX, strlen(OAUTH_WK_SUFFIX)) == 0)
+		wk_end += strlen(OAUTH_WK_SUFFIX);
+	else
+		wk_end = NULL;
+
+	/*
+	 * Even if there's a match, we still need to check to make sure the suffix
+	 * takes up the entire path segment, to weed out constructions like
+	 * "/.well-known/openid-configuration-bad".
+	 */
+	if (!wk_end || (*wk_end != '/' && *wk_end != '\0'))
+	{
+		libpq_append_conn_error(conn,
+								"OAuth discovery URI \"%s\" uses an unsupported .well-known suffix",
+								wkuri);
+		return NULL;
+	}
+
+	/*
+	 * Finally, make sure the .well-known components are provided either as a
+	 * prefix (IETF style) or as a postfix (OIDC style). In other words,
+	 * "https://localhost/a/.well-known/openid-configuration/b" is not allowed
+	 * to claim association with "https://localhost/a/b".
+	 */
+	if (*wk_end != '\0')
+	{
+		/*
+		 * It's not at the end, so it's required to be at the beginning at the
+		 * path. Find the starting slash.
+		 */
+		const char *path_start;
+
+		path_start = strchr(authority_start, '/');
+		Assert(path_start);		/* otherwise we wouldn't have found WK_PREFIX */
+
+		if (wk_start != path_start)
+		{
+			libpq_append_conn_error(conn,
+									"OAuth discovery URI \"%s\" uses an invalid format",
+									wkuri);
+			return NULL;
+		}
+	}
+
+	/* Checks passed! Now build the issuer. */
+	issuer = strdup(wkuri);
+	if (!issuer)
+	{
+		libpq_append_conn_error(conn, "out of memory");
+		return NULL;
+	}
+
+	/*
+	 * The .well-known components are from [wk_start, wk_end). Remove those to
+	 * form the issuer ID, by shifting the path suffix (which may be empty)
+	 * leftwards.
+	 */
+	start_offset = wk_start - wkuri;
+	end_offset = wk_end - wkuri;
+	end_len = strlen(wk_end) + 1;	/* move the NULL terminator too */
+
+	memmove(issuer + start_offset, issuer + end_offset, end_len);
+
+	return issuer;
+}
+
+/*
+ * Parses the server error result (RFC 7628, Sec. 3.2.2) contained in msg and
+ * stores any discovered openid_configuration and scope settings for the
+ * connection.
+ */
+static bool
+handle_oauth_sasl_error(PGconn *conn, const char *msg, int msglen)
+{
+	JsonLexContext lex = {0};
+	JsonSemAction sem = {0};
+	JsonParseErrorType err;
+	struct json_ctx ctx = {0};
+	char	   *errmsg = NULL;
+	bool		success = false;
+
+	Assert(conn->oauth_issuer_id);	/* ensured by setup_oauth_parameters() */
+
+	/* Sanity check. */
+	if (strlen(msg) != msglen)
+	{
+		libpq_append_conn_error(conn,
+								"server's error message contained an embedded NULL, and was discarded");
+		return false;
+	}
+
+	/*
+	 * pg_parse_json doesn't validate the incoming UTF-8, so we have to check
+	 * that up front.
+	 */
+	if (pg_encoding_verifymbstr(PG_UTF8, msg, msglen) != msglen)
+	{
+		libpq_append_conn_error(conn,
+								"server's error response is not valid UTF-8");
+		return false;
+	}
+
+	makeJsonLexContextCstringLen(&lex, msg, msglen, PG_UTF8, true);
+	setJsonLexContextOwnsTokens(&lex, true);	/* must not leak on error */
+
+	initPQExpBuffer(&ctx.errbuf);
+	sem.semstate = &ctx;
+
+	sem.object_start = oauth_json_object_start;
+	sem.object_end = oauth_json_object_end;
+	sem.object_field_start = oauth_json_object_field_start;
+	sem.array_start = oauth_json_array_start;
+	sem.scalar = oauth_json_scalar;
+
+	err = pg_parse_json(&lex, &sem);
+
+	if (err == JSON_SEM_ACTION_FAILED)
+	{
+		if (PQExpBufferDataBroken(ctx.errbuf))
+			errmsg = libpq_gettext("out of memory");
+		else if (ctx.errmsg)
+			errmsg = ctx.errmsg;
+		else
+		{
+			/*
+			 * Developer error: one of the action callbacks didn't call
+			 * oauth_json_set_error() before erroring out.
+			 */
+			Assert(oauth_json_has_error(&ctx));
+			errmsg = "<unexpected empty error>";
+		}
+	}
+	else if (err != JSON_SUCCESS)
+		errmsg = json_errdetail(err, &lex);
+
+	if (errmsg)
+		libpq_append_conn_error(conn,
+								"failed to parse server's error response: %s",
+								errmsg);
+
+	/* Don't need the error buffer or the JSON lexer anymore. */
+	termPQExpBuffer(&ctx.errbuf);
+	freeJsonLexContext(&lex);
+
+	if (errmsg)
+		goto cleanup;
+
+	if (ctx.discovery_uri)
+	{
+		char	   *discovery_issuer;
+
+		/*
+		 * The URI MUST correspond to our existing issuer, to avoid mix-ups.
+		 *
+		 * Issuer comparison is done byte-wise, rather than performing any URL
+		 * normalization; this follows the suggestions for issuer comparison
+		 * in RFC 9207 Sec. 2.4 (which requires simple string comparison) and
+		 * vastly simplifies things. Since this is the key protection against
+		 * a rogue server sending the client to an untrustworthy location,
+		 * simpler is better.
+		 */
+		discovery_issuer = issuer_from_well_known_uri(conn, ctx.discovery_uri);
+		if (!discovery_issuer)
+			goto cleanup;		/* error message already set */
+
+		if (strcmp(conn->oauth_issuer_id, discovery_issuer) != 0)
+		{
+			libpq_append_conn_error(conn,
+									"server's discovery document at %s (issuer \"%s\") is incompatible with oauth_issuer (%s)",
+									ctx.discovery_uri, discovery_issuer,
+									conn->oauth_issuer_id);
+
+			free(discovery_issuer);
+			goto cleanup;
+		}
+
+		free(discovery_issuer);
+
+		if (!conn->oauth_discovery_uri)
+		{
+			conn->oauth_discovery_uri = ctx.discovery_uri;
+			ctx.discovery_uri = NULL;
+		}
+		else
+		{
+			/* This must match the URI we'd previously determined. */
+			if (strcmp(conn->oauth_discovery_uri, ctx.discovery_uri) != 0)
+			{
+				libpq_append_conn_error(conn,
+										"server's discovery document has moved to %s (previous location was %s)",
+										ctx.discovery_uri,
+										conn->oauth_discovery_uri);
+				goto cleanup;
+			}
+		}
+	}
+
+	if (ctx.scope)
+	{
+		/* Servers may not override a previously set oauth_scope. */
+		if (!conn->oauth_scope)
+		{
+			conn->oauth_scope = ctx.scope;
+			ctx.scope = NULL;
+		}
+	}
+
+	if (!ctx.status)
+	{
+		libpq_append_conn_error(conn,
+								"server sent error response without a status");
+		goto cleanup;
+	}
+
+	if (strcmp(ctx.status, "invalid_token") != 0)
+	{
+		/*
+		 * invalid_token is the only error code we'll automatically retry for;
+		 * otherwise, just bail out now.
+		 */
+		libpq_append_conn_error(conn,
+								"server rejected OAuth bearer token: %s",
+								ctx.status);
+		goto cleanup;
+	}
+
+	success = true;
+
+cleanup:
+	free(ctx.status);
+	free(ctx.scope);
+	free(ctx.discovery_uri);
+
+	return success;
+}
+
+/*
+ * Callback implementation of conn->async_auth() for a user-defined OAuth flow.
+ * Delegates the retrieval of the token to the application's async callback.
+ *
+ * This will be called multiple times as needed; the application is responsible
+ * for setting an altsock to signal and returning the correct PGRES_POLLING_*
+ * statuses for use by PQconnectPoll().
+ */
+static PostgresPollingStatusType
+run_user_oauth_flow(PGconn *conn)
+{
+	fe_oauth_state *state = conn->sasl_state;
+	PGoauthBearerRequest *request = state->async_ctx;
+	PostgresPollingStatusType status;
+
+	if (!request->async)
+	{
+		libpq_append_conn_error(conn,
+								"user-defined OAuth flow provided neither a token nor an async callback");
+		return PGRES_POLLING_FAILED;
+	}
+
+	status = request->async(conn, request, &conn->altsock);
+	if (status == PGRES_POLLING_FAILED)
+	{
+		libpq_append_conn_error(conn, "user-defined OAuth flow failed");
+		return status;
+	}
+	else if (status == PGRES_POLLING_OK)
+	{
+		/*
+		 * We already have a token, so copy it into the conn. (We can't hold
+		 * onto the original string, since it may not be safe for us to free()
+		 * it.)
+		 */
+		if (!request->token)
+		{
+			libpq_append_conn_error(conn,
+									"user-defined OAuth flow did not provide a token");
+			return PGRES_POLLING_FAILED;
+		}
+
+		conn->oauth_token = strdup(request->token);
+		if (!conn->oauth_token)
+		{
+			libpq_append_conn_error(conn, "out of memory");
+			return PGRES_POLLING_FAILED;
+		}
+
+		return PGRES_POLLING_OK;
+	}
+
+	/* The hook wants the client to poll the altsock. Make sure it set one. */
+	if (conn->altsock == PGINVALID_SOCKET)
+	{
+		libpq_append_conn_error(conn,
+								"user-defined OAuth flow did not provide a socket for polling");
+		return PGRES_POLLING_FAILED;
+	}
+
+	return status;
+}
+
+/*
+ * Cleanup callback for the async user flow. Delegates most of its job to the
+ * user-provided cleanup implementation, then disconnects the altsock.
+ */
+static void
+cleanup_user_oauth_flow(PGconn *conn)
+{
+	fe_oauth_state *state = conn->sasl_state;
+	PGoauthBearerRequest *request = state->async_ctx;
+
+	Assert(request);
+
+	if (request->cleanup)
+		request->cleanup(conn, request);
+	conn->altsock = PGINVALID_SOCKET;
+
+	free(request);
+	state->async_ctx = NULL;
+}
+
+/*
+ * Chooses an OAuth client flow for the connection, which will retrieve a Bearer
+ * token for presentation to the server.
+ *
+ * If the application has registered a custom flow handler using
+ * PQAUTHDATA_OAUTH_BEARER_TOKEN, it may either return a token immediately (e.g.
+ * if it has one cached for immediate use), or set up for a series of
+ * asynchronous callbacks which will be managed by run_user_oauth_flow().
+ *
+ * If the default handler is used instead, a Device Authorization flow is used
+ * for the connection if support has been compiled in. (See
+ * fe-auth-oauth-curl.c for implementation details.)
+ *
+ * If neither a custom handler nor the builtin flow is available, the connection
+ * fails here.
+ */
+static bool
+setup_token_request(PGconn *conn, fe_oauth_state *state)
+{
+	int			res;
+	PGoauthBearerRequest request = {
+		.openid_configuration = conn->oauth_discovery_uri,
+		.scope = conn->oauth_scope,
+	};
+
+	Assert(request.openid_configuration);
+
+	/* The client may have overridden the OAuth flow. */
+	res = PQauthDataHook(PQAUTHDATA_OAUTH_BEARER_TOKEN, conn, &request);
+	if (res > 0)
+	{
+		PGoauthBearerRequest *request_copy;
+
+		if (request.token)
+		{
+			/*
+			 * We already have a token, so copy it into the conn. (We can't
+			 * hold onto the original string, since it may not be safe for us
+			 * to free() it.)
+			 */
+			conn->oauth_token = strdup(request.token);
+			if (!conn->oauth_token)
+			{
+				libpq_append_conn_error(conn, "out of memory");
+				goto fail;
+			}
+
+			/* short-circuit */
+			if (request.cleanup)
+				request.cleanup(conn, &request);
+			return true;
+		}
+
+		request_copy = malloc(sizeof(*request_copy));
+		if (!request_copy)
+		{
+			libpq_append_conn_error(conn, "out of memory");
+			goto fail;
+		}
+
+		memcpy(request_copy, &request, sizeof(request));
+
+		conn->async_auth = run_user_oauth_flow;
+		conn->cleanup_async_auth = cleanup_user_oauth_flow;
+		state->async_ctx = request_copy;
+	}
+	else if (res < 0)
+	{
+		libpq_append_conn_error(conn, "user-defined OAuth flow failed");
+		goto fail;
+	}
+	else
+	{
+#if USE_LIBCURL
+		/* Hand off to our built-in OAuth flow. */
+		conn->async_auth = pg_fe_run_oauth_flow;
+		conn->cleanup_async_auth = pg_fe_cleanup_oauth_flow;
+
+#else
+		libpq_append_conn_error(conn, "no custom OAuth flows are available, and libpq was not built with libcurl support");
+		goto fail;
+
+#endif
+	}
+
+	return true;
+
+fail:
+	if (request.cleanup)
+		request.cleanup(conn, &request);
+	return false;
+}
+
+/*
+ * Fill in our issuer identifier (and discovery URI, if possible) using the
+ * connection parameters. If conn->oauth_discovery_uri can't be populated in
+ * this function, it will be requested from the server.
+ */
+static bool
+setup_oauth_parameters(PGconn *conn)
+{
+	/*
+	 * This is the only function that sets conn->oauth_issuer_id. If a
+	 * previous connection attempt has already computed it, don't overwrite it
+	 * or the discovery URI. (There's no reason for them to change once
+	 * they're set, and handle_oauth_sasl_error() will fail the connection if
+	 * the server attempts to switch them on us later.)
+	 */
+	if (conn->oauth_issuer_id)
+		return true;
+
+	/*---
+	 * To talk to a server, we require the user to provide issuer and client
+	 * identifiers.
+	 *
+	 * While it's possible for an OAuth client to support multiple issuers, it
+	 * requires additional effort to make sure the flows in use are safe -- to
+	 * quote RFC 9207,
+	 *
+	 *     OAuth clients that interact with only one authorization server are
+	 *     not vulnerable to mix-up attacks. However, when such clients decide
+	 *     to add support for a second authorization server in the future, they
+	 *     become vulnerable and need to apply countermeasures to mix-up
+	 *     attacks.
+	 *
+	 * For now, we allow only one.
+	 */
+	if (!conn->oauth_issuer || !conn->oauth_client_id)
+	{
+		libpq_append_conn_error(conn,
+								"server requires OAuth authentication, but oauth_issuer and oauth_client_id are not both set");
+		return false;
+	}
+
+	/*
+	 * oauth_issuer is interpreted differently if it's a well-known discovery
+	 * URI rather than just an issuer identifier.
+	 */
+	if (strstr(conn->oauth_issuer, WK_PREFIX) != NULL)
+	{
+		/*
+		 * Convert the URI back to an issuer identifier. (This also performs
+		 * validation of the URI format.)
+		 */
+		conn->oauth_issuer_id = issuer_from_well_known_uri(conn,
+														   conn->oauth_issuer);
+		if (!conn->oauth_issuer_id)
+			return false;		/* error message already set */
+
+		conn->oauth_discovery_uri = strdup(conn->oauth_issuer);
+		if (!conn->oauth_discovery_uri)
+		{
+			libpq_append_conn_error(conn, "out of memory");
+			return false;
+		}
+	}
+	else
+	{
+		/*
+		 * Treat oauth_issuer as an issuer identifier. We'll ask the server
+		 * for the discovery URI.
+		 */
+		conn->oauth_issuer_id = strdup(conn->oauth_issuer);
+		if (!conn->oauth_issuer_id)
+		{
+			libpq_append_conn_error(conn, "out of memory");
+			return false;
+		}
+	}
+
+	return true;
+}
+
+/*
+ * Implements the OAUTHBEARER SASL exchange (RFC 7628, Sec. 3.2).
+ *
+ * If the necessary OAuth parameters are set up on the connection, this will run
+ * the client flow asynchronously and present the resulting token to the server.
+ * Otherwise, an empty discovery response will be sent and any parameters sent
+ * back by the server will be stored for a second attempt.
+ *
+ * For a full description of the API, see libpq/sasl.h.
+ */
+static SASLStatus
+oauth_exchange(void *opaq, bool final,
+			   char *input, int inputlen,
+			   char **output, int *outputlen)
+{
+	fe_oauth_state *state = opaq;
+	PGconn	   *conn = state->conn;
+	bool		discover = false;
+
+	*output = NULL;
+	*outputlen = 0;
+
+	switch (state->step)
+	{
+		case FE_OAUTH_INIT:
+			/* We begin in the initial response phase. */
+			Assert(inputlen == -1);
+
+			if (!setup_oauth_parameters(conn))
+				return SASL_FAILED;
+
+			if (conn->oauth_token)
+			{
+				/*
+				 * A previous connection already fetched the token; we'll use
+				 * it below.
+				 */
+			}
+			else if (conn->oauth_discovery_uri)
+			{
+				/*
+				 * We don't have a token, but we have a discovery URI already
+				 * stored. Decide whether we're using a user-provided OAuth
+				 * flow or the one we have built in.
+				 */
+				if (!setup_token_request(conn, state))
+					return SASL_FAILED;
+
+				if (conn->oauth_token)
+				{
+					/*
+					 * A really smart user implementation may have already
+					 * given us the token (e.g. if there was an unexpired copy
+					 * already cached), and we can use it immediately.
+					 */
+				}
+				else
+				{
+					/*
+					 * Otherwise, we'll have to hand the connection over to
+					 * our OAuth implementation.
+					 *
+					 * This could take a while, since it generally involves a
+					 * user in the loop. To avoid consuming the server's
+					 * authentication timeout, we'll continue this handshake
+					 * to the end, so that the server can close its side of
+					 * the connection. We'll open a second connection later
+					 * once we've retrieved a token.
+					 */
+					discover = true;
+				}
+			}
+			else
+			{
+				/*
+				 * If we don't have a token, and we don't have a discovery URI
+				 * to be able to request a token, we ask the server for one
+				 * explicitly.
+				 */
+				discover = true;
+			}
+
+			/*
+			 * Generate an initial response. This either contains a token, if
+			 * we have one, or an empty discovery response which is doomed to
+			 * fail.
+			 */
+			*output = client_initial_response(conn, discover);
+			if (!*output)
+				return SASL_FAILED;
+
+			*outputlen = strlen(*output);
+			state->step = FE_OAUTH_BEARER_SENT;
+
+			if (conn->oauth_token)
+			{
+				/*
+				 * For the purposes of require_auth, our side of
+				 * authentication is done at this point; the server will
+				 * either accept the connection or send an error. Unlike
+				 * SCRAM, there is no additional server data to check upon
+				 * success.
+				 */
+				conn->client_finished_auth = true;
+			}
+
+			return SASL_CONTINUE;
+
+		case FE_OAUTH_BEARER_SENT:
+			if (final)
+			{
+				/*
+				 * OAUTHBEARER does not make use of additional data with a
+				 * successful SASL exchange, so we shouldn't get an
+				 * AuthenticationSASLFinal message.
+				 */
+				libpq_append_conn_error(conn,
+										"server sent unexpected additional OAuth data");
+				return SASL_FAILED;
+			}
+
+			/*
+			 * An error message was sent by the server. Respond with the
+			 * required dummy message (RFC 7628, sec. 3.2.3).
+			 */
+			*output = strdup(kvsep);
+			if (unlikely(!*output))
+			{
+				libpq_append_conn_error(conn, "out of memory");
+				return SASL_FAILED;
+			}
+			*outputlen = strlen(*output);	/* == 1 */
+
+			/* Grab the settings from discovery. */
+			if (!handle_oauth_sasl_error(conn, input, inputlen))
+				return SASL_FAILED;
+
+			if (conn->oauth_token)
+			{
+				/*
+				 * The server rejected our token. Continue onwards towards the
+				 * expected FATAL message, but mark our state to catch any
+				 * unexpected "success" from the server.
+				 */
+				state->step = FE_OAUTH_SERVER_ERROR;
+				return SASL_CONTINUE;
+			}
+
+			if (!conn->async_auth)
+			{
+				/*
+				 * No OAuth flow is set up yet. Did we get enough information
+				 * from the server to create one?
+				 */
+				if (!conn->oauth_discovery_uri)
+				{
+					libpq_append_conn_error(conn,
+											"server requires OAuth authentication, but no discovery metadata was provided");
+					return SASL_FAILED;
+				}
+
+				/* Yes. Set up the flow now. */
+				if (!setup_token_request(conn, state))
+					return SASL_FAILED;
+
+				if (conn->oauth_token)
+				{
+					/*
+					 * A token was available in a custom flow's cache. Skip
+					 * the asynchronous processing.
+					 */
+					goto reconnect;
+				}
+			}
+
+			/*
+			 * Time to retrieve a token. This involves a number of HTTP
+			 * connections and timed waits, so we escape the synchronous auth
+			 * processing and tell PQconnectPoll to transfer control to our
+			 * async implementation.
+			 */
+			Assert(conn->async_auth);	/* should have been set already */
+			state->step = FE_OAUTH_REQUESTING_TOKEN;
+			return SASL_ASYNC;
+
+		case FE_OAUTH_REQUESTING_TOKEN:
+
+			/*
+			 * We've returned successfully from token retrieval. Double-check
+			 * that we have what we need for the next connection.
+			 */
+			if (!conn->oauth_token)
+			{
+				Assert(false);	/* should have failed before this point! */
+				libpq_append_conn_error(conn,
+										"internal error: OAuth flow did not set a token");
+				return SASL_FAILED;
+			}
+
+			goto reconnect;
+
+		case FE_OAUTH_SERVER_ERROR:
+
+			/*
+			 * After an error, the server should send an error response to
+			 * fail the SASL handshake, which is handled in higher layers.
+			 *
+			 * If we get here, the server either sent *another* challenge
+			 * which isn't defined in the RFC, or completed the handshake
+			 * successfully after telling us it was going to fail. Neither is
+			 * acceptable.
+			 */
+			libpq_append_conn_error(conn,
+									"server sent additional OAuth data after error");
+			return SASL_FAILED;
+
+		default:
+			libpq_append_conn_error(conn, "invalid OAuth exchange state");
+			break;
+	}
+
+	Assert(false);				/* should never get here */
+	return SASL_FAILED;
+
+reconnect:
+
+	/*
+	 * Despite being a failure from the point of view of SASL, we have enough
+	 * information to restart with a new connection.
+	 */
+	libpq_append_conn_error(conn, "retrying connection with new bearer token");
+	conn->oauth_want_retry = true;
+	return SASL_FAILED;
+}
+
+static bool
+oauth_channel_bound(void *opaq)
+{
+	/* This mechanism does not support channel binding. */
+	return false;
+}
+
+/*
+ * Fully clears out any stored OAuth token. This is done proactively upon
+ * successful connection as well as during pqClosePGconn().
+ */
+void
+pqClearOAuthToken(PGconn *conn)
+{
+	if (!conn->oauth_token)
+		return;
+
+	explicit_bzero(conn->oauth_token, strlen(conn->oauth_token));
+	free(conn->oauth_token);
+	conn->oauth_token = NULL;
+}
+
+/*
+ * Returns true if the PGOAUTHDEBUG=UNSAFE flag is set in the environment.
+ */
+bool
+oauth_unsafe_debugging_enabled(void)
+{
+	const char *env = getenv("PGOAUTHDEBUG");
+
+	return (env && strcmp(env, "UNSAFE") == 0);
+}
diff --git a/src/interfaces/libpq/fe-auth-oauth.h b/src/interfaces/libpq/fe-auth-oauth.h
new file mode 100644
index 00000000000..3f1a7503a01
--- /dev/null
+++ b/src/interfaces/libpq/fe-auth-oauth.h
@@ -0,0 +1,46 @@
+/*-------------------------------------------------------------------------
+ *
+ * fe-auth-oauth.h
+ *
+ *	  Definitions for OAuth authentication implementations
+ *
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1994, Regents of the University of California
+ *
+ * src/interfaces/libpq/fe-auth-oauth.h
+ *
+ *-------------------------------------------------------------------------
+ */
+
+#ifndef FE_AUTH_OAUTH_H
+#define FE_AUTH_OAUTH_H
+
+#include "libpq-fe.h"
+#include "libpq-int.h"
+
+
+enum fe_oauth_step
+{
+	FE_OAUTH_INIT,
+	FE_OAUTH_BEARER_SENT,
+	FE_OAUTH_REQUESTING_TOKEN,
+	FE_OAUTH_SERVER_ERROR,
+};
+
+typedef struct
+{
+	enum fe_oauth_step step;
+
+	PGconn	   *conn;
+	void	   *async_ctx;
+} fe_oauth_state;
+
+extern PostgresPollingStatusType pg_fe_run_oauth_flow(PGconn *conn);
+extern void pg_fe_cleanup_oauth_flow(PGconn *conn);
+extern void pqClearOAuthToken(PGconn *conn);
+extern bool oauth_unsafe_debugging_enabled(void);
+
+/* Mechanisms in fe-auth-oauth.c */
+extern const pg_fe_sasl_mech pg_oauth_mech;
+
+#endif							/* FE_AUTH_OAUTH_H */
diff --git a/src/interfaces/libpq/fe-auth.c b/src/interfaces/libpq/fe-auth.c
index 761ee8f88f7..ec7a9236044 100644
--- a/src/interfaces/libpq/fe-auth.c
+++ b/src/interfaces/libpq/fe-auth.c
@@ -40,9 +40,11 @@
 #endif
 
 #include "common/md5.h"
+#include "common/oauth-common.h"
 #include "common/scram-common.h"
 #include "fe-auth.h"
 #include "fe-auth-sasl.h"
+#include "fe-auth-oauth.h"
 #include "libpq-fe.h"
 
 #ifdef ENABLE_GSS
@@ -535,6 +537,13 @@ pg_SASL_init(PGconn *conn, int payloadlen, bool *async)
 			conn->sasl = &pg_scram_mech;
 			conn->password_needed = true;
 		}
+		else if (strcmp(mechanism_buf.data, OAUTHBEARER_NAME) == 0 &&
+				 !selected_mechanism)
+		{
+			selected_mechanism = OAUTHBEARER_NAME;
+			conn->sasl = &pg_oauth_mech;
+			conn->password_needed = false;
+		}
 	}
 
 	if (!selected_mechanism)
@@ -559,13 +568,6 @@ pg_SASL_init(PGconn *conn, int payloadlen, bool *async)
 
 		if (!allowed)
 		{
-			/*
-			 * TODO: this is dead code until a second SASL mechanism is added;
-			 * the connection can't have proceeded past check_expected_areq()
-			 * if no SASL methods are allowed.
-			 */
-			Assert(false);
-
 			libpq_append_conn_error(conn, "authentication method requirement \"%s\" failed: server requested %s authentication",
 									conn->require_auth, selected_mechanism);
 			goto error;
@@ -1580,3 +1582,23 @@ PQchangePassword(PGconn *conn, const char *user, const char *passwd)
 		}
 	}
 }
+
+PQauthDataHook_type PQauthDataHook = PQdefaultAuthDataHook;
+
+PQauthDataHook_type
+PQgetAuthDataHook(void)
+{
+	return PQauthDataHook;
+}
+
+void
+PQsetAuthDataHook(PQauthDataHook_type hook)
+{
+	PQauthDataHook = hook ? hook : PQdefaultAuthDataHook;
+}
+
+int
+PQdefaultAuthDataHook(PGauthData type, PGconn *conn, void *data)
+{
+	return 0;					/* handle nothing */
+}
diff --git a/src/interfaces/libpq/fe-auth.h b/src/interfaces/libpq/fe-auth.h
index 1d4991f8996..de98e0d20c4 100644
--- a/src/interfaces/libpq/fe-auth.h
+++ b/src/interfaces/libpq/fe-auth.h
@@ -18,6 +18,9 @@
 #include "libpq-int.h"
 
 
+extern PQauthDataHook_type PQauthDataHook;
+
+
 /* Prototypes for functions in fe-auth.c */
 extern int	pg_fe_sendauth(AuthRequest areq, int payloadlen, PGconn *conn,
 						   bool *async);
diff --git a/src/interfaces/libpq/fe-connect.c b/src/interfaces/libpq/fe-connect.c
index 85d1ca2864f..d5051f5e820 100644
--- a/src/interfaces/libpq/fe-connect.c
+++ b/src/interfaces/libpq/fe-connect.c
@@ -28,6 +28,7 @@
 #include "common/scram-common.h"
 #include "common/string.h"
 #include "fe-auth.h"
+#include "fe-auth-oauth.h"
 #include "libpq-fe.h"
 #include "libpq-int.h"
 #include "mb/pg_wchar.h"
@@ -373,6 +374,23 @@ static const internalPQconninfoOption PQconninfoOptions[] = {
 	{"scram_server_key", NULL, NULL, NULL, "SCRAM-Server-Key", "D", SCRAM_MAX_KEY_LEN * 2,
 	offsetof(struct pg_conn, scram_server_key)},
 
+	/* OAuth v2 */
+	{"oauth_issuer", NULL, NULL, NULL,
+		"OAuth-Issuer", "", 40,
+	offsetof(struct pg_conn, oauth_issuer)},
+
+	{"oauth_client_id", NULL, NULL, NULL,
+		"OAuth-Client-ID", "", 40,
+	offsetof(struct pg_conn, oauth_client_id)},
+
+	{"oauth_client_secret", NULL, NULL, NULL,
+		"OAuth-Client-Secret", "", 40,
+	offsetof(struct pg_conn, oauth_client_secret)},
+
+	{"oauth_scope", NULL, NULL, NULL,
+		"OAuth-Scope", "", 15,
+	offsetof(struct pg_conn, oauth_scope)},
+
 	/* Terminating entry --- MUST BE LAST */
 	{NULL, NULL, NULL, NULL,
 	NULL, NULL, 0}
@@ -399,6 +417,7 @@ static const PQEnvironmentOption EnvironmentOptions[] =
 static const pg_fe_sasl_mech *supported_sasl_mechs[] =
 {
 	&pg_scram_mech,
+	&pg_oauth_mech,
 };
 #define SASL_MECHANISM_COUNT lengthof(supported_sasl_mechs)
 
@@ -655,6 +674,7 @@ pqDropServerData(PGconn *conn)
 	conn->write_failed = false;
 	free(conn->write_err_msg);
 	conn->write_err_msg = NULL;
+	conn->oauth_want_retry = false;
 
 	/*
 	 * Cancel connections need to retain their be_pid and be_key across
@@ -1144,7 +1164,7 @@ static inline void
 fill_allowed_sasl_mechs(PGconn *conn)
 {
 	/*---
-	 * We only support one mechanism at the moment, so rather than deal with a
+	 * We only support two mechanisms at the moment, so rather than deal with a
 	 * linked list, conn->allowed_sasl_mechs is an array of static length. We
 	 * rely on the compile-time assertion here to keep us honest.
 	 *
@@ -1519,6 +1539,10 @@ pqConnectOptions2(PGconn *conn)
 			{
 				mech = &pg_scram_mech;
 			}
+			else if (strcmp(method, "oauth") == 0)
+			{
+				mech = &pg_oauth_mech;
+			}
 
 			/*
 			 * Final group: meta-options.
@@ -4111,7 +4135,19 @@ keep_going:						/* We will come back to here until there is
 				conn->inStart = conn->inCursor;
 
 				if (res != STATUS_OK)
+				{
+					/*
+					 * OAuth connections may perform two-step discovery, where
+					 * the first connection is a dummy.
+					 */
+					if (conn->sasl == &pg_oauth_mech && conn->oauth_want_retry)
+					{
+						need_new_connection = true;
+						goto keep_going;
+					}
+
 					goto error_return;
+				}
 
 				/*
 				 * Just make sure that any data sent by pg_fe_sendauth is
@@ -4390,6 +4426,9 @@ keep_going:						/* We will come back to here until there is
 					}
 				}
 
+				/* Don't hold onto any OAuth tokens longer than necessary. */
+				pqClearOAuthToken(conn);
+
 				/*
 				 * For non cancel requests we can release the address list
 				 * now. For cancel requests we never actually resolve
@@ -5002,6 +5041,12 @@ freePGconn(PGconn *conn)
 	free(conn->load_balance_hosts);
 	free(conn->scram_client_key);
 	free(conn->scram_server_key);
+	free(conn->oauth_issuer);
+	free(conn->oauth_issuer_id);
+	free(conn->oauth_discovery_uri);
+	free(conn->oauth_client_id);
+	free(conn->oauth_client_secret);
+	free(conn->oauth_scope);
 	termPQExpBuffer(&conn->errorMessage);
 	termPQExpBuffer(&conn->workBuffer);
 
@@ -5155,6 +5200,7 @@ pqClosePGconn(PGconn *conn)
 	conn->asyncStatus = PGASYNC_IDLE;
 	conn->xactStatus = PQTRANS_IDLE;
 	conn->pipelineStatus = PQ_PIPELINE_OFF;
+	pqClearOAuthToken(conn);
 	pqClearAsyncResult(conn);	/* deallocate result */
 	pqClearConnErrorState(conn);
 
diff --git a/src/interfaces/libpq/libpq-fe.h b/src/interfaces/libpq/libpq-fe.h
index a3491faf0c3..b7399dee58e 100644
--- a/src/interfaces/libpq/libpq-fe.h
+++ b/src/interfaces/libpq/libpq-fe.h
@@ -59,6 +59,8 @@ extern "C"
 /* Features added in PostgreSQL v18: */
 /* Indicates presence of PQfullProtocolVersion */
 #define LIBPQ_HAS_FULL_PROTOCOL_VERSION 1
+/* Indicates presence of the PQAUTHDATA_PROMPT_OAUTH_DEVICE authdata hook */
+#define LIBPQ_HAS_PROMPT_OAUTH_DEVICE 1
 
 /*
  * Option flags for PQcopyResult
@@ -186,6 +188,13 @@ typedef enum
 	PQ_PIPELINE_ABORTED
 } PGpipelineStatus;
 
+typedef enum
+{
+	PQAUTHDATA_PROMPT_OAUTH_DEVICE, /* user must visit a device-authorization
+									 * URL */
+	PQAUTHDATA_OAUTH_BEARER_TOKEN,	/* server requests an OAuth Bearer token */
+} PGauthData;
+
 /* PGconn encapsulates a connection to the backend.
  * The contents of this struct are not supposed to be known to applications.
  */
@@ -720,10 +729,86 @@ extern int	PQenv2encoding(void);
 
 /* === in fe-auth.c === */
 
+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;
+
+/* for PGoauthBearerRequest.async() */
+#ifdef _WIN32
+#define SOCKTYPE uintptr_t		/* avoids depending on winsock2.h for SOCKET */
+#else
+#define SOCKTYPE int
+#endif
+
+typedef struct _PGoauthBearerRequest
+{
+	/* Hook inputs (constant across all calls) */
+	const char *const openid_configuration; /* OIDC discovery URI */
+	const char *const scope;	/* required scope(s), or NULL */
+
+	/* Hook outputs */
+
+	/*---------
+	 * Callback implementing a custom asynchronous OAuth flow.
+	 *
+	 * The callback may return
+	 * - PGRES_POLLING_READING/WRITING, to indicate that a socket descriptor
+	 *   has been stored in *altsock and libpq should wait until it is
+	 *   readable or writable before calling back;
+	 * - PGRES_POLLING_OK, to indicate that the flow is complete and
+	 *   request->token has been set; or
+	 * - PGRES_POLLING_FAILED, to indicate that token retrieval has failed.
+	 *
+	 * This callback is optional. If the token can be obtained without
+	 * blocking during the original call to the PQAUTHDATA_OAUTH_BEARER_TOKEN
+	 * hook, it may be returned directly, but one of request->async or
+	 * request->token must be set by the hook.
+	 */
+	PostgresPollingStatusType (*async) (PGconn *conn,
+										struct _PGoauthBearerRequest *request,
+										SOCKTYPE * altsock);
+
+	/*
+	 * Callback to clean up custom allocations. A hook implementation may use
+	 * this to free request->token and any resources in request->user.
+	 *
+	 * This is technically optional, but highly recommended, because there is
+	 * no other indication as to when it is safe to free the token.
+	 */
+	void		(*cleanup) (PGconn *conn, struct _PGoauthBearerRequest *request);
+
+	/*
+	 * The hook should set this to the Bearer token contents for the
+	 * connection, once the flow is completed.  The token contents must remain
+	 * available to libpq until the hook's cleanup callback is called.
+	 */
+	char	   *token;
+
+	/*
+	 * Hook-defined data. libpq will not modify this pointer across calls to
+	 * the async callback, so it can be used to keep track of
+	 * application-specific state. Resources allocated here should be freed by
+	 * the cleanup callback.
+	 */
+	void	   *user;
+} PGoauthBearerRequest;
+
+#undef SOCKTYPE
+
 extern char *PQencryptPassword(const char *passwd, const char *user);
 extern char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, const char *algorithm);
 extern PGresult *PQchangePassword(PGconn *conn, const char *user, const char *passwd);
 
+typedef int (*PQauthDataHook_type) (PGauthData type, PGconn *conn, void *data);
+extern void PQsetAuthDataHook(PQauthDataHook_type hook);
+extern PQauthDataHook_type PQgetAuthDataHook(void);
+extern int	PQdefaultAuthDataHook(PGauthData type, PGconn *conn, void *data);
+
 /* === in encnames.c === */
 
 extern int	pg_char_to_encoding(const char *name);
diff --git a/src/interfaces/libpq/libpq-int.h b/src/interfaces/libpq/libpq-int.h
index 2546f9f8a50..f36f7f19d58 100644
--- a/src/interfaces/libpq/libpq-int.h
+++ b/src/interfaces/libpq/libpq-int.h
@@ -437,6 +437,17 @@ struct pg_conn
 								 * cancel request, instead of being a normal
 								 * connection that's used for queries */
 
+	/* OAuth v2 */
+	char	   *oauth_issuer;	/* token issuer/URL */
+	char	   *oauth_issuer_id;	/* token issuer identifier */
+	char	   *oauth_discovery_uri;	/* URI of the issuer's discovery
+										 * document */
+	char	   *oauth_client_id;	/* client identifier */
+	char	   *oauth_client_secret;	/* client secret */
+	char	   *oauth_scope;	/* access token scope */
+	char	   *oauth_token;	/* access token */
+	bool		oauth_want_retry;	/* should we retry on failure? */
+
 	/* Optional file to write trace info to */
 	FILE	   *Pfdebug;
 	int			traceFlags;
@@ -505,7 +516,7 @@ struct pg_conn
 								 * the server? */
 	uint32		allowed_auth_methods;	/* bitmask of acceptable AuthRequest
 										 * codes */
-	const pg_fe_sasl_mech *allowed_sasl_mechs[1];	/* and acceptable SASL
+	const pg_fe_sasl_mech *allowed_sasl_mechs[2];	/* and acceptable SASL
 													 * mechanisms */
 	bool		client_finished_auth;	/* have we finished our half of the
 										 * authentication exchange? */
diff --git a/src/interfaces/libpq/meson.build b/src/interfaces/libpq/meson.build
index dd64d291b3e..19f4a52a97a 100644
--- a/src/interfaces/libpq/meson.build
+++ b/src/interfaces/libpq/meson.build
@@ -1,6 +1,7 @@
 # Copyright (c) 2022-2025, PostgreSQL Global Development Group
 
 libpq_sources = files(
+  'fe-auth-oauth.c',
   'fe-auth-scram.c',
   'fe-auth.c',
   'fe-cancel.c',
@@ -37,6 +38,10 @@ if gssapi.found()
   )
 endif
 
+if libcurl.found()
+  libpq_sources += files('fe-auth-oauth-curl.c')
+endif
+
 export_file = custom_target('libpq.exports',
   kwargs: gen_export_kwargs,
 )