Re: Make SSPI documentation clearer

Hi pgsql documenters,

what is the status of bringing the proposed SSPI documentation chages 
into the git repo?

- is there anything to be improved or missing with the proposed changes?
- does the improvement need a hat tip of someone?
- anybody here that has the guts, time and willingness to take the
   supposed improvement and apply put it into the git repo?

Anything else needed here?

If the change is in principle OK, then I can prepare a patch or such (I 
assume postgres doesn't take pull requests from 
https://github.com/postgres ?)?

Greetings,
*t

On 13.03.23 10:00, Tomas Pospisek wrote:
> 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
> 
>