database/postgres
database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-04-27 22:56:53 +03:00
Code

Make an editorial pass over the Client Authentication material.

Browse Source
This commit is contained in:
Tom Lane 2009-05-16 21:17:21 +00:00
parent 3626043229
commit 2d6e2323a4
1 changed files with 176 additions and 126 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

262
doc/src/sgml/client-auth.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/client-auth.sgml,v 1.121 2009/04/11 02:08:34 momjian Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/client-auth.sgml,v 1.122 2009/05/16 21:17:21 tgl Exp $ -->
<chapter id="client-authentication"> <chapter id="client-authentication">
<title>Client Authentication</title> <title>Client Authentication</title>
@ -173,7 +173,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
<term><replaceable>database</replaceable></term> <term><replaceable>database</replaceable></term>
<listitem> <listitem>
<para> <para>
Specifies which database names this record matches. The value Specifies which database name(s) this record matches. The value
<literal>all</literal> specifies that it matches all databases. <literal>all</literal> specifies that it matches all databases.
The value <literal>sameuser</> specifies that the record The value <literal>sameuser</> specifies that the record
matches if the requested database has the same name as the matches if the requested database has the same name as the
@ -194,7 +194,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
<term><replaceable>user</replaceable></term> <term><replaceable>user</replaceable></term>
<listitem> <listitem>
<para> <para>
Specifies which database user names this record Specifies which database user name(s) this record
matches. The value <literal>all</literal> specifies that it matches. The value <literal>all</literal> specifies that it
matches all users. Otherwise, this is either the name of a specific matches all users. Otherwise, this is either the name of a specific
database user, or a group name preceded by <literal>+</>. database user, or a group name preceded by <literal>+</>.
@ -215,7 +215,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
<listitem> <listitem>
<para> <para>
Specifies the client machine IP address range that this record 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 notation and a CIDR mask length. (IP addresses can only be
specified numerically, not as domain or host names.) The mask specified numerically, not as domain or host names.) The mask
length indicates the number of high-order bits of the client length indicates the number of high-order bits of the client
@ -275,7 +275,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
<term><replaceable>auth-method</replaceable></term> <term><replaceable>auth-method</replaceable></term>
<listitem> <listitem>
<para> <para>
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 this record. The possible choices are summarized here; details
are in <xref linkend="auth-methods">. are in <xref linkend="auth-methods">.
@ -323,7 +323,6 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
authentication. authentication.
Since the password is sent in clear text over the Since the password is sent in clear text over the
network, this should not be used on untrusted networks. network, this should not be used on untrusted networks.
It also does not usually work with threaded client applications.
See <xref linkend="auth-password"> for details. See <xref linkend="auth-password"> for details.
</para> </para>
</listitem> </listitem>
@ -369,9 +368,8 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
Obtain the operating system user name of the client (for Obtain the operating system user name of the client (for
TCP/IP connections by contacting the ident server on the TCP/IP connections by contacting the ident server on the
client, for local connections by getting it from the client, for local connections by getting it from the
operating system) and check if the user is allowed to operating system) and check if it matches the requested
connect as the requested database user by consulting the map database user name.
specified after the <literal>ident</literal> key word.
See <xref linkend="auth-ident"> for details. See <xref linkend="auth-ident"> for details.
</para> </para>
</listitem> </listitem>
@ -381,7 +379,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
<term><literal>ldap</></term> <term><literal>ldap</></term>
<listitem> <listitem>
<para> <para>
Authenticate using LDAP to a central server. See <xref Authenticate using an LDAP server. See <xref
linkend="auth-ldap"> for details. linkend="auth-ldap"> for details.
</para> </para>
</listitem> </listitem>
@ -417,10 +415,10 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
<term><replaceable>auth-options</replaceable></term> <term><replaceable>auth-options</replaceable></term>
<listitem> <listitem>
<para> <para>
This field contains zero or more name-value pairs with After the <replaceable>auth-method</> field, there can be field(s) of
extra options passed to this authentication method. Details the form <replaceable>name</><literal>=</><replaceable>value</> that
about which options are available for which authentication specify options for the authentication method. Details about which
method appear below. options are available for which authentication method appear below.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -493,7 +491,7 @@ local all all trust
# TYPE DATABASE USER CIDR-ADDRESS METHOD # 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 # 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
@ -505,14 +503,14 @@ host all all 127.0.0.1 255.255.255.255 trust
# TYPE DATABASE USER CIDR-ADDRESS METHOD # TYPE DATABASE USER CIDR-ADDRESS METHOD
host postgres all 192.168.93.0/24 ident 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. # "postgres" if the user's password is correctly supplied.
# #
# TYPE DATABASE USER CIDR-ADDRESS METHOD # TYPE DATABASE USER CIDR-ADDRESS METHOD
host postgres all 192.168.12.10/32 md5 host postgres all 192.168.12.10/32 md5
# In the absence of preceding "host" lines, these two lines will # 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 # matched first), but allow Kerberos 5 connections from anywhere else
# on the Internet. The zero mask means that no bits of the host IP # on the Internet. The zero mask means that no bits of the host IP
# address are considered so it matches any host. # address are considered so it matches any host.
@ -560,22 +558,21 @@ local db1,db2,@demodbs all md5
<para> <para>
When using an external authentication system like Ident or GSSAPI, When using an external authentication system like Ident or GSSAPI,
the name of the operating system user that initiated the connection may the name of the operating system user that initiated the connection
not be the same as the database user he is requesting to connect as. 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 In this case, a user name map can be applied to map the operating system
username to a database user, using the <filename>pg_ident.conf</filename> username to a database user. To use username mapping, specify
file. In order to use username mapping, specify
<literal>map</literal>=<replaceable>map-name</replaceable> <literal>map</literal>=<replaceable>map-name</replaceable>
in the options field in <filename>pg_hba.conf</filename>. This option is in the options field in <filename>pg_hba.conf</filename>. This option is
supported for all authentication methods that receive external usernames. supported for all authentication methods that receive external usernames.
Since the <filename>pg_ident.conf</filename> 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 the name of the map to be used is specified in the
<replaceable>map-name</replaceable> parameter in <filename>pg_hba.conf</filename> <replaceable>map-name</replaceable> parameter in <filename>pg_hba.conf</filename>
to indicate which map to use for each individual connection. to indicate which map to use for each individual connection.
</para> </para>
<para> <para>
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
<filename>pg_ident.conf</><indexterm><primary>pg_ident.conf</primary></indexterm> <filename>pg_ident.conf</><indexterm><primary>pg_ident.conf</primary></indexterm>
and is stored in the and is stored in the
cluster's data directory. (It is possible to place the map file cluster's data directory. (It is possible to place the map file
@ -589,26 +586,50 @@ local db1,db2,@demodbs all md5
<filename>pg_hba.conf</>. The <filename>pg_hba.conf</>. The
<replaceable>map-name</> is an arbitrary name that will be used to <replaceable>map-name</> is an arbitrary name that will be used to
refer to this mapping in <filename>pg_hba.conf</filename>. The other refer to this mapping in <filename>pg_hba.conf</filename>. The other
two fields specify which operating system user is allowed to connect two fields specify an operating system user name and a matching
as which database user. The same <replaceable>map-name</> can be database user name. The same <replaceable>map-name</> can be
used repeatedly to specify more user-mappings within a single map. used repeatedly to specify multiple user-mappings within a single map.
</para>
<para>
There is no restriction regarding how many database users a given 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 <quote>this operating system
user is allowed to connect as this database user</quote>, 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.
</para> </para>
<para> <para>
If the <replaceable>system-username</> field starts with a slash (<literal>/</>), If the <replaceable>system-username</> field starts with a slash (<literal>/</>),
the contents of the field is treated as a regular expression. This regular the remainder of the field is treated as a regular expression.
expression supports a single capture, which can be back-referenced as (See <xref linkend="posix-syntax-details"> for details of
<literal>\1</> (backslash-one). This allows the mapping of different syntax <productname>PostgreSQL</>'s regular expression syntax.
names with a single line. Regular expressions in username maps are always treated as being
<quote>advanced</> flavor.) The regular
expression can include a single capture, or parenthesized subexpression,
which can then be referenced in the <replaceable>database-username</>
field as <literal>\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
<programlisting> <programlisting>
mymap /(.*)@mydomain.com \1 mymap /^(.*)@mydomain\.com$ \1
mymap /(.*)@otherdomain.com guest mymap /^(.*)@otherdomain\.com$ guest
</programlisting> </programlisting>
will "remove" the domain part for users with system usernames @mydomain.com, and will remove the domain part for users with system usernames that end with
allow all users from @otherdomain.com to log in as guest. <literal>@mydomain.com</>, and allow any user whose system name ends with
<literal>@otherdomain.com</> to log in as <literal>guest</>.
</para> </para>
<tip>
<para>
Keep in mind that by default, a regular expression can match just part of
a string. It's usually wise to use <literal>^</> and <literal>$</>, as
shown in the above example, to force the match to be to the entire
system username.
</para>
</tip>
<para> <para>
The <filename>pg_ident.conf</filename> file is read on start-up and The <filename>pg_ident.conf</filename> file is read on start-up and
when the main server process receives a when the main server process receives a
@ -638,7 +659,7 @@ mymap /(.*)@otherdomain.com guest
<example id="example-pg-ident.conf"> <example id="example-pg-ident.conf">
<title>An example <filename>pg_ident.conf</> file</title> <title>An example <filename>pg_ident.conf</> file</title>
<programlisting> <programlisting>
# MAPNAME IDENT-USERNAME PG-USERNAME # MAPNAME SYSTEM-USERNAME PG-USERNAME
omicron bryanh bryanh omicron bryanh bryanh
omicron ann ann omicron ann ann
@ -663,7 +684,7 @@ omicron bryanh guest1
When <literal>trust</> authentication is specified, When <literal>trust</> authentication is specified,
<productname>PostgreSQL</productname> assumes that anyone who can <productname>PostgreSQL</productname> assumes that anyone who can
connect to the server is authorized to access the database with 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 <literal>database</> and Of course, restrictions made in the <literal>database</> and
<literal>user</> columns still apply. <literal>user</> columns still apply.
This method should only be used when there is adequate This method should only be used when there is adequate
@ -687,9 +708,10 @@ omicron bryanh guest1
<para> <para>
Setting file-system permissions only helps for Unix-socket connections. Setting file-system permissions only helps for Unix-socket connections.
Local TCP/IP connections are not restricted by it; therefore, if you want Local TCP/IP connections are not restricted by file-system permissions.
to use file-system permissions for local security, remove the <literal>host ... Therefore, if you want to use file-system permissions for local security,
127.0.0.1 ...</> line from <filename>pg_hba.conf</>, or change it to a remove the <literal>host ... 127.0.0.1 ...</> line from
<filename>pg_hba.conf</>, or change it to a
non-<literal>trust</> authentication method. non-<literal>trust</> authentication method.
</para> </para>
@ -715,7 +737,7 @@ omicron bryanh guest1
</indexterm> </indexterm>
<para> <para>
The password-based authentication methods are <literal>md5</>, The password-based authentication methods are <literal>md5</>
and <literal>password</>. These methods operate and <literal>password</>. These methods operate
similarly except for the way that the password is sent across the similarly except for the way that the password is sent across the
connection: respectively, MD5-hashed and clear-text. connection: respectively, MD5-hashed and clear-text.
@ -725,8 +747,11 @@ omicron bryanh guest1
If you are at all concerned about password If you are at all concerned about password
<quote>sniffing</> attacks then <literal>md5</> is preferred. <quote>sniffing</> attacks then <literal>md5</> is preferred.
Plain <literal>password</> should always be avoided if possible. Plain <literal>password</> should always be avoided if possible.
<literal>md5</> cannot be used with <xref However, <literal>md5</> cannot be used with the <xref
linkend="guc-db-user-namespace">. linkend="guc-db-user-namespace"> feature. If the connection is
protected by SSL encryption then <literal>password</> can be used
safely (though SSL certificate authentication might be a better
choice if one is depending on using SSL).
</para> </para>
<para> <para>
@ -758,14 +783,14 @@ omicron bryanh guest1
authentication according to RFC 1964. <productname>GSSAPI</productname> authentication according to RFC 1964. <productname>GSSAPI</productname>
provides automatic authentication (single sign-on) for systems provides automatic authentication (single sign-on) for systems
that support it. The authentication itself is secure, but the 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
<acronym>SSL</acronym> is used. <acronym>SSL</acronym> is used.
</para> </para>
<para> <para>
When <productname>GSSAPI</productname> uses When <productname>GSSAPI</productname> uses
<productname>Kerberos</productname>, it uses a standard principal <productname>Kerberos</productname>, it uses a standard principal
in format in the format
<literal><replaceable>servicename</>/<replaceable>hostname</>@<replaceable>realm</></literal>. For information about the parts of the principal, and <literal><replaceable>servicename</>/<replaceable>hostname</>@<replaceable>realm</></literal>. For information about the parts of the principal, and
how to set up the required keys, see <xref linkend="kerberos-auth">. how to set up the required keys, see <xref linkend="kerberos-auth">.
GSSAPI support has to be enabled when <productname>PostgreSQL</> is built; GSSAPI support has to be enabled when <productname>PostgreSQL</> is built;
@ -776,7 +801,7 @@ omicron bryanh guest1
The following configuration options are supported for <productname>GSSAPI</productname>: The following configuration options are supported for <productname>GSSAPI</productname>:
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>map</term> <term><literal>map</literal></term>
<listitem> <listitem>
<para> <para>
Allows for mapping between system and database usernames. See Allows for mapping between system and database usernames. See
@ -786,23 +811,25 @@ omicron bryanh guest1
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>include_realm</term> <term><literal>include_realm</literal></term>
<listitem> <listitem>
<para> <para>
Include the realm name from the authenticated user principal. This is useful If set to <literal>1</>, the realm name from the authenticated user
in combination with Username maps (See <xref linkend="auth-username-maps"> principal is included in the system user name that's passed through
for details), especially with regular expressions, to map users from username mapping (<xref linkend="auth-username-maps">). This is
multiple realms. useful for handling users from multiple realms.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>krb_realm</term> <term><literal>krb_realm</literal></term>
<listitem> <listitem>
<para> <para>
Sets the realm to match user principal names against. If this parameter 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.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -839,7 +866,7 @@ omicron bryanh guest1
The following configuration options are supported for <productname>SSPI</productname>: The following configuration options are supported for <productname>SSPI</productname>:
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>map</term> <term><literal>map</literal></term>
<listitem> <listitem>
<para> <para>
Allows for mapping between system and database usernames. See Allows for mapping between system and database usernames. See
@ -849,23 +876,25 @@ omicron bryanh guest1
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>include_realm</term> <term><literal>include_realm</literal></term>
<listitem> <listitem>
<para> <para>
Include the realm name from the authenticated user principal. This is useful If set to <literal>1</>, the realm name from the authenticated user
in combination with Username maps (See <xref linkend="auth-username-maps"> principal is included in the system user name that's passed through
for details), especially with regular expressions, to map users from username mapping (<xref linkend="auth-username-maps">). This is
multiple realms. useful for handling users from multiple realms.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>krb_realm</term> <term><literal>krb_realm</literal></term>
<listitem> <listitem>
<para> <para>
Sets the realm to match user principal names against. If this parameter 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.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -923,7 +952,8 @@ omicron bryanh guest1
client side using the <literal>krbsrvname</> connection parameter. (See client side using the <literal>krbsrvname</> connection parameter. (See
also <xref linkend="libpq-connect">.) The installation default can be also <xref linkend="libpq-connect">.) The installation default can be
changed from the default <literal>postgres</literal> at build time using changed from the default <literal>postgres</literal> at build time using
<literal>./configure --with-krb-srvnam=whatever</>. In most environments, <literal>./configure --with-krb-srvnam=</><replaceable>whatever</>.
In most environments,
this parameter never needs to be changed. However, to support multiple this parameter never needs to be changed. However, to support multiple
<productname>PostgreSQL</> installations on the same host it is necessary. <productname>PostgreSQL</> installations on the same host it is necessary.
Some Kerberos implementations might also require a different service name, Some Kerberos implementations might also require a different service name,
@ -940,10 +970,13 @@ omicron bryanh guest1
<para> <para>
Client principals must have their <productname>PostgreSQL</> database user Client principals must have their <productname>PostgreSQL</> database user
name as their first component, for example name as their first component, for example
<literal>pgusername@realm</>. By default, the realm of the client is <literal>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 <productname>PostgreSQL</>. If you have cross-realm not checked by <productname>PostgreSQL</>. If you have cross-realm
authentication enabled and need to verify the realm, use the authentication enabled and need to verify the realm, use the
krb_realm parameter in <filename>pg_hba.conf</>. <literal>krb_realm</> parameter, or enable <literal>include_realm</>
and use username mapping to check the realm.
</para> </para>
<para> <para>
@ -987,10 +1020,11 @@ omicron bryanh guest1
</para> </para>
<para> <para>
The following configuration options are supported for <productname>Kerberos</productname>: The following configuration options are supported for
<productname>Kerberos</productname>:
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>map</term> <term><literal>map</literal></term>
<listitem> <listitem>
<para> <para>
Allows for mapping between system and database usernames. See Allows for mapping between system and database usernames. See
@ -1000,29 +1034,31 @@ omicron bryanh guest1
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>include_realm</term> <term><literal>include_realm</literal></term>
<listitem> <listitem>
<para> <para>
Include the realm name from the authenticated user principal. This is useful If set to <literal>1</>, the realm name from the authenticated user
in combination with Username maps (See <xref linkend="auth-username-maps"> principal is included in the system user name that's passed through
for details), especially with regular expressions, to map users from username mapping (<xref linkend="auth-username-maps">). This is
multiple realms. useful for handling users from multiple realms.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>krb_realm</term> <term><literal>krb_realm</literal></term>
<listitem> <listitem>
<para> <para>
Sets the realm to match user principal names against. If this parameter 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.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>krb_server_hostname</term> <term><literal>krb_server_hostname</literal></term>
<listitem> <listitem>
<para> <para>
Sets the host name part of the service principal. Sets the host name part of the service principal.
@ -1046,9 +1082,9 @@ omicron bryanh guest1
<para> <para>
The ident authentication method works by obtaining the client's The ident authentication method works by obtaining the client's
operating system user name, then optionally determining the allowed operating system user name and using it as the allowed database user
database user names using a map file that lists the permitted name (with an optional username mapping).
corresponding pairs of names. The determination of the client's The determination of the client's
user name is the security-critical point, and it works differently user name is the security-critical point, and it works differently
depending on the connection type. depending on the connection type.
</para> </para>
@ -1057,7 +1093,7 @@ omicron bryanh guest1
The following configuration options are supported for <productname>ident</productname>: The following configuration options are supported for <productname>ident</productname>:
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>map</term> <term><literal>map</literal></term>
<listitem> <listitem>
<para> <para>
Allows for mapping between system and database usernames. See Allows for mapping between system and database usernames. See
@ -1161,17 +1197,17 @@ omicron bryanh guest1
<para> <para>
The server will bind to the distinguished name constructed as The server will bind to the distinguished name constructed as
<replaceable>prefix</> <replaceable>username</> <replaceable>suffix</>. <replaceable>prefix</> <replaceable>username</> <replaceable>suffix</>.
before the bind. Typically, the prefix parameter is used to specify Typically, the <replaceable>prefix</> parameter is used to specify
<replaceable>cn=</>, or <replaceable>DOMAIN\</> in an Active <literal>cn=</>, or <replaceable>DOMAIN</><literal>\</> in an Active
Directory environment, and suffix is used to specify the remaining part Directory environment. <replaceable>suffix</> is used to specify the
of the DN in a non-Active Directory environment. remaining part of the DN in a non-Active Directory environment.
</para> </para>
<para> <para>
The following configuration options are supported for LDAP: The following configuration options are supported for LDAP:
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>ldapserver</term> <term><literal>ldapserver</literal></term>
<listitem> <listitem>
<para> <para>
Name or IP of LDAP server to connect to. Name or IP of LDAP server to connect to.
@ -1179,25 +1215,23 @@ omicron bryanh guest1
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>ldapprefix</term> <term><literal>ldapprefix</literal></term>
<listitem> <listitem>
<para> <para>
String to prepend to the username when building the base DN to String to prepend to the username when forming the DN to bind as.
bind as.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>ldapsuffix</term> <term><literal>ldapsuffix</literal></term>
<listitem> <listitem>
<para> <para>
String to append to the username when building the base DN to String to append to the username when forming the DN to bind as.
bind as.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>ldapport</term> <term><literal>ldapport</literal></term>
<listitem> <listitem>
<para> <para>
Port number on LDAP server to connect to. If no port is specified, Port number on LDAP server to connect to. If no port is specified,
@ -1206,13 +1240,13 @@ omicron bryanh guest1
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>ldaptls</term> <term><literal>ldaptls</literal></term>
<listitem> <listitem>
<para> <para>
Set to 1 to make the connection between PostgreSQL and the Set to <literal>1</> to make the connection between PostgreSQL and the
LDAP server use TLS encryption. Note that this only encrypts LDAP server use TLS encryption. Note that this only encrypts
the traffic to the LDAP server - the connection to the client the traffic to the LDAP server &mdash; the connection to the client
may still be unencrypted unless TLS is used there as well. will still be unencrypted unless SSL is used.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1222,8 +1256,8 @@ omicron bryanh guest1
<note> <note>
<para> <para>
Since LDAP often uses commas and spaces to separate the different Since LDAP often uses commas and spaces to separate the different
parts of a DN, it is advised to always use double-quoted parameter parts of a DN, it is often necessary to use double-quoted parameter
values when configuring LDAP options, such as: values when configuring LDAP options, for example:
</para> </para>
</note> </note>
<synopsis> <synopsis>
@ -1243,11 +1277,27 @@ ldapserver=ldap.example.net prefix="cn=" suffix="dc=example, dc=net"
This authentication method uses SSL client certificates to perform This authentication method uses SSL client certificates to perform
authentication. It is therefore only available for SSL connections. authentication. It is therefore only available for SSL connections.
When using this authentication method, the server will require that 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 <literal>cn</literal> attribute of the certificate to the client. The <literal>cn</literal> attribute of the certificate
will be compared to the login username, and if they match the will be compared to the requested database username, and if they match
login will be allowed. Username mapping can be used if the usernames the login will be allowed. Username mapping can be used to allow
don't match. <literal>cn</literal> to be different from the database username.
</para>
<para>
The following configuration options are supported for SSL certificate
authentication:
<variablelist>
<varlistentry>
<term><literal>map</literal></term>
<listitem>
<para>
Allows for mapping between system and database usernames. See
<xref linkend="auth-username-maps"> for details.
</para>
</listitem>
</varlistentry>
</variablelist>
</para> </para>
</sect2> </sect2>
@ -1276,7 +1326,7 @@ ldapserver=ldap.example.net prefix="cn=" suffix="dc=example, dc=net"
The following configuration options are supported for PAM: The following configuration options are supported for PAM:
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>pamservice</term> <term><literal>pamservice</literal></term>
<listitem> <listitem>
<para> <para>
PAM service name. PAM service name.
@ -1290,8 +1340,8 @@ ldapserver=ldap.example.net prefix="cn=" suffix="dc=example, dc=net"
<para> <para>
If PAM is set up to read <filename>/etc/shadow</>, authentication If PAM is set up to read <filename>/etc/shadow</>, authentication
will fail because the PostgreSQL server is started by a non-root will fail because the PostgreSQL server is started by a non-root
user. However, this is not an issue with LDAP or other authentication user. However, this is not an issue when PAM is configured to use
methods. LDAP or other authentication methods.
</para> </para>
</note> </note>
</sect2> </sect2>
@ -1301,8 +1351,8 @@ ldapserver=ldap.example.net prefix="cn=" suffix="dc=example, dc=net"
<title>Authentication problems</title> <title>Authentication problems</title>
<para> <para>
Genuine authentication failures and related problems generally Authentication failures and related problems generally
manifest themselves through error messages like the following. manifest themselves through error messages like the following:
</para> </para>
<para> <para>
@ -1332,7 +1382,7 @@ FATAL: Password authentication failed for user "andym"
<programlisting> <programlisting>
FATAL: user "andym" does not exist FATAL: user "andym" does not exist
</programlisting> </programlisting>
The indicated user name was not found. The indicated database user name was not found.
</para> </para>
<para> <para>