1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>20.1. The pg_hba.conf File</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="client-authentication.html" title="Chapter 20. Client Authentication" /><link rel="next" href="auth-username-maps.html" title="20.2. User Name Maps" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">20.1. The <code class="filename">pg_hba.conf</code> File</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="client-authentication.html" title="Chapter 20. Client Authentication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="client-authentication.html" title="Chapter 20. Client Authentication">Up</a></td><th width="60%" align="center">Chapter 20. Client Authentication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="auth-username-maps.html" title="20.2. User Name Maps">Next</a></td></tr></table><hr /></div><div class="sect1" id="AUTH-PG-HBA-CONF"><div class="titlepage"><div><div><h2 class="title" style="clear: both">20.1. The <code class="filename">pg_hba.conf</code> File <a href="#AUTH-PG-HBA-CONF" class="id_link">#</a></h2></div></div></div><a id="id-1.6.7.8.2" class="indexterm"></a><p>
3 Client authentication is controlled by a configuration file,
4 which traditionally is named
5 <code class="filename">pg_hba.conf</code> and is stored in the database
6 cluster's data directory.
7 (<acronym class="acronym">HBA</acronym> stands for host-based authentication.) A default
8 <code class="filename">pg_hba.conf</code> file is installed when the data
9 directory is initialized by <a class="xref" href="app-initdb.html" title="initdb"><span class="refentrytitle"><span class="application">initdb</span></span></a>. It is
10 possible to place the authentication configuration file elsewhere,
11 however; see the <a class="xref" href="runtime-config-file-locations.html#GUC-HBA-FILE">hba_file</a> configuration parameter.
13 The <code class="filename">pg_hba.conf</code> file is read on start-up and when
14 the main server process receives a
15 <span class="systemitem">SIGHUP</span><a id="id-1.6.7.8.4.3" class="indexterm"></a>
16 signal. If you edit the file on an
17 active system, you will need to signal the postmaster
18 (using <code class="literal">pg_ctl reload</code>, calling the SQL function
19 <code class="function">pg_reload_conf()</code>, or using <code class="literal">kill
20 -HUP</code>) to make it re-read the file.
21 </p><div class="note"><h3 class="title">Note</h3><p>
22 The preceding statement is not true on Microsoft Windows: there, any
23 changes in the <code class="filename">pg_hba.conf</code> file are immediately
24 applied by subsequent new connections.
27 <a class="link" href="view-pg-hba-file-rules.html" title="53.10. pg_hba_file_rules"><code class="structname">pg_hba_file_rules</code></a>
28 can be helpful for pre-testing changes to the <code class="filename">pg_hba.conf</code>
29 file, or for diagnosing problems if loading of the file did not have the
30 desired effects. Rows in the view with
31 non-null <code class="structfield">error</code> fields indicate problems in the
32 corresponding lines of the file.
34 The general format of the <code class="filename">pg_hba.conf</code> file is
35 a set of records, one per line. Blank lines are ignored, as is any
36 text after the <code class="literal">#</code> comment character.
37 A record can be continued onto the next line by ending the line with
38 a backslash. (Backslashes are not special except at the end of a line.)
40 up of a number of fields which are separated by spaces and/or tabs.
41 Fields can contain white space if the field value is double-quoted.
42 Quoting one of the keywords in a database, user, or address field (e.g.,
43 <code class="literal">all</code> or <code class="literal">replication</code>) makes the word lose its special
44 meaning, and just match a database, user, or host with that name.
45 Backslash line continuation applies even within quoted text or comments.
47 Each authentication record specifies a connection type, a client IP address
48 range (if relevant for the connection type), a database name, a user name,
49 and the authentication method to be used for connections matching
50 these parameters. The first record with a matching connection type,
51 client address, requested database, and user name is used to perform
52 authentication. There is no <span class="quote">“<span class="quote">fall-through</span>”</span> or
53 <span class="quote">“<span class="quote">backup</span>”</span>: if one record is chosen and the authentication
54 fails, subsequent records are not considered. If no record matches,
57 Each record can be an include directive or an authentication record.
58 Include directives specify files that can be included, that contain
59 additional records. The records will be inserted in place of the
60 include directives. Include directives only contain two fields:
61 <code class="literal">include</code>, <code class="literal">include_if_exists</code> or
62 <code class="literal">include_dir</code> directive and the file or directory to be
63 included. The file or directory can be a relative or absolute path, and can
64 be double-quoted. For the <code class="literal">include_dir</code> form, all files
65 not starting with a <code class="literal">.</code> and ending with
66 <code class="literal">.conf</code> will be included. Multiple files within an include
67 directory are processed in file name order (according to C locale rules,
68 i.e., numbers before letters, and uppercase letters before lowercase ones).
70 A record can have several formats:
71 </p><pre class="synopsis">
72 local <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]
73 host <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>address</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]
74 hostssl <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>address</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]
75 hostnossl <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>address</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]
76 hostgssenc <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>address</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]
77 hostnogssenc <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>address</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]
78 host <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>IP-address</code></em> <em class="replaceable"><code>IP-mask</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]
79 hostssl <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>IP-address</code></em> <em class="replaceable"><code>IP-mask</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]
80 hostnossl <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>IP-address</code></em> <em class="replaceable"><code>IP-mask</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]
81 hostgssenc <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>IP-address</code></em> <em class="replaceable"><code>IP-mask</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]
82 hostnogssenc <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>IP-address</code></em> <em class="replaceable"><code>IP-mask</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]
83 include <em class="replaceable"><code>file</code></em>
84 include_if_exists <em class="replaceable"><code>file</code></em>
85 include_dir <em class="replaceable"><code>directory</code></em>
87 The meaning of the fields is as follows:
89 </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">local</code></span></dt><dd><p>
90 This record matches connection attempts using Unix-domain
91 sockets. Without a record of this type, Unix-domain socket
92 connections are disallowed.
93 </p></dd><dt><span class="term"><code class="literal">host</code></span></dt><dd><p>
94 This record matches connection attempts made using TCP/IP.
95 <code class="literal">host</code> records match
96 <acronym class="acronym">SSL</acronym> or non-<acronym class="acronym">SSL</acronym> connection
97 attempts as well as <acronym class="acronym">GSSAPI</acronym> encrypted or
98 non-<acronym class="acronym">GSSAPI</acronym> encrypted connection attempts.
99 </p><div class="note"><h3 class="title">Note</h3><p>
100 Remote TCP/IP connections will not be possible unless
101 the server is started with an appropriate value for the
102 <a class="xref" href="runtime-config-connection.html#GUC-LISTEN-ADDRESSES">listen_addresses</a> configuration parameter,
103 since the default behavior is to listen for TCP/IP connections
104 only on the local loopback address <code class="literal">localhost</code>.
105 </p></div></dd><dt><span class="term"><code class="literal">hostssl</code></span></dt><dd><p>
106 This record matches connection attempts made using TCP/IP,
107 but only when the connection is made with <acronym class="acronym">SSL</acronym>
110 To make use of this option the server must be built with
111 <acronym class="acronym">SSL</acronym> support. Furthermore,
112 <acronym class="acronym">SSL</acronym> must be enabled
113 by setting the <a class="xref" href="runtime-config-connection.html#GUC-SSL">ssl</a> configuration parameter (see
114 <a class="xref" href="ssl-tcp.html" title="18.9. Secure TCP/IP Connections with SSL">Section 18.9</a> for more information).
115 Otherwise, the <code class="literal">hostssl</code> record is ignored except for
116 logging a warning that it cannot match any connections.
117 </p></dd><dt><span class="term"><code class="literal">hostnossl</code></span></dt><dd><p>
118 This record type has the opposite behavior of <code class="literal">hostssl</code>;
119 it only matches connection attempts made over
120 TCP/IP that do not use <acronym class="acronym">SSL</acronym>.
121 </p></dd><dt><span class="term"><code class="literal">hostgssenc</code></span></dt><dd><p>
122 This record matches connection attempts made using TCP/IP,
123 but only when the connection is made with <acronym class="acronym">GSSAPI</acronym>
126 To make use of this option the server must be built with
127 <acronym class="acronym">GSSAPI</acronym> support. Otherwise,
128 the <code class="literal">hostgssenc</code> record is ignored except for logging
129 a warning that it cannot match any connections.
130 </p></dd><dt><span class="term"><code class="literal">hostnogssenc</code></span></dt><dd><p>
131 This record type has the opposite behavior of <code class="literal">hostgssenc</code>;
132 it only matches connection attempts made over
133 TCP/IP that do not use <acronym class="acronym">GSSAPI</acronym> encryption.
134 </p></dd><dt><span class="term"><em class="replaceable"><code>database</code></em></span></dt><dd><p>
135 Specifies which database name(s) this record matches. The value
136 <code class="literal">all</code> specifies that it matches all databases.
137 The value <code class="literal">sameuser</code> specifies that the record
138 matches if the requested database has the same name as the
139 requested user. The value <code class="literal">samerole</code> specifies that
140 the requested user must be a member of the role with the same
141 name as the requested database. (<code class="literal">samegroup</code> is an
142 obsolete but still accepted spelling of <code class="literal">samerole</code>.)
143 Superusers are not considered to be members of a role for the
144 purposes of <code class="literal">samerole</code> unless they are explicitly
145 members of the role, directly or indirectly, and not just by
146 virtue of being a superuser.
147 The value <code class="literal">replication</code> specifies that the record
148 matches if a physical replication connection is requested, however, it
149 doesn't match with logical replication connections. Note that physical
150 replication connections do not specify any particular database whereas
151 logical replication connections do specify it.
152 Otherwise, this is the name of a specific
153 <span class="productname">PostgreSQL</span> database or a regular expression.
154 Multiple database names and/or regular expressions can be supplied by
155 separating them with commas.
157 If the database name starts with a slash (<code class="literal">/</code>), the
158 remainder of the name is treated as a regular expression.
159 (See <a class="xref" href="functions-matching.html#POSIX-SYNTAX-DETAILS" title="9.7.3.1. Regular Expression Details">Section 9.7.3.1</a> for details of
160 <span class="productname">PostgreSQL</span>'s regular expression syntax.)
162 A separate file containing database names and/or regular expressions
163 can be specified by preceding the file name with <code class="literal">@</code>.
164 </p></dd><dt><span class="term"><em class="replaceable"><code>user</code></em></span></dt><dd><p>
165 Specifies which database user name(s) this record
166 matches. The value <code class="literal">all</code> specifies that it
167 matches all users. Otherwise, this is either the name of a specific
168 database user, a regular expression (when starting with a slash
169 (<code class="literal">/</code>), or a group name preceded by <code class="literal">+</code>.
170 (Recall that there is no real distinction between users and groups
171 in <span class="productname">PostgreSQL</span>; a <code class="literal">+</code> mark really means
172 <span class="quote">“<span class="quote">match any of the roles that are directly or indirectly members
173 of this role</span>”</span>, while a name without a <code class="literal">+</code> mark matches
174 only that specific role.) For this purpose, a superuser is only
175 considered to be a member of a role if they are explicitly a member
176 of the role, directly or indirectly, and not just by virtue of
178 Multiple user names and/or regular expressions can be supplied by
179 separating them with commas.
181 If the user name starts with a slash (<code class="literal">/</code>), the
182 remainder of the name is treated as a regular expression.
183 (See <a class="xref" href="functions-matching.html#POSIX-SYNTAX-DETAILS" title="9.7.3.1. Regular Expression Details">Section 9.7.3.1</a> for details of
184 <span class="productname">PostgreSQL</span>'s regular expression syntax.)
186 A separate file containing user names and/or regular expressions can
187 be specified by preceding the file name with <code class="literal">@</code>.
188 </p></dd><dt><span class="term"><em class="replaceable"><code>address</code></em></span></dt><dd><p>
189 Specifies the client machine address(es) that this record
190 matches. This field can contain either a host name, an IP
191 address range, or one of the special key words mentioned below.
193 An IP address range is specified using standard numeric notation
194 for the range's starting address, then a slash (<code class="literal">/</code>)
195 and a <acronym class="acronym">CIDR</acronym> mask length. The mask
196 length indicates the number of high-order bits of the client
197 IP address that must match. Bits to the right of this should
198 be zero in the given IP address.
199 There must not be any white space between the IP address, the
200 <code class="literal">/</code>, and the CIDR mask length.
202 Typical examples of an IPv4 address range specified this way are
203 <code class="literal">172.20.143.89/32</code> for a single host, or
204 <code class="literal">172.20.143.0/24</code> for a small network, or
205 <code class="literal">10.6.0.0/16</code> for a larger one.
206 An IPv6 address range might look like <code class="literal">::1/128</code>
207 for a single host (in this case the IPv6 loopback address) or
208 <code class="literal">fe80::7a31:c1ff:0000:0000/96</code> for a small
210 <code class="literal">0.0.0.0/0</code> represents all
211 IPv4 addresses, and <code class="literal">::0/0</code> represents
213 To specify a single host, use a mask length of 32 for IPv4 or
214 128 for IPv6. In a network address, do not omit trailing zeroes.
216 An entry given in IPv4 format will match only IPv4 connections,
217 and an entry given in IPv6 format will match only IPv6 connections,
218 even if the represented address is in the IPv4-in-IPv6 range.
220 You can also write <code class="literal">all</code> to match any IP address,
221 <code class="literal">samehost</code> to match any of the server's own IP
222 addresses, or <code class="literal">samenet</code> to match any address in any
223 subnet that the server is directly connected to.
225 If a host name is specified (anything that is not an IP address
226 range or a special key word is treated as a host name),
227 that name is compared with the result of a reverse name
228 resolution of the client's IP address (e.g., reverse DNS
229 lookup, if DNS is used). Host name comparisons are case
230 insensitive. If there is a match, then a forward name
231 resolution (e.g., forward DNS lookup) is performed on the host
232 name to check whether any of the addresses it resolves to are
233 equal to the client's IP address. If both directions match,
234 then the entry is considered to match. (The host name that is
235 used in <code class="filename">pg_hba.conf</code> should be the one that
236 address-to-name resolution of the client's IP address returns,
237 otherwise the line won't be matched. Some host name databases
238 allow associating an IP address with multiple host names, but
239 the operating system will only return one host name when asked
240 to resolve an IP address.)
242 A host name specification that starts with a dot
243 (<code class="literal">.</code>) matches a suffix of the actual host
244 name. So <code class="literal">.example.com</code> would match
245 <code class="literal">foo.example.com</code> (but not just
246 <code class="literal">example.com</code>).
248 When host names are specified
249 in <code class="filename">pg_hba.conf</code>, you should make sure that
250 name resolution is reasonably fast. It can be of advantage to
251 set up a local name resolution cache such
252 as <code class="command">nscd</code>. Also, you may wish to enable the
253 configuration parameter <code class="varname">log_hostname</code> to see
254 the client's host name instead of the IP address in the log.
256 These fields do not apply to <code class="literal">local</code> records.
257 </p><div class="note"><h3 class="title">Note</h3><p>
258 Users sometimes wonder why host names are handled
259 in this seemingly complicated way, with two name resolutions
260 including a reverse lookup of the client's IP address. This
261 complicates use of the feature in case the client's reverse DNS
262 entry is not set up or yields some undesirable host name.
263 It is done primarily for efficiency: this way, a connection attempt
264 requires at most two resolver lookups, one reverse and one forward.
265 If there is a resolver problem with some address, it becomes only
266 that client's problem. A hypothetical alternative
267 implementation that only did forward lookups would have to
268 resolve every host name mentioned in
269 <code class="filename">pg_hba.conf</code> during every connection attempt.
270 That could be quite slow if many names are listed.
271 And if there is a resolver problem with one of the host names,
272 it becomes everyone's problem.
274 Also, a reverse lookup is necessary to implement the suffix
275 matching feature, because the actual client host name needs to
276 be known in order to match it against the pattern.
278 Note that this behavior is consistent with other popular
279 implementations of host name-based access control, such as the
280 Apache HTTP Server and TCP Wrappers.
281 </p></div></dd><dt><span class="term"><em class="replaceable"><code>IP-address</code></em><br /></span><span class="term"><em class="replaceable"><code>IP-mask</code></em></span></dt><dd><p>
282 These two fields can be used as an alternative to the
283 <em class="replaceable"><code>IP-address</code></em><code class="literal">/</code><em class="replaceable"><code>mask-length</code></em>
285 specifying the mask length, the actual mask is specified in a
286 separate column. For example, <code class="literal">255.0.0.0</code> represents an IPv4
287 CIDR mask length of 8, and <code class="literal">255.255.255.255</code> represents a
288 CIDR mask length of 32.
290 These fields do not apply to <code class="literal">local</code> records.
291 </p></dd><dt><span class="term"><em class="replaceable"><code>auth-method</code></em></span></dt><dd><p>
292 Specifies the authentication method to use when a connection matches
293 this record. The possible choices are summarized here; details
294 are in <a class="xref" href="auth-methods.html" title="20.3. Authentication Methods">Section 20.3</a>. All the options
295 are lower case and treated case sensitively, so even acronyms like
296 <code class="literal">ldap</code> must be specified as lower case.
298 </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">trust</code></span></dt><dd><p>
299 Allow the connection unconditionally. This method
300 allows anyone that can connect to the
301 <span class="productname">PostgreSQL</span> database server to login as
302 any <span class="productname">PostgreSQL</span> user they wish,
303 without the need for a password or any other authentication. See <a class="xref" href="auth-trust.html" title="20.4. Trust Authentication">Section 20.4</a> for details.
304 </p></dd><dt><span class="term"><code class="literal">reject</code></span></dt><dd><p>
305 Reject the connection unconditionally. This is useful for
306 <span class="quote">“<span class="quote">filtering out</span>”</span> certain hosts from a group, for example a
307 <code class="literal">reject</code> line could block a specific host from connecting,
308 while a later line allows the remaining hosts in a specific
310 </p></dd><dt><span class="term"><code class="literal">scram-sha-256</code></span></dt><dd><p>
311 Perform SCRAM-SHA-256 authentication to verify the user's
312 password. See <a class="xref" href="auth-password.html" title="20.5. Password Authentication">Section 20.5</a> for details.
313 </p></dd><dt><span class="term"><code class="literal">md5</code></span></dt><dd><p>
314 Perform SCRAM-SHA-256 or MD5 authentication to verify the
315 user's password. See <a class="xref" href="auth-password.html" title="20.5. Password Authentication">Section 20.5</a>
317 </p><div class="warning"><h3 class="title">Warning</h3><p>
318 Support for MD5-encrypted passwords is deprecated and will be
319 removed in a future release of
320 <span class="productname">PostgreSQL</span>. Refer to
321 <a class="xref" href="auth-password.html" title="20.5. Password Authentication">Section 20.5</a> for details about migrating to
322 another password type.
323 </p></div></dd><dt><span class="term"><code class="literal">password</code></span></dt><dd><p>
324 Require the client to supply an unencrypted password for
326 Since the password is sent in clear text over the
327 network, this should not be used on untrusted networks.
328 See <a class="xref" href="auth-password.html" title="20.5. Password Authentication">Section 20.5</a> for details.
329 </p></dd><dt><span class="term"><code class="literal">gss</code></span></dt><dd><p>
330 Use GSSAPI to authenticate the user. This is only
331 available for TCP/IP connections. See <a class="xref" href="gssapi-auth.html" title="20.6. GSSAPI Authentication">Section 20.6</a> for details. It can be used in conjunction
332 with GSSAPI encryption.
333 </p></dd><dt><span class="term"><code class="literal">sspi</code></span></dt><dd><p>
334 Use SSPI to authenticate the user. This is only
335 available on Windows. See <a class="xref" href="sspi-auth.html" title="20.7. SSPI Authentication">Section 20.7</a> for details.
336 </p></dd><dt><span class="term"><code class="literal">ident</code></span></dt><dd><p>
337 Obtain the operating system user name of the client
338 by contacting the ident server on the client
339 and check if it matches the requested database user name.
340 Ident authentication can only be used on TCP/IP
341 connections. When specified for local connections, peer
342 authentication will be used instead.
343 See <a class="xref" href="auth-ident.html" title="20.8. Ident Authentication">Section 20.8</a> for details.
344 </p></dd><dt><span class="term"><code class="literal">peer</code></span></dt><dd><p>
345 Obtain the client's operating system user name from the operating
346 system and check if it matches the requested database user name.
347 This is only available for local connections.
348 See <a class="xref" href="auth-peer.html" title="20.9. Peer Authentication">Section 20.9</a> for details.
349 </p></dd><dt><span class="term"><code class="literal">ldap</code></span></dt><dd><p>
350 Authenticate using an <acronym class="acronym">LDAP</acronym> server. See <a class="xref" href="auth-ldap.html" title="20.10. LDAP Authentication">Section 20.10</a> for details.
351 </p></dd><dt><span class="term"><code class="literal">radius</code></span></dt><dd><p>
352 Authenticate using a RADIUS server. See <a class="xref" href="auth-radius.html" title="20.11. RADIUS Authentication">Section 20.11</a> for details.
353 </p></dd><dt><span class="term"><code class="literal">cert</code></span></dt><dd><p>
354 Authenticate using SSL client certificates. See
355 <a class="xref" href="auth-cert.html" title="20.12. Certificate Authentication">Section 20.12</a> for details.
356 </p></dd><dt><span class="term"><code class="literal">pam</code></span></dt><dd><p>
357 Authenticate using the Pluggable Authentication Modules
358 (PAM) service provided by the operating system. See <a class="xref" href="auth-pam.html" title="20.13. PAM Authentication">Section 20.13</a> for details.
359 </p></dd><dt><span class="term"><code class="literal">bsd</code></span></dt><dd><p>
360 Authenticate using the BSD Authentication service provided by the
361 operating system. See <a class="xref" href="auth-bsd.html" title="20.14. BSD Authentication">Section 20.14</a> for details.
362 </p></dd><dt><span class="term"><code class="literal">oauth</code></span></dt><dd><p>
363 Authorize and optionally authenticate using a third-party OAuth 2.0
364 identity provider. See <a class="xref" href="auth-oauth.html" title="20.15. OAuth Authorization/Authentication">Section 20.15</a> for details.
365 </p></dd></dl></div><p>
367 </p></dd><dt><span class="term"><em class="replaceable"><code>auth-options</code></em></span></dt><dd><p>
368 After the <em class="replaceable"><code>auth-method</code></em> field, there can be field(s) of
369 the form <em class="replaceable"><code>name</code></em><code class="literal">=</code><em class="replaceable"><code>value</code></em> that
370 specify options for the authentication method. Details about which
371 options are available for which authentication methods appear below.
373 In addition to the method-specific options listed below, there is a
374 method-independent authentication option <code class="literal">clientcert</code>, which
375 can be specified in any <code class="literal">hostssl</code> record.
376 This option can be set to <code class="literal">verify-ca</code> or
377 <code class="literal">verify-full</code>. Both options require the client
378 to present a valid (trusted) SSL certificate, while
379 <code class="literal">verify-full</code> additionally enforces that the
380 <code class="literal">cn</code> (Common Name) in the certificate matches
381 the username or an applicable mapping.
382 This behavior is similar to the <code class="literal">cert</code> authentication
383 method (see <a class="xref" href="auth-cert.html" title="20.12. Certificate Authentication">Section 20.12</a>) but enables pairing
384 the verification of client certificates with any authentication
385 method that supports <code class="literal">hostssl</code> entries.
387 On any record using client certificate authentication (i.e. one
388 using the <code class="literal">cert</code> authentication method or one
389 using the <code class="literal">clientcert</code> option), you can specify
390 which part of the client certificate credentials to match using
391 the <code class="literal">clientname</code> option. This option can have one
392 of two values. If you specify <code class="literal">clientname=CN</code>, which
393 is the default, the username is matched against the certificate's
394 <code class="literal">Common Name (CN)</code>. If instead you specify
395 <code class="literal">clientname=DN</code> the username is matched against the
396 entire <code class="literal">Distinguished Name (DN)</code> of the certificate.
397 This option is probably best used in conjunction with a username map.
398 The comparison is done with the <code class="literal">DN</code> in
399 <a class="ulink" href="https://datatracker.ietf.org/doc/html/rfc2253" target="_top">RFC 2253</a>
400 format. To see the <code class="literal">DN</code> of a client certificate
402 </p><pre class="programlisting">
403 openssl x509 -in myclient.crt -noout -subject -nameopt RFC2253 | sed "s/^subject=//"
405 Care needs to be taken when using this option, especially when using
406 regular expression matching against the <code class="literal">DN</code>.
407 </p></dd><dt><span class="term"><code class="literal">include</code></span></dt><dd><p>
408 This line will be replaced by the contents of the given file.
409 </p></dd><dt><span class="term"><code class="literal">include_if_exists</code></span></dt><dd><p>
410 This line will be replaced by the content of the given file if the
411 file exists. Otherwise, a message is logged to indicate that the file
413 </p></dd><dt><span class="term"><code class="literal">include_dir</code></span></dt><dd><p>
414 This line will be replaced by the contents of all the files found in
415 the directory, if they don't start with a <code class="literal">.</code> and end
416 with <code class="literal">.conf</code>, processed in file name order (according
417 to C locale rules, i.e., numbers before letters, and uppercase letters
418 before lowercase ones).
419 </p></dd></dl></div><p>
421 Files included by <code class="literal">@</code> constructs are read as lists of names,
422 which can be separated by either whitespace or commas. Comments are
423 introduced by <code class="literal">#</code>, just as in
424 <code class="filename">pg_hba.conf</code>, and nested <code class="literal">@</code> constructs are
425 allowed. Unless the file name following <code class="literal">@</code> is an absolute
426 path, it is taken to be relative to the directory containing the
429 Since the <code class="filename">pg_hba.conf</code> records are examined
430 sequentially for each connection attempt, the order of the records is
431 significant. Typically, earlier records will have tight connection
432 match parameters and weaker authentication methods, while later
433 records will have looser match parameters and stronger authentication
434 methods. For example, one might wish to use <code class="literal">trust</code>
435 authentication for local TCP/IP connections but require a password for
436 remote TCP/IP connections. In this case a record specifying
437 <code class="literal">trust</code> authentication for connections from 127.0.0.1 would
438 appear before a record specifying password authentication for a wider
439 range of allowed client IP addresses.
440 </p><div class="tip"><h3 class="title">Tip</h3><p>
441 To connect to a particular database, a user must not only pass the
442 <code class="filename">pg_hba.conf</code> checks, but must have the
443 <code class="literal">CONNECT</code> privilege for the database. If you wish to
444 restrict which users can connect to which databases, it's usually
445 easier to control this by granting/revoking <code class="literal">CONNECT</code> privilege
446 than to put the rules in <code class="filename">pg_hba.conf</code> entries.
448 Some examples of <code class="filename">pg_hba.conf</code> entries are shown in
449 <a class="xref" href="auth-pg-hba-conf.html#EXAMPLE-PG-HBA.CONF" title="Example 20.1. Example pg_hba.conf Entries">Example 20.1</a>. See the next section for details on the
450 different authentication methods.
451 </p><div class="example" id="EXAMPLE-PG-HBA.CONF"><p class="title"><strong>Example 20.1. Example <code class="filename">pg_hba.conf</code> Entries</strong></p><div class="example-contents"><pre class="programlisting">
452 # Allow any user on the local system to connect to any database with
453 # any database user name using Unix-domain sockets (the default for local
456 # TYPE DATABASE USER ADDRESS METHOD
459 # The same using local loopback TCP/IP connections.
461 # TYPE DATABASE USER ADDRESS METHOD
462 host all all 127.0.0.1/32 trust
464 # The same as the previous line, but using a separate netmask column
466 # TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
467 host all all 127.0.0.1 255.255.255.255 trust
469 # The same over IPv6.
471 # TYPE DATABASE USER ADDRESS METHOD
472 host all all ::1/128 trust
474 # The same using a host name (would typically cover both IPv4 and IPv6).
476 # TYPE DATABASE USER ADDRESS METHOD
477 host all all localhost trust
479 # The same using a regular expression for DATABASE, that allows connection
480 # to any databases with a name beginning with "db" and finishing with a
481 # number using two to four digits (like "db1234" or "db12").
483 # TYPE DATABASE USER ADDRESS METHOD
484 host "/^db\d{2,4}$" all localhost trust
486 # Allow any user from any host with IP address 192.168.93.x to connect
487 # to database "postgres" as the same user name that ident reports for
488 # the connection (typically the operating system user name).
490 # TYPE DATABASE USER ADDRESS METHOD
491 host postgres all 192.168.93.0/24 ident
493 # Allow any user from host 192.168.12.10 to connect to database
494 # "postgres" if the user's password is correctly supplied.
496 # TYPE DATABASE USER ADDRESS METHOD
497 host postgres all 192.168.12.10/32 scram-sha-256
499 # Allow any user from hosts in the example.com domain to connect to
500 # any database if the user's password is correctly supplied.
502 # Require SCRAM authentication for most users, but make an exception
503 # for user 'mike', who uses an older client that doesn't support SCRAM
506 # TYPE DATABASE USER ADDRESS METHOD
507 host all mike .example.com md5
508 host all all .example.com scram-sha-256
510 # In the absence of preceding "host" lines, these three lines will
511 # reject all connections from 192.168.54.1 (since that entry will be
512 # matched first), but allow GSSAPI-encrypted connections from anywhere else
513 # on the Internet. The zero mask causes no bits of the host IP address to
514 # be considered, so it matches any host. Unencrypted GSSAPI connections
515 # (which "fall through" to the third line since "hostgssenc" only matches
516 # encrypted GSSAPI connections) are allowed, but only from 192.168.12.10.
518 # TYPE DATABASE USER ADDRESS METHOD
519 host all all 192.168.54.1/32 reject
520 hostgssenc all all 0.0.0.0/0 gss
521 host all all 192.168.12.10/32 gss
523 # Allow users from 192.168.x.x hosts to connect to any database, if
524 # they pass the ident check. If, for example, ident says the user is
525 # "bryanh" and he requests to connect as PostgreSQL user "guest1", the
526 # connection is allowed if there is an entry in pg_ident.conf for map
527 # "omicron" that says "bryanh" is allowed to connect as "guest1".
529 # TYPE DATABASE USER ADDRESS METHOD
530 host all all 192.168.0.0/16 ident map=omicron
532 # If these are the only four lines for local connections, they will
533 # allow local users to connect only to their own databases (databases
534 # with the same name as their database user name) except for users whose
535 # name end with "helpdesk", administrators and members of role "support",
536 # who can connect to all databases. The file $PGDATA/admins contains a
537 # list of names of administrators. Passwords are required in all cases.
539 # TYPE DATABASE USER ADDRESS METHOD
540 local sameuser all md5
541 local all /^.*helpdesk$ md5
542 local all @admins md5
543 local all +support md5
545 # The last two lines above can be combined into a single line:
546 local all @admins,+support md5
548 # The database column can also use lists and file names:
549 local db1,db2,@demodbs all md5
550 </pre></div></div><br class="example-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="client-authentication.html" title="Chapter 20. Client Authentication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="client-authentication.html" title="Chapter 20. Client Authentication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="auth-username-maps.html" title="20.2. User Name Maps">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 20. Client Authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 20.2. User Name Maps</td></tr></table></div></body></html>
begriffs.com / projects / ai-pg / blob