From 372dbc94e33e6260f90166ba8ef20788df0871d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Fri, 8 Jul 2016 09:06:45 +0200 Subject: [PATCH] adding ldap bundle to doc --- source/bundles/index.rst | 1 + source/bundles/ldap.rst | 204 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 205 insertions(+) create mode 100644 source/bundles/ldap.rst diff --git a/source/bundles/index.rst b/source/bundles/index.rst index c83d96ab5..2c4f3f17e 100644 --- a/source/bundles/index.rst +++ b/source/bundles/index.rst @@ -21,6 +21,7 @@ You will find here documentation about bundles working with Chill. Activity bundle Group bundle Event bundle + Ldap bundle (synchronisation between ldap and database) Your bundle here ? ------------------- diff --git a/source/bundles/ldap.rst b/source/bundles/ldap.rst new file mode 100644 index 000000000..ccea046a8 --- /dev/null +++ b/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 `. +#. 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 `_) +to synchronize ldap and database automatically. + + +