19.6. GSSAPI Authentication#
GSSAPI is an industry-standard protocol for secure authentication defined inRFC 2743.Postgres Pro supportsGSSAPI for authentication, communications encryption, or both.GSSAPI provides automatic authentication (single sign-on) for systems that support it. The authentication itself is secure. IfGSSAPI encryption orSSL encryption is used, the data sent along the database connection will be encrypted; otherwise, it will not.
GSSAPI support has to be enabled whenPostgres Pro is built.
When connecting, the client must know the principal name of the server it intends to connect to. Theservicename part of the principal is ordinarilypostgres, but another value can be selected vialibpq'skrbsrvname connection parameter. Thehostname part is the fully qualified host name thatlibpq is told to connect to. The realm name is the preferred realm specified in the Kerberos configuration file(s) accessible to the client.
The client will also have a principal name for its own identity (and it must have a valid ticket for this principal). To useGSSAPI for authentication, the client principal must be associated with aPostgres Pro database user name. Thepg_ident.conf configuration file can be used to map principals to user names; for example,pgusername@realm could be mapped to justpgusername. Alternatively, you can use the fullusername@realm principal as the role name inPostgres Pro without any mapping.
Postgres Pro also supports mapping client principals to user names by just stripping the realm from the principal. This method is supported for backwards compatibility and is strongly discouraged as it is then impossible to distinguish different users with the same user name but coming from different realms. To enable this, setinclude_realm to 0. For simple single-realm installations, doing that combined with setting thekrb_realm parameter (which checks that the principal's realm matches exactly what is in thekrb_realm parameter) is still secure; but this is a less capable approach compared to specifying an explicit mapping inpg_ident.conf.
The location of the server's keytab file is specified by thekrb_server_keyfile configuration parameter. For security reasons, it is recommended to use a separate keytab just for thePostgres Pro server rather than allowing the server to read the system keytab file. Make sure that your server keytab file is readable (and preferably only readable, not writable) by thePostgres Pro server account. (See alsoSection 17.1.)
The keytab file is generated using the Kerberos software; see the Kerberos documentation for details. The following example shows doing this using thekadmin tool of MIT Kerberos:
kadmin%addprinc -randkey postgres/server.my.domain.orgkadmin%ktadd -k krb5.keytab postgres/server.my.domain.org
The following authentication options are supported for theGSSAPI authentication method:
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 19.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 toPostgres Pro user names.mapAllows mapping from client principals to database user names. SeeSection 19.2 for details. For a GSSAPI/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.
In addition to these settings, which can be different for differentpg_hba.conf entries, there is the server-widekrb_caseins_users configuration parameter. If that is set to true, client principals are matched to user map entries case-insensitively.krb_realm, if set, is also matched case-insensitively.