1- <!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.8 2000/10 /2101:08:34 petere Exp $ -->
1+ <!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.9 2000/11 /2120:44:31 tgl Exp $ -->
22
33<chapter id="client-authentication">
44 <title>Client Authentication</title>
55
66 <para>
7- User names from the operating system and from a
8- <productname>Postgres</productname> database installation are
9- logically separate. When a client application connects, it specifies
10- which database user name it wants to connect as, similar to how one
11- logs into a Unix computer. Within the SQL environment the active
12- database user name determines various access privileges to database
7+ When a client application connects to the database server, it specifies which
8+ <productname>Postgres</productname> user name it wants to connect as,
9+ much the same way one logs into a Unix computer as a particular user.
10+ Within the SQL environment the active
11+ database user name determines access privileges to database
1312 objects -- see <xref linkend="user-manag"> for more information
14- about that. It is therefore obviously essential to restrictwhat
15- database user name a given client can connect as.
13+ about that. It is therefore obviously essential to restrictwhich
14+ database user name(s) a given client can connect as.
1615 </para>
1716
1817 <para>
1918 <firstterm>Authentication</firstterm> is the process by which the
2019 database server establishes the identity of the client, and by
2120 extension determines whether the client application (or the user
22- which runs the client application) is permitted to connect with the
21+ who runs the client application) is permitted to connect with the
2322 user name that was requested.
2423 </para>
2524
2928 authentication methods available.
3029 </para>
3130
31+ <para>
32+ <productname>Postgres</productname> database user names are logically
33+ separate from user names of the operating system in which the server
34+ runs. If all the users of a particular server also have accounts on
35+ the server's machine, it makes sense to assign database user names
36+ that match their Unix user ids. However, a server that accepts remote
37+ connections may have many users who have no local account, and in such
38+ cases there need be no connection between database usernames and Unix
39+ usernames.
40+ </para>
41+
3242 <sect1 id="pg-hba.conf">
3343 <title>The <filename>pg_hba.conf</filename> file</title>
3444
3545 <para>
3646 Client authentication is controlled by the file
37- <filename>pg_hba.conf</filename> in the data directory, e.g.,
38- <filename>/usr/local/pgsql/data/pg_hba.conf</filename>. (HBA =
39- host-based authentication) A default file is installed when the
47+ <filename>pg_hba.conf</filename> in the $PGDATA directory, e.g.,
48+ <filename>/usr/local/pgsql/data/pg_hba.conf</filename>. (HBA stands
49+ for host-based authentication.) A default <filename>pg_hba.conf</filename>
50+ file is installed when the
4051 data area is initialized by <application>initdb</application>.
4152 </para>
4253
@@ -84,7 +95,7 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
8495 <term><literal>hostssl</literal></term>
8596 <listitem>
8697 <para>
87- This record pertains to connectionattemps with SSL over
98+ This record pertains to connectionattempts with SSL over
8899 TCP/IP. To make use of this option the server must be
89100 built with SSL support enabled. Furthermore, SSL must be
90101 enabled with the <option>-l</> option or equivalent configuration
@@ -99,8 +110,10 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
99110 <para>
100111 Specifies the database that this record applies to. The value
101112 <literal>all</literal> specifies that it applies to all
102- databases, the value <literal>sameuser</> identifies the
103- database with the same name as the connecting user.
113+ databases, while the value <literal>sameuser</> identifies the
114+ database with the same name as the connecting user. Otherwise,
115+ this is the name of a specific <productname>Postgres</productname>
116+ database.
104117 </para>
105118 </listitem>
106119 </varlistentry>
@@ -140,7 +153,7 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
140153 <para>
141154 The connection is allowed unconditionally. This method allows
142155 any user that has login access to the client host to connect as
143- any user whatsoever.
156+ any<productname>Postgres</productname> user whatsoever.
144157 </para>
145158 </listitem>
146159 </varlistentry>
@@ -246,17 +259,18 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
246259 </varlistentry>
247260 </variablelist>
248261
249- The first record that matches a connection attempt is used. There
250- is no <quote>fall-through</> or <quote>backup</>, that means, if
262+ The first record that matches a connection attempt's client IP address
263+ and requested database name is used to do the authentication step.
264+ There is no <quote>fall-through</> or <quote>backup</>: if
251265 one record is chosen and the
252266 authentication fails, the following records are not considered. If
253267 no record matches, the access will be denied.
254268 </para>
255269
256270 <para>
257- The <filename>pg_hba.conf</filename> file is re-readbefore each
258- connection attempt. It is thereforeeasily possible to modify
259- access permissions while the server is running.
271+ The <filename>pg_hba.conf</filename> file is re-readduring each
272+ connection attempt. It is thereforetrivial to modify access
273+ permissions while the server is running: just edit the file .
260274 </para>
261275
262276 <para>
@@ -267,42 +281,44 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
267281 <example id="example-pg-hba.conf">
268282 <title>An example <filename>pg_hba.conf</filename> file</title>
269283<programlisting>
270- #TYPE DATABASE IP-ADDRESS MASK AUTHTYPE ARG
271-
272- # Allow any user on the local system to connect to any database under
273- # any user name.
274- #
275- host all 127.0.0.1 255.255.255.255 trust
276-
277- # Allow any user from any host with IP address 192.168.93.x to connect
278- # to database "template1" as the same user name that ident on that
279- # host identifies him as (typically his Unix user name).
280- #
281- host template1 192.168.93.0 255.255.255.0 ident sameuser
282-
283- # Allow a user from host 192.168.12.10 to connect to database
284- # "template1" if the user's password in pg_shadow is supplied.
285- #
286- host template1 192.168.12.10 255.255.255.255 crypt
287-
288- # In absence of the other records, this would allow anyone anywhere
289- # except from 192.168.54.1 to connect to any database under any user
290- # name.
291- #
292- host all 192.168.54.1 255.255.255.255 reject
293- host all 0.0.0.0 0.0.0.0 trust
294-
295- # Allow users from 192.168.77.x hosts to connect to any database, but if,
296- # for example, ident says the user is "bryanh" and he requests to
297- # connect as PostgreSQL user "guest1", the connection is only allowed if
298- # there is an entry for map "omicron" in `pg_ident.conf' that says
299- # "bryanh" is allowed to connect as "guest1".
300- #
301- host all 192.168.77.0 255.255.255.0 ident omicron
302-
303- # Allow all users to connect to all databases via Unix sockets.
304- #
305- local all trust
284+ # TYPE DATABASE IP_ADDRESS MASK AUTHTYPE MAP
285+
286+ # Allow any user on the local system to connect to any
287+ # database under any username, but only via an IP connection:
288+
289+ host all 127.0.0.1 255.255.255.255 trust
290+
291+ # The same, over Unix-socket connections:
292+
293+ local all trust
294+
295+ # Allow any user from any host with IP address 192.168.93.x to
296+ # connect to database "template1" as the same username that ident on that
297+ # host identifies him as (typically his Unix username):
298+
299+ host template1 192.168.93.0 255.255.255.0 ident sameuser
300+
301+ # Allow a user from host 192.168.12.10 to connect to database "template1"
302+ # if the user's password in pg_shadow is correctly supplied:
303+
304+ host template1 192.168.12.10 255.255.255.255 crypt
305+
306+ # In the absence of preceding "host" lines, these two lines will reject
307+ # all connection attempts from 192.168.54.1 (since that entry will be
308+ # matched first), but allow Kerberos V5-validated connections from anywhere
309+ # else on the Internet. The zero mask means that no bits of the host IP
310+ # address are considered, so it matches any host:
311+
312+ host all 192.168.54.1 255.255.255.255 reject
313+ host all 0.0.0.0 0.0.0.0 krb5
314+
315+ # Allow users from 192.168.x.x hosts to connect to any database, if they
316+ # pass the ident check. If, for example, ident says the user is "bryanh"
317+ # and he requests to connect as PostgreSQL user "guest1", the connection
318+ # is allowed if there is an entry in pg_ident.conf for map "omicron" that
319+ # says "bryanh" is allowed to connect as "guest1":
320+
321+ host all 192.168.0.0 255.255.0.0 ident omicron
306322</programlisting>
307323 </example>
308324 </para>
@@ -324,7 +340,7 @@ local all trust
324340 <command>CREATE USER</command> and <command>ALTER USER</command>,
325341 e.g., <userinput>CREATE USER foo WITH PASSWORD
326342 'secret';</userinput>. By default, that is, if no password has
327- explicitly been set up, the stored password is <quote >NULL</quote >
343+ been set up, the stored password is <literal >NULL</literal >
328344 and password authentication will always fail for that user.
329345 </para>
330346
@@ -336,12 +352,12 @@ local all trust
336352 file after the <literal>password</> or <literal>crypt</> keyword,
337353 respectively, in <filename>pg_hba.conf</>. If you do not use this
338354 feature, then any user that is known to the database system can
339- connect to any database (as long as he passes password
355+ connect to any database (so long as he passes password
340356 authentication, of course).
341357 </para>
342358
343359 <para>
344- These files can also be useda apply a different set of passwords
360+ These files can also be usedto apply a different set of passwords
345361 to a particular database or set thereof. In that case, the files
346362 have a format similar to the standard Unix password file
347363 <filename>/etc/passwd</filename>, that is,
@@ -401,7 +417,7 @@ local all trust
401417
402418 <para>
403419 In order to use <productname>Kerberos</>, support for it must be
404- enable at build time. Both Kerberos 4 and 5 are supported
420+ enabled at build time. Both Kerberos 4 and 5 are supported
405421 (<literal>./configure --with-krb4</> or <literal>./configure
406422 --with-krb5</> respectively).
407423 </para>
@@ -411,7 +427,7 @@ local all trust
411427 service. The name of the service principal is normally
412428 <literal>postgres</literal>, unless it was changed during the
413429 build. Make sure that your server key file is readable (and
414- preferrably only readable) by the Postgres server account (see
430+ preferably only readable) by the Postgres server account (see
415431 <xref linkend="postgres-user">). The location of the key file
416432 is specified with the <varname>krb_server_keyfile</> run time
417433 configuration parameter. (See also <xref linkend="runtime-config">.)
@@ -553,13 +569,13 @@ local all trust
553569 A <filename>pg_ident.conf</filename> file that could be used in
554570 conjunction with the <filename>pg_hba.conf</> file in <xref
555571 linkend="example-pg-hba.conf"> is shown in <xref
556- linkend="example-pg-ident.conf">. Inthat example setup, anyone
557- logged in to a machine on the 192.168.77 network that does not have
558- thea user name bryanh, ann, or robert would not be granted access.
572+ linkend="example-pg-ident.conf">. Inthis example setup, anyone
573+ logged in to a machine on the 192.168 network that does not have
574+ theUnix user name bryanh, ann, or robert would not be granted access.
559575 Unix user robert would only be allowed access when he tries to
560- connect as <quote>bob</quote>, not as <quote>robert</quote> or
561- anyone else. <quote>ann</quote> would only be allowed to connect
562- <quote>as herself </>. User bryanh would be allowed to connect as either
576+ connect asPostgres user <quote>bob</quote>, not as <quote>robert</quote>
577+ or anyone else. <quote>ann</quote> would only be allowed to connect as
578+ <quote>ann </>. User bryanh would be allowed to connect as either
563579 <quote>bryanh</> himself or as <quote>guest1</>.
564580 </para>
565581