From 6e4d1906845a7af3ee7931274a76611150b4caf6 Mon Sep 17 00:00:00 2001
From: Zsolt Parragi <zsolt.parragi@percona.com>
Date: Thu, 18 Jun 2026 04:24:22 +0000
Subject: [PATCH v3 1/3] doc: warn that OAuth over plaintext connections is
 unsafe

The bearer token used by OAUTHBEARER authentication grants access to the
database and is sent across the connection, so on an unencrypted
connection it can be captured by network sniffing, just like a
clear-text password.
---
 doc/src/sgml/client-auth.sgml | 16 +++++++++++++++-
 doc/src/sgml/protocol.sgml    | 10 ++++++++++
 2 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index e4e65f8feb1..0e8ac0ba858 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -652,7 +652,12 @@ include_dir         <replaceable>directory</replaceable>
         <listitem>
          <para>
           Authorize and optionally authenticate using a third-party OAuth 2.0
-          identity provider. See <xref linkend="auth-oauth"/> for details.
+          identity provider. The bearer token is sent across the connection and
+          grants access to the database like a clear-text password. On an
+          unencrypted connection it can be captured by network sniffing. For
+          this reason the <literal>oauth</literal> method should only be used
+          over connections protected by SSL/TLS encryption.
+          See <xref linkend="auth-oauth"/> for details.
          </para>
         </listitem>
        </varlistentry>
@@ -2234,6 +2239,15 @@ host ... ldap ldapbasedn="dc=example,dc=net"
     is built, see <xref linkend="installation"/> for more information.
    </para>
 
+   <warning>
+    <para>
+     The bearer token is sent across the connection and grants access to the
+     database like a clear-text password. On an unencrypted connection it can
+     be captured by network sniffing. For this reason OAuth should only be used
+     over connections protected by SSL/TLS encryption.
+    </para>
+   </warning>
+
    <para>
     This documentation uses the following terminology when discussing the OAuth
     ecosystem:
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 49f81676712..b24c36b806a 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -2095,6 +2095,16 @@ SELCT 1/0;<!-- this typo is intentional -->
     server.
    </para>
 
+   <note>
+    <para>
+     The bearer token is sent across the connection, as part of the client
+     initial response, and grants access to the database like a clear-text
+     password. On an unencrypted connection it can be captured by network
+     sniffing. For this reason <literal>OAUTHBEARER</literal> should only be
+     used over connections protected by SSL/TLS encryption.
+    </para>
+   </note>
+
    <para>
     <literal>OAUTHBEARER</literal> does not support channel binding, and there
     is no "OAUTHBEARER-PLUS" mechanism. This mechanism does not make use of
-- 
2.43.0