From 7356381ef57e6ddb09f1b1c72085e5102d0baa1e Mon Sep 17 00:00:00 2001 From: Magnus Hagander Date: Thu, 23 Oct 2008 13:31:10 +0000 Subject: * make pg_hba authoption be a set of 0 or more name=value pairs * make LDAP use this instead of the hacky previous method to specify the DN to bind as * make all auth options behave the same when they are not compiled into the server * rename "ident maps" to "user name maps", and support them for all auth methods that provide an external username This makes a backwards incompatible change in the format of pg_hba.conf for the ident, PAM and LDAP authentication methods. --- doc/src/sgml/client-auth.sgml | 359 +++++++++++++++++++++++++++--------------- 1 file changed, 230 insertions(+), 129 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml index 61f2b1e2e6c..5a308eb8958 100644 --- a/doc/src/sgml/client-auth.sgml +++ b/doc/src/sgml/client-auth.sgml @@ -1,4 +1,4 @@ - + Client Authentication @@ -96,13 +96,13 @@ A record can have one of the seven formats -local database user auth-method auth-option -host database user CIDR-address auth-method auth-option -hostssl database user CIDR-address auth-method auth-option -hostnossl database user CIDR-address auth-method auth-option -host database user IP-address IP-mask auth-method auth-option -hostssl database user IP-address IP-mask auth-method auth-option -hostnossl database user IP-address IP-mask auth-method auth-option +local database user auth-method auth-options +host database user CIDR-address auth-method auth-options +hostssl database user CIDR-address auth-method auth-options +hostnossl database user CIDR-address auth-method auth-options +host database user IP-address IP-mask auth-method auth-options +hostssl database user IP-address IP-mask auth-method auth-options +hostnossl database user IP-address IP-mask auth-method auth-options The meaning of the fields is as follows: @@ -422,11 +422,13 @@ hostnossl database user - auth-option + auth-options - The meaning of this optional field depends on the chosen - authentication method. Details appear below. + 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. @@ -534,7 +536,7 @@ host all all 0.0.0.0/0 krb5 # "omicron" that says "bryanh" is allowed to connect as "guest1". # # TYPE DATABASE USER CIDR-ADDRESS METHOD -host all all 192.168.0.0/16 ident omicron +host all all 192.168.0.0/16 ident map=omicron # If these are the only three lines for local connections, they will # allow local users to connect only to their own databases (databases @@ -557,6 +559,92 @@ local db1,db2,@demodbs all md5 + + Username maps + + + Username maps + + + + 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. + 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 + 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, + 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 + pg_ident.confpg_ident.conf + and is stored in the + cluster's data directory. (It is possible to place the map file + elsewhere, however; see the + configuration parameter.) + The ident map file contains lines of the general form: + +map-name system-username database-username + + Comments and whitespace are handled in the same way as in + 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. + There is no restriction regarding how many database users a given + operating system user can correspond to, nor vice versa. + + + + The pg_ident.conf file is read on start-up and + when the main server process receives a + SIGHUPSIGHUP + signal. If you edit the file on an + active system, you will need to signal the server + (using pg_ctl reload or kill -HUP) to make it + re-read the file. + + + + A pg_ident.conf file that could be used in + conjunction with the pg_hba.conf file in is shown in . In this example setup, anyone + logged in to a machine on the 192.168 network that does not have the + Unix user name bryanh, ann, or + robert would not be granted access. Unix user + robert would only be allowed access when he tries to + connect as PostgreSQL user bob, not + as robert or anyone else. ann would + only be allowed to connect as ann. User + bryanh would be allowed to connect as either + bryanh himself or as guest1. + + + + An example <filename>pg_ident.conf</> file + +# MAPNAME IDENT-USERNAME PG-USERNAME + +omicron bryanh bryanh +omicron ann ann +# bob has user name robert on these machines +omicron robert bob +# bryanh can also connect as guest1 +omicron bryanh guest1 + + + + Authentication methods @@ -685,7 +773,21 @@ local db1,db2,@demodbs all md5 GSSAPI support has to be enabled when PostgreSQL is built; see for more information. - + + + The following configuration options are supported for GSSAPI: + + + map + + + Allows for mapping between system and database usernames. See + for details. + + + + + @@ -713,6 +815,20 @@ local db1,db2,@demodbs all md5 for details. + + The following configuration options are supported for SSPI: + + + map + + + Allows for mapping between system and database usernames. See + for details. + + + + + @@ -846,6 +962,21 @@ local db1,db2,@demodbs all md5 depending on the connection type. + + The following configuration options are supported for GSSAPI: + + + map + + + Allows for mapping between system and database usernames. See + for details. + + + + + + Ident Authentication over TCP/IP @@ -918,83 +1049,6 @@ local db1,db2,@demodbs all md5 - - Ident Maps - - - When using ident-based authentication, after having determined the - name of the operating system user that initiated the connection, - PostgreSQL checks whether that user is - allowed to connect as the database user he is requesting to connect - as. This is controlled by the ident map argument that follows the - ident key word in the pg_hba.conf - file. If an ident map is not specified, the database user will be - checked with the same name as the operating system user. Other maps - must be created manually. - - - - Ident 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 - elsewhere, however; see the - configuration parameter.) - The ident map file contains lines of the general form: - -map-name ident-username database-username - - Comments and whitespace are handled in the same way as in - 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. - There is no restriction regarding how many database users a given - operating system user can correspond to, nor vice versa. - - - - The pg_ident.conf file is read on start-up and - when the main server process receives a - SIGHUPSIGHUP - signal. If you edit the file on an - active system, you will need to signal the server - (using pg_ctl reload or kill -HUP) to make it - re-read the file. - - - - A pg_ident.conf file that could be used in - conjunction with the pg_hba.conf file in is shown in . In this example setup, anyone - logged in to a machine on the 192.168 network that does not have the - Unix user name bryanh, ann, or - robert would not be granted access. Unix user - robert would only be allowed access when he tries to - connect as PostgreSQL user bob, not - as robert or anyone else. ann would - only be allowed to connect as ann. User - bryanh would be allowed to connect as either - bryanh himself or as guest1. - - - - An example <filename>pg_ident.conf</> file - -# MAPNAME IDENT-USERNAME PG-USERNAME - -omicron bryanh bryanh -omicron ann ann -# bob has user name robert on these machines -omicron robert bob -# bryanh can also connect as guest1 -omicron bryanh guest1 - - - @@ -1007,49 +1061,84 @@ omicron bryanh guest1 This authentication method operates similarly to password except that it uses LDAP - as the authentication method. LDAP is used only to validate + as the password verification method. LDAP is used only to validate the user name/password pairs. Therefore the user must already exist in the database before LDAP can be used for - authentication. The server and parameters used are specified - after the ldap key word in the file - pg_hba.conf. The format of this parameter is: - -ldap[s]://servername[:port]/base dn[;prefix[;suffix]] - - Commas are used to specify multiple items in an ldap - component. However, because unquoted commas are treated as item - separators in pg_hba.conf, it is wise to - double-quote the ldap URL to preserve any commas present, - e.g.: - -"ldap://ldap.example.net/dc=example,dc=net;EXAMPLE\" - - - - - If ldaps is specified instead of ldap, - TLS encryption will be enabled for the connection. Note that this - will encrypt only the connection between the PostgreSQL server - and the LDAP server. The connection between the client and the - PostgreSQL server is not affected by this setting. To make use of - TLS encryption, you might need to configure the LDAP library prior - to configuring PostgreSQL. Note that encrypted LDAP is available only - if the platform's LDAP library supports it. - - - If no port is specified, the default port as configured in the - LDAP library will be used. + authentication. + - The server will bind to the distinguished name specified as - base dn using the user name supplied by the client. - If prefix and suffix is - specified, it will be prepended and appended to the user name + 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. + Directory environment, and 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 + + + Name or IP of LDAP server to connect to. + + + + + ldapprefix + + + String to prepend to the username when building the base DN to + bind as. + + + + + ldapsuffix + + + String to append to the username when building the base DN to + bind as. + + + + + ldapport + + + Port number on LDAP server to connect to. If no port is specified, + the default port in the LDAP library will be used. + + + + + ldaptls + + + 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. + + + + + + + + + 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: + + + +ldapserver=ldap.example.net prefix="cn=" suffix="dc=example, dc=net" + + @@ -1063,9 +1152,7 @@ ldap[s]://servername[:port]/password except that it uses PAM (Pluggable Authentication Modules) as the authentication mechanism. The - default PAM service name is postgresql. You can - optionally supply your own service name after the pam - key word in the file pg_hba.conf. + 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 @@ -1075,6 +1162,20 @@ ldap[s]://servername[:port]/Solaris PAM Page. + + The following configuration options are supported for PAM: + + + pamservice + + + PAM service name. + + + + + + If PAM is set up to read /etc/shadow, authentication -- cgit v1.2.3