@ -450,17 +450,6 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>krb5</></term>
<listitem>
<para>
Use Kerberos V5 to authenticate the user. This is only
available for TCP/IP connections. See <xref
linkend="kerberos-auth"> for details.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>ident</></term>
<listitem>
@ -650,13 +639,13 @@ host all all .example.com md5
# In the absence of preceding "host" lines, these two lines will
# reject all connections from 192.168.54.1 (since that entry will be
# matched first), but allow Kerberos 5 connections from anywhere else
# matched first), but allow GSSAPI connections from anywhere else
# on the Internet. The zero mask causes no bits of the host IP
# address to be considered, so it matches any host.
#
# TYPE DATABASE USER ADDRESS METHOD
host all all 192.168.54.1/32 reject
host all all 0.0.0.0/0 krb5
host all all 0.0.0.0/0 gss
# Allow users from 192.168.x.x hosts to connect to any database, if
# they pass the ident check. If, for example, ident says the user is
@ -924,17 +913,75 @@ omicron bryanh guest1
<acronym>SSL</acronym> is used.
</para>
<para>
GSSAPI support has to be enabled when <productname>PostgreSQL</> is built;
see <xref linkend="installation"> for more information.
</para>
<para>
When <productname>GSSAPI</productname> uses
<productname>Kerberos</productname>, it uses a standard principal
in the format
<literal><replaceable>servicename</>/<replaceable>hostname</>@<replaceable>realm</></literal>. For information about the parts of the principal, and
how to set up the required keys, see <xref linkend="kerberos-auth">.
<literal><replaceable>servicename</>/<replaceable>hostname</>@<replaceable>realm</></literal>.
<replaceable>servicename</> can be set on the server side using the
<xref linkend="guc-krb-srvname"> configuration parameter, and on the
client side using the <literal>krbsrvname</> connection parameter. (See
also <xref linkend="libpq-paramkeywords">.) The installation default can be
changed from the default <literal>postgres</literal> at build time using
<literal>./configure --with-krb-srvnam=</><replaceable>whatever</>.
In most environments,
this parameter never needs to be changed. However, it is necessary
when supporting multiple <productname>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 (<literal>POSTGRES</literal>).
</para>
<para>
<replaceable>hostname</> is the fully qualified host name of the
server machine. The service principal's realm is the preferred realm
of the server machine.
</para>
<para>
GSSAPI support has to be enabled when <productname>PostgreSQL</> is built;
see <xref linkend="installation"> for more information.
Client principals must have their <productname>PostgreSQL</> database user
name as their first component, for example
<literal>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 <productname>PostgreSQL</>. If you have cross-realm
authentication enabled and need to verify the realm, use the
<literal>krb_realm</> parameter, or enable <literal>include_realm</>
and use user name mapping to check the realm.
</para>
<para>
Make sure that your server keytab file is readable (and preferably
only readable) by the <productname>PostgreSQL</productname> server
account. (See also <xref linkend="postgres-user">.) The location
of the key file is specified by the <xref
linkend="guc-krb-server-keyfile"> configuration
parameter. The default is
<filename>/usr/local/pgsql/etc/krb5.keytab</> (or whatever
directory was specified as <varname>sysconfdir</> at build time).
</para>
<para>
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:
<screen>
<prompt>kadmin% </><userinput>ank -randkey postgres/server.my.domain.org</>
<prompt>kadmin% </><userinput>ktadd -k krb5.keytab postgres/server.my.domain.org</>
</screen>
</para>
<para>
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 <literal>fred</>, principal
<literal>fred@EXAMPLE.COM</> would be able to connect. To also allow
principal <literal>fred/users.example.com@EXAMPLE.COM</>, use a user name
map, as described in <xref linkend="auth-username-maps">.
</para>
<para>
@ -1050,178 +1097,6 @@ omicron bryanh guest1
</para>
</sect2>
<sect2 id="kerberos-auth">
<title>Kerberos Authentication</title>
<indexterm zone="kerberos-auth">
<primary>Kerberos</primary>
</indexterm>
<note>
<para>
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 <productname>GSSAPI</productname>
authentication method (see <xref linkend="gssapi-auth">) instead.
</para>
</note>
<para>
<productname>Kerberos</productname> is an industry-standard secure
authentication system suitable for distributed computing over a public
network. A description of the <productname>Kerberos</productname> system
is beyond the scope of this document; in full generality it can be
quite complex (yet powerful). The
<ulink url="http://www.cmf.nrl.navy.mil/CCS/people/kenh/kerberos-faq.html">
Kerberos <acronym>FAQ</></ulink> or
<ulink url="http://web.mit.edu/kerberos/www/">MIT Kerberos page</ulink>
can be good starting points for exploration.
Several sources for <productname>Kerberos</> distributions exist.
<productname>Kerberos</productname> provides secure authentication but
does not encrypt queries or data passed over the network; for that
use <acronym>SSL</acronym>.
</para>
<para>
<productname>PostgreSQL</> supports Kerberos version 5. Kerberos
support has to be enabled when <productname>PostgreSQL</> is built;
see <xref linkend="installation"> for more information.
</para>
<para>
<productname>PostgreSQL</> operates like a normal Kerberos service.
The name of the service principal is
<literal><replaceable>servicename</>/<replaceable>hostname</>@<replaceable>realm</></literal>.
</para>
<para>
<replaceable>servicename</> can be set on the server side using the
<xref linkend="guc-krb-srvname"> configuration parameter, and on the
client side using the <literal>krbsrvname</> connection parameter. (See
also <xref linkend="libpq-paramkeywords">.) The installation default can be
changed from the default <literal>postgres</literal> at build time using
<literal>./configure --with-krb-srvnam=</><replaceable>whatever</>.
In most environments,
this parameter never needs to be changed. However, it is necessary
when supporting multiple <productname>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 (<literal>POSTGRES</literal>).
</para>
<para>
<replaceable>hostname</> is the fully qualified host name of the
server machine. The service principal's realm is the preferred realm
of the server machine.
</para>
<para>
Client principals must have their <productname>PostgreSQL</> database user
name as their first component, for example
<literal>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 <productname>PostgreSQL</>. If you have cross-realm
authentication enabled and need to verify the realm, use the
<literal>krb_realm</> parameter, or enable <literal>include_realm</>
and use user name mapping to check the realm.
</para>
<para>
Make sure that your server keytab file is readable (and preferably
only readable) by the <productname>PostgreSQL</productname> server
account. (See also <xref linkend="postgres-user">.) The location
of the key file is specified by the <xref
linkend="guc-krb-server-keyfile"> configuration
parameter. The default is
<filename>/usr/local/pgsql/etc/krb5.keytab</> (or whatever
directory was specified as <varname>sysconfdir</> at build time).
</para>
<para>
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:
<screen>
<prompt>kadmin% </><userinput>ank -randkey postgres/server.my.domain.org</>
<prompt>kadmin% </><userinput>ktadd -k krb5.keytab postgres/server.my.domain.org</>
</screen>
</para>
<para>
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 <literal>fred</>, principal
<literal>fred@EXAMPLE.COM</> would be able to connect. To also allow
principal <literal>fred/users.example.com@EXAMPLE.COM</>, use a user name
map, as described in <xref linkend="auth-username-maps">.
</para>
<para>
If you use <ulink url="http://modauthkerb.sf.net">
<application>mod_auth_kerb</application></ulink>
and <application>mod_perl</application> on your
<productname>Apache</productname> web server, you can use
<literal>AuthType KerberosV5SaveCredentials</literal> with a
<application>mod_perl</application> script. This gives secure
database access over the web, with no additional passwords required.
</para>
<para>
The following configuration options are supported for
<productname>Kerberos</productname>:
<variablelist>
<varlistentry>
<term><literal>map</literal></term>
<listitem>
<para>
Allows for mapping between system and database user names. See
<xref linkend="auth-username-maps"> for details.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>include_realm</literal></term>
<listitem>
<para>
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 (<xref linkend="auth-username-maps">). This is
useful for handling users from multiple realms.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>krb_realm</literal></term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>krb_server_hostname</literal></term>
<listitem>
<para>
Sets the host name part of the service principal.
This, combined with <varname>krb_srvname</>, is used to generate
the complete service principal, that is
<varname>krb_srvname</><literal>/</><varname>krb_server_hostname</><literal>@</>REALM.
If not set, the default is the server host name.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
<sect2 id="auth-ident">
<title>Ident Authentication</title>
Magnus Hagander
12 years ago