From 83aaac41c66959a3ebaec7daadc4885b5f98f561 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter_e@gmx.net>
Date: Tue, 12 Sep 2017 09:46:14 -0400
Subject: Allow custom search filters to be configured for LDAP auth

Before, only filters of the form "(<ldapsearchattribute>=<user>)"
could be used to search an LDAP server.  Introduce ldapsearchfilter
so that more general filters can be configured using patterns, like
"(|(uid=$username)(mail=$username))" and "(&(uid=$username)
(objectClass=posixAccount))".  Also allow search filters to be included
in an LDAP URL.

Author: Thomas Munro
Reviewed-By: Peter Eisentraut, Mark Cave-Ayland, Magnus Hagander
Discussion: https://postgr.es/m/CAEepm=0XTkYvMci0WRubZcf_1am8=gP=7oJErpsUfRYcKF2gwg@mail.gmail.com
---
 doc/src/sgml/client-auth.sgml | 43 +++++++++++++++++++++++++++++++++++++++----
 1 file changed, 39 insertions(+), 4 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index 1b568683a47..405bf268327 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -1507,6 +1507,17 @@ omicron         bryanh                  guest1
         </para>
        </listitem>
       </varlistentry>
+      <varlistentry>
+       <term><literal>ldapsearchfilter</literal></term>
+       <listitem>
+        <para>
+         The search filter to use when doing search+bind authentication.
+         Occurrences of <literal>$username</literal> will be replaced with the
+         user name.  This allows for more flexible search filters than
+         <literal>ldapsearchattribute</literal>.
+        </para>
+       </listitem>
+      </varlistentry>
       <varlistentry>
        <term><literal>ldapurl</literal></term>
        <listitem>
@@ -1514,13 +1525,16 @@ omicron         bryanh                  guest1
          An RFC 4516 LDAP URL.  This is an alternative way to write some of the
          other LDAP options in a more compact and standard form.  The format is
 <synopsis>
-ldap://<replaceable>host</replaceable>[:<replaceable>port</replaceable>]/<replaceable>basedn</replaceable>[?[<replaceable>attribute</replaceable>][?[<replaceable>scope</replaceable>]]]
+ldap://<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 latter.  Only one attribute is used, and some other
-         components of standard LDAP URLs such as filters and extensions are
-         not supported.
+         typically the last.  <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>
@@ -1549,6 +1563,17 @@ ldap://<replaceable>host</replaceable>[:<replaceable>port</replaceable>]/<replac
     for search+bind.
    </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>
     Here is an example for a simple-bind LDAP configuration:
 <programlisting>
@@ -1584,6 +1609,16 @@ host ... ldap ldapurl="ldap://ldap.example.net/dc=example,dc=net?uid?sub"
     same URL format, so it will be easier to share the configuration.
    </para>
 
+   <para>
+    Here is an example for a search+bind configuration that uses
+    <literal>ldapsearchfilter</literal> instead of
+    <literal>ldapsearchattribute</literal> to allow authentication by
+    user ID or email address:
+<programlisting>
+host ... ldap ldapserver=ldap.example.net ldapbasedn="dc=example, dc=net" ldapsearchfilter="(|(uid=$username)(mail=$username))"
+</programlisting>
+   </para>
+
    <tip>
     <para>
      Since LDAP often uses commas and spaces to separate the different
-- 
cgit v1.2.3