Ticket #2507: ldapauthdoc.diff

authentication.txt

@@ -1044 +1044 @@
-password is valid in multiple backends, Django will stop processing at the
-first positive match.
-
+LDAP authentication backend
+---------------------------
+
+Django can also authenticate users against an ldap implementation, such as OpenLDAP.
+To use this backend, in settings.py, ``AUTHENTICATION_BACKENDS`` should read::
+
+    ('django.contrib.auth.contrib.ldapauth.LDAPBackend',)
+
+The LDAP backend needs several additional settings in your settings.py.
+    ``LDAP_SERVER_URI`` -- string, ldap uri.
+        default: 'ldap://localhost'
+    ``LDAP_SEARCHDN`` -- string of the LDAP dn to use for searching
+        default: 'dc=localhost'
+    ``LDAP_SCOPE`` -- one of: ldap.SCOPE_*, used for searching
+        see python-ldap docs for the search function
+        default = ldap.SCOPE_SUBTREE
+    ``LDAP_SEARCH_FILTER`` -- formated string, the filter to use for searching for a
+        user. Used as: filterstr = LDAP_SEARCH_FILTER % username
+        default = 'cn=%s'
+    ``LDAP_UPDATE_FIELDS`` -- boolean, do we sync the db with ldap on each auth
+        default = True
+
+Required unless LDAP_FULL_NAME is set:
+    ``LDAP_FIRST_NAME`` -- string, LDAP attribute to get the given name from
+    ``LDAP_LAST_NAME`` -- string, LDAP attribute to get the last name from
+
+Optional Settings:
+    ``LDAP_FULL_NAME`` -- string, LDAP attribute to get name from, splits on ' '
+    ``LDAP_GID`` -- string, LDAP attribute to get group name/number from
+    ``LDAP_SU_GIDS`` -- list of strings, group names/numbers that are superusers
+    ``LDAP_STAFF_GIDS`` -- list of strings, group names/numbers that are staff
+    ``LDAP_EMAIL`` -- string, LDAP attribute to get email from
+    ``LDAP_DEFAULT_EMAIL_SUFFIX`` -- string, appened to username if no email found
+    ``LDAP_OPTIONS`` -- hash, python-ldap global options and their values
+    {ldap.OPT_X_TLS_CACERTDIR: '/etc/ldap/ca/'}
+
+You must pick a method for determining the DN of a user and set the needed settings:
+    * You can set ``LDAP_BINDDN`` and ``LDAP_BIND_ATTRIBUTE`` like::
+            
+        ``LDAP_BINDDN`` = 'ou=people,dc=example,dc=com'
+        ``LDAP_BIND_ATTRIBUTE`` = 'uid'
+
+     and the user DN would be:
+
+            'uid=%s,ou=people,dc=example,dc=com' % username
+
+    * Look for the DN on the directory, this is what will happen if you do
+      not define the LDAP_BINDDN setting. In that case you may need to
+      define LDAP_PREBINDDN and LDAP_PREBINDPW if your LDAP server does not
+      allow anonymous queries. The search will be performed with the
+      LDAP_SEARCH_FILTER setting.
+
+    * Override the _pre_bind() method, which receives the ldap object and
+      the username as it's parameters and should return the DN of the user.
+
-Writing an authentication backend
----------------------------------
-