21.6. GSSAPI Authentication
GSSAPI is an industry-standard protocol for secure authentication defined in RFC 2743 . PostgreSQL supports GSSAPI for authentication, communications encryption, or both. GSSAPI provides automatic authentication (single sign-on) for systems that support it. The authentication itself is secure. If GSSAPI encryption or SSL encryption is 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 17 for more information.
When
GSSAPI
uses
Kerberos
, it uses a standard service
principal (authentication identity) name in the format
.
The principal name used by a particular installation is not encoded in
the
PostgreSQL
server in any way; rather it
is specified in the
keytab
file that the server
reads to determine its identity. If multiple principals are listed in
the keytab file, the server will accept any one of them.
The server's realm name is the preferred realm specified in the Kerberos
configuration file(s) accessible to the server.
servicename
/
hostname
@
realm
When connecting, the client must know the principal name of the server
it intends to connect to. The
servicename
part of the principal is ordinarily
postgres
,
but another value can be selected via
libpq
's
krbsrvname
connection parameter.
The
hostname
part is the fully qualified
host name that
libpq
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
use
GSSAPI
for authentication, the client
principal must be associated with
a
PostgreSQL
database user name.
The
pg_ident.conf
configuration file can be used
to map principals to user names; 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 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,
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
.
The location of the server's keytab file is specified by the krb_server_keyfile configuration parameter. For security reasons, it is recommended to use a separate keytab just for the PostgreSQL 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 the PostgreSQL server account. (See also Section 19.1 .)
The keytab file is generated using the Kerberos software; see the Kerberos documentation for details. The following example shows doing this using the kadmin tool of MIT Kerberos:
kadmin%
addprinc -randkey postgres/server.my.domain.org
kadmin%
ktadd -k krb5.keytab postgres/server.my.domain.org
The following authentication options are supported for the GSSAPI authentication method:
-
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 21.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 leaveinclude_realm
set to the default (1) and to provide an explicit mapping inpg_ident.conf
to convert principal names to PostgreSQL user names. -
map
-
Allows mapping from client principals to database user names. See Section 21.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_realm
has been set to 0, in which caseusername
(orusername/hostbased
) is what is seen as the system user name when mapping. -
krb_realm
-
Sets 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
different
pg_hba.conf
entries, there is the
server-wide
krb_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.