Re: Make SSPI documentation clearer

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