| 1 |
libpq-oauth is an optional module implementing the Device Authorization flow for |
| 2 |
OAuth clients (RFC 8628). It is maintained as its own shared library in order to |
| 3 |
isolate its dependency on libcurl. (End users who don't want the Curl dependency |
| 4 |
can simply choose not to install this module.) |
| 5 |
|
| 6 |
If a connection string allows the use of OAuth, and the server asks for it, and |
| 7 |
a libpq client has not installed its own custom OAuth flow, libpq will attempt |
| 8 |
to delay-load this module using dlopen() and the following ABI. Failure to load |
| 9 |
results in a failed connection. |
| 10 |
|
| 11 |
= Load-Time ABI = |
| 12 |
|
| 13 |
This module ABI is an internal implementation detail, so it's subject to change |
| 14 |
across major releases; the name of the module (libpq-oauth-MAJOR) reflects this. |
| 15 |
The module exports the following symbols: |
| 16 |
|
| 17 |
- PostgresPollingStatusType pg_fe_run_oauth_flow(PGconn *conn); |
| 18 |
- void pg_fe_cleanup_oauth_flow(PGconn *conn); |
| 19 |
|
| 20 |
pg_fe_run_oauth_flow and pg_fe_cleanup_oauth_flow are implementations of |
| 21 |
conn->async_auth and conn->cleanup_async_auth, respectively. |
| 22 |
|
| 23 |
At the moment, pg_fe_run_oauth_flow() relies on libpq's pg_g_threadlock and |
| 24 |
libpq_gettext(), which must be injected by libpq using this initialization |
| 25 |
function before the flow is run: |
| 26 |
|
| 27 |
- void libpq_oauth_init(pgthreadlock_t threadlock, |
| 28 |
libpq_gettext_func gettext_impl, |
| 29 |
conn_errorMessage_func errmsg_impl, |
| 30 |
conn_oauth_client_id_func clientid_impl, |
| 31 |
conn_oauth_client_secret_func clientsecret_impl, |
| 32 |
conn_oauth_discovery_uri_func discoveryuri_impl, |
| 33 |
conn_oauth_issuer_id_func issuerid_impl, |
| 34 |
conn_oauth_scope_func scope_impl, |
| 35 |
conn_sasl_state_func saslstate_impl, |
| 36 |
set_conn_altsock_func setaltsock_impl, |
| 37 |
set_conn_oauth_token_func settoken_impl); |
| 38 |
|
| 39 |
It also relies on access to several members of the PGconn struct. Not only can |
| 40 |
these change positions across minor versions, but the offsets aren't necessarily |
| 41 |
stable within a single minor release (conn->errorMessage, for instance, can |
| 42 |
change offsets depending on configure-time options). Therefore the necessary |
| 43 |
accessors (named conn_*) and mutators (set_conn_*) are injected here. With this |
| 44 |
approach, we can safely search the standard dlopen() paths (e.g. RPATH, |
| 45 |
LD_LIBRARY_PATH, the SO cache) for an implementation module to use, even if that |
| 46 |
module wasn't compiled at the same time as libpq -- which becomes especially |
| 47 |
important during "live upgrade" situations where a running libpq application has |
| 48 |
the libpq-oauth module updated out from under it before it's first loaded from |
| 49 |
disk. |
| 50 |
|
| 51 |
= Static Build = |
| 52 |
|
| 53 |
The static library libpq.a does not perform any dynamic loading. If the builtin |
| 54 |
flow is enabled, the application is expected to link against libpq-oauth.a |
| 55 |
directly to provide the necessary symbols. (libpq.a and libpq-oauth.a must be |
| 56 |
part of the same build. Unlike the dynamic module, there are no translation |
| 57 |
shims provided.) |