2
$PostgreSQL: pgsql/doc/src/sgml/client-auth.sgml,v 1.70.4.7 2005-04-27 20:11:11 momjian Exp $
5
<chapter id="client-authentication">
6
<title>Client Authentication</title>
8
<indexterm zone="client-authentication">
9
<primary>client authentication</primary>
13
When a client application connects to the database server, it
14
specifies which <productname>PostgreSQL</productname> user name it
15
wants to connect as, much the same way one logs into a Unix computer
16
as a particular user. Within the SQL environment the active database
17
user name determines access privileges to database objects — see
18
<xref linkend="user-manag"> for more information. Therefore, it is
19
essential to restrict which database users can connect.
23
<firstterm>Authentication</firstterm> is the process by which the
24
database server establishes the identity of the client, and by
25
extension determines whether the client application (or the user
26
who runs the client application) is permitted to connect with the
27
user name that was requested.
31
<productname>PostgreSQL</productname> offers a number of different
32
client authentication methods. The method used to authenticate a
33
particular client connection can be selected on the basis of
34
(client) host address, database, and user.
38
<productname>PostgreSQL</productname> user names are logically
39
separate from user names of the operating system in which the server
40
runs. If all the users of a particular server also have accounts on
41
the server's machine, it makes sense to assign database user names
42
that match their operating system user names. However, a server that
43
accepts remote connections may have many database users who have no local operating system
44
account, and in such cases there need be no connection between
45
database user names and OS user names.
48
<sect1 id="auth-pg-hba-conf">
49
<title>The <filename>pg_hba.conf</filename> file</title>
51
<indexterm zone="auth-pg-hba-conf">
52
<primary>pg_hba.conf</primary>
56
Client authentication is controlled by a configuration file,
57
which traditionally is named
58
<filename>pg_hba.conf</filename> and is stored in the database
59
cluster's data directory.
60
(<acronym>HBA</> stands for host-based authentication.) A default
61
<filename>pg_hba.conf</filename> file is installed when the data
62
directory is initialized by <command>initdb</command>. It is
63
possible to place the authentication configuration file elsewhere,
64
however; see the <xref linkend="guc-hba-file"> configuration parameter.
68
The general format of the <filename>pg_hba.conf</filename> file is
69
a set of records, one per line. Blank lines are ignored, as is any
70
text after the <literal>#</literal> comment character. A record is made
71
up of a number of fields which are separated by spaces and/or tabs.
72
Fields can contain white space if the field value is quoted. Records
73
cannot be continued across lines.
77
Each record specifies a connection type, a client IP address range
78
(if relevant for the connection type), a database name, a user name,
79
and the authentication method to be used for connections matching
80
these parameters. The first record with a matching connection type,
81
client address, requested database, and user name is used to perform
82
authentication. There is no <quote>fall-through</> or
83
<quote>backup</>: if one record is chosen and the authentication
84
fails, subsequent records are not considered. If no record matches,
89
A record may have one of the seven formats
91
local <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>authentication-method</replaceable> <optional><replaceable>authentication-option</replaceable></optional>
92
host <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>CIDR-address</replaceable> <replaceable>authentication-method</replaceable> <optional><replaceable>authentication-option</replaceable></optional>
93
hostssl <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>CIDR-address</replaceable> <replaceable>authentication-method</replaceable> <optional><replaceable>authentication-option</replaceable></optional>
94
hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>CIDR-address</replaceable> <replaceable>authentication-method</replaceable> <optional><replaceable>authentication-option</replaceable></optional>
95
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>
96
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>
97
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>
99
The meaning of the fields is as follows:
103
<term><literal>local</literal></term>
106
This record matches connection attempts using Unix-domain
107
sockets. Without a record of this type, Unix-domain socket
108
connections are disallowed.
114
<term><literal>host</literal></term>
117
This record matches connection attempts made using TCP/IP.
118
<literal>host</literal> records match either
119
<acronym>SSL</acronym> or non-<acronym>SSL</acronym> connection
124
Remote TCP/IP connections will not be possible unless
125
the server is started with an appropriate value for the
126
<xref linkend="guc-listen-addresses"> configuration parameter,
127
since the default behavior is to listen for TCP/IP connections
128
only on the local loopback address <literal>localhost</>.
135
<term><literal>hostssl</literal></term>
138
This record matches connection attempts made using TCP/IP,
139
but only when the connection is made with <acronym>SSL</acronym>
144
To make use of this option the server must be built with
145
<acronym>SSL</acronym> support. Furthermore,
146
<acronym>SSL</acronym> must be enabled at server start time
147
by setting the <xref linkend="guc-ssl"> configuration parameter (see
148
<xref linkend="ssl-tcp"> for more information).
154
<term><literal>hostnossl</literal></term>
157
This record type has the opposite logic to <literal>hostssl</>:
158
it only matches connection attempts made over
159
TCP/IP that do not use <acronym>SSL</acronym>.
165
<term><replaceable>database</replaceable></term>
168
Specifies which databases this record matches. The value
169
<literal>all</literal> specifies that it matches all databases.
170
The value <literal>sameuser</> specifies that the record
171
matches if the requested database has the same name as the
172
requested user. The value <literal>samegroup</> specifies that
173
the requested user must be a member of the group with the same
174
name as the requested database. Otherwise, this is the name of
175
a specific <productname>PostgreSQL</productname> database.
176
Multiple database names can be supplied by separating them with
177
commas. A file containing database names can be specified by
178
preceding the file name with <literal>@</>.
184
<term><replaceable>user</replaceable></term>
187
Specifies which <productname>PostgreSQL</> users this record
188
matches. The value <literal>all</literal> specifies that it
189
matches all users. Otherwise, this is the name of a specific
190
<productname>PostgreSQL</productname> user. Multiple user names
191
can be supplied by separating them with commas. Group names can
192
be specified by preceding the group name with <literal>+</>. A
193
file containing user names can be specified by preceding the
194
file name with <literal>@</>.
200
<term><replaceable>CIDR-address</replaceable></term>
203
Specifies the client machine IP address range that this record
204
matches. It contains an IP address in standard dotted decimal
205
notation and a CIDR mask length. (IP addresses can only be
206
specified numerically, not as domain or host names.) The mask
207
length indicates the number of high-order bits of the client
208
IP address that must match. Bits to the right of this must
209
be zero in the given IP address.
210
There must not be any white space between the IP address, the
211
<literal>/</literal>, and the CIDR mask length.
215
A typical <replaceable>CIDR-address</replaceable> is
216
<literal>172.20.143.89/32</literal> for a single host, or
217
<literal>172.20.143.0/24</literal> for a network.
218
To specify a single host, use a CIDR mask of 32 for IPv4 or
223
An IP address given in IPv4 format will match IPv6 connections that
224
have the corresponding address, for example <literal>127.0.0.1</>
225
will match the IPv6 address <literal>::ffff:127.0.0.1</>. An entry
226
given in IPv6 format will match only IPv6 connections, even if the
227
represented address is in the IPv4-in-IPv6 range. Note that entries
228
in IPv6 format will be rejected if the system's C library does not have
229
support for IPv6 addresses.
233
This field only applies to <literal>host</literal>,
234
<literal>hostssl</literal>, and <literal>hostnossl</> records.
240
<term><replaceable>IP-address</replaceable></term>
241
<term><replaceable>IP-mask</replaceable></term>
244
These fields may be used as an alternative to the
245
<replaceable>CIDR-address</replaceable> notation. Instead of
246
specifying the mask length, the actual mask is specified in a
247
separate column. For example, <literal>255.0.0.0</> represents an IPv4
248
CIDR mask length of 8, and <literal>255.255.255.255</> represents a
249
CIDR mask length of 32.
253
These fields only apply to <literal>host</literal>,
254
<literal>hostssl</literal>, and <literal>hostnossl</> records.
260
<term><replaceable>authentication-method</replaceable></term>
263
Specifies the authentication method to use when connecting via
264
this record. The possible choices are summarized here; details
265
are in <xref linkend="auth-methods">.
269
<term><literal>trust</></term>
272
Allow the connection unconditionally. This method
273
allows anyone that can connect to the
274
<productname>PostgreSQL</productname> database server to login as
275
any <productname>PostgreSQL</productname> user they like,
276
without the need for a password. See <xref
277
linkend="auth-trust"> for details.
283
<term><literal>reject</></term>
286
Reject the connection unconditionally. This is useful for
287
<quote>filtering out</> certain hosts from a group.
293
<term><literal>md5</></term>
296
Require the client to supply an MD5-encrypted password for
298
See <xref linkend="auth-password"> for details.
304
<term><literal>crypt</></term>
307
Require the client to supply a <function>crypt()</>-encrypted
308
password for authentication.
309
<literal>md5</literal> is preferred for 7.2 and later clients,
310
but pre-7.2 clients only support <literal>crypt</>.
311
See <xref linkend="auth-password"> for details.
317
<term><literal>password</></term>
320
Require the client to supply an unencrypted password for
322
Since the password is sent in clear text over the
323
network, this should not be used on untrusted networks.
324
See <xref linkend="auth-password"> for details.
330
<term><literal>krb4</></term>
333
Use Kerberos V4 to authenticate the user. This is only
334
available for TCP/IP connections. See <xref
335
linkend="kerberos-auth"> for details.
341
<term><literal>krb5</></term>
344
Use Kerberos V5 to authenticate the user. This is only
345
available for TCP/IP connections. See <xref
346
linkend="kerberos-auth"> for details.
352
<term><literal>ident</></term>
355
Obtain the operating system user name of the client (for
356
TCP/IP connections by contacting the ident server on the
357
client, for local connections by getting it from the
358
operating system) and check if the user is allowed to
359
connect as the requested database user by consulting the map
360
specified after the <literal>ident</literal> key word.
361
See <xref linkend="auth-ident"> for details.
367
<term><literal>pam</></term>
370
Authenticate using the Pluggable Authentication Modules
371
(PAM) service provided by the operating system. See <xref
372
linkend="auth-pam"> for details.
383
<term><replaceable>authentication-option</replaceable></term>
386
The meaning of this optional field depends on the chosen
387
authentication method. Details appear below.
395
Files included by <literal>@</> constructs are read as lists of names,
396
which can be separated by either whitespace or commas. Comments are
397
introduced by <literal>#</literal>, just as in
398
<filename>pg_hba.conf</filename>, and nested <literal>@</> constructs are
399
allowed. Unless the file name following <literal>@</> is an absolute
400
path, it is taken to be relative to the directory containing the
405
Since the <filename>pg_hba.conf</filename> records are examined
406
sequentially for each connection attempt, the order of the records is
407
significant. Typically, earlier records will have tight connection
408
match parameters and weaker authentication methods, while later
409
records will have looser match parameters and stronger authentication
410
methods. For example, one might wish to use <literal>trust</>
411
authentication for local TCP/IP connections but require a password for
412
remote TCP/IP connections. In this case a record specifying
413
<literal>trust</> authentication for connections from 127.0.0.1 would
414
appear before a record specifying password authentication for a wider
415
range of allowed client IP addresses.
419
The <filename>pg_hba.conf</filename> file is read on start-up and when
420
the main server process (<command>postmaster</>) receives a
421
<systemitem>SIGHUP</systemitem><indexterm><primary>SIGHUP</primary></indexterm>
422
signal. If you edit the file on an
423
active system, you will need to signal the <command>postmaster</>
424
(using <literal>pg_ctl reload</> or <literal>kill -HUP</>) to make it
429
Some examples of <filename>pg_hba.conf</filename> entries are shown in
430
<xref linkend="example-pg-hba.conf">. See the next section for details on the
431
different authentication methods.
434
<example id="example-pg-hba.conf">
435
<title>Example <filename>pg_hba.conf</filename> entries</title>
437
# Allow any user on the local system to connect to any database under
438
# any user name using Unix-domain sockets (the default for local
441
# TYPE DATABASE USER CIDR-ADDRESS METHOD
444
# The same using local loopback TCP/IP connections.
446
# TYPE DATABASE USER CIDR-ADDRESS METHOD
447
host all all 127.0.0.1/32 trust
449
# The same as the last line but using a separate netmask column
451
# TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
452
host all all 127.0.0.1 255.255.255.255 trust
454
# Allow any user from any host with IP address 192.168.93.x to connect
455
# to database "template1" as the same user name that ident reports for
456
# the connection (typically the Unix user name).
458
# TYPE DATABASE USER CIDR-ADDRESS METHOD
459
host template1 all 192.168.93.0/24 ident sameuser
461
# Allow a user from host 192.168.12.10 to connect to database
462
# "template1" if the user's password is correctly supplied.
464
# TYPE DATABASE USER CIDR-ADDRESS METHOD
465
host template1 all 192.168.12.10/32 md5
467
# In the absence of preceding "host" lines, these two lines will
468
# reject all connection from 192.168.54.1 (since that entry will be
469
# matched first), but allow Kerberos 5 connections from anywhere else
470
# on the Internet. The zero mask means that no bits of the host IP
471
# address are considered so it matches any host.
473
# TYPE DATABASE USER CIDR-ADDRESS METHOD
474
host all all 192.168.54.1/32 reject
475
host all all 0.0.0.0/0 krb5
477
# Allow users from 192.168.x.x hosts to connect to any database, if
478
# they pass the ident check. If, for example, ident says the user is
479
# "bryanh" and he requests to connect as PostgreSQL user "guest1", the
480
# connection is allowed if there is an entry in pg_ident.conf for map
481
# "omicron" that says "bryanh" is allowed to connect as "guest1".
483
# TYPE DATABASE USER CIDR-ADDRESS METHOD
484
host all all 192.168.0.0/16 ident omicron
486
# If these are the only three lines for local connections, they will
487
# allow local users to connect only to their own databases (databases
488
# with the same name as their user name) except for administrators and
489
# members of group "support" who may connect to all databases. The file
490
# $PGDATA/admins contains a list of user names. Passwords are required in
493
# TYPE DATABASE USER CIDR-ADDRESS METHOD
494
local sameuser all md5
495
local all @admins md5
496
local all +support md5
498
# The last two lines above can be combined into a single line:
499
local all @admins,+support md5
501
# The database column can also use lists and file names, but not groups:
502
local db1,db2,@demodbs all md5
507
<sect1 id="auth-methods">
508
<title>Authentication methods</title>
510
The following subsections describe the authentication methods in more detail.
513
<sect2 id="auth-trust">
514
<title>Trust authentication</title>
517
When <literal>trust</> authentication is specified,
518
<productname>PostgreSQL</productname> assumes that anyone who can
519
connect to the server is authorized to access the database with
520
whatever database user they specify (including the database superuser).
521
Of course, restrictions made in the <literal>database</> and
522
<literal>user</> columns still apply.
523
This method should only be used when there is adequate
524
operating-system-level protection on connections to the server.
528
<literal>trust</> authentication is appropriate and very
529
convenient for local connections on a single-user workstation. It
530
is usually <emphasis>not</> appropriate by itself on a multiuser
531
machine. However, you may be able to use <literal>trust</> even
532
on a multiuser machine, if you restrict access to the server's
533
Unix-domain socket file using file-system permissions. To do this, set the
534
<varname>unix_socket_permissions</varname> (and possibly
535
<varname>unix_socket_group</varname>) configuration parameters as
536
described in <xref linkend="runtime-config-connection">. Or you
537
could set the <varname>unix_socket_directory</varname>
538
configuration parameter to place the socket file in a suitably
539
restricted directory.
543
Setting file-system permissions only helps for Unix-socket connections.
544
Local TCP/IP connections are not restricted by it; therefore, if you want
545
to use file-system permissions for local security, remove the <literal>host ...
546
127.0.0.1 ...</> line from <filename>pg_hba.conf</>, or change it to a
547
non-<literal>trust</> authentication method.
551
<literal>trust</> authentication is only suitable for TCP/IP connections
552
if you trust every user on every machine that is allowed to connect
553
to the server by the <filename>pg_hba.conf</> lines that specify
554
<literal>trust</>. It is seldom reasonable to use <literal>trust</>
555
for any TCP/IP connections other than those from <systemitem>localhost</> (127.0.0.1).
560
<sect2 id="auth-password">
561
<title>Password authentication</title>
570
<primary>password</primary>
571
<secondary>authentication</secondary>
575
The password-based authentication methods are <literal>md5</>,
576
<literal>crypt</>, and <literal>password</>. These methods operate
577
similarly except for the way that the password is sent across the
578
connection. However, <literal>crypt</> does not allow encrypted
579
passwords to be stored in <structname>pg_shadow</structname>.
583
If you are at all concerned about password
584
<quote>sniffing</> attacks then <literal>md5</> is preferred, with
585
<literal>crypt</> a second choice if you must support pre-7.2
586
clients. Plain <literal>password</> should especially be avoided for
587
connections over the open Internet (unless you use <acronym>SSL</acronym>, SSH, or
588
other communications security wrappers around the connection).
592
<productname>PostgreSQL</productname> database passwords are
593
separate from operating system user passwords. The password for
594
each database user is stored in the <literal>pg_shadow</> system
595
catalog table. Passwords can be managed with the SQL commands
596
<xref linkend="sql-createuser" endterm="sql-createuser-title"> and
597
<xref linkend="sql-alteruser" endterm="sql-alteruser-title">,
598
e.g., <userinput>CREATE USER foo WITH PASSWORD 'secret';</userinput>.
599
By default, that is, if no password has been set up, the stored password
600
is null and password authentication will always fail for that user.
605
<sect2 id="kerberos-auth">
606
<title>Kerberos authentication</title>
608
<indexterm zone="kerberos-auth">
609
<primary>Kerberos</primary>
613
<productname>Kerberos</productname> is an industry-standard secure
614
authentication system suitable for distributed computing over a public
615
network. A description of the <productname>Kerberos</productname> system
616
is far beyond the scope of this document; in full generality it can be
617
quite complex (yet powerful). The <ulink
618
url="http://www.nrl.navy.mil/CCS/people/kenh/kerberos-faq.html">Kerberos
619
<acronym>FAQ</></ulink> or <ulink url="ftp://athena-dist.mit.edu">MIT
620
Project Athena</ulink> can be a good starting point for exploration.
621
Several sources for <productname>Kerberos</> distributions exist.
625
While <productname>PostgreSQL</> supports both Kerberos 4 and
626
Kerberos 5, only Kerberos 5 is recommended. Kerberos 4 is
627
considered insecure and no longer recommended for general
632
In order to use <productname>Kerberos</>, support for it must be
633
enabled at build time. See <xref linkend="installation"> for more
634
information. Both Kerberos 4 and 5 are supported, but only one
635
version can be supported in any one build.
639
<productname>PostgreSQL</> operates like a normal Kerberos service.
640
The name of the service principal is
641
<literal><replaceable>servicename</>/<replaceable>hostname</>@<replaceable>realm</></literal>, where
642
<replaceable>servicename</> is <literal>postgres</literal> (unless a
643
different service name was selected at configure time with
644
<literal>./configure --with-krb-srvnam=whatever</>).
645
<replaceable>hostname</> is the fully qualified host name of the
646
server machine. The service principal's realm is the preferred realm
647
of the server machine.
651
Client principals must have their <productname>PostgreSQL</> user
652
name as their first component, for example
653
<literal>pgusername/otherstuff@realm</>. At present the realm of
654
the client is not checked by <productname>PostgreSQL</>; so if you
655
have cross-realm authentication enabled, then any principal in any
656
realm that can communicate with yours will be accepted.
660
Make sure that your server key file is readable (and preferably
661
only readable) by the <productname>PostgreSQL</productname> server
662
account. (See also <xref linkend="postgres-user">.) The location
663
of the key file is specified by the <xref
664
linkend="guc-krb-server-keyfile"> configuration
665
parameter. (See also <xref linkend="runtime-config">.) The default
666
is <filename>/etc/srvtab</> if you are using Kerberos 4 and
667
<filename>/usr/local/pgsql/etc/krb5.keytab</> (or whichever
668
directory was specified as <varname>sysconfdir</> at build time)
673
To generate the keytab file, use for example (with version 5)
675
<prompt>kadmin% </><userinput>ank -randkey postgres/server.my.domain.org</>
676
<prompt>kadmin% </><userinput>ktadd -k krb5.keytab postgres/server.my.domain.org</>
678
Read the <productname>Kerberos</> documentation for details.
682
When connecting to the database make sure you have a ticket for a
683
principal matching the requested database user name. An example: For
684
database user name <literal>fred</>, both principal
685
<literal>fred@EXAMPLE.COM</> and
686
<literal>fred/users.example.com@EXAMPLE.COM</> can be used to
687
authenticate to the database server.
691
If you use <application>mod_auth_kerb</application> from
692
<ulink url="http://modauthkerb.sf.net">http://modauthkerb.sf.net</ulink>
693
and <application>mod_perl</application> on your
694
<productname>Apache</productname> web server, you can use
695
<literal>AuthType KerberosV5SaveCredentials</literal> with a
696
<application>mod_perl</application> script. This gives secure
697
database access over the web, no extra passwords required.
702
<sect2 id="auth-ident">
703
<title>Ident-based authentication</title>
706
<primary>ident</primary>
710
The ident authentication method works by obtaining the client's
711
operating system user name, then determining the allowed database
712
user names using a map file that lists the permitted
713
corresponding pairs of names. The determination of the client's
714
user name is the security-critical point, and it works differently
715
depending on the connection type.
719
<title>Ident Authentication over TCP/IP</title>
722
The <quote>Identification Protocol</quote> is described in
723
<citetitle>RFC 1413</citetitle>. Virtually every Unix-like
724
operating system ships with an ident server that listens on TCP
725
port 113 by default. The basic functionality of an ident server
726
is to answer questions like <quote>What user initiated the
727
connection that goes out of your port <replaceable>X</replaceable>
728
and connects to my port <replaceable>Y</replaceable>?</quote>.
729
Since <productname>PostgreSQL</> knows both <replaceable>X</> and
730
<replaceable>Y</> when a physical connection is established, it
731
can interrogate the ident server on the host of the connecting
732
client and could theoretically determine the operating system user
733
for any given connection this way.
737
The drawback of this procedure is that it depends on the integrity
738
of the client: if the client machine is untrusted or compromised
739
an attacker could run just about any program on port 113 and
740
return any user name he chooses. This authentication method is
741
therefore only appropriate for closed networks where each client
742
machine is under tight control and where the database and system
743
administrators operate in close contact. In other words, you must
744
trust the machine running the ident server.
747
<attribution>RFC 1413</attribution>
749
The Identification Protocol is not intended as an authorization
750
or access control protocol.
756
Some ident servers have a nonstandard option that causes the returned
757
user name to be encrypted, using a key that only the originating
758
machine's administrator knows. This option <emphasis>must not</> be
759
used when using the ident server with <productname>PostgreSQL</>,
760
since <productname>PostgreSQL</> does not have any way to decrypt the
761
returned string to determine the actual user name.
766
<title>Ident Authentication over Local Sockets</title>
769
On systems supporting <symbol>SO_PEERCRED</symbol> requests for
770
Unix-domain sockets (currently <systemitem
771
class="osname">Linux</>, <systemitem class="osname">FreeBSD</>,
772
<systemitem class="osname">NetBSD</>, <systemitem class=osname>OpenBSD</>,
773
and <systemitem class="osname">BSD/OS</>), ident authentication can also
774
be applied to local connections. In this case, no security risk is added by
775
using ident authentication; indeed it is a preferable choice for
776
local connections on such systems.
780
On systems without <symbol>SO_PEERCRED</> requests, ident
781
authentication is only available for TCP/IP connections. As a
782
work-around, it is possible to specify the <systemitem
783
class="systemname">localhost</> address <systemitem
784
class="systemname">127.0.0.1</> and make connections to this
785
address. This method is trustworthy to the extent that you trust
786
the local ident server.
790
<sect3 id="auth-ident-maps">
791
<title>Ident Maps</title>
794
When using ident-based authentication, after having determined the
795
name of the operating system user that initiated the connection,
796
<productname>PostgreSQL</productname> checks whether that user is
797
allowed to connect as the database user he is requesting to connect
798
as. This is controlled by the ident map argument that follows the
799
<literal>ident</> key word in the <filename>pg_hba.conf</filename>
800
file. There is a predefined ident map <literal>sameuser</literal>,
801
which allows any operating system user to connect as the database
802
user of the same name (if the latter exists). Other maps must be
807
Ident maps other than <literal>sameuser</literal> are defined in the
808
ident map file, which by default is named
809
<filename>pg_ident.conf</><indexterm><primary>pg_ident.conf</primary></indexterm>
811
cluster's data directory. (It is possible to place the map file
812
elsewhere, however; see the <xref linkend="guc-ident-file">
813
configuration parameter.)
814
The ident map file contains lines of the general form:
816
<replaceable>map-name</> <replaceable>ident-username</> <replaceable>database-username</>
818
Comments and whitespace are handled in the same way as in
819
<filename>pg_hba.conf</>. The
820
<replaceable>map-name</> is an arbitrary name that will be used to
821
refer to this mapping in <filename>pg_hba.conf</filename>. The other
822
two fields specify which operating system user is allowed to connect
823
as which database user. The same <replaceable>map-name</> can be
824
used repeatedly to specify more user-mappings within a single map.
825
There is no restriction regarding how many database users a given
826
operating system user may correspond to, nor vice versa.
830
The <filename>pg_ident.conf</filename> file is read on start-up and
831
when the main server process (<command>postmaster</>) receives a
832
<systemitem>SIGHUP</systemitem><indexterm><primary>SIGHUP</primary></indexterm>
833
signal. If you edit the file on an
834
active system, you will need to signal the <command>postmaster</>
835
(using <literal>pg_ctl reload</> or <literal>kill -HUP</>) to make it
840
A <filename>pg_ident.conf</filename> file that could be used in
841
conjunction with the <filename>pg_hba.conf</> file in <xref
842
linkend="example-pg-hba.conf"> is shown in <xref
843
linkend="example-pg-ident.conf">. In this example setup, anyone
844
logged in to a machine on the 192.168 network that does not have the
845
Unix user name <literal>bryanh</>, <literal>ann</>, or
846
<literal>robert</> would not be granted access. Unix user
847
<literal>robert</> would only be allowed access when he tries to
848
connect as <productname>PostgreSQL</> user <literal>bob</>, not
849
as <literal>robert</> or anyone else. <literal>ann</> would
850
only be allowed to connect as <literal>ann</>. User
851
<literal>bryanh</> would be allowed to connect as either
852
<literal>bryanh</> himself or as <literal>guest1</>.
855
<example id="example-pg-ident.conf">
856
<title>An example <filename>pg_ident.conf</> file</title>
858
# MAPNAME IDENT-USERNAME PG-USERNAME
860
omicron bryanh bryanh
862
# bob has user name robert on these machines
864
# bryanh can also connect as guest1
865
omicron bryanh guest1
871
<sect2 id="auth-pam">
872
<title>PAM authentication</title>
874
<indexterm zone="auth-pam">
875
<primary>PAM</primary>
879
This authentication method operates similarly to
880
<literal>password</literal> except that it uses PAM (Pluggable
881
Authentication Modules) as the authentication mechanism. The
882
default PAM service name is <literal>postgresql</literal>. You can
883
optionally supply your own service name after the <literal>pam</>
884
key word in the file <filename>pg_hba.conf</filename>.
885
PAM is used only to validate username/password pairs.
886
Therefore the user must already exist in the database before PAM
887
can be used for authentication. For more information about
888
PAM, please read the <ulink url="http://www.kernel.org/pub/linux/libs/pam/">
889
<productname>Linux-PAM</> Page</ulink>
890
and the <ulink url="http://www.sun.com/software/solaris/pam/">
891
<systemitem class="osname">Solaris</> PAM Page</ulink>.
896
<sect1 id="client-authentication-problems">
897
<title>Authentication problems</title>
900
Genuine authentication failures and related problems generally
901
manifest themselves through error messages like the following.
906
FATAL: no pg_hba.conf entry for host "123.123.123.123", user "andym", database "testdb"
908
This is what you are most likely to get if you succeed in contacting
909
the server, but it does not want to talk to you. As the message
910
suggests, the server refused the connection request because it found
911
no authorizing entry in its <filename>pg_hba.conf</filename>
917
FATAL: Password authentication failed for user "andym"
919
Messages like this indicate that you contacted the server, and it is
920
willing to talk to you, but not until you pass the authorization
921
method specified in the <filename>pg_hba.conf</filename> file. Check
922
the password you are providing, or check your Kerberos or ident
923
software if the complaint mentions one of those authentication
929
FATAL: user "andym" does not exist
931
The indicated user name was not found.
936
FATAL: database "testdb" does not exist
938
The database you are trying to connect to does not exist. Note that
939
if you do not specify a database name, it defaults to the database
940
user name, which may or may not be the right thing.
945
The server log may contain more information about an
946
authentication failure than is reported to the client. If you are
947
confused about the reason for a failure, check the log.
added
removed
doc/src/sgml/client-auth.sgml
