Re: Make SSPI documentation clearer

On 13.03.23 01:36, Stephen Frost wrote:

> * PG Doc comments form (noreply(at)postgresql(dot)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