document some LDAP settings

configuration.rst

@@ -18,7 +18,7 @@ Authentic 2 can be configured by adding or overriding:
 * `Authentic 2 A2_AUTH_SAML_* settings <https://git.entrouvert.org/authentic.git/tree/src/authentic2_auth_saml/app_settings.py>`__
 * `Authentic 2 A2_IDP_CAS_* settings <https://git.entrouvert.org/authentic.git/tree/src/authentic2_idp_cas/app_settings.py>`__
 * `Authentic 2 A2_IDP_OIDC_* settings <https://git.entrouvert.org/authentic.git/tree/src/authentic2_idp_oidc/app_settings.py>`__
-* `Authentic 2 LDAP_AUTH_SETTINGS <https://git.entrouvert.org/authentic.git/tree/src/authentic2/backends/ldap_backend.py#n531>`__
+* :ref:`configuration_ldap`
 
 The following files will be read, in the following order, and their
 value will override the defaults found in the sources above:

configuration_ldap.rst

@@ -0,0 +1,32 @@
+.. _configuration_ldap:
+
+==================
+LDAP Configuration
+==================
+
+Introduction
+============
+
+The `Authentic LDAP backend <https://git.entrouvert.org/authentic.git/tree/src/authentic2/backends/ldap_backend.py>`__ is configured by overriding the `dictionary <https://git.entrouvert.org/authentic.git/tree/src/authentic2/backends/ldap_backend.py#n531>`__ found in the sources with a `LDAP_AUTH_SETTINGS` dictionary in the Django settings file.
+
+The
+
+Settings
+========
+
+* **url** (required):
+* **basedn** (required): the `distinguished name` used for searching LDAP
+* **binddn** and **bindpw**: if both are set and no credentials were provided by the caller, they will be used as the `distinguished name` and the `password` of the LDAP `bind` function. If they are not set the `bind` function will be anonymous.
+* **bindsasl**: if set and no credentials were provided by the caller, it must be a list of three elements. The first is the string that specifies the LDAP SASL mechanism (for instance 'gssapi', 'cram_md5', etc. See `the documentation for the full list <https://www.python-ldap.org/en/python-ldap-3.3.0/reference/ldap-sasl.html#classes>`__), the second is the `distinguised name` used with the `bind` function, the third is a list that will be provided verbatim to the constructor of the SASL mechanism class.
+* **user_dn_template**: if set the name of the user `username` will be converted into `user_dn_template.format(username=username)`. For instance if `user_dn_template` is `geek({username})`, then the user `foo` will be transformed into `geek(foo)`, the user `bar` will be transformed into `geek(bar)` etc.
+* **user_basedn**: the `distinguished name` used for searching LDAP users (defaults to **basedn** if not set)
+* **user_filter**: the `LDAP filter when searching for users <https://www.python-ldap.org/en/python-ldap-3.3.0/reference/ldap-filter.html#ldap.filter.filter_format>`__ (defaults to 'uid=%s' or '(|(mail=%s)(uid=%s))' if the A2_ACCEPT_EMAIL_AUTHENTICATION setting is set)
+* **sync_ldap_users_filter**: the `LDAP filter <https://www.python-ldap.org/en/python-ldap-3.3.0/reference/ldap-filter.html>`__ when searching for all users (defaults to 'uid=*')
+* **group_basedn**: the `distinguished name` to use when searching for groups (defaults to **basedn**)
+* **member_of_attribute** (required): the LDAP attributes of a LDAP user that are to be interpreted as containing the `distinguished name` of a group to which the user belongs to (defaults to '')
+* **group_filter**: the `LDAP filter when searching for groups <https://www.python-ldap.org/en/python-ldap-3.3.0/reference/ldap-filter.html#ldap.filter.filter_format>`__ (defaults to '(&(member={user_dn})(objectClass=groupOfNames))')
+* **groupsu**: the list of `groupOfNames` for which the `is_admin` flag will be set when a user becomes a member (example [u'cn=group1,o=ôrga'])
+* **groupstaff**: the list of `groupOfNames` for which the `is_staff` flag will be set when a user becomes a member (example [u'cn=group1,o=ôrga'])
+* **groupactive**: the list of `groupOfNames` for which the `is_active` flag will be set when a user becomes a member (example [u'cn=group1,o=ôrga'])
+* **group_mapping**: a list mapping `groupOfNames` to a list of groups names. For instance [[u'cn=group2,o=ôrga', ['Group2']]] will ensure that a user that belongs to the 'cn=group2,o=ôrga' LDAP group also belongs to the Authentic group 'Group2'. The user will be removed from the Authentic groups that are not mentionned in this setting.
+* **group_to_role_mapping**: a list mapping `groupOfNames` to a list of roles names. For instance [[u'cn=group2,o=ôrga', ['Role2']]] will ensure that a user that belongs to the 'cn=group2,o=ôrga' LDAP group also belongs to the Authentic role 'Role2'. The user will be removed from the Authentic roles that are not mentionned in this setting.