From: Chao Li <li.evan.chao@gmail.com>
Message-Id: <28A71A53-EB55-4A29-8C20-BBAF1BC82D2A@gmail.com>
Content-Type: multipart/mixed;
	boundary="Apple-Mail=_7CBA6C13-19A8-4876-AA9B-408594820246"
Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3864.600.51.1.1\))
Subject: Re: Fix OAuth validator docs for error_detail on internal errors
Date: Fri, 5 Jun 2026 06:21:07 +0800
In-Reply-To: <D9F1340C-22C2-43A5-B790-5D5EB379394A@yesql.se>
Cc: Postgres hackers <pgsql-hackers@lists.postgresql.org>,
 Jacob Champion <jacob.champion@enterprisedb.com>
To: Daniel Gustafsson <daniel@yesql.se>
References: <0281836A-F5FF-41A5-9EE1-656C1FAAC6B2@gmail.com>
 <D9F1340C-22C2-43A5-B790-5D5EB379394A@yesql.se>
Archived-At: 
 <https://www.postgresql.org/message-id/28A71A53-EB55-4A29-8C20-BBAF1BC82D2A%40gmail.com>
Precedence: bulk


--Apple-Mail=_7CBA6C13-19A8-4876-AA9B-408594820246
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain;
	charset=utf-8


> On Jun 5, 2026, at 04:19, Daniel Gustafsson <daniel@yesql.se> wrote:
>=20
>> On 4 Jun 2026, at 14:33, Chao Li <li.evan.chao@gmail.com> wrote:
>=20
>> =E2=80=9CAny result parameters are ignored=E2=80=9D is no longer =
accurate; it should be something like =E2=80=9Cany result parameters =
except result->error_detail are ignored=E2=80=9D. This patch just makes =
that tiny doc fix.
>=20
> 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 =E2=80=9Cexception for result->error_detail=E2=80=9D =
sounds a bit redundant with the next paragraph. But =E2=80=9Cany result =
parameters are ignored=E2=80=9D 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=E2=80=99s return =
values.
* The third paragraph talks about result->error_detail when the =
validator fails.

>=20
> 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?
>=20

This is a good point. I added that in v2.

Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/


--Apple-Mail=_7CBA6C13-19A8-4876-AA9B-408594820246
Content-Disposition: attachment;
	filename=v2-0001-doc-clarify-OAuth-validator-authn_id-logging-on-a.patch
Content-Type: application/octet-stream;
	x-unix-mode=0644;
	name="v2-0001-doc-clarify-OAuth-validator-authn_id-logging-on-a.patch"
Content-Transfer-Encoding: quoted-printable

=46rom=20475fc04a7b9d3d388c089126a95686c867b0768e=20Mon=20Sep=2017=20=
00:00:00=202001=0AFrom:=20"Chao=20Li=20(Evan)"=20<lic@highgo.com>=0A=
Date:=20Thu,=204=20Jun=202026=2019:23:59=20+0800=0ASubject:=20[PATCH=20=
v2]=20doc:=20clarify=20OAuth=20validator=20authn_id=20logging=20on=20=
auth=0A=20failure=0A=0AOAuth=20validators=20can=20return=20an=20=
authenticated=20identity=20in=0AValidatorModuleResult.authn_id.=20The=20=
server=20records=20this=20value=20before=0Achecking=20whether=20the=20=
connection=20is=20authorized,=20so=20it=20may=20appear=20in=0A=
connection-authentication=20logs=20even=20when=20the=20connection=20is=20=
later=20rejected.=0A=0AAlso=20remove=20outdated=20wording=20saying=20=
that=20all=20result=20parameters=20are=20ignored=0Awhen=20a=20validator=20=
returns=20false.=20Validators=20may=20still=20provide=20error_detail=20=
for=0Aboth=20validation=20failures=20and=20internal=20errors,=20as=20=
described=20in=20the=20following=0Aparagraph.=0A=0AAuthor:=20Chao=20Li=20=
<lic@highgo.com>=0AReported-by:=20Daniel=20Gustafsson=20=
<daniel@yesql.se>=0ADiscussion:=20=
https://postgr.es/m/0281836A-F5FF-41A5-9EE1-656C1FAAC6B2@gmail.com=0A---=0A=
=20doc/src/sgml/oauth-validators.sgml=20|=2013=20+++++++++----=0A=201=20=
file=20changed,=209=20insertions(+),=204=20deletions(-)=0A=0Adiff=20=
--git=20a/doc/src/sgml/oauth-validators.sgml=20=
b/doc/src/sgml/oauth-validators.sgml=0Aindex=208aad470a464..245f3ebb95e=20=
100644=0A---=20a/doc/src/sgml/oauth-validators.sgml=0A+++=20=
b/doc/src/sgml/oauth-validators.sgml=0A@@=20-395,13=20+395,18=20@@=20=
typedef=20struct=20ValidatorModuleResult=0A=20=20=20=20=20token)=20shall=20=
be=20palloc'd=20and=20returned=20in=20the=20=
<structfield>result->authn_id</structfield>=0A=20=20=20=20=20field.=20=20=
Alternatively,=20<structfield>result->authn_id</structfield>=20may=20be=20=
set=20to=0A=20=20=20=20=20NULL=20if=20the=20token=20is=20valid=20but=20=
the=20associated=20user=20identity=20cannot=20be=0A-=20=20=20=20=
determined.=0A+=20=20=20=20determined.=20=20If=20the=20validator=20=
returns=20<literal>true</literal>=20and=0A+=20=20=20=20=
<structfield>result->authn_id</structfield>=20is=20set,=20the=20server=20=
records=20it=0A+=20=20=20=20before=20checking=20whether=20the=20=
connection=20is=20authorized,=20so=20it=20may=20appear=20in=0A+=20=20=20=20=
the=20server=20log=20when=20<xref=20linkend=3D"guc-log-connections"/>=20=
includes=0A+=20=20=20=20<literal>authentication</literal>,=20even=20when=20=
the=20connection=20is=20later=0A+=20=20=20=20rejected.=0A=20=20=20=20=
</para>=0A=20=20=20=20<para>=0A=20=20=20=20=20A=20validator=20may=20=
return=20<literal>false</literal>=20to=20signal=20an=20internal=20error,=0A=
-=20=20=20=20in=20which=20case=20any=20result=20parameters=20are=20=
ignored=20and=20the=20connection=20fails.=0A-=20=20=20=20Otherwise=20the=20=
validator=20should=20return=20<literal>true</literal>=20to=20indicate=0A=
-=20=20=20=20that=20it=20has=20processed=20the=20token=20and=20made=20an=20=
authorization=20decision.=0A+=20=20=20=20in=20which=20case=20the=20=
connection=20fails.=20=20Otherwise=20the=20validator=20should=20return=0A=
+=20=20=20=20<literal>true</literal>=20to=20indicate=20that=20it=20has=20=
processed=20the=20token=20and=20made=0A+=20=20=20=20an=20authorization=20=
decision.=0A=20=20=20=20</para>=0A=20=20=20=20<para>=0A=20=20=20=20=20In=20=
either=20failure=20case=20(validation=20error=20or=20internal=20error)=20=
the=20module=20may=0A--=20=0A2.50.1=20(Apple=20Git-155)=0A=0A=

--Apple-Mail=_7CBA6C13-19A8-4876-AA9B-408594820246--