1<!-- doc/src/sgml/client-auth.sgml --> 2 3<chapter id="client-authentication"> 4 <title>Client Authentication</title> 5 6 <indexterm zone="client-authentication"> 7 <primary>client authentication</primary> 8 </indexterm> 9 10 <para> 11 When a client application connects to the database server, it 12 specifies which <productname>PostgreSQL</productname> database user name it 13 wants to connect as, much the same way one logs into a Unix computer 14 as a particular user. Within the SQL environment the active database 15 user name determines access privileges to database objects — see 16 <xref linkend="user-manag"/> for more information. Therefore, it is 17 essential to restrict which database users can connect. 18 </para> 19 20 <note> 21 <para> 22 As explained in <xref linkend="user-manag"/>, 23 <productname>PostgreSQL</productname> actually does privilege 24 management in terms of <quote>roles</quote>. In this chapter, we 25 consistently use <firstterm>database user</firstterm> to mean <quote>role with the 26 <literal>LOGIN</literal> privilege</quote>. 27 </para> 28 </note> 29 30 <para> 31 <firstterm>Authentication</firstterm> is the process by which the 32 database server establishes the identity of the client, and by 33 extension determines whether the client application (or the user 34 who runs the client application) is permitted to connect with the 35 database user name that was requested. 36 </para> 37 38 <para> 39 <productname>PostgreSQL</productname> offers a number of different 40 client authentication methods. The method used to authenticate a 41 particular client connection can be selected on the basis of 42 (client) host address, database, and user. 43 </para> 44 45 <para> 46 <productname>PostgreSQL</productname> database user names are logically 47 separate from user names of the operating system in which the server 48 runs. If all the users of a particular server also have accounts on 49 the server's machine, it makes sense to assign database user names 50 that match their operating system user names. However, a server that 51 accepts remote connections might have many database users who have no local 52 operating system 53 account, and in such cases there need be no connection between 54 database user names and OS user names. 55 </para> 56 57 <sect1 id="auth-pg-hba-conf"> 58 <title>The <filename>pg_hba.conf</filename> File</title> 59 60 <indexterm zone="auth-pg-hba-conf"> 61 <primary>pg_hba.conf</primary> 62 </indexterm> 63 64 <para> 65 Client authentication is controlled by a configuration file, 66 which traditionally is named 67 <filename>pg_hba.conf</filename> and is stored in the database 68 cluster's data directory. 69 (<acronym>HBA</acronym> stands for host-based authentication.) A default 70 <filename>pg_hba.conf</filename> file is installed when the data 71 directory is initialized by <command>initdb</command>. It is 72 possible to place the authentication configuration file elsewhere, 73 however; see the <xref linkend="guc-hba-file"/> configuration parameter. 74 </para> 75 76 <para> 77 The general format of the <filename>pg_hba.conf</filename> file is 78 a set of records, one per line. Blank lines are ignored, as is any 79 text after the <literal>#</literal> comment character. 80 Records cannot be continued across lines. 81 A record is made 82 up of a number of fields which are separated by spaces and/or tabs. 83 Fields can contain white space if the field value is double-quoted. 84 Quoting one of the keywords in a database, user, or address field (e.g., 85 <literal>all</literal> or <literal>replication</literal>) makes the word lose its special 86 meaning, and just match a database, user, or host with that name. 87 </para> 88 89 <para> 90 Each record specifies a connection type, a client IP address range 91 (if relevant for the connection type), a database name, a user name, 92 and the authentication method to be used for connections matching 93 these parameters. The first record with a matching connection type, 94 client address, requested database, and user name is used to perform 95 authentication. There is no <quote>fall-through</quote> or 96 <quote>backup</quote>: if one record is chosen and the authentication 97 fails, subsequent records are not considered. If no record matches, 98 access is denied. 99 </para> 100 101 <para> 102 A record can have several formats: 103<synopsis> 104local <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>auth-method</replaceable> <optional><replaceable>auth-options</replaceable></optional> 105host <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>address</replaceable> <replaceable>auth-method</replaceable> <optional><replaceable>auth-options</replaceable></optional> 106hostssl <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>address</replaceable> <replaceable>auth-method</replaceable> <optional><replaceable>auth-options</replaceable></optional> 107hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>address</replaceable> <replaceable>auth-method</replaceable> <optional><replaceable>auth-options</replaceable></optional> 108hostgssenc <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>address</replaceable> <replaceable>auth-method</replaceable> <optional><replaceable>auth-options</replaceable></optional> 109hostnogssenc <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>address</replaceable> <replaceable>auth-method</replaceable> <optional><replaceable>auth-options</replaceable></optional> 110host <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>auth-method</replaceable> <optional><replaceable>auth-options</replaceable></optional> 111hostssl <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>auth-method</replaceable> <optional><replaceable>auth-options</replaceable></optional> 112hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>auth-method</replaceable> <optional><replaceable>auth-options</replaceable></optional> 113hostgssenc <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>auth-method</replaceable> <optional><replaceable>auth-options</replaceable></optional> 114hostnogssenc <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>auth-method</replaceable> <optional><replaceable>auth-options</replaceable></optional> 115</synopsis> 116 The meaning of the fields is as follows: 117 118 <variablelist> 119 <varlistentry> 120 <term><literal>local</literal></term> 121 <listitem> 122 <para> 123 This record matches connection attempts using Unix-domain 124 sockets. Without a record of this type, Unix-domain socket 125 connections are disallowed. 126 </para> 127 </listitem> 128 </varlistentry> 129 130 <varlistentry> 131 <term><literal>host</literal></term> 132 <listitem> 133 <para> 134 This record matches connection attempts made using TCP/IP. 135 <literal>host</literal> records match 136 <acronym>SSL</acronym> or non-<acronym>SSL</acronym> connection 137 attempts as well as <acronym>GSSAPI</acronym> encrypted or 138 non-<acronym>GSSAPI</acronym> encrypted connection attempts. 139 </para> 140 <note> 141 <para> 142 Remote TCP/IP connections will not be possible unless 143 the server is started with an appropriate value for the 144 <xref linkend="guc-listen-addresses"/> configuration parameter, 145 since the default behavior is to listen for TCP/IP connections 146 only on the local loopback address <literal>localhost</literal>. 147 </para> 148 </note> 149 </listitem> 150 </varlistentry> 151 152 <varlistentry> 153 <term><literal>hostssl</literal></term> 154 <listitem> 155 <para> 156 This record matches connection attempts made using TCP/IP, 157 but only when the connection is made with <acronym>SSL</acronym> 158 encryption. 159 </para> 160 161 <para> 162 To make use of this option the server must be built with 163 <acronym>SSL</acronym> support. Furthermore, 164 <acronym>SSL</acronym> must be enabled 165 by setting the <xref linkend="guc-ssl"/> configuration parameter (see 166 <xref linkend="ssl-tcp"/> for more information). 167 Otherwise, the <literal>hostssl</literal> record is ignored except for 168 logging a warning that it cannot match any connections. 169 </para> 170 </listitem> 171 </varlistentry> 172 173 <varlistentry> 174 <term><literal>hostnossl</literal></term> 175 <listitem> 176 <para> 177 This record type has the opposite behavior of <literal>hostssl</literal>; 178 it only matches connection attempts made over 179 TCP/IP that do not use <acronym>SSL</acronym>. 180 </para> 181 </listitem> 182 </varlistentry> 183 184 <varlistentry> 185 <term><literal>hostgssenc</literal></term> 186 <listitem> 187 <para> 188 This record matches connection attempts made using TCP/IP, 189 but only when the connection is made with <acronym>GSSAPI</acronym> 190 encryption. 191 </para> 192 193 <para> 194 To make use of this option the server must be built with 195 <acronym>GSSAPI</acronym> support. Otherwise, 196 the <literal>hostgssenc</literal> record is ignored except for logging 197 a warning that it cannot match any connections. 198 </para> 199 </listitem> 200 </varlistentry> 201 202 <varlistentry> 203 <term><literal>hostnogssenc</literal></term> 204 <listitem> 205 <para> 206 This record type has the opposite behavior of <literal>hostgssenc</literal>; 207 it only matches connection attempts made over 208 TCP/IP that do not use <acronym>GSSAPI</acronym> encryption. 209 </para> 210 </listitem> 211 </varlistentry> 212 213 <varlistentry> 214 <term><replaceable>database</replaceable></term> 215 <listitem> 216 <para> 217 Specifies which database name(s) this record matches. The value 218 <literal>all</literal> specifies that it matches all databases. 219 The value <literal>sameuser</literal> specifies that the record 220 matches if the requested database has the same name as the 221 requested user. The value <literal>samerole</literal> specifies that 222 the requested user must be a member of the role with the same 223 name as the requested database. (<literal>samegroup</literal> is an 224 obsolete but still accepted spelling of <literal>samerole</literal>.) 225 Superusers are not considered to be members of a role for the 226 purposes of <literal>samerole</literal> unless they are explicitly 227 members of the role, directly or indirectly, and not just by 228 virtue of being a superuser. 229 The value <literal>replication</literal> specifies that the record 230 matches if a physical replication connection is requested (note that 231 replication connections do not specify any particular database). 232 Otherwise, this is the name of 233 a specific <productname>PostgreSQL</productname> database. 234 Multiple database names can be supplied by separating them with 235 commas. A separate file containing database names can be specified by 236 preceding the file name with <literal>@</literal>. 237 </para> 238 </listitem> 239 </varlistentry> 240 241 <varlistentry> 242 <term><replaceable>user</replaceable></term> 243 <listitem> 244 <para> 245 Specifies which database user name(s) this record 246 matches. The value <literal>all</literal> specifies that it 247 matches all users. Otherwise, this is either the name of a specific 248 database user, or a group name preceded by <literal>+</literal>. 249 (Recall that there is no real distinction between users and groups 250 in <productname>PostgreSQL</productname>; a <literal>+</literal> mark really means 251 <quote>match any of the roles that are directly or indirectly members 252 of this role</quote>, while a name without a <literal>+</literal> mark matches 253 only that specific role.) For this purpose, a superuser is only 254 considered to be a member of a role if they are explicitly a member 255 of the role, directly or indirectly, and not just by virtue of 256 being a superuser. 257 Multiple user names can be supplied by separating them with commas. 258 A separate file containing user names can be specified by preceding the 259 file name with <literal>@</literal>. 260 </para> 261 </listitem> 262 </varlistentry> 263 264 <varlistentry> 265 <term><replaceable>address</replaceable></term> 266 <listitem> 267 <para> 268 Specifies the client machine address(es) that this record 269 matches. This field can contain either a host name, an IP 270 address range, or one of the special key words mentioned below. 271 </para> 272 273 <para> 274 An IP address range is specified using standard numeric notation 275 for the range's starting address, then a slash (<literal>/</literal>) 276 and a <acronym>CIDR</acronym> mask length. The mask 277 length indicates the number of high-order bits of the client 278 IP address that must match. Bits to the right of this should 279 be zero in the given IP address. 280 There must not be any white space between the IP address, the 281 <literal>/</literal>, and the CIDR mask length. 282 </para> 283 284 <para> 285 Typical examples of an IPv4 address range specified this way are 286 <literal>172.20.143.89/32</literal> for a single host, or 287 <literal>172.20.143.0/24</literal> for a small network, or 288 <literal>10.6.0.0/16</literal> for a larger one. 289 An IPv6 address range might look like <literal>::1/128</literal> 290 for a single host (in this case the IPv6 loopback address) or 291 <literal>fe80::7a31:c1ff:0000:0000/96</literal> for a small 292 network. 293 <literal>0.0.0.0/0</literal> represents all 294 IPv4 addresses, and <literal>::0/0</literal> represents 295 all IPv6 addresses. 296 To specify a single host, use a mask length of 32 for IPv4 or 297 128 for IPv6. In a network address, do not omit trailing zeroes. 298 </para> 299 300 <para> 301 An entry given in IPv4 format will match only IPv4 connections, 302 and an entry given in IPv6 format will match only IPv6 connections, 303 even if the represented address is in the IPv4-in-IPv6 range. 304 Note that entries in IPv6 format will be rejected if the system's 305 C library does not have support for IPv6 addresses. 306 </para> 307 308 <para> 309 You can also write <literal>all</literal> to match any IP address, 310 <literal>samehost</literal> to match any of the server's own IP 311 addresses, or <literal>samenet</literal> to match any address in any 312 subnet that the server is directly connected to. 313 </para> 314 315 <para> 316 If a host name is specified (anything that is not an IP address 317 range or a special key word is treated as a host name), 318 that name is compared with the result of a reverse name 319 resolution of the client's IP address (e.g., reverse DNS 320 lookup, if DNS is used). Host name comparisons are case 321 insensitive. If there is a match, then a forward name 322 resolution (e.g., forward DNS lookup) is performed on the host 323 name to check whether any of the addresses it resolves to are 324 equal to the client's IP address. If both directions match, 325 then the entry is considered to match. (The host name that is 326 used in <filename>pg_hba.conf</filename> should be the one that 327 address-to-name resolution of the client's IP address returns, 328 otherwise the line won't be matched. Some host name databases 329 allow associating an IP address with multiple host names, but 330 the operating system will only return one host name when asked 331 to resolve an IP address.) 332 </para> 333 334 <para> 335 A host name specification that starts with a dot 336 (<literal>.</literal>) matches a suffix of the actual host 337 name. So <literal>.example.com</literal> would match 338 <literal>foo.example.com</literal> (but not just 339 <literal>example.com</literal>). 340 </para> 341 342 <para> 343 When host names are specified 344 in <filename>pg_hba.conf</filename>, you should make sure that 345 name resolution is reasonably fast. It can be of advantage to 346 set up a local name resolution cache such 347 as <command>nscd</command>. Also, you may wish to enable the 348 configuration parameter <varname>log_hostname</varname> to see 349 the client's host name instead of the IP address in the log. 350 </para> 351 352 <para> 353 These fields do not apply to <literal>local</literal> records. 354 </para> 355 356 <note> 357 <para> 358 Users sometimes wonder why host names are handled 359 in this seemingly complicated way, with two name resolutions 360 including a reverse lookup of the client's IP address. This 361 complicates use of the feature in case the client's reverse DNS 362 entry is not set up or yields some undesirable host name. 363 It is done primarily for efficiency: this way, a connection attempt 364 requires at most two resolver lookups, one reverse and one forward. 365 If there is a resolver problem with some address, it becomes only 366 that client's problem. A hypothetical alternative 367 implementation that only did forward lookups would have to 368 resolve every host name mentioned in 369 <filename>pg_hba.conf</filename> during every connection attempt. 370 That could be quite slow if many names are listed. 371 And if there is a resolver problem with one of the host names, 372 it becomes everyone's problem. 373 </para> 374 375 <para> 376 Also, a reverse lookup is necessary to implement the suffix 377 matching feature, because the actual client host name needs to 378 be known in order to match it against the pattern. 379 </para> 380 381 <para> 382 Note that this behavior is consistent with other popular 383 implementations of host name-based access control, such as the 384 Apache HTTP Server and TCP Wrappers. 385 </para> 386 </note> 387 </listitem> 388 </varlistentry> 389 390 <varlistentry> 391 <term><replaceable>IP-address</replaceable></term> 392 <term><replaceable>IP-mask</replaceable></term> 393 <listitem> 394 <para> 395 These two fields can be used as an alternative to the 396 <replaceable>IP-address</replaceable><literal>/</literal><replaceable>mask-length</replaceable> 397 notation. Instead of 398 specifying the mask length, the actual mask is specified in a 399 separate column. For example, <literal>255.0.0.0</literal> represents an IPv4 400 CIDR mask length of 8, and <literal>255.255.255.255</literal> represents a 401 CIDR mask length of 32. 402 </para> 403 404 <para> 405 These fields do not apply to <literal>local</literal> records. 406 </para> 407 </listitem> 408 </varlistentry> 409 410 <varlistentry> 411 <term><replaceable>auth-method</replaceable></term> 412 <listitem> 413 <para> 414 Specifies the authentication method to use when a connection matches 415 this record. The possible choices are summarized here; details 416 are in <xref linkend="auth-methods"/>. 417 418 <variablelist> 419 <varlistentry> 420 <term><literal>trust</literal></term> 421 <listitem> 422 <para> 423 Allow the connection unconditionally. This method 424 allows anyone that can connect to the 425 <productname>PostgreSQL</productname> database server to login as 426 any <productname>PostgreSQL</productname> user they wish, 427 without the need for a password or any other authentication. See <xref 428 linkend="auth-trust"/> for details. 429 </para> 430 </listitem> 431 </varlistentry> 432 433 <varlistentry> 434 <term><literal>reject</literal></term> 435 <listitem> 436 <para> 437 Reject the connection unconditionally. This is useful for 438 <quote>filtering out</quote> certain hosts from a group, for example a 439 <literal>reject</literal> line could block a specific host from connecting, 440 while a later line allows the remaining hosts in a specific 441 network to connect. 442 </para> 443 </listitem> 444 </varlistentry> 445 446 <varlistentry> 447 <term><literal>scram-sha-256</literal></term> 448 <listitem> 449 <para> 450 Perform SCRAM-SHA-256 authentication to verify the user's 451 password. See <xref linkend="auth-password"/> for details. 452 </para> 453 </listitem> 454 </varlistentry> 455 456 <varlistentry> 457 <term><literal>md5</literal></term> 458 <listitem> 459 <para> 460 Perform SCRAM-SHA-256 or MD5 authentication to verify the 461 user's password. See <xref linkend="auth-password"/> 462 for details. 463 </para> 464 </listitem> 465 </varlistentry> 466 467 <varlistentry> 468 <term><literal>password</literal></term> 469 <listitem> 470 <para> 471 Require the client to supply an unencrypted password for 472 authentication. 473 Since the password is sent in clear text over the 474 network, this should not be used on untrusted networks. 475 See <xref linkend="auth-password"/> for details. 476 </para> 477 </listitem> 478 </varlistentry> 479 480 <varlistentry> 481 <term><literal>gss</literal></term> 482 <listitem> 483 <para> 484 Use GSSAPI to authenticate the user. This is only 485 available for TCP/IP connections. See <xref 486 linkend="gssapi-auth"/> for details. It can be used in conjunction 487 with GSSAPI encryption. 488 </para> 489 </listitem> 490 </varlistentry> 491 492 <varlistentry> 493 <term><literal>sspi</literal></term> 494 <listitem> 495 <para> 496 Use SSPI to authenticate the user. This is only 497 available on Windows. See <xref 498 linkend="sspi-auth"/> for details. 499 </para> 500 </listitem> 501 </varlistentry> 502 503 <varlistentry> 504 <term><literal>ident</literal></term> 505 <listitem> 506 <para> 507 Obtain the operating system user name of the client 508 by contacting the ident server on the client 509 and check if it matches the requested database user name. 510 Ident authentication can only be used on TCP/IP 511 connections. When specified for local connections, peer 512 authentication will be used instead. 513 See <xref linkend="auth-ident"/> for details. 514 </para> 515 </listitem> 516 </varlistentry> 517 518 <varlistentry> 519 <term><literal>peer</literal></term> 520 <listitem> 521 <para> 522 Obtain the client's operating system user name from the operating 523 system and check if it matches the requested database user name. 524 This is only available for local connections. 525 See <xref linkend="auth-peer"/> for details. 526 </para> 527 </listitem> 528 </varlistentry> 529 530 <varlistentry> 531 <term><literal>ldap</literal></term> 532 <listitem> 533 <para> 534 Authenticate using an <acronym>LDAP</acronym> server. See <xref 535 linkend="auth-ldap"/> for details. 536 </para> 537 </listitem> 538 </varlistentry> 539 540 <varlistentry> 541 <term><literal>radius</literal></term> 542 <listitem> 543 <para> 544 Authenticate using a RADIUS server. See <xref 545 linkend="auth-radius"/> for details. 546 </para> 547 </listitem> 548 </varlistentry> 549 550 <varlistentry> 551 <term><literal>cert</literal></term> 552 <listitem> 553 <para> 554 Authenticate using SSL client certificates. See 555 <xref linkend="auth-cert"/> for details. 556 </para> 557 </listitem> 558 </varlistentry> 559 560 <varlistentry> 561 <term><literal>pam</literal></term> 562 <listitem> 563 <para> 564 Authenticate using the Pluggable Authentication Modules 565 (PAM) service provided by the operating system. See <xref 566 linkend="auth-pam"/> for details. 567 </para> 568 </listitem> 569 </varlistentry> 570 571 <varlistentry> 572 <term><literal>bsd</literal></term> 573 <listitem> 574 <para> 575 Authenticate using the BSD Authentication service provided by the 576 operating system. See <xref linkend="auth-bsd"/> for details. 577 </para> 578 </listitem> 579 </varlistentry> 580 </variablelist> 581 582 </para> 583 </listitem> 584 </varlistentry> 585 586 <varlistentry> 587 <term><replaceable>auth-options</replaceable></term> 588 <listitem> 589 <para> 590 After the <replaceable>auth-method</replaceable> field, there can be field(s) of 591 the form <replaceable>name</replaceable><literal>=</literal><replaceable>value</replaceable> that 592 specify options for the authentication method. Details about which 593 options are available for which authentication methods appear below. 594 </para> 595 596 <para> 597 In addition to the method-specific options listed below, there is one 598 method-independent authentication option <literal>clientcert</literal>, which 599 can be specified in any <literal>hostssl</literal> record. 600 This option can be set to <literal>verify-ca</literal> or 601 <literal>verify-full</literal>. Both options require the client 602 to present a valid (trusted) SSL certificate, while 603 <literal>verify-full</literal> additionally enforces that the 604 <literal>cn</literal> (Common Name) in the certificate matches 605 the username or an applicable mapping. 606 This behavior is similar to the <literal>cert</literal> authentication 607 method (see <xref linkend="auth-cert"/>) but enables pairing 608 the verification of client certificates with any authentication 609 method that supports <literal>hostssl</literal> entries. 610 </para> 611 </listitem> 612 </varlistentry> 613 </variablelist> 614 </para> 615 616 <para> 617 Files included by <literal>@</literal> constructs are read as lists of names, 618 which can be separated by either whitespace or commas. Comments are 619 introduced by <literal>#</literal>, just as in 620 <filename>pg_hba.conf</filename>, and nested <literal>@</literal> constructs are 621 allowed. Unless the file name following <literal>@</literal> is an absolute 622 path, it is taken to be relative to the directory containing the 623 referencing file. 624 </para> 625 626 <para> 627 Since the <filename>pg_hba.conf</filename> records are examined 628 sequentially for each connection attempt, the order of the records is 629 significant. Typically, earlier records will have tight connection 630 match parameters and weaker authentication methods, while later 631 records will have looser match parameters and stronger authentication 632 methods. For example, one might wish to use <literal>trust</literal> 633 authentication for local TCP/IP connections but require a password for 634 remote TCP/IP connections. In this case a record specifying 635 <literal>trust</literal> authentication for connections from 127.0.0.1 would 636 appear before a record specifying password authentication for a wider 637 range of allowed client IP addresses. 638 </para> 639 640 <para> 641 The <filename>pg_hba.conf</filename> file is read on start-up and when 642 the main server process receives a 643 <systemitem>SIGHUP</systemitem><indexterm><primary>SIGHUP</primary></indexterm> 644 signal. If you edit the file on an 645 active system, you will need to signal the postmaster 646 (using <literal>pg_ctl reload</literal>, calling the SQL function 647 <function>pg_reload_conf()</function>, or using <literal>kill 648 -HUP</literal>) to make it re-read the file. 649 </para> 650 651 <note> 652 <para> 653 The preceding statement is not true on Microsoft Windows: there, any 654 changes in the <filename>pg_hba.conf</filename> file are immediately 655 applied by subsequent new connections. 656 </para> 657 </note> 658 659 <para> 660 The system view 661 <link linkend="view-pg-hba-file-rules"><structname>pg_hba_file_rules</structname></link> 662 can be helpful for pre-testing changes to the <filename>pg_hba.conf</filename> 663 file, or for diagnosing problems if loading of the file did not have the 664 desired effects. Rows in the view with 665 non-null <structfield>error</structfield> fields indicate problems in the 666 corresponding lines of the file. 667 </para> 668 669 <tip> 670 <para> 671 To connect to a particular database, a user must not only pass the 672 <filename>pg_hba.conf</filename> checks, but must have the 673 <literal>CONNECT</literal> privilege for the database. If you wish to 674 restrict which users can connect to which databases, it's usually 675 easier to control this by granting/revoking <literal>CONNECT</literal> privilege 676 than to put the rules in <filename>pg_hba.conf</filename> entries. 677 </para> 678 </tip> 679 680 <para> 681 Some examples of <filename>pg_hba.conf</filename> entries are shown in 682 <xref linkend="example-pg-hba.conf"/>. See the next section for details on the 683 different authentication methods. 684 </para> 685 686 <example id="example-pg-hba.conf"> 687 <title>Example <filename>pg_hba.conf</filename> Entries</title> 688<programlisting> 689# Allow any user on the local system to connect to any database with 690# any database user name using Unix-domain sockets (the default for local 691# connections). 692# 693# TYPE DATABASE USER ADDRESS METHOD 694local all all trust 695 696# The same using local loopback TCP/IP connections. 697# 698# TYPE DATABASE USER ADDRESS METHOD 699host all all 127.0.0.1/32 trust 700 701# The same as the previous line, but using a separate netmask column 702# 703# TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD 704host all all 127.0.0.1 255.255.255.255 trust 705 706# The same over IPv6. 707# 708# TYPE DATABASE USER ADDRESS METHOD 709host all all ::1/128 trust 710 711# The same using a host name (would typically cover both IPv4 and IPv6). 712# 713# TYPE DATABASE USER ADDRESS METHOD 714host all all localhost trust 715 716# Allow any user from any host with IP address 192.168.93.x to connect 717# to database "postgres" as the same user name that ident reports for 718# the connection (typically the operating system user name). 719# 720# TYPE DATABASE USER ADDRESS METHOD 721host postgres all 192.168.93.0/24 ident 722 723# Allow any user from host 192.168.12.10 to connect to database 724# "postgres" if the user's password is correctly supplied. 725# 726# TYPE DATABASE USER ADDRESS METHOD 727host postgres all 192.168.12.10/32 scram-sha-256 728 729# Allow any user from hosts in the example.com domain to connect to 730# any database if the user's password is correctly supplied. 731# 732# Require SCRAM authentication for most users, but make an exception 733# for user 'mike', who uses an older client that doesn't support SCRAM 734# authentication. 735# 736# TYPE DATABASE USER ADDRESS METHOD 737host all mike .example.com md5 738host all all .example.com scram-sha-256 739 740# In the absence of preceding "host" lines, these three lines will 741# reject all connections from 192.168.54.1 (since that entry will be 742# matched first), but allow GSSAPI-encrypted connections from anywhere else 743# on the Internet. The zero mask causes no bits of the host IP address to 744# be considered, so it matches any host. Unencrypted GSSAPI connections 745# (which "fall through" to the third line since "hostgssenc" only matches 746# encrypted GSSAPI connections) are allowed, but only from 192.168.12.10. 747# 748# TYPE DATABASE USER ADDRESS METHOD 749host all all 192.168.54.1/32 reject 750hostgssenc all all 0.0.0.0/0 gss 751host all all 192.168.12.10/32 gss 752 753# Allow users from 192.168.x.x hosts to connect to any database, if 754# they pass the ident check. If, for example, ident says the user is 755# "bryanh" and he requests to connect as PostgreSQL user "guest1", the 756# connection is allowed if there is an entry in pg_ident.conf for map 757# "omicron" that says "bryanh" is allowed to connect as "guest1". 758# 759# TYPE DATABASE USER ADDRESS METHOD 760host all all 192.168.0.0/16 ident map=omicron 761 762# If these are the only three lines for local connections, they will 763# allow local users to connect only to their own databases (databases 764# with the same name as their database user name) except for administrators 765# and members of role "support", who can connect to all databases. The file 766# $PGDATA/admins contains a list of names of administrators. Passwords 767# are required in all cases. 768# 769# TYPE DATABASE USER ADDRESS METHOD 770local sameuser all md5 771local all @admins md5 772local all +support md5 773 774# The last two lines above can be combined into a single line: 775local all @admins,+support md5 776 777# The database column can also use lists and file names: 778local db1,db2,@demodbs all md5 779</programlisting> 780 </example> 781 </sect1> 782 783 <sect1 id="auth-username-maps"> 784 <title>User Name Maps</title> 785 786 <indexterm zone="auth-username-maps"> 787 <primary>User name maps</primary> 788 </indexterm> 789 790 <para> 791 When using an external authentication system such as Ident or GSSAPI, 792 the name of the operating system user that initiated the connection 793 might not be the same as the database user (role) that is to be used. 794 In this case, a user name map can be applied to map the operating system 795 user name to a database user. To use user name mapping, specify 796 <literal>map</literal>=<replaceable>map-name</replaceable> 797 in the options field in <filename>pg_hba.conf</filename>. This option is 798 supported for all authentication methods that receive external user names. 799 Since different mappings might be needed for different connections, 800 the name of the map to be used is specified in the 801 <replaceable>map-name</replaceable> parameter in <filename>pg_hba.conf</filename> 802 to indicate which map to use for each individual connection. 803 </para> 804 805 <para> 806 User name maps are defined in the ident map file, which by default is named 807 <filename>pg_ident.conf</filename><indexterm><primary>pg_ident.conf</primary></indexterm> 808 and is stored in the 809 cluster's data directory. (It is possible to place the map file 810 elsewhere, however; see the <xref linkend="guc-ident-file"/> 811 configuration parameter.) 812 The ident map file contains lines of the general form: 813<synopsis> 814<replaceable>map-name</replaceable> <replaceable>system-username</replaceable> <replaceable>database-username</replaceable> 815</synopsis> 816 Comments and whitespace are handled in the same way as in 817 <filename>pg_hba.conf</filename>. The 818 <replaceable>map-name</replaceable> is an arbitrary name that will be used to 819 refer to this mapping in <filename>pg_hba.conf</filename>. The other 820 two fields specify an operating system user name and a matching 821 database user name. The same <replaceable>map-name</replaceable> can be 822 used repeatedly to specify multiple user-mappings within a single map. 823 </para> 824 <para> 825 There is no restriction regarding how many database users a given 826 operating system user can correspond to, nor vice versa. Thus, entries 827 in a map should be thought of as meaning <quote>this operating system 828 user is allowed to connect as this database user</quote>, rather than 829 implying that they are equivalent. The connection will be allowed if 830 there is any map entry that pairs the user name obtained from the 831 external authentication system with the database user name that the 832 user has requested to connect as. 833 </para> 834 <para> 835 If the <replaceable>system-username</replaceable> field starts with a slash (<literal>/</literal>), 836 the remainder of the field is treated as a regular expression. 837 (See <xref linkend="posix-syntax-details"/> for details of 838 <productname>PostgreSQL</productname>'s regular expression syntax.) The regular 839 expression can include a single capture, or parenthesized subexpression, 840 which can then be referenced in the <replaceable>database-username</replaceable> 841 field as <literal>\1</literal> (backslash-one). This allows the mapping of 842 multiple user names in a single line, which is particularly useful for 843 simple syntax substitutions. For example, these entries 844<programlisting> 845mymap /^(.*)@mydomain\.com$ \1 846mymap /^(.*)@otherdomain\.com$ guest 847</programlisting> 848 will remove the domain part for users with system user names that end with 849 <literal>@mydomain.com</literal>, and allow any user whose system name ends with 850 <literal>@otherdomain.com</literal> to log in as <literal>guest</literal>. 851 </para> 852 853 <tip> 854 <para> 855 Keep in mind that by default, a regular expression can match just part of 856 a string. It's usually wise to use <literal>^</literal> and <literal>$</literal>, as 857 shown in the above example, to force the match to be to the entire 858 system user name. 859 </para> 860 </tip> 861 862 <para> 863 The <filename>pg_ident.conf</filename> file is read on start-up and 864 when the main server process receives a 865 <systemitem>SIGHUP</systemitem><indexterm><primary>SIGHUP</primary></indexterm> 866 signal. If you edit the file on an 867 active system, you will need to signal the postmaster 868 (using <literal>pg_ctl reload</literal>, calling the SQL function 869 <function>pg_reload_conf()</function>, or using <literal>kill 870 -HUP</literal>) to make it re-read the file. 871 </para> 872 873 <para> 874 A <filename>pg_ident.conf</filename> file that could be used in 875 conjunction with the <filename>pg_hba.conf</filename> file in <xref 876 linkend="example-pg-hba.conf"/> is shown in <xref 877 linkend="example-pg-ident.conf"/>. In this example, anyone 878 logged in to a machine on the 192.168 network that does not have the 879 operating system user name <literal>bryanh</literal>, <literal>ann</literal>, or 880 <literal>robert</literal> would not be granted access. Unix user 881 <literal>robert</literal> would only be allowed access when he tries to 882 connect as <productname>PostgreSQL</productname> user <literal>bob</literal>, not 883 as <literal>robert</literal> or anyone else. <literal>ann</literal> would 884 only be allowed to connect as <literal>ann</literal>. User 885 <literal>bryanh</literal> would be allowed to connect as either 886 <literal>bryanh</literal> or as <literal>guest1</literal>. 887 </para> 888 889 <example id="example-pg-ident.conf"> 890 <title>An Example <filename>pg_ident.conf</filename> File</title> 891<programlisting> 892# MAPNAME SYSTEM-USERNAME PG-USERNAME 893 894omicron bryanh bryanh 895omicron ann ann 896# bob has user name robert on these machines 897omicron robert bob 898# bryanh can also connect as guest1 899omicron bryanh guest1 900</programlisting> 901 </example> 902 </sect1> 903 904 <sect1 id="auth-methods"> 905 <title>Authentication Methods</title> 906 907 <para> 908 <productname>PostgreSQL</productname> provides various methods for 909 authenticating users: 910 911 <itemizedlist> 912 <listitem> 913 <para> 914 <link linkend="auth-trust">Trust authentication</link>, which 915 simply trusts that users are who they say they are. 916 </para> 917 </listitem> 918 <listitem> 919 <para> 920 <link linkend="auth-password">Password authentication</link>, which 921 requires that users send a password. 922 </para> 923 </listitem> 924 <listitem> 925 <para> 926 <link linkend="gssapi-auth">GSSAPI authentication</link>, which 927 relies on a GSSAPI-compatible security library. Typically this is 928 used to access an authentication server such as a Kerberos or 929 Microsoft Active Directory server. 930 </para> 931 </listitem> 932 <listitem> 933 <para> 934 <link linkend="sspi-auth">SSPI authentication</link>, which 935 uses a Windows-specific protocol similar to GSSAPI. 936 </para> 937 </listitem> 938 <listitem> 939 <para> 940 <link linkend="auth-ident">Ident authentication</link>, which 941 relies on an <quote>Identification Protocol</quote> (RFC 1413) 942 service on the client's machine. (On local Unix-socket connections, 943 this is treated as peer authentication.) 944 </para> 945 </listitem> 946 <listitem> 947 <para> 948 <link linkend="auth-peer">Peer authentication</link>, which 949 relies on operating system facilities to identify the process at the 950 other end of a local connection. This is not supported for remote 951 connections. 952 </para> 953 </listitem> 954 <listitem> 955 <para> 956 <link linkend="auth-ldap">LDAP authentication</link>, which 957 relies on an LDAP authentication server. 958 </para> 959 </listitem> 960 <listitem> 961 <para> 962 <link linkend="auth-radius">RADIUS authentication</link>, which 963 relies on a RADIUS authentication server. 964 </para> 965 </listitem> 966 <listitem> 967 <para> 968 <link linkend="auth-cert">Certificate authentication</link>, which 969 requires an SSL connection and authenticates users by checking the 970 SSL certificate they send. 971 </para> 972 </listitem> 973 <listitem> 974 <para> 975 <link linkend="auth-pam">PAM authentication</link>, which 976 relies on a PAM (Pluggable Authentication Modules) library. 977 </para> 978 </listitem> 979 <listitem> 980 <para> 981 <link linkend="auth-bsd">BSD authentication</link>, which 982 relies on the BSD Authentication framework (currently available 983 only on OpenBSD). 984 </para> 985 </listitem> 986 </itemizedlist> 987 </para> 988 989 <para> 990 Peer authentication is usually recommendable for local connections, 991 though trust authentication might be sufficient in some circumstances. 992 Password authentication is the easiest choice for remote connections. 993 All the other options require some kind of external security 994 infrastructure (usually an authentication server or a certificate 995 authority for issuing SSL certificates), or are platform-specific. 996 </para> 997 998 <para> 999 The following sections describe each of these authentication methods 1000 in more detail. 1001 </para> 1002 </sect1> 1003 1004 <sect1 id="auth-trust"> 1005 <title>Trust Authentication</title> 1006 1007 <para> 1008 When <literal>trust</literal> authentication is specified, 1009 <productname>PostgreSQL</productname> assumes that anyone who can 1010 connect to the server is authorized to access the database with 1011 whatever database user name they specify (even superuser names). 1012 Of course, restrictions made in the <literal>database</literal> and 1013 <literal>user</literal> columns still apply. 1014 This method should only be used when there is adequate 1015 operating-system-level protection on connections to the server. 1016 </para> 1017 1018 <para> 1019 <literal>trust</literal> authentication is appropriate and very 1020 convenient for local connections on a single-user workstation. It 1021 is usually <emphasis>not</emphasis> appropriate by itself on a multiuser 1022 machine. However, you might be able to use <literal>trust</literal> even 1023 on a multiuser machine, if you restrict access to the server's 1024 Unix-domain socket file using file-system permissions. To do this, set the 1025 <varname>unix_socket_permissions</varname> (and possibly 1026 <varname>unix_socket_group</varname>) configuration parameters as 1027 described in <xref linkend="runtime-config-connection"/>. Or you 1028 could set the <varname>unix_socket_directories</varname> 1029 configuration parameter to place the socket file in a suitably 1030 restricted directory. 1031 </para> 1032 1033 <para> 1034 Setting file-system permissions only helps for Unix-socket connections. 1035 Local TCP/IP connections are not restricted by file-system permissions. 1036 Therefore, if you want to use file-system permissions for local security, 1037 remove the <literal>host ... 127.0.0.1 ...</literal> line from 1038 <filename>pg_hba.conf</filename>, or change it to a 1039 non-<literal>trust</literal> authentication method. 1040 </para> 1041 1042 <para> 1043 <literal>trust</literal> authentication is only suitable for TCP/IP connections 1044 if you trust every user on every machine that is allowed to connect 1045 to the server by the <filename>pg_hba.conf</filename> lines that specify 1046 <literal>trust</literal>. It is seldom reasonable to use <literal>trust</literal> 1047 for any TCP/IP connections other than those from <systemitem>localhost</systemitem> (127.0.0.1). 1048 </para> 1049 1050 </sect1> 1051 1052 <sect1 id="auth-password"> 1053 <title>Password Authentication</title> 1054 1055 <indexterm> 1056 <primary>MD5</primary> 1057 </indexterm> 1058 <indexterm> 1059 <primary>SCRAM</primary> 1060 </indexterm> 1061 <indexterm> 1062 <primary>password</primary> 1063 <secondary>authentication</secondary> 1064 </indexterm> 1065 1066 <para> 1067 There are several password-based authentication methods. These methods 1068 operate similarly but differ in how the users' passwords are stored on the 1069 server and how the password provided by a client is sent across the 1070 connection. 1071 </para> 1072 1073 <variablelist> 1074 <varlistentry> 1075 <term><literal>scram-sha-256</literal></term> 1076 <listitem> 1077 <para> 1078 The method <literal>scram-sha-256</literal> performs SCRAM-SHA-256 1079 authentication, as described in 1080 <ulink url="https://tools.ietf.org/html/rfc7677">RFC 7677</ulink>. It 1081 is a challenge-response scheme that prevents password sniffing on 1082 untrusted connections and supports storing passwords on the server in a 1083 cryptographically hashed form that is thought to be secure. 1084 </para> 1085 1086 <para> 1087 This is the most secure of the currently provided methods, but it is 1088 not supported by older client libraries. 1089 </para> 1090 </listitem> 1091 </varlistentry> 1092 1093 <varlistentry> 1094 <term><literal>md5</literal></term> 1095 <listitem> 1096 <para> 1097 The method <literal>md5</literal> uses a custom less secure challenge-response 1098 mechanism. It prevents password sniffing and avoids storing passwords 1099 on the server in plain text but provides no protection if an attacker 1100 manages to steal the password hash from the server. Also, the MD5 hash 1101 algorithm is nowadays no longer considered secure against determined 1102 attacks. 1103 </para> 1104 1105 <para> 1106 The <literal>md5</literal> method cannot be used with 1107 the <xref linkend="guc-db-user-namespace"/> feature. 1108 </para> 1109 1110 <para> 1111 To ease transition from the <literal>md5</literal> method to the newer 1112 SCRAM method, if <literal>md5</literal> is specified as a method 1113 in <filename>pg_hba.conf</filename> but the user's password on the 1114 server is encrypted for SCRAM (see below), then SCRAM-based 1115 authentication will automatically be chosen instead. 1116 </para> 1117 </listitem> 1118 </varlistentry> 1119 1120 <varlistentry> 1121 <term><literal>password</literal></term> 1122 <listitem> 1123 <para> 1124 The method <literal>password</literal> sends the password in clear-text and is 1125 therefore vulnerable to password <quote>sniffing</quote> attacks. It should 1126 always be avoided if possible. If the connection is protected by SSL 1127 encryption then <literal>password</literal> can be used safely, though. 1128 (Though SSL certificate authentication might be a better choice if one 1129 is depending on using SSL). 1130 </para> 1131 </listitem> 1132 </varlistentry> 1133 </variablelist> 1134 1135 <para> 1136 <productname>PostgreSQL</productname> database passwords are 1137 separate from operating system user passwords. The password for 1138 each database user is stored in the <literal>pg_authid</literal> system 1139 catalog. Passwords can be managed with the SQL commands 1140 <xref linkend="sql-createrole"/> and 1141 <xref linkend="sql-alterrole"/>, 1142 e.g., <userinput>CREATE ROLE foo WITH LOGIN PASSWORD 'secret'</userinput>, 1143 or the <application>psql</application> 1144 command <literal>\password</literal>. 1145 If no password has been set up for a user, the stored password 1146 is null and password authentication will always fail for that user. 1147 </para> 1148 1149 <para> 1150 The availability of the different password-based authentication methods 1151 depends on how a user's password on the server is encrypted (or hashed, 1152 more accurately). This is controlled by the configuration 1153 parameter <xref linkend="guc-password-encryption"/> at the time the 1154 password is set. If a password was encrypted using 1155 the <literal>scram-sha-256</literal> setting, then it can be used for the 1156 authentication methods <literal>scram-sha-256</literal> 1157 and <literal>password</literal> (but password transmission will be in 1158 plain text in the latter case). The authentication method 1159 specification <literal>md5</literal> will automatically switch to using 1160 the <literal>scram-sha-256</literal> method in this case, as explained 1161 above, so it will also work. If a password was encrypted using 1162 the <literal>md5</literal> setting, then it can be used only for 1163 the <literal>md5</literal> and <literal>password</literal> authentication 1164 method specifications (again, with the password transmitted in plain text 1165 in the latter case). (Previous PostgreSQL releases supported storing the 1166 password on the server in plain text. This is no longer possible.) To 1167 check the currently stored password hashes, see the system 1168 catalog <literal>pg_authid</literal>. 1169 </para> 1170 1171 <para> 1172 To upgrade an existing installation from <literal>md5</literal> 1173 to <literal>scram-sha-256</literal>, after having ensured that all client 1174 libraries in use are new enough to support SCRAM, 1175 set <literal>password_encryption = 'scram-sha-256'</literal> 1176 in <filename>postgresql.conf</filename>, make all users set new passwords, 1177 and change the authentication method specifications 1178 in <filename>pg_hba.conf</filename> to <literal>scram-sha-256</literal>. 1179 </para> 1180 </sect1> 1181 1182 <sect1 id="gssapi-auth"> 1183 <title>GSSAPI Authentication</title> 1184 1185 <indexterm zone="gssapi-auth"> 1186 <primary>GSSAPI</primary> 1187 </indexterm> 1188 1189 <para> 1190 <productname>GSSAPI</productname> is an industry-standard protocol 1191 for secure authentication defined in 1192 <ulink url="https://tools.ietf.org/html/rfc2743">RFC 2743</ulink>. 1193 <productname>PostgreSQL</productname> 1194 supports <productname>GSSAPI</productname> for authentication, 1195 communications encryption, or both. 1196 <productname>GSSAPI</productname> provides automatic authentication 1197 (single sign-on) for systems that support it. The authentication itself is 1198 secure. If <productname>GSSAPI</productname> encryption 1199 or <acronym>SSL</acronym> encryption is 1200 used, the data sent along the database connection will be encrypted; 1201 otherwise, it will not. 1202 </para> 1203 1204 <para> 1205 GSSAPI support has to be enabled when <productname>PostgreSQL</productname> is built; 1206 see <xref linkend="installation"/> for more information. 1207 </para> 1208 1209 <para> 1210 When <productname>GSSAPI</productname> uses 1211 <productname>Kerberos</productname>, it uses a standard service 1212 principal (authentication identity) name in the format 1213 <literal><replaceable>servicename</replaceable>/<replaceable>hostname</replaceable>@<replaceable>realm</replaceable></literal>. 1214 The principal name used by a particular installation is not encoded in 1215 the <productname>PostgreSQL</productname> server in any way; rather it 1216 is specified in the <firstterm>keytab</firstterm> file that the server 1217 reads to determine its identity. If multiple principals are listed in 1218 the keytab file, the server will accept any one of them. 1219 The server's realm name is the preferred realm specified in the Kerberos 1220 configuration file(s) accessible to the server. 1221 </para> 1222 1223 <para> 1224 When connecting, the client must know the principal name of the server 1225 it intends to connect to. The <replaceable>servicename</replaceable> 1226 part of the principal is ordinarily <literal>postgres</literal>, 1227 but another value can be selected via <application>libpq</application>'s 1228 <xref linkend="libpq-connect-krbsrvname"/> connection parameter. 1229 The <replaceable>hostname</replaceable> part is the fully qualified 1230 host name that <application>libpq</application> is told to connect to. 1231 The realm name is the preferred realm specified in the Kerberos 1232 configuration file(s) accessible to the client. 1233 </para> 1234 1235 <para> 1236 The client will also have a principal name for its own identity 1237 (and it must have a valid ticket for this principal). To 1238 use <productname>GSSAPI</productname> for authentication, the client 1239 principal must be associated with 1240 a <productname>PostgreSQL</productname> database user name. 1241 The <filename>pg_ident.conf</filename> configuration file can be used 1242 to map principals to user names; for example, 1243 <literal>pgusername@realm</literal> could be mapped to just <literal>pgusername</literal>. 1244 Alternatively, you can use the full <literal>username@realm</literal> principal as 1245 the role name in <productname>PostgreSQL</productname> without any mapping. 1246 </para> 1247 1248 <para> 1249 <productname>PostgreSQL</productname> also supports mapping 1250 client principals to user names by just stripping the realm from 1251 the principal. This method is supported for backwards compatibility and is 1252 strongly discouraged as it is then impossible to distinguish different users 1253 with the same user name but coming from different realms. To enable this, 1254 set <literal>include_realm</literal> to 0. For simple single-realm 1255 installations, doing that combined with setting the 1256 <literal>krb_realm</literal> parameter (which checks that the principal's realm 1257 matches exactly what is in the <literal>krb_realm</literal> parameter) 1258 is still secure; but this is a 1259 less capable approach compared to specifying an explicit mapping in 1260 <filename>pg_ident.conf</filename>. 1261 </para> 1262 1263 <para> 1264 The location of the server's keytab file is specified by the <xref 1265 linkend="guc-krb-server-keyfile"/> configuration parameter. 1266 For security reasons, it is recommended to use a separate keytab 1267 just for the <productname>PostgreSQL</productname> server rather 1268 than allowing the server to read the system keytab file. 1269 Make sure that your server keytab file is readable (and preferably 1270 only readable, not writable) by the <productname>PostgreSQL</productname> 1271 server account. (See also <xref linkend="postgres-user"/>.) 1272 </para> 1273 1274 <para> 1275 The keytab file is generated using the Kerberos software; see the 1276 Kerberos documentation for details. The following example shows 1277 doing this using the <application>kadmin</application> tool of 1278 MIT-compatible Kerberos 5 implementations: 1279<screen> 1280<prompt>kadmin% </prompt><userinput>addprinc -randkey postgres/server.my.domain.org</userinput> 1281<prompt>kadmin% </prompt><userinput>ktadd -k krb5.keytab postgres/server.my.domain.org</userinput> 1282</screen> 1283 </para> 1284 1285 <para> 1286 The following authentication options are supported for 1287 the <productname>GSSAPI</productname> authentication method: 1288 <variablelist> 1289 <varlistentry> 1290 <term><literal>include_realm</literal></term> 1291 <listitem> 1292 <para> 1293 If set to 0, the realm name from the authenticated user principal is 1294 stripped off before being passed through the user name mapping 1295 (<xref linkend="auth-username-maps"/>). This is discouraged and is 1296 primarily available for backwards compatibility, as it is not secure 1297 in multi-realm environments unless <literal>krb_realm</literal> is 1298 also used. It is recommended to 1299 leave <literal>include_realm</literal> set to the default (1) and to 1300 provide an explicit mapping in <filename>pg_ident.conf</filename> to convert 1301 principal names to <productname>PostgreSQL</productname> user names. 1302 </para> 1303 </listitem> 1304 </varlistentry> 1305 1306 <varlistentry> 1307 <term><literal>map</literal></term> 1308 <listitem> 1309 <para> 1310 Allows mapping from client principals to database user names. See 1311 <xref linkend="auth-username-maps"/> for details. For a GSSAPI/Kerberos 1312 principal, such as <literal>username@EXAMPLE.COM</literal> (or, less 1313 commonly, <literal>username/hostbased@EXAMPLE.COM</literal>), the 1314 user name used for mapping is 1315 <literal>username@EXAMPLE.COM</literal> (or 1316 <literal>username/hostbased@EXAMPLE.COM</literal>, respectively), 1317 unless <literal>include_realm</literal> has been set to 0, in which case 1318 <literal>username</literal> (or <literal>username/hostbased</literal>) 1319 is what is seen as the system user name when mapping. 1320 </para> 1321 </listitem> 1322 </varlistentry> 1323 1324 <varlistentry> 1325 <term><literal>krb_realm</literal></term> 1326 <listitem> 1327 <para> 1328 Sets the realm to match user principal names against. If this parameter 1329 is set, only users of that realm will be accepted. If it is not set, 1330 users of any realm can connect, subject to whatever user name mapping 1331 is done. 1332 </para> 1333 </listitem> 1334 </varlistentry> 1335 </variablelist> 1336 </para> 1337 1338 <para> 1339 In addition to these settings, which can be different for 1340 different <filename>pg_hba.conf</filename> entries, there is the 1341 server-wide <xref linkend="guc-krb-caseins-users"/> configuration 1342 parameter. If that is set to true, client principals are matched to 1343 user map entries case-insensitively. <literal>krb_realm</literal>, if 1344 set, is also matched case-insensitively. 1345 </para> 1346 </sect1> 1347 1348 <sect1 id="sspi-auth"> 1349 <title>SSPI Authentication</title> 1350 1351 <indexterm zone="sspi-auth"> 1352 <primary>SSPI</primary> 1353 </indexterm> 1354 1355 <para> 1356 <productname>SSPI</productname> is a <productname>Windows</productname> 1357 technology for secure authentication with single sign-on. 1358 <productname>PostgreSQL</productname> will use SSPI in 1359 <literal>negotiate</literal> mode, which will use 1360 <productname>Kerberos</productname> when possible and automatically 1361 fall back to <productname>NTLM</productname> in other cases. 1362 <productname>SSPI</productname> authentication only works when both 1363 server and client are running <productname>Windows</productname>, 1364 or, on non-Windows platforms, when <productname>GSSAPI</productname> 1365 is available. 1366 </para> 1367 1368 <para> 1369 When using <productname>Kerberos</productname> authentication, 1370 <productname>SSPI</productname> works the same way 1371 <productname>GSSAPI</productname> does; see <xref linkend="gssapi-auth"/> 1372 for details. 1373 </para> 1374 1375 <para> 1376 The following configuration options are supported for <productname>SSPI</productname>: 1377 <variablelist> 1378 1379 <varlistentry> 1380 <term><literal>include_realm</literal></term> 1381 <listitem> 1382 <para> 1383 If set to 0, the realm name from the authenticated user principal is 1384 stripped off before being passed through the user name mapping 1385 (<xref linkend="auth-username-maps"/>). This is discouraged and is 1386 primarily available for backwards compatibility, as it is not secure 1387 in multi-realm environments unless <literal>krb_realm</literal> is 1388 also used. It is recommended to 1389 leave <literal>include_realm</literal> set to the default (1) and to 1390 provide an explicit mapping in <filename>pg_ident.conf</filename> to convert 1391 principal names to <productname>PostgreSQL</productname> user names. 1392 </para> 1393 </listitem> 1394 </varlistentry> 1395 1396 <varlistentry> 1397 <term><literal>compat_realm</literal></term> 1398 <listitem> 1399 <para> 1400 If set to 1, the domain's SAM-compatible name (also known as the 1401 NetBIOS name) is used for the <literal>include_realm</literal> 1402 option. This is the default. If set to 0, the true realm name from 1403 the Kerberos user principal name is used. 1404 </para> 1405 <para> 1406 Do not disable this option unless your server runs under a domain 1407 account (this includes virtual service accounts on a domain member 1408 system) and all clients authenticating through SSPI are also using 1409 domain accounts, or authentication will fail. 1410 </para> 1411 </listitem> 1412 </varlistentry> 1413 1414 <varlistentry> 1415 <term><literal>upn_username</literal></term> 1416 <listitem> 1417 <para> 1418 If this option is enabled along with <literal>compat_realm</literal>, 1419 the user name from the Kerberos UPN is used for authentication. If 1420 it is disabled (the default), the SAM-compatible user name is used. 1421 By default, these two names are identical for new user accounts. 1422 </para> 1423 <para> 1424 Note that <application>libpq</application> uses the SAM-compatible name if no 1425 explicit user name is specified. If you use 1426 <application>libpq</application> or a driver based on it, you should 1427 leave this option disabled or explicitly specify user name in the 1428 connection string. 1429 </para> 1430 </listitem> 1431 </varlistentry> 1432 1433 <varlistentry> 1434 <term><literal>map</literal></term> 1435 <listitem> 1436 <para> 1437 Allows for mapping between system and database user names. See 1438 <xref linkend="auth-username-maps"/> for details. For a SSPI/Kerberos 1439 principal, such as <literal>username@EXAMPLE.COM</literal> (or, less 1440 commonly, <literal>username/hostbased@EXAMPLE.COM</literal>), the 1441 user name used for mapping is 1442 <literal>username@EXAMPLE.COM</literal> (or 1443 <literal>username/hostbased@EXAMPLE.COM</literal>, respectively), 1444 unless <literal>include_realm</literal> has been set to 0, in which case 1445 <literal>username</literal> (or <literal>username/hostbased</literal>) 1446 is what is seen as the system user name when mapping. 1447 </para> 1448 </listitem> 1449 </varlistentry> 1450 1451 <varlistentry> 1452 <term><literal>krb_realm</literal></term> 1453 <listitem> 1454 <para> 1455 Sets the realm to match user principal names against. If this parameter 1456 is set, only users of that realm will be accepted. If it is not set, 1457 users of any realm can connect, subject to whatever user name mapping 1458 is done. 1459 </para> 1460 </listitem> 1461 </varlistentry> 1462 </variablelist> 1463 </para> 1464 </sect1> 1465 1466 <sect1 id="auth-ident"> 1467 <title>Ident Authentication</title> 1468 1469 <indexterm> 1470 <primary>ident</primary> 1471 </indexterm> 1472 1473 <para> 1474 The ident authentication method works by obtaining the client's 1475 operating system user name from an ident server and using it as 1476 the allowed database user name (with an optional user name mapping). 1477 This is only supported on TCP/IP connections. 1478 </para> 1479 1480 <note> 1481 <para> 1482 When ident is specified for a local (non-TCP/IP) connection, 1483 peer authentication (see <xref linkend="auth-peer"/>) will be 1484 used instead. 1485 </para> 1486 </note> 1487 1488 <para> 1489 The following configuration options are supported for <productname>ident</productname>: 1490 <variablelist> 1491 <varlistentry> 1492 <term><literal>map</literal></term> 1493 <listitem> 1494 <para> 1495 Allows for mapping between system and database user names. See 1496 <xref linkend="auth-username-maps"/> for details. 1497 </para> 1498 </listitem> 1499 </varlistentry> 1500 </variablelist> 1501 </para> 1502 1503 <para> 1504 The <quote>Identification Protocol</quote> is described in 1505 RFC 1413. Virtually every Unix-like 1506 operating system ships with an ident server that listens on TCP 1507 port 113 by default. The basic functionality of an ident server 1508 is to answer questions like <quote>What user initiated the 1509 connection that goes out of your port <replaceable>X</replaceable> 1510 and connects to my port <replaceable>Y</replaceable>?</quote>. 1511 Since <productname>PostgreSQL</productname> knows both <replaceable>X</replaceable> and 1512 <replaceable>Y</replaceable> when a physical connection is established, it 1513 can interrogate the ident server on the host of the connecting 1514 client and can theoretically determine the operating system user 1515 for any given connection. 1516 </para> 1517 1518 <para> 1519 The drawback of this procedure is that it depends on the integrity 1520 of the client: if the client machine is untrusted or compromised, 1521 an attacker could run just about any program on port 113 and 1522 return any user name they choose. This authentication method is 1523 therefore only appropriate for closed networks where each client 1524 machine is under tight control and where the database and system 1525 administrators operate in close contact. In other words, you must 1526 trust the machine running the ident server. 1527 Heed the warning: 1528 <blockquote> 1529 <attribution>RFC 1413</attribution> 1530 <para> 1531 The Identification Protocol is not intended as an authorization 1532 or access control protocol. 1533 </para> 1534 </blockquote> 1535 </para> 1536 1537 <para> 1538 Some ident servers have a nonstandard option that causes the returned 1539 user name to be encrypted, using a key that only the originating 1540 machine's administrator knows. This option <emphasis>must not</emphasis> be 1541 used when using the ident server with <productname>PostgreSQL</productname>, 1542 since <productname>PostgreSQL</productname> does not have any way to decrypt the 1543 returned string to determine the actual user name. 1544 </para> 1545 </sect1> 1546 1547 <sect1 id="auth-peer"> 1548 <title>Peer Authentication</title> 1549 1550 <indexterm> 1551 <primary>peer</primary> 1552 </indexterm> 1553 1554 <para> 1555 The peer authentication method works by obtaining the client's 1556 operating system user name from the kernel and using it as the 1557 allowed database user name (with optional user name mapping). This 1558 method is only supported on local connections. 1559 </para> 1560 1561 <para> 1562 The following configuration options are supported for <productname>peer</productname>: 1563 <variablelist> 1564 <varlistentry> 1565 <term><literal>map</literal></term> 1566 <listitem> 1567 <para> 1568 Allows for mapping between system and database user names. See 1569 <xref linkend="auth-username-maps"/> for details. 1570 </para> 1571 </listitem> 1572 </varlistentry> 1573 </variablelist> 1574 </para> 1575 1576 <para> 1577 Peer authentication is only available on operating systems providing 1578 the <function>getpeereid()</function> function, the <symbol>SO_PEERCRED</symbol> 1579 socket parameter, or similar mechanisms. Currently that includes 1580 <systemitem class="osname">Linux</systemitem>, 1581 most flavors of <systemitem class="osname">BSD</systemitem> including 1582 <systemitem class="osname">macOS</systemitem>, 1583 and <systemitem class="osname">Solaris</systemitem>. 1584 </para> 1585 1586 </sect1> 1587 1588 <sect1 id="auth-ldap"> 1589 <title>LDAP Authentication</title> 1590 1591 <indexterm zone="auth-ldap"> 1592 <primary>LDAP</primary> 1593 </indexterm> 1594 1595 <para> 1596 This authentication method operates similarly to 1597 <literal>password</literal> except that it uses LDAP 1598 as the password verification method. LDAP is used only to validate 1599 the user name/password pairs. Therefore the user must already 1600 exist in the database before LDAP can be used for 1601 authentication. 1602 </para> 1603 1604 <para> 1605 LDAP authentication can operate in two modes. In the first mode, 1606 which we will call the simple bind mode, 1607 the server will bind to the distinguished name constructed as 1608 <replaceable>prefix</replaceable> <replaceable>username</replaceable> <replaceable>suffix</replaceable>. 1609 Typically, the <replaceable>prefix</replaceable> parameter is used to specify 1610 <literal>cn=</literal>, or <replaceable>DOMAIN</replaceable><literal>\</literal> in an Active 1611 Directory environment. <replaceable>suffix</replaceable> is used to specify the 1612 remaining part of the DN in a non-Active Directory environment. 1613 </para> 1614 1615 <para> 1616 In the second mode, which we will call the search+bind mode, 1617 the server first binds to the LDAP directory with 1618 a fixed user name and password, specified with <replaceable>ldapbinddn</replaceable> 1619 and <replaceable>ldapbindpasswd</replaceable>, and performs a search for the user trying 1620 to log in to the database. If no user and password is configured, an 1621 anonymous bind will be attempted to the directory. The search will be 1622 performed over the subtree at <replaceable>ldapbasedn</replaceable>, and will try to 1623 do an exact match of the attribute specified in 1624 <replaceable>ldapsearchattribute</replaceable>. 1625 Once the user has been found in 1626 this search, the server disconnects and re-binds to the directory as 1627 this user, using the password specified by the client, to verify that the 1628 login is correct. This mode is the same as that used by LDAP authentication 1629 schemes in other software, such as Apache <literal>mod_authnz_ldap</literal> and <literal>pam_ldap</literal>. 1630 This method allows for significantly more flexibility 1631 in where the user objects are located in the directory, but will cause 1632 two separate connections to the LDAP server to be made. 1633 </para> 1634 1635 <para> 1636 The following configuration options are used in both modes: 1637 <variablelist> 1638 <varlistentry> 1639 <term><literal>ldapserver</literal></term> 1640 <listitem> 1641 <para> 1642 Names or IP addresses of LDAP servers to connect to. Multiple 1643 servers may be specified, separated by spaces. 1644 </para> 1645 </listitem> 1646 </varlistentry> 1647 <varlistentry> 1648 <term><literal>ldapport</literal></term> 1649 <listitem> 1650 <para> 1651 Port number on LDAP server to connect to. If no port is specified, 1652 the LDAP library's default port setting will be used. 1653 </para> 1654 </listitem> 1655 </varlistentry> 1656 <varlistentry> 1657 <term><literal>ldapscheme</literal></term> 1658 <listitem> 1659 <para> 1660 Set to <literal>ldaps</literal> to use LDAPS. This is a non-standard 1661 way of using LDAP over SSL, supported by some LDAP server 1662 implementations. See also the <literal>ldaptls</literal> option for 1663 an alternative. 1664 </para> 1665 </listitem> 1666 </varlistentry> 1667 <varlistentry> 1668 <term><literal>ldaptls</literal></term> 1669 <listitem> 1670 <para> 1671 Set to 1 to make the connection between PostgreSQL and the LDAP server 1672 use TLS encryption. This uses the <literal>StartTLS</literal> 1673 operation per RFC 4513. See also the <literal>ldapscheme</literal> 1674 option for an alternative. 1675 </para> 1676 </listitem> 1677 </varlistentry> 1678 </variablelist> 1679 </para> 1680 1681 <para> 1682 Note that using <literal>ldapscheme</literal> or 1683 <literal>ldaptls</literal> only encrypts the traffic between the 1684 PostgreSQL server and the LDAP server. The connection between the 1685 PostgreSQL server and the PostgreSQL client will still be unencrypted 1686 unless SSL is used there as well. 1687 </para> 1688 1689 <para> 1690 The following options are used in simple bind mode only: 1691 <variablelist> 1692 <varlistentry> 1693 <term><literal>ldapprefix</literal></term> 1694 <listitem> 1695 <para> 1696 String to prepend to the user name when forming the DN to bind as, 1697 when doing simple bind authentication. 1698 </para> 1699 </listitem> 1700 </varlistentry> 1701 <varlistentry> 1702 <term><literal>ldapsuffix</literal></term> 1703 <listitem> 1704 <para> 1705 String to append to the user name when forming the DN to bind as, 1706 when doing simple bind authentication. 1707 </para> 1708 </listitem> 1709 </varlistentry> 1710 </variablelist> 1711 </para> 1712 1713 <para> 1714 The following options are used in search+bind mode only: 1715 <variablelist> 1716 <varlistentry> 1717 <term><literal>ldapbasedn</literal></term> 1718 <listitem> 1719 <para> 1720 Root DN to begin the search for the user in, when doing search+bind 1721 authentication. 1722 </para> 1723 </listitem> 1724 </varlistentry> 1725 <varlistentry> 1726 <term><literal>ldapbinddn</literal></term> 1727 <listitem> 1728 <para> 1729 DN of user to bind to the directory with to perform the search when 1730 doing search+bind authentication. 1731 </para> 1732 </listitem> 1733 </varlistentry> 1734 <varlistentry> 1735 <term><literal>ldapbindpasswd</literal></term> 1736 <listitem> 1737 <para> 1738 Password for user to bind to the directory with to perform the search 1739 when doing search+bind authentication. 1740 </para> 1741 </listitem> 1742 </varlistentry> 1743 <varlistentry> 1744 <term><literal>ldapsearchattribute</literal></term> 1745 <listitem> 1746 <para> 1747 Attribute to match against the user name in the search when doing 1748 search+bind authentication. If no attribute is specified, the 1749 <literal>uid</literal> attribute will be used. 1750 </para> 1751 </listitem> 1752 </varlistentry> 1753 <varlistentry> 1754 <term><literal>ldapsearchfilter</literal></term> 1755 <listitem> 1756 <para> 1757 The search filter to use when doing search+bind authentication. 1758 Occurrences of <literal>$username</literal> will be replaced with the 1759 user name. This allows for more flexible search filters than 1760 <literal>ldapsearchattribute</literal>. 1761 </para> 1762 </listitem> 1763 </varlistentry> 1764 <varlistentry> 1765 <term><literal>ldapurl</literal></term> 1766 <listitem> 1767 <para> 1768 An RFC 4516 LDAP URL. This is an alternative way to write some of the 1769 other LDAP options in a more compact and standard form. The format is 1770<synopsis> 1771ldap[s]://<replaceable>host</replaceable>[:<replaceable>port</replaceable>]/<replaceable>basedn</replaceable>[?[<replaceable>attribute</replaceable>][?[<replaceable>scope</replaceable>][?[<replaceable>filter</replaceable>]]]] 1772</synopsis> 1773 <replaceable>scope</replaceable> must be one 1774 of <literal>base</literal>, <literal>one</literal>, <literal>sub</literal>, 1775 typically the last. (The default is <literal>base</literal>, which 1776 is normally not useful in this application.) <replaceable>attribute</replaceable> can 1777 nominate a single attribute, in which case it is used as a value for 1778 <literal>ldapsearchattribute</literal>. If 1779 <replaceable>attribute</replaceable> is empty then 1780 <replaceable>filter</replaceable> can be used as a value for 1781 <literal>ldapsearchfilter</literal>. 1782 </para> 1783 1784 <para> 1785 The URL scheme <literal>ldaps</literal> chooses the LDAPS method for 1786 making LDAP connections over SSL, equivalent to using 1787 <literal>ldapscheme=ldaps</literal>. To use encrypted LDAP 1788 connections using the <literal>StartTLS</literal> operation, use the 1789 normal URL scheme <literal>ldap</literal> and specify the 1790 <literal>ldaptls</literal> option in addition to 1791 <literal>ldapurl</literal>. 1792 </para> 1793 1794 <para> 1795 For non-anonymous binds, <literal>ldapbinddn</literal> 1796 and <literal>ldapbindpasswd</literal> must be specified as separate 1797 options. 1798 </para> 1799 1800 <para> 1801 LDAP URLs are currently only supported with 1802 <productname>OpenLDAP</productname>, not on Windows. 1803 </para> 1804 </listitem> 1805 </varlistentry> 1806 </variablelist> 1807 </para> 1808 1809 <para> 1810 It is an error to mix configuration options for simple bind with options 1811 for search+bind. 1812 </para> 1813 1814 <para> 1815 When using search+bind mode, the search can be performed using a single 1816 attribute specified with <literal>ldapsearchattribute</literal>, or using 1817 a custom search filter specified with 1818 <literal>ldapsearchfilter</literal>. 1819 Specifying <literal>ldapsearchattribute=foo</literal> is equivalent to 1820 specifying <literal>ldapsearchfilter="(foo=$username)"</literal>. If neither 1821 option is specified the default is 1822 <literal>ldapsearchattribute=uid</literal>. 1823 </para> 1824 1825 <para> 1826 If <productname>PostgreSQL</productname> was compiled with 1827 <productname>OpenLDAP</productname> as the LDAP client library, the 1828 <literal>ldapserver</literal> setting may be omitted. In that case, a 1829 list of host names and ports is looked up via RFC 2782 DNS SRV records. 1830 The name <literal>_ldap._tcp.DOMAIN</literal> is looked up, where 1831 <literal>DOMAIN</literal> is extracted from <literal>ldapbasedn</literal>. 1832 </para> 1833 1834 <para> 1835 Here is an example for a simple-bind LDAP configuration: 1836<programlisting> 1837host ... ldap ldapserver=ldap.example.net ldapprefix="cn=" ldapsuffix=", dc=example, dc=net" 1838</programlisting> 1839 When a connection to the database server as database 1840 user <literal>someuser</literal> is requested, PostgreSQL will attempt to 1841 bind to the LDAP server using the DN <literal>cn=someuser, dc=example, 1842 dc=net</literal> and the password provided by the client. If that connection 1843 succeeds, the database access is granted. 1844 </para> 1845 1846 <para> 1847 Here is an example for a search+bind configuration: 1848<programlisting> 1849host ... ldap ldapserver=ldap.example.net ldapbasedn="dc=example, dc=net" ldapsearchattribute=uid 1850</programlisting> 1851 When a connection to the database server as database 1852 user <literal>someuser</literal> is requested, PostgreSQL will attempt to 1853 bind anonymously (since <literal>ldapbinddn</literal> was not specified) to 1854 the LDAP server, perform a search for <literal>(uid=someuser)</literal> 1855 under the specified base DN. If an entry is found, it will then attempt to 1856 bind using that found information and the password supplied by the client. 1857 If that second connection succeeds, the database access is granted. 1858 </para> 1859 1860 <para> 1861 Here is the same search+bind configuration written as a URL: 1862<programlisting> 1863host ... ldap ldapurl="ldap://ldap.example.net/dc=example,dc=net?uid?sub" 1864</programlisting> 1865 Some other software that supports authentication against LDAP uses the 1866 same URL format, so it will be easier to share the configuration. 1867 </para> 1868 1869 <para> 1870 Here is an example for a search+bind configuration that uses 1871 <literal>ldapsearchfilter</literal> instead of 1872 <literal>ldapsearchattribute</literal> to allow authentication by 1873 user ID or email address: 1874<programlisting> 1875host ... ldap ldapserver=ldap.example.net ldapbasedn="dc=example, dc=net" ldapsearchfilter="(|(uid=$username)(mail=$username))" 1876</programlisting> 1877 </para> 1878 1879 <para> 1880 Here is an example for a search+bind configuration that uses DNS SRV 1881 discovery to find the host name(s) and port(s) for the LDAP service for the 1882 domain name <literal>example.net</literal>: 1883<programlisting> 1884host ... ldap ldapbasedn="dc=example,dc=net" 1885</programlisting> 1886 </para> 1887 1888 <tip> 1889 <para> 1890 Since LDAP often uses commas and spaces to separate the different 1891 parts of a DN, it is often necessary to use double-quoted parameter 1892 values when configuring LDAP options, as shown in the examples. 1893 </para> 1894 </tip> 1895 1896 </sect1> 1897 1898 <sect1 id="auth-radius"> 1899 <title>RADIUS Authentication</title> 1900 1901 <indexterm zone="auth-radius"> 1902 <primary>RADIUS</primary> 1903 </indexterm> 1904 1905 <para> 1906 This authentication method operates similarly to 1907 <literal>password</literal> except that it uses RADIUS 1908 as the password verification method. RADIUS is used only to validate 1909 the user name/password pairs. Therefore the user must already 1910 exist in the database before RADIUS can be used for 1911 authentication. 1912 </para> 1913 1914 <para> 1915 When using RADIUS authentication, an Access Request message will be sent 1916 to the configured RADIUS server. This request will be of type 1917 <literal>Authenticate Only</literal>, and include parameters for 1918 <literal>user name</literal>, <literal>password</literal> (encrypted) and 1919 <literal>NAS Identifier</literal>. The request will be encrypted using 1920 a secret shared with the server. The RADIUS server will respond to 1921 this request with either <literal>Access Accept</literal> or 1922 <literal>Access Reject</literal>. There is no support for RADIUS accounting. 1923 </para> 1924 1925 <para> 1926 Multiple RADIUS servers can be specified, in which case they will 1927 be tried sequentially. If a negative response is received from 1928 a server, the authentication will fail. If no response is received, 1929 the next server in the list will be tried. To specify multiple 1930 servers, separate the server names with commas and surround the list 1931 with double quotes. If multiple servers are specified, the other 1932 RADIUS options can also be given as comma-separated lists, to provide 1933 individual values for each server. They can also be specified as 1934 a single value, in which case that value will apply to all servers. 1935 </para> 1936 1937 <para> 1938 The following configuration options are supported for RADIUS: 1939 <variablelist> 1940 <varlistentry> 1941 <term><literal>radiusservers</literal></term> 1942 <listitem> 1943 <para> 1944 The DNS names or IP addresses of the RADIUS servers to connect to. 1945 This parameter is required. 1946 </para> 1947 </listitem> 1948 </varlistentry> 1949 1950 <varlistentry> 1951 <term><literal>radiussecrets</literal></term> 1952 <listitem> 1953 <para> 1954 The shared secrets used when talking securely to the RADIUS 1955 servers. This must have exactly the same value on the PostgreSQL 1956 and RADIUS servers. It is recommended that this be a string of 1957 at least 16 characters. This parameter is required. 1958 <note> 1959 <para> 1960 The encryption vector used will only be cryptographically 1961 strong if <productname>PostgreSQL</productname> is built with support for 1962 <productname>OpenSSL</productname>. In other cases, the transmission to the 1963 RADIUS server should only be considered obfuscated, not secured, and 1964 external security measures should be applied if necessary. 1965 </para> 1966 </note> 1967 </para> 1968 </listitem> 1969 </varlistentry> 1970 1971 <varlistentry> 1972 <term><literal>radiusports</literal></term> 1973 <listitem> 1974 <para> 1975 The port numbers to connect to on the RADIUS servers. If no port 1976 is specified, the default RADIUS port (<literal>1812</literal>) 1977 will be used. 1978 </para> 1979 </listitem> 1980 </varlistentry> 1981 1982 <varlistentry> 1983 <term><literal>radiusidentifiers</literal></term> 1984 <listitem> 1985 <para> 1986 The strings to be used as <literal>NAS Identifier</literal> in the 1987 RADIUS requests. This parameter can be used, for example, to 1988 identify which database cluster the user is attempting to connect 1989 to, which can be useful for policy matching on 1990 the RADIUS server. If no identifier is specified, the default 1991 <literal>postgresql</literal> will be used. 1992 </para> 1993 </listitem> 1994 </varlistentry> 1995 1996 </variablelist> 1997 </para> 1998 1999 <para> 2000 If it is necessary to have a comma or whitespace in a RADIUS parameter 2001 value, that can be done by putting double quotes around the value, but 2002 it is tedious because two layers of double-quoting are now required. 2003 An example of putting whitespace into RADIUS secret strings is: 2004<programlisting> 2005host ... radius radiusservers="server1,server2" radiussecrets="""secret one"",""secret two""" 2006</programlisting> 2007 </para> 2008 </sect1> 2009 2010 <sect1 id="auth-cert"> 2011 <title>Certificate Authentication</title> 2012 2013 <indexterm zone="auth-cert"> 2014 <primary>Certificate</primary> 2015 </indexterm> 2016 2017 <para> 2018 This authentication method uses SSL client certificates to perform 2019 authentication. It is therefore only available for SSL connections. 2020 When using this authentication method, the server will require that 2021 the client provide a valid, trusted certificate. No password prompt 2022 will be sent to the client. The <literal>cn</literal> (Common Name) 2023 attribute of the certificate 2024 will be compared to the requested database user name, and if they match 2025 the login will be allowed. User name mapping can be used to allow 2026 <literal>cn</literal> to be different from the database user name. 2027 </para> 2028 2029 <para> 2030 The following configuration options are supported for SSL certificate 2031 authentication: 2032 <variablelist> 2033 <varlistentry> 2034 <term><literal>map</literal></term> 2035 <listitem> 2036 <para> 2037 Allows for mapping between system and database user names. See 2038 <xref linkend="auth-username-maps"/> for details. 2039 </para> 2040 </listitem> 2041 </varlistentry> 2042 </variablelist> 2043 </para> 2044 2045 <para> 2046 It is redundant to use the <literal>clientcert</literal> option with 2047 <literal>cert</literal> authentication because <literal>cert</literal> 2048 authentication is effectively <literal>trust</literal> authentication 2049 with <literal>clientcert=verify-full</literal>. 2050 </para> 2051 </sect1> 2052 2053 <sect1 id="auth-pam"> 2054 <title>PAM Authentication</title> 2055 2056 <indexterm zone="auth-pam"> 2057 <primary>PAM</primary> 2058 </indexterm> 2059 2060 <para> 2061 This authentication method operates similarly to 2062 <literal>password</literal> except that it uses PAM (Pluggable 2063 Authentication Modules) as the authentication mechanism. The 2064 default PAM service name is <literal>postgresql</literal>. 2065 PAM is used only to validate user name/password pairs and optionally the 2066 connected remote host name or IP address. Therefore the user must already 2067 exist in the database before PAM can be used for authentication. For more 2068 information about PAM, please read the 2069 <ulink url="https://www.kernel.org/pub/linux/libs/pam/"> 2070 <productname>Linux-PAM</productname> Page</ulink>. 2071 </para> 2072 2073 <para> 2074 The following configuration options are supported for PAM: 2075 <variablelist> 2076 <varlistentry> 2077 <term><literal>pamservice</literal></term> 2078 <listitem> 2079 <para> 2080 PAM service name. 2081 </para> 2082 </listitem> 2083 </varlistentry> 2084 <varlistentry> 2085 <term><literal>pam_use_hostname</literal></term> 2086 <listitem> 2087 <para> 2088 Determines whether the remote IP address or the host name is provided 2089 to PAM modules through the <symbol>PAM_RHOST</symbol> item. By 2090 default, the IP address is used. Set this option to 1 to use the 2091 resolved host name instead. Host name resolution can lead to login 2092 delays. (Most PAM configurations don't use this information, so it is 2093 only necessary to consider this setting if a PAM configuration was 2094 specifically created to make use of it.) 2095 </para> 2096 </listitem> 2097 </varlistentry> 2098 </variablelist> 2099 </para> 2100 2101 <note> 2102 <para> 2103 If PAM is set up to read <filename>/etc/shadow</filename>, authentication 2104 will fail because the PostgreSQL server is started by a non-root 2105 user. However, this is not an issue when PAM is configured to use 2106 LDAP or other authentication methods. 2107 </para> 2108 </note> 2109 </sect1> 2110 2111 <sect1 id="auth-bsd"> 2112 <title>BSD Authentication</title> 2113 2114 <indexterm zone="auth-bsd"> 2115 <primary>BSD Authentication</primary> 2116 </indexterm> 2117 2118 <para> 2119 This authentication method operates similarly to 2120 <literal>password</literal> except that it uses BSD Authentication 2121 to verify the password. BSD Authentication is used only 2122 to validate user name/password pairs. Therefore the user's role must 2123 already exist in the database before BSD Authentication can be used 2124 for authentication. The BSD Authentication framework is currently 2125 only available on OpenBSD. 2126 </para> 2127 2128 <para> 2129 BSD Authentication in <productname>PostgreSQL</productname> uses 2130 the <literal>auth-postgresql</literal> login type and authenticates with 2131 the <literal>postgresql</literal> login class if that's defined 2132 in <filename>login.conf</filename>. By default that login class does not 2133 exist, and <productname>PostgreSQL</productname> will use the default login class. 2134 </para> 2135 2136 <note> 2137 <para> 2138 To use BSD Authentication, the PostgreSQL user account (that is, the 2139 operating system user running the server) must first be added to 2140 the <literal>auth</literal> group. The <literal>auth</literal> group 2141 exists by default on OpenBSD systems. 2142 </para> 2143 </note> 2144 </sect1> 2145 2146 <sect1 id="client-authentication-problems"> 2147 <title>Authentication Problems</title> 2148 2149 <para> 2150 Authentication failures and related problems generally 2151 manifest themselves through error messages like the following: 2152 </para> 2153 2154 <para> 2155<programlisting> 2156FATAL: no pg_hba.conf entry for host "123.123.123.123", user "andym", database "testdb" 2157</programlisting> 2158 This is what you are most likely to get if you succeed in contacting 2159 the server, but it does not want to talk to you. As the message 2160 suggests, the server refused the connection request because it found 2161 no matching entry in its <filename>pg_hba.conf</filename> 2162 configuration file. 2163 </para> 2164 2165 <para> 2166<programlisting> 2167FATAL: password authentication failed for user "andym" 2168</programlisting> 2169 Messages like this indicate that you contacted the server, and it is 2170 willing to talk to you, but not until you pass the authorization 2171 method specified in the <filename>pg_hba.conf</filename> file. Check 2172 the password you are providing, or check your Kerberos or ident 2173 software if the complaint mentions one of those authentication 2174 types. 2175 </para> 2176 2177 <para> 2178<programlisting> 2179FATAL: user "andym" does not exist 2180</programlisting> 2181 The indicated database user name was not found. 2182 </para> 2183 2184 <para> 2185<programlisting> 2186FATAL: database "testdb" does not exist 2187</programlisting> 2188 The database you are trying to connect to does not exist. Note that 2189 if you do not specify a database name, it defaults to the database 2190 user name, which might or might not be the right thing. 2191 </para> 2192 2193 <tip> 2194 <para> 2195 The server log might contain more information about an 2196 authentication failure than is reported to the client. If you are 2197 confused about the reason for a failure, check the server log. 2198 </para> 2199 </tip> 2200 </sect1> 2201 2202 </chapter> 2203