client-auth.sgml

PostgreSQL7.4.6 for Linux

    Several sources for <productname>Kerberos</> distributions exist.
   </para>

   <para>
    While <productname>PostgreSQL</> supports both Kerberos 4 and 
    Kerberos 5, only Kerberos 5 is recommended.  Kerberos 4 is
    considered insecure and no longer recommended for general
    use.
   </para>

   <para>
    In order to use <productname>Kerberos</>, support for it must be
    enabled at build time.  See <xref linkend="installation"> for more
    information.  Both Kerberos 4 and 5 are supported, but 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
    <literal><replaceable>servicename</>/<replaceable>hostname</>@<replaceable>realm</></literal>, 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 host 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
    <literal>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 also <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>[e-mail]</> and
    <literal>fred/[e-mail]</> can be used to
    authenticate to the database server.
   </para>

   <para>
    If you use <application>mod_auth_kerb</application> from
    <ulink url="http://modauthkerb.sf.net">http://modauthkerb.sf.net</ulink>
    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 id="auth-ident">
   <title>Ident-based authentication</title>

   <indexterm>
    <primary>ident</primary>
   </indexterm>

   <para>
    The ident authentication method works by inspecting the client's
    operating system user name and determining the allowed database
    user names by using a map file that lists the permitted
    corresponding user name pairs.  The determination of the client's
    user name is the security-critical point, and it works differently
    depending on the connection type.
   </para>

   <sect3>
    <title>Ident Authentication over TCP/IP</title>

   <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>
   </sect3>

   <sect3>
    <title>Ident Authentication over Local Sockets</title>

   <para>
    On systems supporting <symbol>SO_PEERCRED</symbol> requests for
    Unix-domain sockets (currently <systemitem
    class="osname">Linux</>, <systemitem class="osname">FreeBSD</>,
    <systemitem class="osname">NetBSD</>, <systemitem class=osname>OpenBSD</>, 
    and <systemitem class="osname">BSD/OS</>), 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>
     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>
    </sect3>

   <sect3>
    <title>Ident Maps</title>

   <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</> key word 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>
    Ident maps
    other than <literal>sameuser</literal> are defined in the file
    <filename>pg_ident.conf</filename><indexterm><primary>pg_ident.conf</primary></indexterm>
    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>
   The <filename>pg_ident.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>
    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 <literal>bryanh</>, <literal>ann</>, or
    <literal>robert</> would not be granted access. Unix user
    <literal>robert</> would only be allowed access when he tries to
    connect as <productname>PostgreSQL</> user <literal>bob</>, not
    as <literal>robert</> or anyone else. <literal>ann</> would
    only be allowed to connect as <literal>ann</>. User
    <literal>bryanh</> would be allowed to connect as either
    <literal>bryanh</> himself or as <literal>guest1</>.
   </para>

   <example id="example-pg-ident.conf">
    <title>An example <filename>pg_ident.conf</> file</title>
<programlisting>
# MAPNAME     IDENT-USERNAME    PG-USERNAME

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>
   </sect3>
  </sect2>

  <sect2 id="auth-pam">
   <title>PAM Authentication</title>

   <indexterm zone="auth-pam">
    <primary>PAM</primary>
   </indexterm>

   <para>
    This authentication method operates similarly to
    <literal>password</literal> 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</>
    key word in the file <filename>pg_hba.conf</filename>. For more information about PAM, please read
    the <ulink
    url="http://www.kernel.org/pub/linux/libs/pam/"><productname>Linux-PAM</>
    Page</ulink> and the <ulink
    url="http://www.sun.com/software/solaris/pam/"><systemitem
    class="osname">Solaris</> PAM Page</ulink>.
   </para>
  </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>
FATAL:  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>
FATAL:  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:  user "andym" does not exist
</ProgramListing>
    The indicated user name was not found.
   </para>

   <para>
<ProgramListing>
FATAL:  database "testdb" does not exist
</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>

   <tip>
   <para>
    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>
   </tip>
  </sect1>

 </chapter>