797 lines
32 KiB
Plaintext
797 lines
32 KiB
Plaintext
<!--
|
|
$Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.35 2002/04/09 00:38:24 momjian Exp $
|
|
-->
|
|
|
|
<chapter id="client-authentication">
|
|
<title>Client Authentication</title>
|
|
|
|
<indexterm zone="client-authentication">
|
|
<primary>client authentication</primary>
|
|
</indexterm>
|
|
|
|
<para>
|
|
When a client application connects to the database server, it
|
|
specifies which <productname>PostgreSQL</productname> user name it
|
|
wants to connect as, much the same way one logs into a Unix computer
|
|
as a particular user. Within the SQL environment the active database
|
|
user name determines access privileges to database objects -- see
|
|
<xref linkend="user-manag"> for more information. Therefore, it is
|
|
essential to restrict which database users can connect.
|
|
</para>
|
|
|
|
<para>
|
|
<firstterm>Authentication</firstterm> is the process by which the
|
|
database server establishes the identity of the client, and by
|
|
extension determines whether the client application (or the user
|
|
who runs the client application) is permitted to connect with the
|
|
user name that was requested.
|
|
</para>
|
|
|
|
<para>
|
|
<productname>PostgreSQL</productname> offers a number of different
|
|
client authentication methods. The method to be used can be selected
|
|
on the basis of (client) host, database, and user.
|
|
</para>
|
|
|
|
<para>
|
|
<productname>PostgreSQL</productname> user names are logically
|
|
separate from user names of the operating system in which the server
|
|
runs. If all the users of a particular server also have accounts on
|
|
the server's machine, it makes sense to assign database user names
|
|
that match their operating system user names. However, a server that
|
|
accepts remote connections may have many users who have no local
|
|
account, and in such cases there need be no connection between
|
|
database user names and OS user names.
|
|
</para>
|
|
|
|
<sect1 id="pg-hba-conf">
|
|
<title>The <filename>pg_hba.conf</filename> file</title>
|
|
|
|
<indexterm zone="pg-hba-conf">
|
|
<primary>pg_hba.conf</primary>
|
|
</indexterm>
|
|
|
|
<para>
|
|
Client authentication is controlled by the file
|
|
<filename>pg_hba.conf</filename> in the data directory, e.g.,
|
|
<filename>/usr/local/pgsql/data/pg_hba.conf</filename>.
|
|
(<acronym>HBA</> stands for host-based authentication.) A default
|
|
<filename>pg_hba.conf</filename> file is installed when the data area
|
|
is initialized by <command>initdb</command>.
|
|
</para>
|
|
|
|
<para>
|
|
The general format of the <filename>pg_hba.conf</filename> file is of
|
|
a set of records, one per line. Blank lines are ignored, as is any
|
|
text after the <quote>#</quote> comment character. A record is made
|
|
up of a number of fields which are separated by spaces and/or tabs.
|
|
Fields can contain white space if the field value is quoted. Records
|
|
cannot be continued across lines.
|
|
</para>
|
|
|
|
<para>
|
|
Each record specifies a connection type, a client IP address range
|
|
(if relevant for the connection type), a database name, a user name,
|
|
and the authentication method to be used for connections matching
|
|
these parameters. The first record with a matching connection type,
|
|
client address, requested database, and user name is used to perform
|
|
authentication. There is no <quote>fall-through</> or
|
|
<quote>backup</>: if one record is chosen and the authentication
|
|
fails, subsequent records are not considered. If no record matches,
|
|
access is denied.
|
|
</para>
|
|
|
|
<para>
|
|
A record may have one of the three formats
|
|
<synopsis>
|
|
local <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>authentication-method</replaceable> [ <replaceable>authentication-option</replaceable> ]
|
|
host <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>authentication-method</replaceable>
|
|
hostssl <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>authentication-method</replaceable>
|
|
</synopsis>
|
|
The meaning of the fields is as follows:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><literal>local</literal></term>
|
|
<listitem>
|
|
<para>
|
|
This record applies to connection attempts using Unix domain
|
|
sockets.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>host</literal></term>
|
|
<listitem>
|
|
<para>
|
|
This record applied to connection attempts using TCP/IP networks.
|
|
Note that TCP/IP connections are disabled unless the server is
|
|
started with the <option>-i</option> option or the
|
|
<literal>tcpip_socket</> <filename>postgresql.conf</>
|
|
configuration parameter is enabled.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>hostssl</literal></term>
|
|
<listitem>
|
|
<para>
|
|
This record applies to connection attempts using SSL over
|
|
TCP/IP. To make use of this option the server must be
|
|
built with SSL support enabled. Furthermore, SSL must be
|
|
enabled with the <option>-l</> option or equivalent configuration
|
|
setting when the server is started. (Note: <literal>host</literal>
|
|
records will match either SSL or non-SSL connection attempts, but
|
|
<literal>hostssl</literal> records requires SSL connections.)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable>database</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the database for this record. The value
|
|
<literal>all</literal> specifies that it applies to all
|
|
databases, while the value <literal>sameuser</> identifies the
|
|
database with the same name as the connecting user. The value
|
|
<literal>samegroup</> identifies a group with the same name as
|
|
the database name. Only members of this group can connect to the
|
|
database. Otherwise, this is the name of a specific
|
|
<productname>PostgreSQL</productname> database. Multiple database
|
|
names can be supplied by separating them with commas. A file
|
|
containing database names can be specified by preceding the file
|
|
name with <literal>@</>. The file must be in the same directory
|
|
as <filename>pg_hba.conf</>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable>user</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the user for this record. The value
|
|
<literal>all</literal> specifies that it applies to all users.
|
|
Otherwise, this is the name of a specific
|
|
<productname>PostgreSQL</productname> user. Multiple user names
|
|
can be supplied by separating them with commas. Group names can
|
|
be specified by preceding the group name with <literal>+</>. A
|
|
file containing user names can be specified by preceding the file
|
|
name with <literal>@</>. The file must be in the same directory
|
|
as <filename>pg_hba.conf</>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable>IP address</replaceable></term>
|
|
<term><replaceable>IP mask</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
These two fields specify the client machine IP addresses
|
|
(<literal>host</literal> or <literal>hostssl</literal>) for this
|
|
record. (Of course IP addresses can be spoofed but this
|
|
consideration is beyond the scope of
|
|
<productname>PostgreSQL</productname>.) The precise logic is that
|
|
<blockquote>
|
|
<informalfigure>
|
|
<programlisting>(<replaceable>actual-IP-address</replaceable> xor <replaceable>IP-address-field</replaceable>) and <replaceable>IP-mask-field</replaceable></programlisting>
|
|
</informalfigure>
|
|
</blockquote>
|
|
must be zero for the record to match.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable>authentication method</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the authentication method to use when connecting via
|
|
this record. The possible choices are summarized here; details
|
|
are in <xref linkend="auth-methods">.
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><literal>trust</></term>
|
|
<listitem>
|
|
<para>
|
|
The connection is allowed unconditionally. This method allows
|
|
any user that has login access to the client host to connect as
|
|
any <productname>PostgreSQL</productname> user whatsoever.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>reject</></term>
|
|
<listitem>
|
|
<para>
|
|
The connection is rejected unconditionally. This is useful for
|
|
<quote>filtering out</> certain hosts from a group.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>md5</></term>
|
|
<listitem>
|
|
<para>
|
|
Requires the client to supply an MD5 encrypted password for
|
|
authentication. This is the only method that allows encrypted
|
|
passwords to be stored in pg_shadow.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>crypt</></term>
|
|
<listitem>
|
|
<para>
|
|
Like <literal>md5</literal> method but uses older crypt
|
|
encryption, which is needed for pre-7.2 clients.
|
|
<literal>md5</literal> is preferred for 7.2 and later clients.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>password</></term>
|
|
<listitem>
|
|
<para>
|
|
Same as "md5", but the password is sent in cleartext over the
|
|
network. This should not be used on untrusted networks.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>krb4</></term>
|
|
<listitem>
|
|
<para>
|
|
Kerberos V4 is used to authenticate the user. This is only
|
|
available for TCP/IP connections.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>krb5</></term>
|
|
<listitem>
|
|
<para>
|
|
Kerberos V5 is used to authenticate the user. This is only
|
|
available for TCP/IP connections.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>ident</></term>
|
|
<listitem>
|
|
<para>
|
|
For TCP/IP connections, authentication is done by contacting
|
|
the <firstterm>ident</firstterm> server on the client host.
|
|
This is only as secure as the client machine. You must specify
|
|
the map name after the 'ident' keyword. It determines how to
|
|
map remote user names to PostgreSQL user names. If you use
|
|
"sameuser", the user names are assumed to be identical. If
|
|
not, the map name is looked up in the $PGDATA/pg_ident.conf
|
|
file. The connection is accepted if that file contains an
|
|
entry for this map name with the ident-supplied user name and
|
|
the requested PostgreSQL user name.
|
|
</para>
|
|
<para>
|
|
On machines that support unix-domain socket credentials
|
|
(currently Linux, FreeBSD, NetBSD, and BSD/OS), ident allows
|
|
reliable authentication of 'local' connections without ident
|
|
running on the local machine.
|
|
</para>
|
|
<para>
|
|
On systems without <symbol>SO_PEERCRED</> requests, ident
|
|
authentication is only available for TCP/IP connections. As a
|
|
work around, it is possible to specify the <systemitem
|
|
class="systemname">localhost</> address <systemitem
|
|
class="systemname">127.0.0.1</> and make connections to this
|
|
address.
|
|
</para>
|
|
<para>
|
|
Following the <literal>ident</> keyword, an <firstterm>ident
|
|
map</firstterm> name should be supplied which specifies which
|
|
operating system users equate with which database users. See
|
|
below for details.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>pam</></term>
|
|
<listitem>
|
|
<para>
|
|
This authentication type operates similarly to
|
|
<firstterm>password</firstterm> except that it uses PAM
|
|
(Pluggable Authentication Modules) as the authentication
|
|
mechanism. The default PAM service name is
|
|
<literal>postgresql</literal>. You can optionally supply you
|
|
own service name after the <literal>pam</> keyword in the
|
|
file. For more information about PAM, please read the <ulink
|
|
url="http://www.kernel.org/pub/linux/libs/pam/"><productname>L
|
|
inux-PAM</productname> Page</ulink> and the <ulink
|
|
url="http://www.sun.com/software/solaris/pam/"><systemitem
|
|
class="osname">Solaris</> PAM Page</ulink>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</para>
|
|
|
|
<para>
|
|
Since the <filename>pg_hba.conf</filename> records are examined
|
|
sequentially for each connection attempt, the order of the records is
|
|
significant. Typically, earlier records will have tight connection
|
|
match parameters and weaker authentication methods, while later
|
|
records will have looser match parameters and stronger authentication
|
|
methods. For example, one might wish to use <literal>trust</>
|
|
authentication for local TCP connections but require a password for
|
|
remote TCP connections. In this case a record specifying
|
|
<literal>trust</> authentication for connections from 127.0.0.1 would
|
|
appear before a record specifying password authentication for a wider
|
|
range of allowed client IP addresses.
|
|
</para>
|
|
|
|
<para>
|
|
<indexterm>
|
|
<primary>SIGHUP</primary>
|
|
</indexterm>
|
|
The <filename>pg_hba.conf</filename> file is read on start-up and when
|
|
the <application>postmaster</> receives a
|
|
<systemitem>SIGHUP</systemitem> signal. If you edit the file on an
|
|
active system, you will need to signal the <application>postmaster</>
|
|
(using <literal>pg_ctl reload</> or <literal>kill -HUP</>) to make it
|
|
re-read the file.
|
|
</para>
|
|
|
|
<para>
|
|
An example of a <filename>pg_hba.conf</filename> file is shown in
|
|
<xref linkend="example-pg-hba.conf">. See below for details on the
|
|
different authentication methods.
|
|
|
|
<example id="example-pg-hba.conf">
|
|
<title>An example <filename>pg_hba.conf</filename> file</title>
|
|
<programlisting>
|
|
# TYPE DATABASE USER IP_ADDRESS MASK AUTHTYPE
|
|
|
|
# Allow any user on the local system to connect to any
|
|
# database under any user name, but only via an IP connection:
|
|
|
|
host all all 127.0.0.1 255.255.255.255 trust
|
|
|
|
# The same, over Unix-socket connections:
|
|
|
|
local all all trust
|
|
|
|
# Allow any user from any host with IP address 192.168.93.x to
|
|
# connect to database "template1" as the same user name that ident on that
|
|
# host identifies him as (typically his Unix user name):
|
|
|
|
host template1 all 192.168.93.0 255.255.255.0 ident sameuser
|
|
|
|
# Allow a user from host 192.168.12.10 to connect to database "template1"
|
|
# if the user's password is correctly supplied:
|
|
|
|
host template1 all 192.168.12.10 255.255.255.255 md5
|
|
|
|
# In the absence of preceding "host" lines, these two lines will reject
|
|
# all connection attempts from 192.168.54.1 (since that entry will be
|
|
# matched first), but allow Kerberos V5-validated connections from anywhere
|
|
# else on the Internet. The zero mask means that no bits of the host IP
|
|
# address are considered, so it matches any host:
|
|
|
|
host all all 192.168.54.1 255.255.255.255 reject
|
|
host all all 0.0.0.0 0.0.0.0 krb5
|
|
|
|
# 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 "bryanh"
|
|
# and he requests to connect as <productname>PostgreSQL</> user "guest1", the connection
|
|
# is allowed if there is an entry in pg_ident.conf for map "omicron" that
|
|
# says "bryanh" is allowed to connect as "guest1":
|
|
|
|
host all all 192.168.0.0 255.255.0.0 ident omicron
|
|
|
|
# If these are the only two lines for local connections, they will allow
|
|
# local users to connect only to their own databases (database named the
|
|
# same as the user name), except for administrators who may connect to
|
|
# all databases. The file $PGDATA/admins lists the user names who are
|
|
# permitted to connect to all databases. Passwords are required in all
|
|
# cases. (If you prefer to use ident authorization, an ident map can
|
|
# serve a parallel purpose to the password list file used here.)
|
|
|
|
local sameuser all md5
|
|
local all @admins md5
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="auth-methods">
|
|
<title>Authentication methods</title>
|
|
<para>
|
|
The following describes the authentication methods in more detail.
|
|
</para>
|
|
|
|
<sect2 id="auth-trust">
|
|
<title>Trust authentication</title>
|
|
|
|
<para>
|
|
When <literal>trust</> authentication is specified,
|
|
<productname>PostgreSQL</productname> assumes that anyone who can
|
|
connect to the postmaster is authorized to access the database as
|
|
whatever database user he specifies (including the database superuser).
|
|
This method should only be used when there is adequate system-level
|
|
protection on connections to the postmaster port.
|
|
</para>
|
|
|
|
<para>
|
|
<literal>trust</> authentication is appropriate and very convenient
|
|
for local connections on a single-user workstation. It is usually
|
|
<emphasis>not</> appropriate by itself on a multiuser machine.
|
|
However, you may be able to use <literal>trust</> even on a multiuser
|
|
machine, if you restrict access to the postmaster's socket file using
|
|
file-system permissions. To do this, set the parameter
|
|
<varname>unix_socket_permissions</varname> (and possibly
|
|
<varname>unix_socket_group</varname>) in <filename>postgresql.conf</>,
|
|
as described in <xref linkend="runtime-config-general">. Or you could
|
|
set <varname>unix_socket_directory</varname> to place the socket file
|
|
in a suitably restricted directory.
|
|
</para>
|
|
|
|
<para>
|
|
Setting file-system permissions only helps for Unix-socket connections.
|
|
Local TCP connections are not restricted by it; therefore, if you want
|
|
to use permissions for local security, remove the <literal>host ...
|
|
127.0.0.1 ...</> line from <filename>pg_hba.conf</>, or change it to a
|
|
non-<literal>trust</> authentication method.
|
|
</para>
|
|
|
|
<para>
|
|
<literal>trust</> authentication is only suitable for TCP connections
|
|
if you trust every user on every machine that is allowed to connect
|
|
to the postmaster by the <filename>pg_hba.conf</> lines that specify
|
|
<literal>trust</>. It is seldom reasonable to use <literal>trust</>
|
|
for any TCP connections other than those from localhost (127.0.0.1).
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="auth-password">
|
|
<title>Password authentication</title>
|
|
|
|
<indexterm>
|
|
<primary>MD5</>
|
|
</indexterm>
|
|
<indexterm>
|
|
<primary>crypt</>
|
|
</indexterm>
|
|
<indexterm>
|
|
<primary>password</primary>
|
|
</indexterm>
|
|
|
|
<para>
|
|
Password-based authentication methods include <literal>md5</>,
|
|
<literal>crypt</>, and <literal>password</>. These methods operate
|
|
similarly except for the way that the password is sent across the
|
|
connection. If you are at all concerned about password
|
|
<quote>sniffing</> attacks then <literal>md5</> is preferred, with
|
|
<literal>crypt</> a second choice if you must support pre-7.2
|
|
clients. Plain <literal>password</> should especially be avoided for
|
|
connections over the open Internet (unless you use SSL, SSH, or
|
|
other communications security wrappers around the connection).
|
|
</para>
|
|
|
|
<para>
|
|
<productname>PostgreSQL</productname> database passwords are
|
|
separate from operating system user passwords. Ordinarily, the
|
|
password for each database user is stored in the pg_shadow system
|
|
catalog table. Passwords can be managed with the query language
|
|
commands <command>CREATE USER</command> and <command>ALTER
|
|
USER</command>, e.g., <userinput>CREATE USER foo WITH PASSWORD
|
|
'secret';</userinput>. By default, that is, if no password has been
|
|
set up, the stored password is <literal>NULL</literal> and password
|
|
authentication will always fail for that user.
|
|
</para>
|
|
|
|
<para>
|
|
To restrict the set of users that are allowed to connect to certain
|
|
databases, list the users separated by commas, or in a separate
|
|
file. The file should contain user names separated by commas or one
|
|
user name per line, and be in the same directory as
|
|
<filename>pg_hba.conf</>. Mention the (base) name of the file
|
|
preceded with <literal>@</>in the <literal>USER</> column. The
|
|
<literal>DATABASE</> column can similarly accept a list of values or
|
|
a file name. You can also specify group names by preceding the group
|
|
name with <literal>+</>.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="kerberos-auth">
|
|
<title>Kerberos authentication</title>
|
|
|
|
<indexterm zone="kerberos-auth">
|
|
<primary>Kerberos</primary>
|
|
</indexterm>
|
|
|
|
<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 far beyond the scope
|
|
of this document; in all generality it can be quite complex (yet
|
|
powerful). The <ulink
|
|
url="http://www.nrl.navy.mil/CCS/people/kenh/kerberos-faq.html">Kerb
|
|
eros <acronym>FAQ</></ulink> or <ulink
|
|
url="ftp://athena-dist.mit.edu">MIT Project Athena</ulink> can be a
|
|
good starting point for exploration. Several sources for
|
|
<productname>Kerberos</> distributions exist.
|
|
</para>
|
|
|
|
<para>
|
|
In order to use <productname>Kerberos</>, support for it must be
|
|
enabled at build time. Both Kerberos 4 and 5 are supported
|
|
(<literal>./configure --with-krb4</> or <literal>./configure
|
|
--with-krb5</> respectively), although only one version can be
|
|
supported in any one build.
|
|
</para>
|
|
|
|
<para>
|
|
<productname>PostgreSQL</> operates like a normal Kerberos service.
|
|
The name of the service principal is
|
|
<replaceable>servicename/hostname@realm</>, where
|
|
<replaceable>servicename</> is <literal>postgres</literal> (unless a
|
|
different service name was selected at configure time with
|
|
<literal>./configure --with-krb-srvnam=whatever</>).
|
|
<replaceable>hostname</> is the fully qualified domain 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</> user
|
|
name as their first component, for example
|
|
<replaceable>pgusername/otherstuff@realm</>. At present the realm of
|
|
the client is not checked by <productname>PostgreSQL</>; so if you
|
|
have cross-realm authentication enabled, then any principal in any
|
|
realm that can communicate with yours will be accepted.
|
|
</para>
|
|
|
|
<para>
|
|
Make sure that your server key file is readable (and preferably only
|
|
readable) by the <productname>PostgreSQL</productname> server
|
|
account (see <xref linkend="postgres-user">). The location of the
|
|
key file is specified with the <varname>krb_server_keyfile</> run
|
|
time configuration parameter. (See also <xref
|
|
linkend="runtime-config">.) The default is <filename>/etc/srvtab</>
|
|
if you are using Kerberos 4 and
|
|
<filename>FILE:/usr/local/pgsql/etc/krb5.keytab</> (or whichever
|
|
directory was specified as <varname>sysconfdir</> at build time)
|
|
with Kerberos 5.
|
|
</para>
|
|
|
|
<para>
|
|
To generate the keytab file, use for example (with version 5)
|
|
<screen>
|
|
<prompt>kadmin% </><userinput>ank -randkey postgres/server.my.domain.org</>
|
|
<prompt>kadmin% </><userinput>ktadd -k krb5.keytab postgres/server.my.domain.org</>
|
|
</screen>
|
|
Read the <productname>Kerberos</> documentation for details.
|
|
</para>
|
|
|
|
<para>
|
|
When connecting to the database make sure you have a ticket for a
|
|
principal matching the requested database user name. An example: For
|
|
database user name <literal>fred</>, both principal
|
|
<literal>fred@EXAMPLE.COM</> and
|
|
<literal>fred/users.example.com@EXAMPLE.COM</> can be used to
|
|
authenticate to the database server.
|
|
</para>
|
|
|
|
<para>
|
|
If you use <application>mod_auth_krb</application> 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, no extra passwords required.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Ident-based authentication</title>
|
|
|
|
<indexterm>
|
|
<primary>ident</primary>
|
|
</indexterm>
|
|
|
|
<para>
|
|
The <quote>Identification Protocol</quote> is described in
|
|
<citetitle>RFC 1413</citetitle>. Virtually every Unix-like
|
|
operating system ships with an ident server that listens on TCP
|
|
port 113 by default. The basic functionality of an ident server
|
|
is to answer questions like <quote>What user initiated the
|
|
connection that goes out of your port <replaceable>X</replaceable>
|
|
and connects to my port <replaceable>Y</replaceable>?</quote>.
|
|
Since <productname>PostgreSQL</> knows both <replaceable>X</> and
|
|
<replaceable>Y</> when a physical connection is established, it
|
|
can interrogate the ident server on the host of the connecting
|
|
client and could theoretically determine the operating system user
|
|
for any given connection this way.
|
|
</para>
|
|
|
|
<para>
|
|
The drawback of this procedure is that it depends on the integrity
|
|
of the client: if the client machine is untrusted or compromised
|
|
an attacker could run just about any program on port 113 and
|
|
return any user name he chooses. This authentication method is
|
|
therefore only appropriate for closed networks where each client
|
|
machine is under tight control and where the database and system
|
|
administrators operate in close contact. In other words, you must
|
|
trust the machine running the ident server.
|
|
Heed the warning:
|
|
<blockquote>
|
|
<attribution>RFC 1413</attribution>
|
|
<para>
|
|
The Identification Protocol is not intended as an authorization
|
|
or access control protocol.
|
|
</para>
|
|
</blockquote>
|
|
</para>
|
|
|
|
<para>
|
|
On systems supporting <symbol>SO_PEERCRED</symbol> requests for
|
|
Unix-domain sockets, ident authentication can also be applied to
|
|
local connections. In this case, no security risk is added by using
|
|
ident authentication; indeed it is a preferable choice for local
|
|
connections on such systems.
|
|
</para>
|
|
|
|
<para>
|
|
When using ident-based authentication, after having determined the
|
|
name of the operating system user that initiated the connection,
|
|
<productname>PostgreSQL</productname> checks whether that user is
|
|
allowed to connect as the database user he is requesting to connect
|
|
as. This is controlled by the ident map argument that follows the
|
|
<literal>ident</> keyword in the <filename>pg_hba.conf</filename>
|
|
file. There is a predefined ident map <literal>sameuser</literal>,
|
|
which allows any operating system user to connect as the database
|
|
user of the same name (if the latter exists). Other maps must be
|
|
created manually.
|
|
</para>
|
|
|
|
<para>
|
|
<indexterm><primary>pg_ident.conf</primary></indexterm> Ident maps
|
|
other than <literal>sameuser</literal> are defined in the file
|
|
<filename>pg_ident.conf</filename> in the data directory, which
|
|
contains lines of the general form:
|
|
<synopsis>
|
|
<replaceable>map-name</> <replaceable>ident-username</> <replaceable>database-username</>
|
|
</synopsis>
|
|
Comments and whitespace are handled in the usual way. The
|
|
<replaceable>map-name</> is an arbitrary name that will be used to
|
|
refer to this mapping in <filename>pg_hba.conf</filename>. The other
|
|
two fields specify which operating system user is allowed to connect
|
|
as which database user. The same <replaceable>map-name</> can be
|
|
used repeatedly to specify more user-mappings within a single map.
|
|
There is no restriction regarding how many database users a given
|
|
operating system user may correspond to and vice versa.
|
|
</para>
|
|
|
|
<para>
|
|
<indexterm>
|
|
<primary>SIGHUP</primary>
|
|
</indexterm>
|
|
The <filename>pg_ident.conf</filename> file is read on start-up and
|
|
when the <application>postmaster</> receives a
|
|
<systemitem>SIGHUP</systemitem> signal. If you edit the file on an
|
|
active system, you will need to signal the <application>postmaster</>
|
|
(using <literal>pg_ctl reload</> or <literal>kill -HUP</>) to make it
|
|
re-read the file.
|
|
</para>
|
|
|
|
<para>
|
|
A <filename>pg_ident.conf</filename> file that could be used in
|
|
conjunction with the <filename>pg_hba.conf</> file in <xref
|
|
linkend="example-pg-hba.conf"> is shown in <xref
|
|
linkend="example-pg-ident.conf">. In this example setup, anyone
|
|
logged in to a machine on the 192.168 network that does not have the
|
|
Unix user name <systemitem>bryanh</>, <systemitem>ann</>, or
|
|
<systemitem>robert</> would not be granted access. Unix user
|
|
<systemitem>robert</> would only be allowed access when he tries to
|
|
connect as <productname>PostgreSQL</> user <systemitem>bob</>, not
|
|
as <systemitem>robert</> or anyone else. <systemitem>ann</> would
|
|
only be allowed to connect as <systemitem>ann</>. User
|
|
<systemitem>bryanh</> would be allowed to connect as either
|
|
<systemitem>bryanh</> himself or as <systemitem>guest1</>.
|
|
</para>
|
|
|
|
<example id="example-pg-ident.conf">
|
|
<title>An example <filename>pg_ident.conf</> file</title>
|
|
<programlisting>
|
|
#MAP IDENT-NAME POSTGRESQL-NAME
|
|
|
|
omicron bryanh bryanh
|
|
omicron ann ann
|
|
# bob has user name robert on these machines
|
|
omicron robert bob
|
|
# bryanh can also connect as guest1
|
|
omicron bryanh guest1
|
|
</programlisting>
|
|
</example>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="client-authentication-problems">
|
|
<title>Authentication problems</title>
|
|
|
|
<para>
|
|
Genuine authentication failures and related problems generally
|
|
manifest themselves through error messages like the following.
|
|
</para>
|
|
|
|
<para>
|
|
<ProgramListing>
|
|
No pg_hba.conf entry for host 123.123.123.123, user andym, database testdb
|
|
</ProgramListing>
|
|
This is what you are most likely to get if you succeed in contacting
|
|
the server, but it does not want to talk to you. As the message
|
|
suggests, the server refused the connection request because it found
|
|
no authorizing entry in its <filename>pg_hba.conf</filename>
|
|
configuration file.
|
|
</para>
|
|
|
|
<para>
|
|
<ProgramListing>
|
|
Password authentication failed for user 'andym'
|
|
</ProgramListing>
|
|
Messages like this indicate that you contacted the server, and it is
|
|
willing to talk to you, but not until you pass the authorization
|
|
method specified in the <filename>pg_hba.conf</filename> file. Check
|
|
the password you are providing, or check your Kerberos or ident
|
|
software if the complaint mentions one of those authentication
|
|
types.
|
|
</para>
|
|
|
|
<para>
|
|
<ProgramListing>
|
|
FATAL 1: user "andym" does not exist
|
|
</ProgramListing>
|
|
The indicated user name was not found.
|
|
</para>
|
|
|
|
<para>
|
|
<ProgramListing>
|
|
FATAL 1: Database "testdb" does not exist in the system catalog.
|
|
</ProgramListing>
|
|
The database you are trying to connect to does not exist. Note that
|
|
if you do not specify a database name, it defaults to the database
|
|
user name, which may or may not be the right thing.
|
|
</para>
|
|
|
|
<para>
|
|
Note that the server log may contain more information about an
|
|
authentication failure than is reported to the client. If you are
|
|
confused about the reason for a failure, check the log.
|
|
</para>
|
|
</sect1>
|
|
|
|
</chapter>
|