From b0635bfda0535a7fc36cd11d10eecec4e2a96330 Mon Sep 17 00:00:00 2001 From: Jacob Champion Date: Thu, 1 May 2025 09:14:30 -0700 Subject: oauth: Move the builtin flow into a separate module The additional packaging footprint of the OAuth Curl dependency, as well as the existence of libcurl in the address space even if OAuth isn't ever used by a client, has raised some concerns. Split off this dependency into a separate loadable module called libpq-oauth. When configured using --with-libcurl, libpq.so searches for this new module via dlopen(). End users may choose not to install the libpq-oauth module, in which case the default flow is disabled. For static applications using libpq.a, the libpq-oauth staticlib is a mandatory link-time dependency for --with-libcurl builds. libpq.pc has been updated accordingly. The default flow relies on some libpq internals. Some of these can be safely duplicated (such as the SIGPIPE handlers), but others need to be shared between libpq and libpq-oauth for thread-safety. To avoid exporting these internals to all libpq clients forever, these dependencies are instead injected from the libpq side via an initialization function. This also lets libpq communicate the offsets of PGconn struct members to libpq-oauth, so that we can function without crashing if the module on the search path came from a different build of Postgres. (A minor-version upgrade could swap the libpq-oauth module out from under a long-running libpq client before it does its first load of the OAuth flow.) This ABI is considered "private". The module has no SONAME or version symlinks, and it's named libpq-oauth-.so to avoid mixing and matching across Postgres versions. (Future improvements may promote this "OAuth flow plugin" to a first-class concept, at which point we would need a public API to replace this anyway.) Additionally, NLS support for error messages in b3f0be788a was incomplete, because the new error macros weren't being scanned by xgettext. Fix that now. Per request from Tom Lane and Bruce Momjian. Based on an initial patch by Daniel Gustafsson, who also contributed docs changes. The "bare" dlopen() concept came from Thomas Munro. Many people reviewed the design and implementation; thank you! Co-authored-by: Daniel Gustafsson Reviewed-by: Andres Freund Reviewed-by: Christoph Berg Reviewed-by: Daniel Gustafsson Reviewed-by: Jelte Fennema-Nio Reviewed-by: Peter Eisentraut Reviewed-by: Wolfgang Walther Discussion: https://postgr.es/m/641687.1742360249%40sss.pgh.pa.us --- doc/src/sgml/installation.sgml | 8 ++++++++ doc/src/sgml/libpq.sgml | 30 ++++++++++++++++++++++-------- 2 files changed, 30 insertions(+), 8 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index e7ffb942bbd..60419312113 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -313,6 +313,14 @@ + + + You need Curl to build an optional module + which implements the OAuth Device + Authorization flow for client applications. + + + You need LZ4, if you want to support diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 8cdd2997d43..695fe958c3e 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -10226,15 +10226,20 @@ void PQinitSSL(int do_ssl); OAuth Support - libpq implements support for the OAuth v2 Device Authorization client flow, + libpq implements support for the OAuth v2 Device Authorization client flow, documented in RFC 8628, - which it will attempt to use by default if the server + as an optional module. See the + installation documentation for information on how to enable support + for Device Authorization as a builtin flow. + + + When support is enabled and the optional module installed, libpq + will use the builtin flow by default if the server requests a bearer token during authentication. This flow can be utilized even if the system running the client application does not have a usable web browser, for example when - running a client via SSH. Client applications may implement their own flows - instead; see . + running a client via SSH. The builtin flow will, by default, print a URL to visit and a user code to @@ -10251,6 +10256,11 @@ Visit https://example.com/device and enter the code: ABCD-EFGH they match expectations, before continuing. Permissions should not be given to untrusted third parties. + + Client applications may implement their own flows to customize interaction + and integration with applications. See + for more information on how add a custom flow to libpq. + For an OAuth client flow to be usable, the connection string must at minimum contain and @@ -10366,7 +10376,9 @@ typedef struct _PGpromptOAuthDevice - The OAuth Device Authorization flow included in libpq + The OAuth Device Authorization flow which + can be included + in libpq requires the end user to visit a URL with a browser, then enter a code which permits libpq to connect to the server on their behalf. The default prompt simply prints the @@ -10378,7 +10390,8 @@ typedef struct _PGpromptOAuthDevice This callback is only invoked during the builtin device authorization flow. If the application installs a custom OAuth - flow, this authdata type will not be used. + flow, or libpq was not built with + support for the builtin flow, this authdata type will not be used. If a non-NULL verification_uri_complete is @@ -10400,8 +10413,9 @@ typedef struct _PGpromptOAuthDevice - Replaces the entire OAuth flow with a custom implementation. The hook - should either directly return a Bearer token for the current + Adds a custom implementation of a flow, replacing the builtin flow if + it is installed. + The hook should either directly return a Bearer token for the current user/issuer/scope combination, if one is available without blocking, or else set up an asynchronous callback to retrieve one. -- cgit v1.2.3