client-auth.sgml

PostgreSQL7.4.6 for Linux

       <varlistentry>
        <term><literal>krb4</></term>
        <listitem>
         <para>
          Kerberos V4 is used 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>krb5</></term>
        <listitem>
         <para>
          Kerberos V5 is used 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>
         <para>
          Obtain the operating system user name of the client (for
          TCP/IP connections by contacting the ident server on the
          client, for local connections by getting it from the
          operating system) and check if the user is allowed to
          connect as the requested database user by consulting the map
          specified after the <literal>ident</literal> key word.
         </para>

         <para>
          If you use the map <literal>sameuser</literal>, the user
          names are required to be identical. If not, the map name is
          looked up in the file <filename>pg_ident.conf</filename>
          in the same directory as <filename>pg_hba.conf</filename>.
          The connection is accepted if that file contains an
          entry for this map name with the operating-system user name
          and the requested <productname>PostgreSQL</productname> user
          name.
         </para>

         <para>
          For local connections, this only works on machines that
          support Unix-domain socket credentials (currently
          <systemitem class=osname>Linux</>, <systemitem
          class=osname>FreeBSD</>, <systemitem class=osname>NetBSD</>,
          <systemitem class=osname>OpenBSD</>, and 
          <systemitem class=osname>BSD/OS</>).
         </para>

         <para>
          See <xref linkend="auth-ident"> below for details.
         </para>
        </listitem>
       </varlistentry>

       <varlistentry>
        <term><literal>pam</></term>
        <listitem>
         <para>
          Authenticate using the Pluggable Authentication Modules
          (PAM) service provided by the operating system.  See <xref
          linkend="auth-pam"> for details.
         </para>
        </listitem>
       </varlistentry>
      </variablelist>

      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable>authentication-option</replaceable></term>
     <listitem>
      <para>
       The meaning of this optional field depends on the chosen
       authentication method and is described in the next section.
      </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/IP connections but require a password for
   remote TCP/IP 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>

  <important>
   <para>
    Do not prevent the superuser from accessing the <literal>template1</literal>
    database.  Various utility commands need access to <literal>template1</literal>.
   </para>
  </important>

  <para>
   The <filename>pg_hba.conf</filename> file is read on start-up and when
   the main server process (<command>postmaster</>) receives a
   <systemitem>SIGHUP</systemitem><indexterm><primary>SIGHUP</primary></indexterm>
   signal. If you edit the file on an
   active system, you will need to signal the <command>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 the next section for details on the
   different authentication methods.
  </para>

   <example id="example-pg-hba.conf">
    <title>An example <filename>pg_hba.conf</filename> file</title>
<programlisting>
# Allow any user on the local system to connect to any database under
# any user name using Unix-domain sockets (the default for local
# connections).
#
# TYPE  DATABASE    USER        IP-ADDRESS        IP-MASK           METHOD
local   all         all                                             trust

# The same using local loopback TCP/IP connections.
#
# TYPE  DATABASE    USER        IP-ADDRESS        IP-MASK           METHOD
host    all         all         127.0.0.1         255.255.255.255   trust     

# The same as the last line but using a CIDR mask
#
# TYPE  DATABASE    USER        IP-ADDRESS/CIDR-mask  METHOD
host    all         all         127.0.0.1/32          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 reports for
# the connection (typically the Unix user name).
# 
# TYPE  DATABASE    USER        IP-ADDRESS        IP-MASK           METHOD
host    template1   all         192.168.93.0      255.255.255.0     ident sameuser

# The same as the last line but using a CIDR mask
#
# TYPE  DATABASE    USER        IP-ADDRESS/CIDR-mask  METHOD
host    template1   all         192.168.93.0/24       ident sameuser

# Allow a user from host 192.168.12.10 to connect to database
# "template1" if the user's password is correctly supplied.
# 
# TYPE  DATABASE    USER        IP-ADDRESS        IP-MASK           METHOD
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 from 192.168.54.1 (since that entry will be
# matched first), but allow Kerberos V 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.
# 
# TYPE  DATABASE    USER        IP-ADDRESS        IP-MASK           METHOD
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 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".
#
# TYPE  DATABASE    USER        IP-ADDRESS        IP-MASK           METHOD
host    all         all         192.168.0.0       255.255.0.0       ident omicron

# If these are the only three lines for local connections, they will
# allow local users to connect only to their own databases (databases
# with the same name as their user name) except for administrators and
# members of group "support" who may connect to all databases.  The file
# $PGDATA/admins contains a list of user names.  Passwords are required in
# all cases.
#
# TYPE  DATABASE    USER        IP-ADDRESS        IP-MASK           METHOD
local   sameuser    all                                             md5
local   all         @admins                                         md5
local   all         +support                                        md5

# The last two lines above can be combined into a single line:
local   all         @admins,+support                                md5

# The database column can also use lists and file names, but not groups:
local   db1,db2,@demodbs  all                                       md5
</programlisting>
   </example>
 </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 server 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 operating system-level
    protection on connections to the server.
   </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 server's
    Unix-domain socket file using file-system permissions.  To do this, set the
    <varname>unix_socket_permissions</varname> (and possibly
    <varname>unix_socket_group</varname>) configuration parameters as
    described in <xref linkend="runtime-config-connection">.  Or you
    could set the <varname>unix_socket_directory</varname>
    configuration parameter to place the socket file in a suitably
    restricted directory.
   </para>

   <para>
    Setting file-system permissions only helps for Unix-socket connections.
    Local TCP/IP connections are not restricted by it; therefore, if you want
    to use file-system 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/IP connections
    if you trust every user on every machine that is allowed to connect
    to the server by the <filename>pg_hba.conf</> lines that specify
    <literal>trust</>.  It is seldom reasonable to use <literal>trust</>
    for any TCP/IP connections other than those from <systemitem>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>
    <secondary>authentication</secondary>
   </indexterm>

   <para>
    The password-based authentication methods are <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. The password for
    each database user is stored in the <literal>pg_shadow</> system
    catalog table. Passwords can be managed with the SQL
    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 null 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 in the <replaceable>user</>
    column of <filename>pg_hba.conf</filename>, as explained in the
    previous section.
   </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.