GSSAPI is an industry-standard protocol
for secure authentication defined in RFC 2743.
PostgreSQL
supports GSSAPI for use as either an encrypted,
authenticated layer, or for authentication only.
GSSAPI provides automatic authentication
(single sign-on) for systems that support it. The authentication itself is
secure. If GSSAPI encryption
(see hostgssenc) or SSL encryption are
used, the data sent along the database connection will be encrypted;
otherwise, it will not.
GSSAPI support has to be enabled when PostgreSQL is built; see Chapter 16 for more information.
When GSSAPI uses
Kerberos, it uses a standard principal
in the format
servicename/hostname@realmkrbsrvname connection parameter. (See
also Section 33.1.2.) The installation default can be
changed from the default postgres at build time using
./configure --with-krb-srvnam=whatever.
In most environments,
this parameter never needs to be changed.
Some Kerberos implementations might require a different service name,
such as Microsoft Active Directory which requires the service name
to be in upper case (POSTGRES).
hostname is the fully qualified host name of the
server machine. The service principal's realm is the preferred realm
of the server machine.
Client principals can be mapped to different PostgreSQL
database user names with pg_ident.conf. For example,
pgusername@realm could be mapped to just pgusername.
Alternatively, you can use the full username@realm principal as
the role name in PostgreSQL without any mapping.
PostgreSQL also supports a parameter to strip 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,
set include_realm to 0. For simple single-realm
installations, doing that combined with setting the
krb_realm parameter (which checks that the principal's realm
matches exactly what is in the krb_realm parameter)
is still secure; but this is a
less capable approach compared to specifying an explicit mapping in
pg_ident.conf.
Make sure that your server keytab file is readable (and preferably
only readable, not writable) by the PostgreSQL
server account. (See also Section 18.1.) The location
of the key file is specified by the krb_server_keyfile configuration
parameter. The default is
/usr/local/pgsql/etc/krb5.keytab (or whatever
directory was specified as sysconfdir at build time).
For security reasons, it is recommended to use a separate keytab
just for the PostgreSQL server rather
than opening up permissions on the system keytab file.
The keytab file is generated by the Kerberos software; see the Kerberos documentation for details. The following example is for MIT-compatible Kerberos 5 implementations:
kadmin%ank -randkey postgres/server.my.domain.orgkadmin%ktadd -k krb5.keytab postgres/server.my.domain.org
When connecting to the database make sure you have a ticket for a
principal matching the requested database user name. For example, for
database user name fred, principal
fred@EXAMPLE.COM would be able to connect. To also allow
principal fred/users.example.com@EXAMPLE.COM, use a user name
map, as described in Section 20.2.
The following configuration options are supported for GSSAPI:
include_realm
If set to 0, the realm name from the authenticated user principal is
stripped off before being passed through the user name mapping
(Section 20.2). This is discouraged and is
primarily available for backwards compatibility, as it is not secure
in multi-realm environments unless krb_realm is
also used. It is recommended to
leave include_realm set to the default (1) and to
provide an explicit mapping in pg_ident.conf to convert
principal names to PostgreSQL user names.
map
Allows for mapping between system and database user names. See
Section 20.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 is
username@EXAMPLE.COM (or
username/hostbased@EXAMPLE.COM, respectively),
unless include_realm has been set to 0, in which case
username (or username/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.