From 3642df265d09779443a9f44f5cb873df40974e89 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter@eisentraut.org>
Date: Wed, 26 Mar 2025 10:05:49 +0100
Subject: dblink: SCRAM authentication pass-through

This enables SCRAM authentication for dblink (using dblink_fdw) when
connecting to a foreign server without having to store a plain-text
password on user mapping options

This uses the same approach as it was implemented for postgres_fdw in
commit 761c79508e7.  (It also contains the equivalent of the
subsequent fixes 76563f88cfb and d2028e9bbc1.)

Author: Matheus Alcantara <mths.dev@pm.me>
Reviewed-by: Jacob Champion <jacob.champion@enterprisedb.com>
Discussion: https://www.postgresql.org/message-id/flat/CAFY6G8ercA1KES%3DE_0__R9QCTR805TTyYr1No8qF8ZxmMg8z2Q%40mail.gmail.com
---
 doc/src/sgml/dblink.sgml       | 21 ++++++++++++++++++---
 doc/src/sgml/postgres-fdw.sgml |  4 ++--
 2 files changed, 20 insertions(+), 5 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/dblink.sgml b/doc/src/sgml/dblink.sgml
index 81f35986c88..808c690985b 100644
--- a/doc/src/sgml/dblink.sgml
+++ b/doc/src/sgml/dblink.sgml
@@ -150,9 +150,23 @@ dblink_connect(text connname, text connstr) returns text
     executing arbitrary SQL commands.
    </para>
 
+   <para>
+    The foreign-data wrapper <filename>dblink_fdw</filename> has an additional
+    Boolean option <literal>use_scram_passthrough</literal> that controls
+    whether <filename>dblink</filename> will use the SCRAM pass-through
+    authentication to connect to the remote database.  With SCRAM pass-through
+    authentication, <filename>dblink</filename> uses SCRAM-hashed secrets
+    instead of plain-text user passwords to connect to the remote server. This
+    avoids storing plain-text user passwords in PostgreSQL system catalogs.
+    See the documentation of the equivalent <link
+    linkend="postgres-fdw-option-use-scram-passthrough"><literal>use_scram_passthrough</literal></link>
+    option of postgres_fdw for further details and restrictions.
+   </para>
+
    <para>
     Only superusers may use <function>dblink_connect</function> to create
-    non-password-authenticated and non-GSSAPI-authenticated connections.
+    connections that use neither password authentication, SCRAM pass-through,
+    nor GSSAPI-authentication.
     If non-superusers need this capability, use
     <function>dblink_connect_u</function> instead.
    </para>
@@ -181,8 +195,9 @@ SELECT dblink_connect('myconn', 'dbname=postgres options=-csearch_path=');
 (1 row)
 
 -- FOREIGN DATA WRAPPER functionality
--- Note: local connection must require password authentication for this to work properly
---       Otherwise, you will receive the following error from dblink_connect():
+-- Note: local connections that don't use SCRAM pass-through require password
+--       authentication for this to work properly. Otherwise, you will receive
+--       the following error from dblink_connect():
 --       ERROR:  password is required
 --       DETAIL:  Non-superuser cannot connect if the server does not request a password.
 --       HINT:  Target server's authentication method must be changed.
diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml
index 65e36f1f3e4..781a01067f7 100644
--- a/doc/src/sgml/postgres-fdw.sgml
+++ b/doc/src/sgml/postgres-fdw.sgml
@@ -756,7 +756,7 @@ OPTIONS (ADD password_required 'false');
 
     <variablelist>
 
-     <varlistentry>
+     <varlistentry id="postgres-fdw-option-keep-connections">
       <term><literal>keep_connections</literal> (<type>boolean</type>)</term>
       <listitem>
        <para>
@@ -770,7 +770,7 @@ OPTIONS (ADD password_required 'false');
       </listitem>
      </varlistentry>
 
-     <varlistentry>
+     <varlistentry id="postgres-fdw-option-use-scram-passthrough">
       <term><literal>use_scram_passthrough</literal> (<type>boolean</type>)</term>
       <listitem>
        <para>
-- 
cgit v1.2.3