client-auth.sgml

PostgreSQL7.4.6 for Linux

<!--
$Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.59.2.1 2003/11/04 09:45:29 petere 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 used to authenticate a
  particular client connection can be selected on the basis of
  (client) host address, 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 database users who have no local operating system
  account, and in such cases there need be no connection between
  database user names and OS user names.
 </para>

 <sect1 id="auth-pg-hba-conf">
  <title>The <filename>pg_hba.conf</filename> file</title>

  <indexterm zone="auth-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
   directory is initialized by <command>initdb</command>.
  </para>

  <para>
   The general format of the <filename>pg_hba.conf</filename> file is
   a set of records, one per line. Blank lines are ignored, as is any
   text after the <literal>#</literal> 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 seven formats
<synopsis>
local      <replaceable>database</replaceable>  <replaceable>user</replaceable>  <replaceable>authentication-method</replaceable>  <optional><replaceable>authentication-option</replaceable></optional>
host       <replaceable>database</replaceable>  <replaceable>user</replaceable>  <replaceable>IP-address</replaceable>  <replaceable>IP-mask</replaceable>  <replaceable>authentication-method</replaceable>  <optional><replaceable>authentication-option</replaceable></optional>
hostssl    <replaceable>database</replaceable>  <replaceable>user</replaceable>  <replaceable>IP-address</replaceable>  <replaceable>IP-mask</replaceable>  <replaceable>authentication-method</replaceable>  <optional><replaceable>authentication-option</replaceable></optional>
hostnossl  <replaceable>database</replaceable>  <replaceable>user</replaceable>  <replaceable>IP-address</replaceable>  <replaceable>IP-mask</replaceable>  <replaceable>authentication-method</replaceable>  <optional><replaceable>authentication-option</replaceable></optional>
host       <replaceable>database</replaceable>  <replaceable>user</replaceable>  <replaceable>IP-address</replaceable>/<replaceable>IP-masklen</replaceable>  <replaceable>authentication-method</replaceable>  <optional><replaceable>authentication-option</replaceable></optional>
hostssl    <replaceable>database</replaceable>  <replaceable>user</replaceable>  <replaceable>IP-address</replaceable>/<replaceable>IP-masklen</replaceable>  <replaceable>authentication-method</replaceable>  <optional><replaceable>authentication-option</replaceable></optional>
hostnossl  <replaceable>database</replaceable>  <replaceable>user</replaceable>  <replaceable>IP-address</replaceable>/<replaceable>IP-masklen</replaceable>  <replaceable>authentication-method</replaceable>  <optional><replaceable>authentication-option</replaceable></optional>
</synopsis>
   The meaning of the fields is as follows:

   <variablelist>
    <varlistentry>
     <term><literal>local</literal></term>
     <listitem>
      <para>
       This record matches connection attempts using Unix-domain
       sockets.  Without a record of this type, Unix-domain socket
       connections are disallowed.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>host</literal></term>
     <listitem>
      <para>
       This record matches 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
       <varname>tcpip_socket</> configuration parameter is enabled.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>hostssl</literal></term>
     <listitem>
      <para>
       This record matches connection attempts using SSL over TCP/IP.
       <literal>host</literal> records will match either SSL or
       non-SSL connection attempts, but <literal>hostssl</literal>
       records require SSL connections.
      </para>

      <para>
       To make use of this option the server must be built
       with SSL support enabled. Furthermore, SSL must be enabled by
       enabling the <varname>ssl</varname> configuration parameter
       (see <xref linkend="runtime-config"> for more information).
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>hostnossl</literal></term>
     <listitem>
      <para>
       This record is similar to <literal>hostssl</> but with the
	   opposite logic: it matches only regular connection attempts not
	   using SSL.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable>database</replaceable></term>
     <listitem>
      <para>
       Specifies which databases this record matches.  The value
       <literal>all</literal> specifies that it matches all databases.
       The value <literal>sameuser</> specifies that the record
       matches if the requested database has the same name as the
       requested user.  The value <literal>samegroup</> specifies that
       the requested user must a member of the group with the same
       name as the requested 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 which <productname>PostgreSQL</> users this record
       matches. The value <literal>all</literal> specifies that it
       matches 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 contain IP address and mask values in standard
       dotted decimal notation. (IP addresses can only be specified
       numerically, not as domain or host names.)  Taken together they
       specify the client machine IP addresses that this record
       matches.  The precise logic is that
<programlisting>
(<replaceable>actual-IP-address</replaceable> xor <replaceable>IP-address-field</replaceable>) and <replaceable>IP-mask-field</replaceable>
</programlisting>
       must be zero for the record to match.
      </para>

      <para>
       An IP address given in IPv4 format will match IPv6 connections that
       have the corresponding address, for example <literal>127.0.0.1</>
       will match the IPv6 address <literal>::ffff:127.0.0.1</>.  An entry
       given in IPv6 format will match only IPv6 connections, even if the
       represented address is in the IPv4-in-IPv6 range.  Note that entries
       in IPv6 format will be rejected if the system's C library does not have
       support for IPv6 addresses.
      </para>

      <para>
       These fields only apply to <literal>host</literal>,
       <literal>hostssl</literal>, and <literal>hostnossl</> records.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable>IP-masklen</replaceable></term>
     <listitem>
      <para>
       This field may be used as an alternative to the
       <replaceable>IP-mask</replaceable> notation.  It is an integer
       specifying the number of high-order bits to set in the mask.
       The number must be between 0 and 32 (in the case of an IPv4
       address) or 128 (in the case of an IPv6 address) inclusive. 0
       will match any address, while 32 (or 128, respectively) will
       match only the exact host specified.  The same matching logic
       is used as for a dotted notation
       <replaceable>IP-mask</replaceable>.
      </para>

      <para>
       There must be no white space between the
       <replaceable>IP-address</replaceable> and the
       <literal>/</literal> or the <literal>/</literal> and the
       <replaceable>IP-masklen</replaceable>, or the file will not be
       parsed correctly.
      </para>

      <para>
       This field only applies to <literal>host</literal>,
       <literal>hostssl</literal>, and <literal>hostnossl</> records.
      </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 anyone that can connect to the
          <productname>PostgreSQL</productname> database server to login as
          any <productname>PostgreSQL</productname> user they like,
          without the need for a password.  See <xref
          linkend="auth-trust"> for details.
         </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 <structname>pg_shadow</structname>.
          See <xref linkend="auth-password"> for details.
         </para>
        </listitem>
       </varlistentry>

       <varlistentry>
        <term><literal>crypt</></term>
        <listitem>
         <para>
          Like the <literal>md5</literal> method but uses older <function>crypt()</>
          encryption, which is needed for pre-7.2 clients.
          <literal>md5</literal> is preferred for 7.2 and later clients.
          See <xref linkend="auth-password"> for details.
         </para>
        </listitem>
       </varlistentry>

       <varlistentry>
        <term><literal>password</></term>
        <listitem>
         <para>
          Same as <literal>md5</>, but the password is sent in clear text over the
          network. This should not be used on untrusted networks.
          See <xref linkend="auth-password"> for details.
         </para>
        </listitem>
       </varlistentry>