Message-ID: <29df68b8-00a8-a42d-aa49-4956b228d357@sourcepole.ch>
Date: Mon, 13 Mar 2023 10:00:36 +0100
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101
 Thunderbird/102.8.0
Subject: Re: Make SSPI documentation clearer
To: Stephen Frost <sfrost@snowman.net>, pgsql-docs@lists.postgresql.org
References: 
 <167846222574.1803490.15815104179136215862@wrigleys.postgresql.org>
 <ZA5wJQFOcULuIwwn@tamriel.snowman.net>
Content-Language: en-GB
From: Tomas Pospisek <tpo2@sourcepole.ch>
In-Reply-To: <ZA5wJQFOcULuIwwn@tamriel.snowman.net>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit
Archived-At: 
 <https://www.postgresql.org/message-id/29df68b8-00a8-a42d-aa49-4956b228d357%40sourcepole.ch>
Precedence: bulk

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