Merge pull request #1232 from Jaxom99/groups-webadmin

Groups page - webadmin EN

groups_and_permissions.md

@@ -1,7 +1,7 @@
 User groups and permissions
 ===========================
 
-You can access the group and permissions management interface from the webadmin
+You can access the *groups and permissions* management interface from the webadmin
 by going into the 'Users' section and clicking the corresponding button:
 
 ![](./images/button_to_go_to_permission_interface.png)
@@ -9,13 +9,25 @@ by going into the 'Users' section and clicking the corresponding button:
 Managing groups
 ---------------
 
-The group mechanism can be used to define group of users which then can be used to restrict permissions for applications and other services such as mail or xmpp. Note that it is *not* mandatory to create a group to do so : you can also restrict access to an app or service to just a specific list of user.
+The group mechanism can be used to define groups of users which then can be used to restrict permissions for applications and other services (such as mail or xmpp). Note that it is *not* mandatory to create a group to do so: you can also restrict access to an app or service on a user-per-user basis.
 
-Using groups is however useful for semantic, for example if you host multiple group of friends, association or enterprise on your server, you might want to create groups like `association1` and `association2` and add members of each association to the relevant group.
+Using groups is however useful for semantics, for example if you host multiple groups of friends, associations or businesses on your server, you might want to create groups like `association1` and `association2` and add members of each association to the relevant group.
+
+### Default groups
+
+By default, two special groups are created:
+- `all_users`, that contain all users registered on YunoHost,
+- `visitors`, that applies to people viewing the server while not logged in. 
+
+The content of those groups cannot be changed, only the permissions given to them.
 
 ### List existing groups
 
-To list the currently existing groups :
+The existing groups are listed at the top of the *groups and permissions* page.
+
+![](./images/groups_default-groups.png)
+
+To list the currently existing groups in CLI :
 
 ```bash
 $ yunohost user group list
@@ -28,17 +40,30 @@ groups:
       - delphine
 ```
 
-By default, a special group called `all_users` exists and contain all users registered on YunoHost. This group can not be edited.
 
 ### Creating a new group
 
-To create a new group called `yolo_crew`
+To create a new group, simply click on the "New Group" button at the top of the page. You may only choose a name formed with letters (uper- and lowercase) and spaces. The group is created empty and without any permission.
+
+![](./images/groups_button-new-group.png)
+
+In CLI, to create a new group called `yolo_crew`
 
 ```bash
 $ yunohost user group create yolo_crew
 ```
 
-Let's add Charlie and Delphine to this group:
+### Updating a group
+
+Let's add a first to this group: in the group panel, click the button "add a user" and scroll to the desired user, then click on it.
+
+![](./images/groups_button-add-user.png)
+
+To remove a user, click on the cross next to their username, in the group panel.
+
+![](./images/groups_button-remove-user.png)
+
+In CLI, use the following command to add `charlie` and `delphine`to the `yolo_crew` group:
 
 ```bash
 $ yunohost user group update yolo_crew --add charlie delphine
@@ -65,7 +90,11 @@ groups:
 
 ### Deleting groups
 
-To delete the group `yolo_crew`, you may run
+To delete a group, click on the red cross on the top right of the group panel. You will be asked for confirmation.
+
+![](./images/groups_button-delete-group.png)
+
+To delete the group `yolo_crew` in CLI, you may run
 
 ```bash
 $ yunohost user group delete yolo_crew
@@ -74,11 +103,15 @@ $ yunohost user group delete yolo_crew
 Managing permissions
 --------------------
 
-The permission mechanism allow to restrict access to services (for example mail, xmpp, ...) and apps, or even specific part of the apps (for example the administration interface of wordpress).
+The permission mechanism allow to restrict access to services (for example mail, xmpp, ...) and apps, or even specific parts of the apps (for example the administration interface of wordpress).
 
 ### List permissions
 
-To list permissions and corresponding accesses:
+The groups page lists the permissions given to each group, including the special groups `all_users` and `visitors`.
+
+![](./images/groups_default-with-permissions.png)
+
+To list permissions and corresponding accesses in CLI:
 
 ```bash
 $ yunohost user permission list
@@ -93,19 +126,27 @@ permissions:
     allowed: all_users
 ```
 
-Here, we find that all registered users can use mails, xmpp, and access the wordpress blog. However, nobody can access the wordpress admin interface.
+Here, we find that all registered users can use email, xmpp, and access the wordpress blog. However, nobody can access the wordpress admin interface.
 
 More details can be displayed by adding the `--full` option which will display the list of users corresponding to groups allowed, as well as urls associated to a permission (relevant for web apps).
 
 ### Add accesses to group or users
 
-To allow a group to access the wordpress admin interface:
+To add a permission to a group, simply click the "+" button in the group panel, scroll to the desired permission, then click on it.
+
+![](./images/groups_add-permission-group.png)
+
+To allow a group to access the wordpress admin interface in CLI:
 
 ```bash
 $ yunohost user permission update wordpress.admin --add yolo_crew
 ```
 
-Note that you can also allow a single user:
+Note that you can also allow a single user, by using the specific panel at the bottom of the page.
+
+![](./images/groups_add-permission-user.png)
+
+or in CLI:
 
 ```bash
 $ yunohost user permission update wordpress.admin --add alice
@@ -123,18 +164,21 @@ $ yunohost user permission list
   [...]
 ```
 
-Note that, for example, if we want to restrict permission for email so that only Bob is allowed to email, we should also remove `all_users` from the permission :
+Note that, for example, if we want to restrict permission for email so that only Bob is allowed to email, we should also remove `all_users` from the permission, by deleting it from the `all_users` group panel, or in CLI :
 
 ```bash
 $ yunohost user permission update mail --remove all_users --add bob
 ```
 
+The webadmin will issue a warning if you set a permission that is superseeded by a wider permission.
+![](./images/groups_alerte-permission.png)
+
 Notes for apps packagers
 ------------------------
 
 Installing an app creates the permission `app.main` with `all_users` allowed by default.
 
-If you wish to make the application publicly available, instead of the old `unprotected_urls` mechanism, you should give access to the special groups `visitors`:
+If you wish to make the application publicly available, instead of the old `unprotected_urls` mechanism, you should give access to the special group `visitors`:
 
 ```bash
 ynh_permission_update --permission "main" --add visitors
@@ -150,7 +194,7 @@ You don't need to take care of removing permissions or backing up/restoring them
 
 ### Migrating away from the legacy permission management
 
-When migrating/fixing an app still using the legacy permission system, it should be understood that the accesses are now to be managed by features from the core, outside the application scripts!
+When migrating/fixing an app still using the legacy permission system, it should be understood that the accesses are now to be managed by features from the core, outside of the application scripts!
 
 Application scripts are only expected to:
 - if relevant, during the install script, initialize the main permission of the app as public (`visitors`) or private (`all_users`) or only accessible to specific groups/users ;
@@ -207,7 +251,7 @@ fi
 
 In this example, if the app is public the group `visitors` has access to the permission `create poll`, the group is removed from this permission otherwise.
 
-Then create two files in the directory `hooks` at the root of the git repository: `post_app_addaccess` and `post_app_removeaccess`. In these hooks, you'll remove or readd the regex protection if the `visitors` group is add or remove from this permission:
+Then create two files in the directory `hooks` at the root of the git repository: `post_app_addaccess` and `post_app_removeaccess`. In these hooks, you'll remove or readd the regex protection if the `visitors` group is added or removed from this permission:
 
 `post_app_addaccess`:
 
@@ -280,6 +324,6 @@ fi
 
 Don't forget to replace `__APP__` during the install/upgrade script.
 
-Here some apps that use this specific case: [Lutim](https://github.com/YunoHost-Apps/lutim_ynh/pull/44/files) and [Opensondage](https://github.com/YunoHost-Apps/opensondage_ynh/pull/59/files)
+Here are some apps that use this specific case: [Lutim](https://github.com/YunoHost-Apps/lutim_ynh/pull/44/files) and [Opensondage](https://github.com/YunoHost-Apps/opensondage_ynh/pull/59/files)
 
-If you have any questions, please contact someone from the apps-group.
+If you have any question, please contact someone from the apps-group.

groups_and_permissions_fr.md

@@ -0,0 +1,176 @@
+Groupes et permissions
+===========================
+
+Vous pouvez accéder à l'interface de gestion des *groupes et des permissions* depuis la webadmin
+en allant dans la section "Utilisateurs" et en cliquant sur le bouton correspondant :
+
+![](./images/button_to_go_to_permission_interface_fr.png)
+
+Gestion des groupes
+---------------
+Le mécanisme de groupe peut être utilisé pour définir des groupes d'utilisateurs qui peuvent ensuite être utilisés pour restreindre les autorisations pour les applications et autres services (tels que l'email ou xmpp). Notez qu'il n'est *pas* obligatoire de créer un groupe pour ce faire : vous pouvez également restreindre l'accès à une application ou à un service de manière individuelle.
+
+L'utilisation de groupes est cependant utile pour la sémantique, par exemple si vous hébergez plusieurs groupes d'amis, des associations ou des entreprises sur votre serveur, vous pouvez créer des groupes comme "association1" et "association2" et ajouter les membres de chaque association au groupe concerné.
+
+
+### Groupes par défaut
+Par défaut, deux groupes spéciaux sont créés :
+- `all_users`, qui contient tous les utilisateurs enregistrés sur YunoHost,
+- `visitors`, c'est-à-dire les personnes qui consultent le serveur sans être connectées. 
+
+Vous ne pouvez pas changer le contenu de ces groupes, seulement les permissions qui leur sont accordées.
+ 
+### Lister les groupes existants
+Les groupes existants sont listés en haut de la page *groupes et autorisations*.
+
+![](./images/groups_default-groups.png)
+
+Pour obtenir la liste des groupes existants en CLI :
+
+
+```bash
+$ yunohost user group list
+groups:
+  all_users:
+    members:
+      - alice
+      - bob
+      - charlie
+      - delphine
+```
+
+
+### Créer un nouveau groupe
+Pour créer un nouveau groupe, il suffit de cliquer sur le bouton "Nouveau groupe" en haut de la page. Vous ne pouvez choisir qu'un nom formé de lettres (majuscules et minuscules) et d'espaces. Le groupe est créé vide et sans aucune permissions.
+
+![](./images/groups_button-new-group.png)
+
+Dans la CLI, pour créer un nouveau groupe appelé `yolo_crew`, il faut utiliser
+
+```bash
+$ yunohost user group create yolo_crew
+```
+
+### Mettre à jour un groupe
+Ajoutons un premier utilisateur à ce groupe : dans le panneau du groupe, cliquez sur le bouton "ajouter un utilisateur" et faites défiler jusqu'à l'utilisateur souhaité, puis cliquez dessus.
+
+![](./images/groups_button-add-user.png)
+
+Pour supprimer un utilisateur, cliquez sur la croix à côté de son nom d'utilisateur, dans le panneau du groupe.
+
+![](./images/groups_button-remove-user.png)
+
+En CLI, utilisez la commande suivante pour ajouter `charlie` et `delphine` au groupe `yolo_crew` :
+
+```bash
+$ yunohost user group update yolo_crew --add charlie delphine
+```
+
+(De même, `--remove` peut être utilisé pour retirer des membres d'un groupe)
+
+Dans la liste des groupes, nous devrions voir :
+
+```bash
+$ yunohost user group list
+groups:
+  all_users:
+    members:
+      - alice
+      - bob
+      - charlie
+      - delphine
+  yolo_crew:
+    members:
+      - charlie
+      - delphine
+```
+
+### Supprimer un groupe
+
+Pour supprimer un groupe, cliquez sur la croix rouge en haut à droite du panneau du groupes. Une confirmation vous sera demandée.
+
+![](./images/groups_button-delete-group.png)
+
+Pour supprimer le groupe `yolo_crew` dans CLI, vous pouvez exécuter
+
+```bash
+$ yunohost user group delete yolo_crew
+```
+
+Gestion des permissions
+--------------------
+
+Le mécanisme de permissions permet de restreindre l'accès aux services (par exemple mail, xmpp, ...) et aux applications, ou même à des parties spécifiques des applications (par exemple l'interface d'administration de wordpress).
+
+### Liste des permissions
+
+La page des groupes liste les permissions données à chaque groupe, y compris les groupes spéciaux `all_users` et `visitors`.
+
+![](./images/groups_default-with-permissions.png)
+
+Pour répertorier les permissions et les accès correspondants en CLI :
+```bash
+$ yunohost user permission list
+permissions:
+  mail.main:
+    allowed: all_users
+  wordpress.admin:
+    allowed:
+  wordpress.main:
+    allowed: all_users
+  xmpp.main:
+    allowed: all_users
+```
+Ici, nous constatons que tous les utilisateurs enregistrés peuvent utiliser le courrier électronique, xmpp, et accéder au blog wordpress. Cependant, personne ne peut accéder à l'interface d'administration de wordpress.
+
+Plus de détails peuvent être affichés en ajoutant l'option `--full` qui affichera la liste des utilisateurs correspondant aux groupes autorisés, ainsi que les urls associées à une permission (pertinent pour les applications web).
+
+### Ajouter des permissions à un groupe ou un utilisateur
+
+Pour ajouter une permission à un groupe, il suffit de cliquer sur le bouton "+" dans le panneau du groupe, de faire défiler jusqu'à la permission souhaitée, puis de cliquer dessus.
+
+![](./images/groups_add-permission-group.png)
+
+Pour permettre à un groupe d'accéder à l'interface d'administration de wordpress via la CLI :
+
+```bash
+$ yunohost user permission update wordpress.admin --add yolo_crew
+```
+
+Notez que vous pouvez également autoriser un seul utilisateur, en utilisant le panneau spécifique en bas de la page.
+
+![](./images/groups_add-permission-user.png)
+
+ou en CLI :
+
+```bash
+$ yunohost user permission update wordpress.admin --add alice
+```
+
+Et maintenant, nous pouvons voir que YoloCrew et Alice ont tous deux accès à l'interface d'administration de Wordpress :
+
+```bash
+$ yunohost user permission list
+  [...]
+  wordpress.admin:
+    allowed:
+      - yolo_crew
+      - alice
+  [...]
+```
+
+Notez que, par exemple, si nous voulons restreindre la permission pour le courrier électronique 
+afin que seul Bob soit autorisé à envoyer des courriels, nous devons également supprimer `all_users` 
+de la permission, en la supprimant du panneau de groupe `all_users`, ou en CLI :
+
+```bash
+$ yunohost user permission update mail --remove all_users --add bob
+```
+
+La webadmin émettra un avertissement si vous définissez une permission qui est remplacée par une permission plus large.
+![](./images/groups_alerte-permission.png)
+
+Notes pour les packageurs d'applications
+------------------------
+
+[Voir la version anglaise de cette page](groups_and_permissions).