linkend="auth-ldap"> for details.
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.
# 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
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
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
An example <filename>pg_ident.conf</> file
-# MAPNAME IDENT-USERNAME PG-USERNAME
+# MAPNAME SYSTEM-USERNAME PG-USERNAME
omicron bryanh bryanh
omicron ann ann
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
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.
- 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.
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
- linkend="guc-db-user-namespace">.
+ However,
md5 cannot be used with the
+ linkend="guc-db-user-namespace"> 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).
GSSAPI is an industry-standard protocol
- for secure authentication defined in RFC 2743.
+ for secure authentication defined in RFC 2743.
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
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; The following configuration options are supported for
GSSAPI:
- map
+ map
Allows for mapping between system and database usernames. See
- 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.
- 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
- When using
Kerberos authentication,
-
SSPI works the same way
+ When using
Kerberos authentication,
+
SSPI works the same way
for details.
The following configuration options are supported for
SSPI:
- map
+ map
Allows for mapping between system and database usernames. See
- 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.
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
can be good starting points for exploration.
Several sources for
Kerberos distributions exist. 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,
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.
- 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
- The following configuration options are supported for
Kerberos:
+ The following configuration options are supported for
- map
+ map
Allows for mapping between system and database usernames. See
- 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.
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.
The following configuration options are supported for
ident:
- map
+ map
Allows for mapping between system and database usernames. See
On systems supporting SO_PEERCRED requests for
Unix-domain sockets (currently
class="osname">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.
The server will bind to the distinguished name constructed as
prefix username suffix.
- before the bind. Typically, the prefix parameter is used to specify
- <replaceable>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
+ <literal>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.
- 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,
- 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.
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:
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.
+
+
+
+
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
The following configuration options are supported for PAM:
- pamservice
+ pamservice
PAM service name.
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.
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:
FATAL: user "andym" does not exist
- The indicated user name was not found.
+ The indicated database user name was not found.
projects / postgresql.git / commitdiff