Add rudimentary Active Directory LDAP auth support

* Active Directory organises the LDAP directory in an unusual fashion,
  and to complicate matters, it's unlikely that two AD's will have the
  same layout in the field.

* This patch tries to make the LDAP authentication mechanism a bit more
  generic. It introduces two new config fields: basedn and sfilter.

  - basedn is the "base distinguished name" to start the search on.
    Usually, this is the root of your AD.

  - sfilter is the search filter, to look up the user account that
    has just authenticated.

* How this works in practice: LDAP binding is done with an account in
  in the form of user@domain.example.com. The cn associated with this
  account does not necessarily have anything in common with "user", but
  the field sAMAccountName likely contains "user". So, using a basedn
  and search filter, the LDAP entry is looked up, and the rest of the
  code proceeds as normal.

Change-Id: Ic5d5900a612a9cda2716cd88d68b3c1635fb501b

2 files changed, 31 insertions, 1 deletions

diff --git a/cauth/auth/password.py b/cauth/auth/password.py
index d9f356d..02543c6 100644
--- a/cauth/auth/password.py
+++ b/cauth/auth/password.py
@@ -98,7 +98,9 @@ class LDAPAuthPlugin(BasePasswordAuthPlugin):
             logger.error('Client unable to bind on LDAP invalid credentials.')
             raise base.UnauthenticatedError('invalid credentials')
 
-        result = conn.search_s(who, ldap.SCOPE_SUBTREE, '(cn=*)',
+        basedn = self.conf.get('basedn', who)
+        sfilter = self.conf.get('sfilter', '(cn=*)') % {'username': username}
+        result = conn.search_s(basedn, ldap.SCOPE_SUBTREE, sfilter,
                                attrlist=[self.conf['sn'], self.conf['mail']])
         if len(result) == 1:
             user = result[0]  # user is a tuple
diff --git a/doc/source/authentication.rst b/doc/source/authentication.rst
index e7afa2e..7a6c612 100644
--- a/doc/source/authentication.rst
+++ b/doc/source/authentication.rst
@@ -112,6 +112,34 @@ LDAP
 * **sn**: the attribute to use for the full name
 * **mail**: the attribute to use as the user's e-mail
 
+LDAP (for Active Directory)
+,,,,,,,,,,,,,,,,,,,,,,,,,,,
+
+This example illustrates how to use LDAP authentication in a more
+arbitrary scenario. In this case, the user account used to bind to the
+directory does not map directly to the cn, and a search filter has to
+look up the user's information.
+
+.. code-block:: python
+
+   auth = {
+      'ldap': {
+          'host': 'ldap://adc00.branch.example.com',
+          'dn': '%(username)s@branch.example.com',
+          'basedn': 'ou=people,dc=branch,dc=example,dc=com',
+          'sfilter': '(&(objectClass=user)(sAMAccountName=%(username)s))',
+          'sn': 'name',
+          'mail': 'mail',
+      },
+   }
+
+* **host**: the ldap URI to bind to
+* **dn**: the user's login, used to bind to the ldap directory
+* **basedn**: the base distinguished name, used to start the ldap search from
+* **sfilter**: the search filter, used to match the user's entry
+* **sn**: the attribute to use for the full name
+* **mail**: the attribute to use as the user's e-mail
+
 Login with GitHub
 -----------------