The following option may be used as an alternative way to write some of the
above LDAP options in a more compact and standard form:
<variablelist>
<varlistentry>
<term><literal>ldapurl</literal></term>
<listitem>
<para>
An <ulink url="https://datatracker.ietf.org/doc/html/rfc4516">RFC 4516</ulink>
LDAP URL. The format is
<synopsis>
ldap[s]://<replaceable>host</replaceable>[:<replaceable>port</replaceable>]/<replaceable>basedn</replaceable>[?[<replaceable>attribute</replaceable>][?[<replaceable>scope</replaceable>][?[<replaceable>filter</replaceable>]]]]
</synopsis>
<replaceable>scope</replaceable> must be one
of <literal>base</literal>, <literal>one</literal>, <literal>sub</literal>,
typically the last. (The default is <literal>base</literal>, which
is normally not useful in this application.) <replaceable>attribute</replaceable> can
nominate a single attribute, in which case it is used as a value for
<literal>ldapsearchattribute</literal>. If
<replaceable>attribute</replaceable> is empty then
<replaceable>filter</replaceable> can be used as a value for
<literal>ldapsearchfilter</literal>.
</para>
<para>
The URL scheme <literal>ldaps</literal> chooses the LDAPS method for
making LDAP connections over SSL, equivalent to using
<literal>ldapscheme=ldaps</literal>. To use encrypted LDAP
connections using the <literal>StartTLS</literal> operation, use the
normal URL scheme <literal>ldap</literal> and specify the
<literal>ldaptls</literal> option in addition to
<literal>ldapurl</literal>.
</para>
<para>
For non-anonymous binds, <literal>ldapbinddn</literal>
and <literal>ldapbindpasswd</literal> must be specified as separate
options.
</para>
<para>
LDAP URLs are currently only supported with
<productname>OpenLDAP</productname>, not on Windows.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
It is an error to mix configuration options for simple bind with options
for search+bind. To use <literal>ldapurl</literal> in simple bind mode, the
URL must not contain a <literal>basedn</literal> or query elements.
</para>
<para>
When using search+bind mode, the search can be performed using a single
attribute specified with <literal>ldapsearchattribute</literal>, or using
a custom search filter specified with
<literal>ldapsearchfilter</literal>.
Specifying <literal>ldapsearchattribute=foo</literal> is equivalent to
specifying <literal>ldapsearchfilter="(foo=$username)"</literal>. If neither
option is specified the default is
<literal>ldapsearchattribute=uid</literal>.
</para>
<para>
If <productname>PostgreSQL</productname> was compiled with
<productname>OpenLDAP</productname> as the LDAP client library, the
<literal>ldapserver</literal> setting may be omitted. In that case, a
list of host names and ports is looked up via
<ulink url="https://datatracker.ietf.org/doc/html/rfc2782">RFC 2782</ulink> DNS SRV records.
The name <literal>_ldap._tcp.DOMAIN</literal> is looked up, where
<literal>DOMAIN</literal> is extracted from <literal>ldapbasedn</literal>.
</para>
<para>
Here is an example for a simple-bind LDAP configuration:
<programlisting>
host ... ldap ldapserver=ldap.example.net ldapprefix="cn=" ldapsuffix=", dc=example, dc=net"
</programlisting>
When a connection to the database server as database
user <literal>someuser</literal> is requested, PostgreSQL will attempt to
bind to the LDAP server using the DN <literal>cn=someuser, dc=example,
dc=net</literal> and the password provided by the client. If that connection
succeeds, the database access is granted.
</para>