adding ldap bundle to doc

source/bundles/index.rst

@@ -21,6 +21,7 @@ You will find here documentation about bundles working with Chill.
     Activity bundle <activity.rst>
     Group bundle <group.rst>
     Event bundle <event.rst>
+    Ldap bundle (synchronisation between ldap and database) <ldap.rst>
 
 Your bundle here ?
 -------------------

source/bundles/ldap.rst

@@ -0,0 +1,204 @@
+.. Copyright (C)  2014 Champs Libres Cooperative SCRLFS
+   Permission is granted to copy, distribute and/or modify this document
+   under the terms of the GNU Free Documentation License, Version 1.3
+   or any later version published by the Free Software Foundation;
+   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+   A copy of the license is included in the section entitled "GNU
+   Free Documentation License".
+
+.. _ldap-bundle:
+
+LDAP bundle
+###########
+
+This bundle binds the database with an ldap directory.
+
+The bundle synchronize the ldap directory with users in the database. It also
+provides a way to check user credentials against the ldap directory.
+
+
+.. contents:: Table of content
+   :local:
+
+Current limitations
+*******************
+
+- The length of the ldap dn must be < 255 characters
+- if the username extracted from the ldap is updated, the changes are not reflected in the database and remains the same
+
+
+Entities provided
+*****************
+
+This bundle provides only one entity : :class:`Chill\\LdapBundle\\Entity\\UserLdapBinding`
+
+How the synchronizer works ?
+****************************
+
+#. The synchronizer performs a query on :code:`dn` and :code:`query` defined in the :ref:`configuration <configuration>`.
+#. For each entry returned by the query, it looks if the :code:`dn` exists in the database
+
+   #. If the entry does not exists :
+
+      #. the synchronizer looks for user with same username as defined by :code:`username_attr`, and bind it with the :code:`dn` if it exists.
+      #. else, a user is created with username defined by :code:`username_attr` (if the ldap contains more than one attribute, the first attribute returned is used)
+
+   #. if a user exists which is already binded with the :code:`dn`, the entry is ignored.
+
+#. The synchronizer looks for dn existing in database and which were not returned by the query performed in 1. 
+
+   #. If they exists, those user are set to :code:`enabled=false`: they are not allowed to login.
+
+Installation
+************
+
+This bundle requires : 
+
+- PHP LDAP ext
+- :code:`symfony/ldap` with minimal version 3.1. Note that, currently, Chill uses Symfony 2.8: you should add the dependency on this single package manually
+
+In your composer.json, for stable version : 
+
+.. code-block:: json
+
+   "require": {
+           // .. other dependencies 
+           "symfony/ldap" : "~3.1",
+           "chill-project/ldap": "~1.0"
+   }
+
+
+
+And for dev version :
+
+.. code-block:: json
+
+   "require": {
+           // .. other dependencies 
+           "symfony/ldap" : "~3.1",
+           "chill-project/ldap": "dev-master@dev"
+   }
+
+
+.. _configuration:
+
+Configuration
+**************
+
+Configuration of the bundle
+============================
+
+.. code-block:: yaml
+
+   # Default configuration for extension with alias: "chill_ldap"
+   chill_ldap:
+       server:               # Required
+
+           # the host of the ldap directory
+           host:                 ~ # Required, Example: localhost
+
+           # the port to reach the ldap directory
+           port:                 389
+
+           # the version of the ldap directory
+           version:              3
+
+           # Is the use of ssl required to establish connection
+           use_ssl:              false
+
+           # Is the use of startssl required to establish connection
+           use_starttls:         false
+
+           # the user to bind to dn directory. Required for searching existing users.
+           bind_dn:              ~ # Required, Example: cn=user,dn=chill,dn=social
+
+           # the user's password to bind to dn directory.
+           bind_password:        ~ # Required, Example: paSSw0rD
+       user_query:           # Required
+
+           # The DN where the query is executed
+           dn:                   ~ # Example: ou=People,dc=champs-libres,dc=coop
+
+           # The query which will allow to retrieve users
+           query:                ~ # Example: (&(objectClass=inetOrgPerson)(userPassword=*))
+
+           # The attribute which will provide username (=login)
+           username_attr:        cn
+
+
+Example : 
+
+.. code-block:: yaml
+
+   chill_ldap:
+       server:
+           # host, bind_dn and bind_password are imported from parameters.yml
+           host: "%ldap_host%"
+           bind_dn: "%ldap_bind_dn%"
+           bind_password: "%ldap_bind_password%"
+       user_query:
+           dn: dc=champs-libres,dc=coop
+           query: "(&(objectClass=inetOrgPerson)(userPassword=*))"
+
+
+Configuration of the security part of chill
+============================================
+
+Simply add the following config in the firewall of the security bundle :
+`chill_ldap_form_login: ~`. This config is located in `app/config/security.yml`
+
+Example of a configuration : 
+
+.. code-block:: yaml
+
+   # in app/config/security.yml
+
+       firewalls:
+           dev:
+               pattern: ^/(_(profiler|wdt)|css|images|js)/
+               security: false
+
+           default:
+               anonymous: ~
+               # enable the login check by a form, agaisnt the database
+               form_login:
+                   csrf_parameter: _csrf_token
+                   csrf_token_id: authenticate
+                   csrf_provider: form.csrf_provider
+               # enable the login check by a form, against the ldap
+               chill_ldap_form_login: ~ # this is the line you should add
+
+
+Note that, if you enable the login check by form **and** by the ldap, 
+the password will be checked against the database **and** against the ldap.
+If one of them match, the login will succeed.
+
+If you want to completely disable login check against the database, 
+simply remove the :code:`form_login` entry and all his options.
+
+.. _command-and-crontab:
+
+Command and crontab
+===================
+
+Synchronize the database : 
+
+.. code-block:: bash
+
+   php app/console chill:ldap:synchronize
+
+
+For getting more debug message : 
+
+.. code-block:: bash
+
+   php app/console chill:ldap:synchronize -vvv
+
+
+
+You should run this command regularly (using crontab or 
+`systemd timer <https://www.freedesktop.org/software/systemd/man/systemd.timer.html#>`_)
+to synchronize ldap and database automatically.
+
+
+