diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml index 6ebe46190d1..ff08fc446cf 100644 --- a/doc/src/sgml/client-auth.sgml +++ b/doc/src/sgml/client-auth.sgml @@ -1,4 +1,4 @@ - + Client Authentication @@ -173,7 +173,7 @@ hostnossl database user database - Specifies which database names this record matches. The value + Specifies which database name(s) this record matches. The value all specifies that it matches all databases. The value sameuser specifies that the record matches if the requested database has the same name as the @@ -194,7 +194,7 @@ hostnossl database user user - Specifies which database user names this record + Specifies which database user name(s) this record matches. The value all specifies that it matches all users. Otherwise, this is either the name of a specific database user, or a group name preceded by +. @@ -215,7 +215,7 @@ hostnossl database user Specifies the client machine IP address range that this record - matches. It contains an IP address in standard dotted decimal + matches. This field contains an IP address in standard dotted decimal notation and a CIDR mask length. (IP addresses can only be specified numerically, not as domain or host names.) The mask length indicates the number of high-order bits of the client @@ -269,13 +269,13 @@ hostnossl database user hostssl, and hostnossl records. - + auth-method - Specifies the authentication method to use when connecting via + Specifies the authentication method to use when a connection matches this record. The possible choices are summarized here; details are in . @@ -323,7 +323,6 @@ hostnossl database user authentication. Since the password is sent in clear text over the network, this should not be used on untrusted networks. - It also does not usually work with threaded client applications. See for details. @@ -333,7 +332,7 @@ hostnossl database user gss - Use GSSAPI to authenticate the user. This is only + Use GSSAPI to authenticate the user. This is only available for TCP/IP connections. See for details. @@ -369,9 +368,8 @@ hostnossl database user Obtain the operating system user name of the client (for TCP/IP connections by contacting the ident server on the client, for local connections by getting it from the - operating system) and check if the user is allowed to - connect as the requested database user by consulting the map - specified after the ident key word. + operating system) and check if it matches the requested + database user name. See for details. @@ -381,7 +379,7 @@ hostnossl database user ldap - Authenticate using LDAP to a central server. See for details. @@ -417,10 +415,10 @@ hostnossl database user auth-options - This field contains zero or more name-value pairs with - extra options passed to this authentication method. Details - about which options are available for which authentication - method appear below. + After the auth-method field, there can be field(s) of + the form name=value that + specify options for the authentication method. Details about which + options are available for which authentication method appear below. @@ -491,32 +489,32 @@ local all all trust # The same using local loopback TCP/IP connections. # # TYPE DATABASE USER CIDR-ADDRESS METHOD -host all all 127.0.0.1/32 trust +host all all 127.0.0.1/32 trust -# The same as the last line but using a separate netmask column +# The same as the previous line, but using a separate netmask column # # TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD -host all all 127.0.0.1 255.255.255.255 trust +host all all 127.0.0.1 255.255.255.255 trust # Allow any user from any host with IP address 192.168.93.x to connect # to database "postgres" as the same user name that ident reports for # the connection (typically the Unix user name). -# +# # TYPE DATABASE USER CIDR-ADDRESS METHOD host postgres all 192.168.93.0/24 ident -# Allow a user from host 192.168.12.10 to connect to database +# Allow any user from host 192.168.12.10 to connect to database # "postgres" if the user's password is correctly supplied. -# +# # TYPE DATABASE USER CIDR-ADDRESS METHOD host postgres all 192.168.12.10/32 md5 # In the absence of preceding "host" lines, these two lines will -# reject all connection from 192.168.54.1 (since that entry will be +# reject all connections from 192.168.54.1 (since that entry will be # matched first), but allow Kerberos 5 connections from anywhere else # on the Internet. The zero mask means that no bits of the host IP # address are considered so it matches any host. -# +# # TYPE DATABASE USER CIDR-ADDRESS METHOD host all all 192.168.54.1/32 reject host all all 0.0.0.0/0 krb5 @@ -560,22 +558,21 @@ local db1,db2,@demodbs all md5 When using an external authentication system like Ident or GSSAPI, - the name of the operating system user that initiated the connection may - not be the same as the database user he is requesting to connect as. + the name of the operating system user that initiated the connection + might not be the same as the database user he needs to connect as. In this case, a user name map can be applied to map the operating system - username to a database user, using the pg_ident.conf - file. In order to use username mapping, specify + username to a database user. To use username mapping, specify map=map-name in the options field in pg_hba.conf. This option is supported for all authentication methods that receive external usernames. - Since the pg_ident.conf file can contain multiple maps, + Since different mappings might be needed for different connections, the name of the map to be used is specified in the map-name parameter in pg_hba.conf to indicate which map to use for each individual connection. - Ident maps are defined in the ident map file, which by default is named + Username maps are defined in the ident map file, which by default is named pg_ident.confpg_ident.conf and is stored in the cluster's data directory. (It is possible to place the map file @@ -589,26 +586,50 @@ local db1,db2,@demodbs all md5 pg_hba.conf. The map-name is an arbitrary name that will be used to refer to this mapping in pg_hba.conf. The other - two fields specify which operating system user is allowed to connect - as which database user. The same map-name can be - used repeatedly to specify more user-mappings within a single map. + two fields specify an operating system user name and a matching + database user name. The same map-name can be + used repeatedly to specify multiple user-mappings within a single map. + + There is no restriction regarding how many database users a given - operating system user can correspond to, nor vice versa. + operating system user can correspond to, nor vice versa. Thus, entries + in a map should be thought of as meaning this operating system + user is allowed to connect as this database user, rather than + implying that they are equivalent. The connection will be allowed if + there is any map entry that matches the user name obtained from the + external authentication system to the database user name that the + user has requested to connect as. If the system-username field starts with a slash (/), - the contents of the field is treated as a regular expression. This regular - expression supports a single capture, which can be back-referenced as - \1 (backslash-one). This allows the mapping of different syntax - names with a single line. - -mymap /(.*)@mydomain.com \1 -mymap /(.*)@otherdomain.com guest - - will "remove" the domain part for users with system usernames @mydomain.com, and - allow all users from @otherdomain.com to log in as guest. + the remainder of the field is treated as a regular expression. + (See for details of + PostgreSQL's regular expression syntax. + Regular expressions in username maps are always treated as being + advanced flavor.) The regular + expression can include a single capture, or parenthesized subexpression, + which can then be referenced in the database-username + field as \1 (backslash-one). This allows the mapping of + multiple usernames in a single line, which is particularly useful for + simple syntax substitutions. For example, these entries + +mymap /^(.*)@mydomain\.com$ \1 +mymap /^(.*)@otherdomain\.com$ guest + + will remove the domain part for users with system usernames that end with + @mydomain.com, and allow any user whose system name ends with + @otherdomain.com to log in as guest. + + + Keep in mind that by default, a regular expression can match just part of + a string. It's usually wise to use ^ and $, as + shown in the above example, to force the match to be to the entire + system username. + + + The pg_ident.conf file is read on start-up and when the main server process receives a @@ -638,7 +659,7 @@ mymap /(.*)@otherdomain.com guest An example <filename>pg_ident.conf</> file -# MAPNAME IDENT-USERNAME PG-USERNAME +# MAPNAME SYSTEM-USERNAME PG-USERNAME omicron bryanh bryanh omicron ann ann @@ -663,7 +684,7 @@ omicron bryanh guest1 When trust authentication is specified, PostgreSQL assumes that anyone who can connect to the server is authorized to access the database with - whatever database user name they specify (including superusers). + whatever database user name they specify (even superuser names). Of course, restrictions made in the database and user columns still apply. This method should only be used when there is adequate @@ -687,9 +708,10 @@ omicron bryanh guest1 Setting file-system permissions only helps for Unix-socket connections. - Local TCP/IP connections are not restricted by it; therefore, if you want - to use file-system permissions for local security, remove the host ... - 127.0.0.1 ... line from pg_hba.conf, or change it to a + Local TCP/IP connections are not restricted by file-system permissions. + Therefore, if you want to use file-system permissions for local security, + remove the host ... 127.0.0.1 ... line from + pg_hba.conf, or change it to a non-trust authentication method. @@ -715,7 +737,7 @@ omicron bryanh guest1 - The password-based authentication methods are md5, + The password-based authentication methods are md5 and password. These methods operate similarly except for the way that the password is sent across the connection: respectively, MD5-hashed and clear-text. @@ -725,8 +747,11 @@ omicron bryanh guest1 If you are at all concerned about password sniffing attacks then md5 is preferred. Plain password should always be avoided if possible. - md5 cannot be used with . + However, md5 cannot be used with the feature. If the connection is + protected by SSL encryption then password can be used + safely (though SSL certificate authentication might be a better + choice if one is depending on using SSL). @@ -752,20 +777,20 @@ omicron bryanh guest1 GSSAPI is an industry-standard protocol - for secure authentication defined in RFC 2743. + for secure authentication defined in RFC 2743. PostgreSQL supports GSSAPI with Kerberos authentication according to RFC 1964. GSSAPI provides automatic authentication (single sign-on) for systems that support it. The authentication itself is secure, but the - data sent over the connection will be in clear unless + data sent over the database connection will be in clear unless SSL is used. When GSSAPI uses Kerberos, it uses a standard principal - in format + in the format servicename/hostname@realm. For information about the parts of the principal, and how to set up the required keys, see . GSSAPI support has to be enabled when PostgreSQL is built; @@ -776,7 +801,7 @@ omicron bryanh guest1 The following configuration options are supported for GSSAPI: - map + map Allows for mapping between system and database usernames. See @@ -786,23 +811,25 @@ omicron bryanh guest1 - include_realm + include_realm - Include the realm name from the authenticated user principal. This is useful - in combination with Username maps (See - for details), especially with regular expressions, to map users from - multiple realms. + If set to 1, the realm name from the authenticated user + principal is included in the system user name that's passed through + username mapping (). This is + useful for handling users from multiple realms. - krb_realm + krb_realm Sets the realm to match user principal names against. If this parameter - is not set, the realm of the user will be ignored. + is set, only users of that realm will be accepted. If it is not set, + users of any realm can connect, subject to whatever username mapping + is done. @@ -819,7 +846,7 @@ omicron bryanh guest1 SSPI is a Windows - technology for secure authentication with single sign-on. + technology for secure authentication with single sign-on. PostgreSQL will use SSPI in negotiate mode, which will use Kerberos when possible and automatically @@ -829,8 +856,8 @@ omicron bryanh guest1 - When using Kerberos authentication, - SSPI works the same way + When using Kerberos authentication, + SSPI works the same way GSSAPI does. See for details. @@ -839,7 +866,7 @@ omicron bryanh guest1 The following configuration options are supported for SSPI: - map + map Allows for mapping between system and database usernames. See @@ -849,23 +876,25 @@ omicron bryanh guest1 - include_realm + include_realm - Include the realm name from the authenticated user principal. This is useful - in combination with Username maps (See - for details), especially with regular expressions, to map users from - multiple realms. + If set to 1, the realm name from the authenticated user + principal is included in the system user name that's passed through + username mapping (). This is + useful for handling users from multiple realms. - krb_realm + krb_realm Sets the realm to match user principal names against. If this parameter - is not set, the realm of the user will be ignored. + is set, only users of that realm will be accepted. If it is not set, + users of any realm can connect, subject to whatever username mapping + is done. @@ -894,9 +923,9 @@ omicron bryanh guest1 authentication system suitable for distributed computing over a public network. A description of the Kerberos system is far beyond the scope of this document; in full generality it can be - quite complex (yet powerful). The + quite complex (yet powerful). The - Kerberos FAQ or + Kerberos FAQ or MIT Kerberos page can be good starting points for exploration. Several sources for Kerberos distributions exist. @@ -923,7 +952,8 @@ omicron bryanh guest1 client side using the krbsrvname connection parameter. (See also .) The installation default can be changed from the default postgres at build time using - ./configure --with-krb-srvnam=whatever. In most environments, + ./configure --with-krb-srvnam=whatever. + In most environments, this parameter never needs to be changed. However, to support multiple PostgreSQL installations on the same host it is necessary. Some Kerberos implementations might also require a different service name, @@ -940,10 +970,13 @@ omicron bryanh guest1 Client principals must have their PostgreSQL database user name as their first component, for example - pgusername@realm. By default, the realm of the client is + pgusername@realm. Alternatively, you can use a username + mapping to map from the first component of the principal name to the + database user name. By default, the realm of the client is not checked by PostgreSQL. If you have cross-realm authentication enabled and need to verify the realm, use the - krb_realm parameter in pg_hba.conf. + krb_realm parameter, or enable include_realm + and use username mapping to check the realm. @@ -958,8 +991,8 @@ omicron bryanh guest1 - The keytab file is generated by the Kerberos software; see the - Kerberos documentation for details. The following example is + The keytab file is generated by the Kerberos software; see the + Kerberos documentation for details. The following example is for MIT-compatible Kerberos 5 implementations: kadmin% ank -randkey postgres/server.my.domain.org @@ -987,10 +1020,11 @@ omicron bryanh guest1 - The following configuration options are supported for Kerberos: + The following configuration options are supported for + Kerberos: - map + map Allows for mapping between system and database usernames. See @@ -1000,29 +1034,31 @@ omicron bryanh guest1 - include_realm + include_realm - Include the realm name from the authenticated user principal. This is useful - in combination with Username maps (See - for details), especially with regular expressions, to map users from - multiple realms. + If set to 1, the realm name from the authenticated user + principal is included in the system user name that's passed through + username mapping (). This is + useful for handling users from multiple realms. - krb_realm + krb_realm Sets the realm to match user principal names against. If this parameter - is not set, the realm of the user will be ignored. + is set, only users of that realm will be accepted. If it is not set, + users of any realm can connect, subject to whatever username mapping + is done. - krb_server_hostname + krb_server_hostname Sets the host name part of the service principal. @@ -1046,9 +1082,9 @@ omicron bryanh guest1 The ident authentication method works by obtaining the client's - operating system user name, then optionally determining the allowed - database user names using a map file that lists the permitted - corresponding pairs of names. The determination of the client's + operating system user name and using it as the allowed database user + name (with an optional username mapping). + The determination of the client's user name is the security-critical point, and it works differently depending on the connection type. @@ -1057,7 +1093,7 @@ omicron bryanh guest1 The following configuration options are supported for ident: - map + map Allows for mapping between system and database usernames. See @@ -1122,8 +1158,8 @@ omicron bryanh guest1 On systems supporting SO_PEERCRED requests for Unix-domain sockets (currently Linux, FreeBSD, - NetBSD, OpenBSD, - BSD/OS, and Solaris), ident authentication can also + NetBSD, OpenBSD, + BSD/OS, and Solaris), ident authentication can also be applied to local connections. In this case, no security risk is added by using ident authentication; indeed it is a preferable choice for local connections on such systems. @@ -1161,17 +1197,17 @@ omicron bryanh guest1 The server will bind to the distinguished name constructed as prefix username suffix. - before the bind. Typically, the prefix parameter is used to specify - cn=, or DOMAIN\ in an Active - Directory environment, and suffix is used to specify the remaining part - of the DN in a non-Active Directory environment. + Typically, the prefix parameter is used to specify + cn=, or DOMAIN\ in an Active + Directory environment. suffix is used to specify the + remaining part of the DN in a non-Active Directory environment. The following configuration options are supported for LDAP: - ldapserver + ldapserver Name or IP of LDAP server to connect to. @@ -1179,25 +1215,23 @@ omicron bryanh guest1 - ldapprefix + ldapprefix - String to prepend to the username when building the base DN to - bind as. + String to prepend to the username when forming the DN to bind as. - ldapsuffix + ldapsuffix - String to append to the username when building the base DN to - bind as. + String to append to the username when forming the DN to bind as. - ldapport + ldapport Port number on LDAP server to connect to. If no port is specified, @@ -1206,13 +1240,13 @@ omicron bryanh guest1 - ldaptls + ldaptls - Set to 1 to make the connection between PostgreSQL and the + Set to 1 to make the connection between PostgreSQL and the LDAP server use TLS encryption. Note that this only encrypts - the traffic to the LDAP server - the connection to the client - may still be unencrypted unless TLS is used there as well. + the traffic to the LDAP server — the connection to the client + will still be unencrypted unless SSL is used. @@ -1222,8 +1256,8 @@ omicron bryanh guest1 Since LDAP often uses commas and spaces to separate the different - parts of a DN, it is advised to always use double-quoted parameter - values when configuring LDAP options, such as: + parts of a DN, it is often necessary to use double-quoted parameter + values when configuring LDAP options, for example: @@ -1243,11 +1277,27 @@ ldapserver=ldap.example.net prefix="cn=" suffix="dc=example, dc=net" This authentication method uses SSL client certificates to perform authentication. It is therefore only available for SSL connections. When using this authentication method, the server will require that - the client provide a certificate. No password prompt will be sent + the client provide a valid certificate. No password prompt will be sent to the client. The cn attribute of the certificate - will be compared to the login username, and if they match the - login will be allowed. Username mapping can be used if the usernames - don't match. + will be compared to the requested database username, and if they match + the login will be allowed. Username mapping can be used to allow + cn to be different from the database username. + + + + The following configuration options are supported for SSL certificate + authentication: + + + map + + + Allows for mapping between system and database usernames. See + for details. + + + + @@ -1265,7 +1315,7 @@ ldapserver=ldap.example.net prefix="cn=" suffix="dc=example, dc=net" default PAM service name is postgresql. PAM is used only to validate user name/password pairs. Therefore the user must already exist in the database before PAM - can be used for authentication. For more information about + can be used for authentication. For more information about PAM, please read the Linux-PAM Page and the @@ -1276,7 +1326,7 @@ ldapserver=ldap.example.net prefix="cn=" suffix="dc=example, dc=net" The following configuration options are supported for PAM: - pamservice + pamservice PAM service name. @@ -1290,8 +1340,8 @@ ldapserver=ldap.example.net prefix="cn=" suffix="dc=example, dc=net" If PAM is set up to read /etc/shadow, authentication will fail because the PostgreSQL server is started by a non-root - user. However, this is not an issue with LDAP or other authentication - methods. + user. However, this is not an issue when PAM is configured to use + LDAP or other authentication methods. @@ -1301,8 +1351,8 @@ ldapserver=ldap.example.net prefix="cn=" suffix="dc=example, dc=net" Authentication problems - Genuine authentication failures and related problems generally - manifest themselves through error messages like the following. + Authentication failures and related problems generally + manifest themselves through error messages like the following: @@ -1332,7 +1382,7 @@ FATAL: Password authentication failed for user "andym" FATAL: user "andym" does not exist - The indicated user name was not found. + The indicated database user name was not found.