From: Tomas Pospisek <tpo2@sourcepole.ch>
To: Stephen Frost <sfrost@snowman.net>
To: pgsql-docs@lists.postgresql.org
Subject: Re: Make SSPI documentation clearer
Date: Mon, 13 Mar 2023 10:00:36 +0100
Message-ID: <29df68b8-00a8-a42d-aa49-4956b228d357@sourcepole.ch> (raw)
In-Reply-To: <ZA5wJQFOcULuIwwn@tamriel.snowman.net>
References: <167846222574.1803490.15815104179136215862@wrigleys.postgresql.org>
<ZA5wJQFOcULuIwwn@tamriel.snowman.net>
On 13.03.23 01:36, Stephen Frost wrote:
> * PG Doc comments form (noreply@postgresql.org) wrote:
> > Page: https://www.postgresql.org/docs/15/sspi-auth.html
> > Description:
> >
> > The [current SSPI
> > documentation](https://www.postgresql.org/docs/current/sspi-auth.html)
> > reads:
> >
> > "SSPI authentication only works when both server and client are
> > running Windows, or, on non-Windows platforms, when GSSAPI is
> > available."
> >
> > I interpret that phrase like this:
> >
> > * there's a case where both server and client are running Windows
> > * there's a case where both are running non-Windows
>
> Yeah, that phrasing isn't great.
>
> > What about mixed cases? When the client is non-Windows, then can it
> > use SSPI? No, AFAIK not. So I'd suggest to make that phrase above
> > clearer and completely explicit:
>
> SSPI is Windows-specific, yeah.
>
> > "SSPI authentication works when both server and client are running
> > Windows.
> >
> > When the server is on a non-Windows platform then the server must
> > use GSSAPI if it wants to authenticate the client either via
> > Kerberos or via Active Directory. A client on a Windows platform
> > that connects to a non-Windows Postgresql server can either use SSPI
> > (strongly encouraged) or GSS (much more difficult to set up) if it
> > wants to authenticate via Kerberos or Active Directory. A client
> > from a non-Windows platform must use GSS if it wants to authenticate
> > via Kerberos or Active Directory."
>
> Rather than work in negative, I feel like it might make more sense to
> work in positives? That is, perhaps this instead:
>
> On Windows platforms, SSPI is the default and most commonly used
> mechanism. Note that an SSPI client can authenticate to a server
> which is using either SSPI or GSSAPI, and a GSSAPI client can
> authenticate to a server which is using either SSPI or GSSAPI.
> Generally speaking, clients and servers on Windows are recommended to
> use SSPI while clients and servers on Unix (non-Windows) platforms use
> GSSAPI.
>
> Stricltly speaking, this is all independent of if AD is being used as
> the KDC or not.
I agree, that's a better formulation. I'd suggest to improve your
version in three ways:
1. replace "mechanism" with "authentication mechanism"
2. be explicit about Active Directory so there's no doubt wrt to setting
up authentication
3. be explicit that GSSAPI should be used on non-Windows platform
servers when one wants clients in an AD domain to seamlessly
authenticate with the non-Windows server. I'd mention that because if
the windows clients are *not* in an AD domain then they will *not* be
able to authenticate to the non-Windows server with GSSAPI.
So finally the whole start of the SSPI paragraph in the docu would look
like this:
----------------------
21.7. SSPI Authentication
On Windows platforms, SSPI is the default and most commonly used
authentication mechanism. Note that an SSPI client can authenticate to
a server which is using either SSPI or GSSAPI, and a GSSAPI client can
authenticate to a server which is using either SSPI or GSSAPI.
Generally speaking, clients and servers on Windows are recommended to
use SSPI while clients and servers on Unix (non-Windows) platforms are
recommended to use GSSAPI if they want to interoperate seamlessly with
Active Directory or Kerberos authentication.
When using Kerberos authentication, SSPI works the same way GSSAPI does;
see Section 21.6 for details.
----------------------
If the docu is changed in this way, then the phrase "PostgreSQL will use
SSPI in negotiate mode" is dropped wrt to the previous documentation. I
have not been able to find out what "SSPI in negotion mode" is and
therefore if it's in any way relevant to mention that in the docs.
Thanks,
*t
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: pgsql-docs@postgresql.org
Cc: tpo2@sourcepole.ch, sfrost@snowman.net, pgsql-docs@lists.postgresql.org
Subject: Re: Make SSPI documentation clearer
In-Reply-To: <29df68b8-00a8-a42d-aa49-4956b228d357@sourcepole.ch>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox