doc: Update LDAP configuration doc

Add some examples to explain clearer how to configure LDAP in LibrePlan.

doc/src/user/en/16-ldap-authentication.rst

@@ -24,13 +24,18 @@ will depend on the roles in LDAP that the user has.
 Configuration
 =============
 
-This section has the parameter values for accessing LDAP.*Base, UserDN and
+This section has the parameter values for accessing LDAP. *Base*, *UserDN* and
-Password* are parameters used to connect to LDAP and search for the users, so
+*Password* are parameters used to connect to LDAP and search for the users, so
 given user must have permission to do that operation in LDAP. At bottom part of
 this section there is a button to check if LDAP connection is possible with the
 given parameters. It is a good idea to try it before continuing the
 configuration.
 
+.. NOTE::
+
+   If your LDAP is configured to work with anonymous authentication you can
+   leave empty *UserDN* and *Password* attributes.
+
 Authentication
 ==============
 
@@ -55,29 +60,171 @@ Group strategy
 
 When this strategy is used, it means that LDAP has a role-group strategy. It
 means that users in LDAP are nodes that hang directly from a branch which
-represents the group. In this way, considering as example an LDAP with a branch
+represents the group.
-(group) called *Admin* and two nodes (users) in the branch called *John* and
+
-*William*, an administrator could assign to both users a role in LibrePlan. The
+The next example represents a valid LDAP structure to use group strategy.
-only parameter needed in this case is the *Group path* that represents the path
+
-in LDAP to find the branches with the groups.
+* LDAP structure::
+
+   dc=example,dc=org
+   |- ou=groups
+      |- cn=admins
+      |- cn=itpeople
+      |- cn=workers
+   |- ou=people
+      |- uid=admin1
+      |- uid=it1
+      |- uid=it2
+      |- uid=worker1
+      |- uid=worker2
+      |- uid=worker3
+
+In this case, each group will have an attribute, for example called ``member``,
+with the list of users belonging to the group:
+
+* ``cn=admins``:
+
+  * ``member: uid=admin1,ou=people,dc=example,dc=org``
+  * ``member: uid=it1,ou=people,dc=example,dc=org``
+
+* ``cn=itpeople``:
+
+  * ``member: uid=it1,ou=people,dc=example,dc=org``
+  * ``member: uid=it2,ou=people,dc=example,dc=org``
+
+* ``cn=workers``:
+
+  * ``member: uid=worker1,ou=people,dc=example,dc=org``
+  * ``member: uid=worker2,ou=people,dc=example,dc=org``
+  * ``member: uid=worker3,ou=people,dc=example,dc=org``
+
+The configuration for this case is the following:
+
+* Role search strategy: ``Group strategy``
+* Group path: ``ou=groups``
+* Role property: ``member``
+* Role search query: ``uid=[USER_ID],ou=people,dc=example,dc=org``
+
+And for example if you want to match some roles:
+
+* Administration: ``cn=admins;cn=itpeople``
+* Web service reader: ``cn=itpeople``
+* Web service writer: ``cn=itpeople``
+* All projects read allowed: ``cn=admins``
+* All projects edition allowed: ``cn=admins``
+* Project creation allowed: ``cn=workers``
 
 Property strategy
 -----------------
 
 When administrator decides to use this strategy, it means that each user is a
 LDAP node and in the node exists a property that represents the group(s) for
-the user. In this case, the configuration needs two parameters:
+the user. In this case, the configuration does not need the parameter *Group
+path*:
 
-* *Role property*. It represents the property in user's node in LDAP which
+The next example represents a valid LDAP structure to use property strategy.
-  contains all the roles for that user.
 
-* *Role search query*. It represents the path in LDAP to find the nodes of
+* LDAP structure::
-  the users; in this case, note that is important to know that string
+
-  "[USER_ID]" represents the place where the login name given in the login
+   dc=example,dc=org
-  form should be placed to get the correct user's node in LDAP.
+   |- ou=people
+      |- uid=admin1
+      |- uid=it1
+      |- uid=it2
+      |- uid=worker1
+      |- uid=worker2
+      |- uid=worker3
+
+With attribute
+..............
+
+In this case, each user will have attribute, for example called ``group`` with
+the name of the group to which it belongs:
+
+* ``uid=admin1``:
+
+  * ``group: admins``
+
+* ``uid=it1``:
+
+  * ``group: itpeople``
+
+* ``uid=it2``:
+
+  * ``group: itpeople``
+
+* ``uid=worker1``:
+
+  * ``group: workers``
+
+* ``uid=worker2``:
+
+  * ``group: workers``
+
+* ``uid=worker3``:
+
+  * ``group: workers``
+
+
+.. WARNING::
+
+   This strategy has a restriction, each user can belongs only to one group.
+
+The configuration for this case is the following:
+
+* Role search strategy: ``Property strategy``
+* Group path:
+* Role property: ``group``
+* Role search query: ``[USER_ID]``
+
+And for example if you want to match some roles:
+
+* Administration: ``admins;itpeople``
+* Web service reader: ``itpeople``
+* Web service writer: ``itpeople``
+* All projects read allowed: ``admins``
+* All projects edition allowed: ``admins``
+* Project creation allowed: ``workers``
+
+By user identifier
+..................
+
+You can even have a workaround to specify LibrePlan roles directly to users,
+without having an attribute in each LDAP user.
+
+In this case, you will specify which users have the different LibrePlan roles
+by uid.
+
+The configuration for this case is the following:
+
+* Role search strategy: ``Property strategy``
+* Group path:
+* Role property: ``uid``
+* Role search query: ``[USER_ID]``
+
+And for example if you want to match some roles:
+
+* Administration: ``admin1;it1``
+* Web service reader: ``it1;it2``
+* Web service writer: ``it1;it2``
+* All projects read allowed: ``admin1``
+* All projects edition allowed: ``admin1``
+* Project creation allowed: ``worker1;worker2;worker3``
+
+Role matching
+-------------
 
 At the bottom of this section there is a table with all the LibrePlan roles and
 a text field next to each one. This is for matching roles. For instance, if
 administrator decides that *Administration* LibrePlan role matches with *admin*
 and *administrators* roles of LDAP, in the text field should appear:
-"admin;administrators". The character for splitting roles is ";".
+"``admin;administrators``". The character for splitting roles is "``;``".
+
+.. NOTE::
+
+   If you want to specify that all users or all groups have one permission you
+   can use an asterisk (``*``) as wildcard to refer to them. For example, if you
+   want that everybody has the role *Project creation allowed* you will
+   configure the role matching as follows:
+
+   * Project creation allowed: ``*``