<!-- doc/src/sgml/client-auth.sgml -->

<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> database 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 &mdash; see
  <xref linkend="user-manag"/> for more information. Therefore, it is
  essential to restrict which database users can connect.
 </para>

 <note>
  <para>
   As explained in <xref linkend="user-manag"/>,
   <productname>PostgreSQL</productname> actually does privilege
   management in terms of <quote>roles</quote>.  In this chapter, we
   consistently use <firstterm>database user</firstterm> to mean <quote>role with the
   <literal>LOGIN</literal> privilege</quote>.
  </para>
 </note>

 <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
  database 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> 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 operating system user names. However, a server that
  accepts remote connections might 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 a configuration file,
   which traditionally is named
   <filename>pg_hba.conf</filename> and is stored in the database
   cluster's data directory.
   (<acronym>HBA</acronym> stands for host-based authentication.) A default
   <filename>pg_hba.conf</filename> file is installed when the data
   directory is initialized by <xref linkend="app-initdb"/>.  It is
   possible to place the authentication configuration file elsewhere,
   however; see the <xref linkend="guc-hba-file"/> configuration parameter.
  </para>

  <para>
   The <filename>pg_hba.conf</filename> file is read on start-up and when
   the main server process 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 postmaster
   (using <literal>pg_ctl reload</literal>, calling the SQL function
   <function>pg_reload_conf()</function>, or using <literal>kill
   -HUP</literal>) to make it re-read the file.
  </para>

  <note>
   <para>
    The preceding statement is not true on Microsoft Windows: there, any
    changes in the <filename>pg_hba.conf</filename> file are immediately
    applied by subsequent new connections.
   </para>
  </note>

  <para>
   The system view
   <link linkend="view-pg-hba-file-rules"><structname>pg_hba_file_rules</structname></link>
   can be helpful for pre-testing changes to the <filename>pg_hba.conf</filename>
   file, or for diagnosing problems if loading of the file did not have the
   desired effects.