21.7. SSPI Authentication
SSPI is aWindows technology for secure authentication with single sign-on.PostgreSQL will use SSPI innegotiate mode, which will useKerberos when possible and automatically fall back toNTLM in other cases.SSPI andGSSAPI interoperate as clients and servers, e.g., anSSPI client can authenticate to anGSSAPI server. It is recommended to useSSPI on Windows clients and servers andGSSAPI on non-Windows platforms.
When usingKerberos authentication,SSPI works the same wayGSSAPI does; seeSection 21.6 for details.
The following configuration options are supported forSSPI:
include_realmIf set to 0, the realm name from the authenticated user principal is stripped off before being passed through the user name mapping (Section 21.2). This is discouraged and is primarily available for backwards compatibility, as it is not secure in multi-realm environments unless
krb_realmis also used. It is recommended to leaveinclude_realmset to the default (1) and to provide an explicit mapping inpg_ident.confto convert principal names toPostgreSQL user names.compat_realmIf set to 1, the domain's SAM-compatible name (also known as the NetBIOS name) is used for the
include_realmoption. This is the default. If set to 0, the true realm name from the Kerberos user principal name is used.Do not disable this option unless your server runs under a domain account (this includes virtual service accounts on a domain member system) and all clients authenticating through SSPI are also using domain accounts, or authentication will fail.
upn_usernameIf this option is enabled along with
compat_realm, the user name from the Kerberos UPN is used for authentication. If it is disabled (the default), the SAM-compatible user name is used. By default, these two names are identical for new user accounts.Note thatlibpq uses the SAM-compatible name if no explicit user name is specified. If you uselibpq or a driver based on it, you should leave this option disabled or explicitly specify user name in the connection string.
mapAllows for mapping between system and database user names. SeeSection 21.2 for details. For an SSPI/Kerberos principal, such as
username@EXAMPLE.COM(or, less commonly,username/hostbased@EXAMPLE.COM), the user name used for mapping isusername@EXAMPLE.COM(orusername/hostbased@EXAMPLE.COM, respectively), unlessinclude_realmhas been set to 0, in which caseusername(orusername/hostbased) is what is seen as the system user name when mapping.krb_realmSets the realm to match user principal names against. If this parameter is set, only users of that realm will be accepted. If it is not set, users of any realm can connect, subject to whatever user name mapping is done.