mirror of https://github.com/postgres/postgres
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
788 lines
31 KiB
788 lines
31 KiB
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.29 2001/11/21 05:53:40 thomas 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
|
|
about that. It is therefore obviously essential to restrict which
|
|
database user name(s) a given client can connect as.
|
|
</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 and database; some authentication methods
|
|
allow you to restrict by user name as well.
|
|
</para>
|
|
|
|
<para>
|
|
<productname>PostgreSQL</productname> database 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 Unix user ids. 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 Unix
|
|
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 <application>initdb</application>.
|
|
</para>
|
|
|
|
<para>
|
|
The general format of the <filename>pg_hba.conf</filename> file is
|
|
of a set of records, one per line. Blank lines and lines beginning
|
|
with a hash character (<quote>#</quote>) are ignored. A record is
|
|
made up of a number of fields which are separated by spaces and/or
|
|
tabs. 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 or names,
|
|
and the authentication method to be used for connections matching
|
|
these parameters.
|
|
The first record that matches the type, client address and requested
|
|
database name of a connection attempt is used to do the
|
|
authentication step. There is no <quote>fall-through</> or
|
|
<quote>backup</>: if one record is chosen and the authentication
|
|
fails, the following records are not considered. If no record
|
|
matches, the access will be denied.
|
|
</para>
|
|
|
|
<para>
|
|
A record may have one of the three formats
|
|
<synopsis>
|
|
local <replaceable>database</replaceable> <replaceable>authentication-method</replaceable> [ <replaceable>authentication-option</replaceable> ]
|
|
host <replaceable>database</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>authentication-method</replaceable> [ <replaceable>authentication-option</replaceable> ]
|
|
hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>authentication-method</replaceable> [ <replaceable>authentication-option</replaceable> ]
|
|
</synopsis>
|
|
The meaning of the fields is as follows:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><literal>local</literal></term>
|
|
<listitem>
|
|
<para>
|
|
This record pertains to connection attempts over Unix domain
|
|
sockets.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>host</literal></term>
|
|
<listitem>
|
|
<para>
|
|
This record pertains to connection attempts over TCP/IP
|
|
networks. Note that TCP/IP connections are completely disabled
|
|
unless the server is started with the <option>-i</option> switch or
|
|
the equivalent configuration parameter is set.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>hostssl</literal></term>
|
|
<listitem>
|
|
<para>
|
|
This record pertains to connection attempts with 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 match only SSL connections.)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable>database</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the database that this record applies to. 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. Otherwise,
|
|
this is the name of a specific <productname>PostgreSQL</productname>
|
|
database.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable>IP address</replaceable></term>
|
|
<term><replaceable>IP mask</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
These two fields specify to which client machines a
|
|
<literal>host</literal> or <literal>hostssl</literal>
|
|
record applies, based on their IP
|
|
address. (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 method that users must use to authenticate themselves
|
|
when connecting under the control of this authentication 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 mostly
|
|
useful to <quote>filter out</> certain hosts from a group.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>password</></term>
|
|
<listitem>
|
|
<para>
|
|
The client is required to supply a password which is required to
|
|
match the database password that was set up for the user.
|
|
</para>
|
|
|
|
<para>
|
|
An optional file name may be specified after the
|
|
<literal>password</literal> keyword. This file is expected to
|
|
contain a list of users who may connect using this record,
|
|
and optionally alternative passwords for them.
|
|
</para>
|
|
|
|
<para>
|
|
The password is sent over the wire in clear text. For better
|
|
protection, use the <literal>md5</literal> or
|
|
<literal>crypt</literal> methods.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>md5</></term>
|
|
<listitem>
|
|
<para>
|
|
Like the <literal>password</literal> method, but the password
|
|
is sent over the wire encrypted using a simple
|
|
challenge-response protocol. This protects against incidental
|
|
wire-sniffing. This is now the recommended choice for
|
|
password-based authentication.
|
|
</para>
|
|
|
|
<para>
|
|
The name of a file may follow the
|
|
<literal>md5</literal> keyword. It contains a list of users
|
|
who may connect using this record.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>crypt</></term>
|
|
<listitem>
|
|
<para>
|
|
Like the <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. The <literal>crypt</>
|
|
method is not compatible with encrypting passwords in
|
|
<filename>pg_shadow</>, and may fail if client and server
|
|
machines have different implementations of the crypt() library
|
|
routine.
|
|
</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>
|
|
The identity of the user as determined on login to the
|
|
operating system is used by <productname>PostgreSQL</productname>
|
|
to determine whether the user
|
|
is allowed to connect as the requested database user.
|
|
For TCP/IP connections the user's identity is determined by
|
|
contacting the <firstterm>ident</firstterm> server on the client
|
|
host. (Note that this is only as reliable as the remote ident
|
|
server; ident authentication should never be used for remote hosts
|
|
whose administrators are not trustworthy.)
|
|
On operating systems
|
|
supporting <symbol>SO_PEERCRED</> requests for Unix domain sockets,
|
|
ident authentication is possible for local connections;
|
|
the system is then asked for the connecting user's identity.
|
|
</para>
|
|
<para>
|
|
On systems without <symbol>SO_PEERCRED</> requests, ident authentication
|
|
is only available for TCP/IP connections. As a workaround,
|
|
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>
|
|
The <replaceable>authentication option</replaceable> following
|
|
the <literal>ident</> keyword specifies the name of an
|
|
<firstterm>ident map</firstterm> that 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>, with the main difference that
|
|
it will use PAM (Pluggable Authentication Modules) as the
|
|
authentication mechanism. The <replaceable>authentication
|
|
option</replaceable> following the <literal>pam</> keyword
|
|
specifies the service name that will be passed to PAM. The
|
|
default service name is <literal>postgresql</literal>.
|
|
For more information about PAM, please read the <ulink
|
|
url="http://www.kernel.org/pub/linux/libs/pam/"><productname>Linux-PAM</productname>
|
|
Page</ulink> and/or the <ulink
|
|
url="http://www.sun.com/software/solaris/pam/"><systemitem class="osname">Solaris</> PAM
|
|
Page</ulink>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable>authentication option</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
This field is interpreted differently depending on the
|
|
authentication method, as described above.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<para>
|
|
Since the <filename>pg_hba.conf</filename> records are examined
|
|
sequentially for each connection attempt, order of the records is
|
|
very 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 startup
|
|
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 <application>pg_ctl reload</> or <application>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 IP_ADDRESS MASK AUTHTYPE MAP
|
|
|
|
# Allow any user on the local system to connect to any
|
|
# database under any username, but only via an IP connection:
|
|
|
|
host all 127.0.0.1 255.255.255.255 trust
|
|
|
|
# The same, over Unix-socket connections:
|
|
|
|
local all trust
|
|
|
|
# Allow any user from any host with IP address 192.168.93.x to
|
|
# connect to database "template1" as the same username that ident on that
|
|
# host identifies him as (typically his Unix username):
|
|
|
|
host template1 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 in pg_shadow is correctly supplied:
|
|
|
|
host template1 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 192.168.54.1 255.255.255.255 reject
|
|
host 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 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 md5
|
|
local all md5 admins
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="auth-methods">
|
|
<title>Authentication methods</title>
|
|
<para>
|
|
The following describes the authentication methods in detail.
|
|
</para>
|
|
|
|
<sect2 id="auth-password">
|
|
<title>Password authentication</title>
|
|
|
|
<indexterm>
|
|
<primary>password</primary>
|
|
</indexterm>
|
|
<indexterm>
|
|
<primary>MD5</>
|
|
</indexterm>
|
|
|
|
<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 set of users in a separate file (one user name
|
|
per line) in the same directory that <filename>pg_hba.conf</> is in,
|
|
and mention the (base) name of the file after the
|
|
<literal>password</>, <literal>md5</>, or <literal>crypt</> keyword,
|
|
respectively, in <filename>pg_hba.conf</>. If you do not use this
|
|
feature, then any user that is known to the database system can
|
|
connect to any database (so long as he supplies the correct password,
|
|
of course).
|
|
</para>
|
|
|
|
<para>
|
|
These files can also be used to apply a different set of passwords
|
|
to a particular database or set thereof. In that case, the files
|
|
have a format similar to the standard Unix password file
|
|
<filename>/etc/passwd</filename>, that is,
|
|
<synopsis>
|
|
<replaceable>username</replaceable>:<replaceable>password</replaceable>
|
|
</synopsis>
|
|
Any extra colon separated fields following the password are
|
|
ignored. The password is expected to be encrypted using the
|
|
system's <function>crypt()</function> function. The utility
|
|
program <application>pg_passwd</application> that is installed
|
|
with <productname>PostgreSQL</productname> can be used to manage
|
|
these password files.
|
|
</para>
|
|
|
|
<para>
|
|
Lines with and without passwords can be mixed in secondary
|
|
password files. Lines without password indicate use of the main
|
|
password in <literal>pg_shadow</> that is managed by
|
|
<command>CREATE USER</> and <command>ALTER USER</>. Lines with
|
|
passwords will cause that password to be used. A password entry of
|
|
<quote>+</quote> also means using the pg_shadow password.
|
|
</para>
|
|
|
|
<para>
|
|
Alternative passwords cannot be used when using the <literal>md5</>
|
|
or <literal>crypt</> methods. The file will be read as
|
|
usual, but the password field will simply be ignored and the
|
|
<literal>pg_shadow</> password will always be used.
|
|
</para>
|
|
|
|
<para>
|
|
Note that using alternative passwords like this means that one can
|
|
no longer use <command>ALTER USER</command> to change one's
|
|
password. It will appear to work but the password one is
|
|
changing is not the password that the system will end up
|
|
using.
|
|
</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">Kerberos
|
|
<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</> username 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 username.
|
|
An example: For database username <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 such a system.
|
|
</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 startup
|
|
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 <application>pg_ctl reload</> or <application>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 username 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 joeblow, database testdb
|
|
</ProgramListing>
|
|
This is what you are most likely to get if you succeed in
|
|
contacting the server, but it doesn't 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 'joeblow'
|
|
</ProgramListing>
|
|
Messages like this indicate that you contacted the server, and
|
|
it's 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're
|
|
providing, or check your Kerberos or IDENT software if the
|
|
complaint mentions one of those authentication types.
|
|
</para>
|
|
|
|
<para>
|
|
<ProgramListing>
|
|
FATAL 1: user "joeblow" does not exist
|
|
</ProgramListing>
|
|
The indicated user name was not found in pg_shadow.
|
|
</para>
|
|
|
|
<para>
|
|
<ProgramListing>
|
|
FATAL 1: Database "testdb" does not exist in the system catalog.
|
|
</ProgramListing>
|
|
The database you're trying to connect to doesn't exist. Note that
|
|
if you don't 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>
|
|
|