public inbox for [email protected]
help / color / mirror / Atom feedFrom: Chao Li <[email protected]>
To: Daniel Gustafsson <[email protected]>
Cc: Postgres hackers <[email protected]>
Cc: Jacob Champion <[email protected]>
Subject: Re: Fix OAuth validator docs for error_detail on internal errors
Date: Fri, 5 Jun 2026 06:21:07 +0800
Message-ID: <[email protected]> (raw)
In-Reply-To: <[email protected]>
References: <[email protected]>
<[email protected]>
> On Jun 5, 2026, at 04:19, Daniel Gustafsson <[email protected]> wrote:
>
>> On 4 Jun 2026, at 14:33, Chao Li <[email protected]> wrote:
>
>> “Any result parameters are ignored” is no longer accurate; it should be something like “any result parameters except result->error_detail are ignored”. This patch just makes that tiny doc fix.
>
> That's true, but error_detail is explained in detail in the next paragraph so
> I'm not sure this change is needed.
Agreed. Adding the “exception for result->error_detail” sounds a bit redundant with the next paragraph. But “any result parameters are ignored” also seems to conflict with the next paragraph, so I think we can just delete that part.
ValidatorModuleResult has three fields, so the logic is:
* The first paragraph talks about authorized and authn_id when the validator succeeds.
* The second paragraph talks about the validator’s return values.
* The third paragraph talks about result->error_detail when the validator fails.
>
> Another thing we don't explicitly document which seems more interesting is that
> authn_id is used even in case of failure if log_connections is enabled. Maybe
> that deserves a mention?
>
This is a good point. I added that in v2.
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/
Attachments:
[application/octet-stream] v2-0001-doc-clarify-OAuth-validator-authn_id-logging-on-a.patch (2.5K, 2-v2-0001-doc-clarify-OAuth-validator-authn_id-logging-on-a.patch)
download | inline diff:
From 475fc04a7b9d3d388c089126a95686c867b0768e Mon Sep 17 00:00:00 2001
From: "Chao Li (Evan)" <[email protected]>
Date: Thu, 4 Jun 2026 19:23:59 +0800
Subject: [PATCH v2] doc: clarify OAuth validator authn_id logging on auth
failure
OAuth validators can return an authenticated identity in
ValidatorModuleResult.authn_id. The server records this value before
checking whether the connection is authorized, so it may appear in
connection-authentication logs even when the connection is later rejected.
Also remove outdated wording saying that all result parameters are ignored
when a validator returns false. Validators may still provide error_detail for
both validation failures and internal errors, as described in the following
paragraph.
Author: Chao Li <[email protected]>
Reported-by: Daniel Gustafsson <[email protected]>
Discussion: https://postgr.es/m/[email protected]
---
doc/src/sgml/oauth-validators.sgml | 13 +++++++++----
1 file changed, 9 insertions(+), 4 deletions(-)
diff --git a/doc/src/sgml/oauth-validators.sgml b/doc/src/sgml/oauth-validators.sgml
index 8aad470a464..245f3ebb95e 100644
--- a/doc/src/sgml/oauth-validators.sgml
+++ b/doc/src/sgml/oauth-validators.sgml
@@ -395,13 +395,18 @@ typedef struct ValidatorModuleResult
token) shall be palloc'd and returned in the <structfield>result->authn_id</structfield>
field. Alternatively, <structfield>result->authn_id</structfield> may be set to
NULL if the token is valid but the associated user identity cannot be
- determined.
+ determined. If the validator returns <literal>true</literal> and
+ <structfield>result->authn_id</structfield> is set, the server records it
+ before checking whether the connection is authorized, so it may appear in
+ the server log when <xref linkend="guc-log-connections"/> includes
+ <literal>authentication</literal>, even when the connection is later
+ rejected.
</para>
<para>
A validator may return <literal>false</literal> to signal an internal error,
- in which case any result parameters are ignored and the connection fails.
- Otherwise the validator should return <literal>true</literal> to indicate
- that it has processed the token and made an authorization decision.
+ in which case the connection fails. Otherwise the validator should return
+ <literal>true</literal> to indicate that it has processed the token and made
+ an authorization decision.
</para>
<para>
In either failure case (validation error or internal error) the module may
--
2.50.1 (Apple Git-155)
view thread (7+ messages) latest in thread
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: [email protected]
Cc: [email protected], [email protected], [email protected], [email protected]
Subject: Re: Fix OAuth validator docs for error_detail on internal errors
In-Reply-To: <[email protected]>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox