The PostgreSQL 9.0 Reference Manual - Volume 3 - Server Administration Guide by The PostgreSQL Global Development Group Paperback (6"x9"), 274 pages ISBN 9781906966072 RRP £9.95 ($14.95) Sales of this book support the PostgreSQL project! Get a printed copy>>>

PostgreSQL 9.0 Reference Manual Volume 3 Buy the book here! >>> learn more

5.3.5 Kerberos authentication

Note: Native Kerberos authentication has been deprecated and should be used only for backward compatibility. New and upgraded installations are encouraged to use the industry-standard GSSAPI authentication method (see section 5.3.3 GSSAPI authentication) instead.

Kerberos is an industry-standard secure authentication system suitable for distributed computing over a public network. A description of the Kerberos system is beyond the scope of this document; in full generality it can be quite complex (yet powerful). The Kerberos FAQ or MIT Kerberos page can be good starting points for exploration. Several sources for Kerberos distributions exist. Kerberos provides secure authentication but does not encrypt queries or data passed over the network; for that use SSL.

PostgreSQL supports Kerberos version 5. Kerberos support has to be enabled when PostgreSQL is built; see section 1 Installation from Source Code for more information.

PostgreSQL operates like a normal Kerberos service. The name of the service principal is servicename/hostname@realm.

servicename can be set on the server side using the krb_srvname configuration parameter, and on the client side using the krbsrvname connection parameter. (See also Volume 2: Database Connection Control Functions.) 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. However, it is necessary when supporting multiple PostgreSQL installations on the same host. Some Kerberos implementations might also 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 must have their PostgreSQL database user name as their first component, for example pgusername@realm. Alternatively, you can use a user name mapping to map from the first component of the principal name to the database user name. By default, the realm of the client is not checked by PostgreSQL. If you have cross-realm authentication enabled and need to verify the realm, use the krb_realm parameter, or enable include_realm and use user name mapping to check the realm.

Make sure that your server keytab file is readable (and preferably only readable) by the PostgreSQL server account. (See also section 3.1 The PostgreSQL User Account.) 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).

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.org
kadmin% 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 5.2 User name maps.

If you use mod_auth_kerb and mod_perl on your Apache web server, you can use AuthType KerberosV5SaveCredentials with a mod_perl script. This gives secure database access over the web, with no additional passwords required.

The following configuration options are supported for Kerberos:

map

Allows for mapping between system and database user names. See section 5.2 User name maps for details.

include_realm

If set to 1, the realm name from the authenticated user principal is included in the system user name that's passed through user name mapping (section 5.2 User name maps). This is useful for handling users from multiple realms.

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.

krb_server_hostname

Sets the host name part of the service principal. This, combined with krb_srvname, is used to generate the complete service principal, that is krb_srvname/krb_server_hostname@REALM. If not set, the default is the server host name.