20.6. GSSAPI Authentication
GSSAPI is an industry-standard protocol for secure authentication defined in RFC 2743. PostgreSQL supports GSSAPI with Kerberos authentication according to RFC 1964. GSSAPI provides automatic authentication (single sign-on) for systems that support it. The authentication itself is secure, but the data sent over the database connection will be sent unencrypted unless SSL is used.
GSSAPI support has to be enabled when PostgreSQL is built; see Chapter 16 for more information.
, it uses a standard principal
in the format
connection parameter. (See
.) The installation default can be
changed from the default
at build time using
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 (
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
database user names with
. For example,
could be mapped to just
Alternatively, you can use the full
the role name in
without any mapping.
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,
to 0. For simple single-realm
installations, doing that combined with setting the
parameter (which checks that the principal's realm
matches exactly what is in the
is still secure; but this is a
less capable approach compared to specifying an explicit mapping in
Make sure that your server keytab file is readable (and preferably
only readable, not writable) by the
server account. (See also
.) The location
of the key file is specified by the
parameter. The default is
directory was specified as
at build time).
For security reasons, it is recommended to use a separate keytab
just for the
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:
ank -randkey postgres/server.my.domain.org
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
would be able to connect. To also allow
, use a user name
map, as described in
The following configuration options are supported for GSSAPI :
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_realmis also used. It is recommended to leave
include_realmset to the default (1) and to provide an explicit mapping in
pg_ident.confto convert principal names to PostgreSQL user names.
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/hostbased@EXAMPLE.COM, respectively), unless
include_realmhas been set to 0, in which case
username/hostbased) is what is seen as the system user name when mapping.
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.