v48-0003-fixup-Add-OAUTHBEARER-SASL-mechanism.patch

From 1bd03e1de1010d1f99f490776a63e53f75e34ec4 Mon Sep 17 00:00:00 2001
From: Jacob Champion <jacob.champion@enterprisedb.com>
Date: Fri, 7 Feb 2025 14:23:40 -0800
Subject: [PATCH v48 3/8] fixup! Add OAUTHBEARER SASL mechanism

---
 doc/src/sgml/libpq.sgml            | 40 +++++++++++++++++++++++++++++-
 doc/src/sgml/oauth-validators.sgml |  9 ++++++-
 2 files changed, 47 insertions(+), 2 deletions(-)

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 3ee0a31e6b7..e655ee20890 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -10133,8 +10133,46 @@ void PQinitSSL(int do_ssl);
   <title>OAuth Support</title>
 
   <para>
-   TODO
+   libpq implements support for the OAuth v2 Device Authorization client flow,
+   documented in
+   <ulink url="https://datatracker.ietf.org/doc/html/rfc8628">RFC 8628</ulink>,
+   which it will attempt to use by default if the server
+   <link linkend="auth-oauth">requests a bearer token</link> 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 <xref linkend="libpq-oauth-authdata-hooks"/>.
   </para>
+  <para>
+   The builtin flow will, by default, print a URL to visit and a user code to
+   enter there:
+<programlisting>
+$ psql 'dbname=postgres oauth_issuer=https://example.com oauth_client_id=...'
+Visit https://example.com/device and enter the code: ABCD-EFGH
+</programlisting>
+   (This prompt may be
+   <link linkend="libpq-oauth-authdata-prompt-oauth-device">customized</link>.)
+   You will then log into your OAuth provider, which will ask whether you want
+   to allow libpq and the server to perform actions on your behalf. It is always
+   a good idea to carefully review the URL and permissions displayed, to ensure
+   they match your expectations, before continuing. Do not give permissions to
+   untrusted third parties.
+  </para>
+  <para>
+   For an OAuth client flow to be usable, the connection string must at minimum
+   contain <xref linkend="libpq-connect-oauth-issuer"/> and
+   <xref linkend="libpq-connect-oauth-client-id"/>. (These settings are
+   determined by your organization's OAuth provider.) The builtin flow
+   additionally requires the OAuth authorization server to publish a device
+   authorization endpoint.
+  </para>
+
+  <note>
+   <para>
+    The builtin Device Authorization flow is not currently supported on Windows.
+    Custom client flows may still be implemented.
+   </para>
+  </note>
 
   <sect2 id="libpq-oauth-authdata-hooks">
    <title>Authdata Hooks</title>
diff --git a/doc/src/sgml/oauth-validators.sgml b/doc/src/sgml/oauth-validators.sgml
index d0bca9196d9..c8bbac7b462 100644
--- a/doc/src/sgml/oauth-validators.sgml
+++ b/doc/src/sgml/oauth-validators.sgml
@@ -41,7 +41,9 @@
   <sect2 id="oauth-validator-design-responsibilities">
    <title>Validator Responsibilities</title>
    <para>
-    TODO
+    Although different modules may take very different approaches to token
+    validation, implementations generally need to perform three separate
+    actions:
    </para>
    <variablelist>
     <varlistentry>
@@ -121,6 +123,11 @@
        </footnote>
        if users are not prompted for additional scopes.
       </para>
+      <para>
+       Even if authorization fails, a module may choose to continue to pull
+       authentication information from the token for use in auditing and
+       debugging.
+      </para>
      </listitem>
     </varlistentry>
     <varlistentry>
-- 
2.34.1