From ac42e9a5427cf9bc8bacff89fa6b35b6962feb4b Mon Sep 17 00:00:00 2001 From: Alexandre Aubin Date: Fri, 13 Sep 2019 19:09:43 +0200 Subject: [PATCH 1/6] Draft of documentation for groups and permissions --- groups_and_permissions.md | 145 ++++++++++++++++++++++++++++++++++++++ users.md | 6 +- 2 files changed, 148 insertions(+), 3 deletions(-) create mode 100644 groups_and_permissions.md diff --git a/groups_and_permissions.md b/groups_and_permissions.md new file mode 100644 index 00000000..a24b5a7c --- /dev/null +++ b/groups_and_permissions.md @@ -0,0 +1,145 @@ +User groups and permissions +=========================== + +Warning : for now, these features are only available through the command line (c.f. `yunohost user group --help` and `yunohost user permission --help`) + +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. + +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. + +### List existing groups + +To list the currently existing groups : + +```bash +$ yunohost user group list +groups: + all_users: + members: + - alice + - bob + - charlie + - 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` + +```bash +$ yunohost user group create yolo_crew +``` + +Let's add Charlie and Delphine to this group: + +```bash +$ yunohost user group update yolo_crew --add charlie delphine +``` + +(similarly, `--remove` can be used to remove members from a group) + +Now in the group list we should see : + +```bash +$ yunohost user group list +groups: + all_users: + members: + - alice + - bob + - charlie + - delphine + yolo_crew: + members: + - charlie + - delphine +``` + +### Deleting groups + +To delete the group `yolo_crew`, you may run + +```bash +$ 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). + +### List permissions + +To list permissions and corresponding accesses: + +```bash +$ yunohost user permission list +permissions: + mail.main: + allowed: all_users + wordpress.admin: + allowed: + wordpress.main: + allowed: all_users + xmpp.main: + 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. + +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: + +```bash +$ yunohost user permission update wordpress.admin --add yolo_crew +``` + +Note that you can also allow a single user: + +```bash +$ yunohost user permission update wordpress.admin --add alice +``` + +And now we may see that both the YoloCrew and Alice have access to the wordpress admin interface : + +```bash +$ yunohost user permission list + [...] + wordpress.admin: + allowed: + - yolo_crew + - john + [...] +``` + +Note that, for example, if we want to restrict permission for email so that only Bob, we should also remove `all_users` from the permission : + +```bash +$ yunohost user permission update mail --remove all_users --add bob +``` + +### Notes for apps packagers + +By default, installing an app creates the permission `$app.main` with `all_users` allowed by default. +If you want to create a custom permission for your app (e.g. to restrict access to an admin interface) you may use the following helpers: + +```bash +ynh_permission_create --permission "admin" --urls "$domain$path_url/admin" +ynh_permission_update --permission "admin" --add "$admin_user" +``` + +For now, inside the `change_url` script, you need to take care of updating the url corresponding to your permission: + +```bash +ynh_permission_urls --permission "admin" --remove "$old_domain$old_path_url/admin" --add "$domain$path_url/admin" +``` + +However, you don't need to take care of removing permissions or backing up/restoring them as it is handled by the core of YunoHost. diff --git a/users.md b/users.md index 1d7ea512..e4b979ce 100644 --- a/users.md +++ b/users.md @@ -25,10 +25,10 @@ In the portal, users can also click on the avatar in the top-left to configure s You should be aware that the SSO can only be reached through the actual domain name (i.e. `https://the.domain.tld/yunohost/sso`), and NOT by just using the IP of the server (i.e. `https://11.22.33.44/yunohost/sso`), contrarily to the webadmin ! This is a bit confusing but is necessary for technical reason. If you are in a situation where you need to access the SSO without having your DNS properly configured for some reason, you might consider tweaking your `/etc/hosts` as described in [this page](dns_local_nework). -App permissions ---------------- +User groups and permissions +--------------------------- -Access to apps can be restricted to some users only. This can be configured via the webadmin in Applications > (choose an app) > Access, or similarly via the command line `yunohost app addaccess`, `removeaccess` and `clearaccess`. +See [this dedicated page](groups_and_permissions). SSH access ---------- From 1376de666b22547b3ebf12c477c1449cb0330672 Mon Sep 17 00:00:00 2001 From: Alexandre Aubin Date: Wed, 9 Oct 2019 23:31:50 +0200 Subject: [PATCH 2/6] Updating documentation following changes in the PRs --- groups_and_permissions.md | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/groups_and_permissions.md b/groups_and_permissions.md index a24b5a7c..6b89207d 100644 --- a/groups_and_permissions.md +++ b/groups_and_permissions.md @@ -12,13 +12,13 @@ Using groups is however useful for semantic, for example if you host multiple gr ### List existing groups -To list the currently existing groups : +To list the currently existing groups : ```bash $ yunohost user group list -groups: - all_users: - members: +groups: + all_users: + members: - alice - bob - charlie @@ -43,7 +43,7 @@ $ yunohost user group update yolo_crew --add charlie delphine (similarly, `--remove` can be used to remove members from a group) -Now in the group list we should see : +Now in the group list we should see : ```bash $ yunohost user group list @@ -79,14 +79,14 @@ To list permissions and corresponding accesses: ```bash $ yunohost user permission list -permissions: - mail.main: +permissions: + mail.main: allowed: all_users - wordpress.admin: - allowed: - wordpress.main: + wordpress.admin: + allowed: + wordpress.main: allowed: all_users - xmpp.main: + xmpp.main: allowed: all_users ``` @@ -108,7 +108,7 @@ Note that you can also allow a single user: $ yunohost user permission update wordpress.admin --add alice ``` -And now we may see that both the YoloCrew and Alice have access to the wordpress admin interface : +And now we may see that both the YoloCrew and Alice have access to the wordpress admin interface : ```bash $ yunohost user permission list @@ -120,7 +120,7 @@ $ yunohost user permission list [...] ``` -Note that, for example, if we want to restrict permission for email so that only Bob, 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, we should also remove `all_users` from the permission : ```bash $ yunohost user permission update mail --remove all_users --add bob @@ -129,17 +129,17 @@ $ yunohost user permission update mail --remove all_users --add bob ### Notes for apps packagers By default, installing an app creates the permission `$app.main` with `all_users` allowed by default. -If you want to create a custom permission for your app (e.g. to restrict access to an admin interface) you may use the following helpers: + +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`: ```bash -ynh_permission_create --permission "admin" --urls "$domain$path_url/admin" -ynh_permission_update --permission "admin" --add "$admin_user" +ynh_permission_update --permission "main" --remove "all_users" --add "visitors" ``` -For now, inside the `change_url` script, you need to take care of updating the url corresponding to your permission: +If you wish to create a custom permission for your app (e.g. to restrict access to an admin interface) you may use the following helpers: ```bash -ynh_permission_urls --permission "admin" --remove "$old_domain$old_path_url/admin" --add "$domain$path_url/admin" +ynh_permission_create --permission "admin" --url "/admin" --allowed "$admin_user" ``` -However, you don't need to take care of removing permissions or backing up/restoring them as it is handled by the core of YunoHost. +You don't need to take care of removing permissions or backing up/restoring them as it is handled by the core of YunoHost. From da3d8d107d19ac3382b5bfed24d855b6f38cbe6b Mon Sep 17 00:00:00 2001 From: Eauchat <34686393+eauchat@users.noreply.github.com> Date: Thu, 17 Oct 2019 15:46:16 +0000 Subject: [PATCH 3/6] Corrected small typos --- groups_and_permissions.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/groups_and_permissions.md b/groups_and_permissions.md index 6b89207d..6e1c6c4a 100644 --- a/groups_and_permissions.md +++ b/groups_and_permissions.md @@ -116,11 +116,11 @@ $ yunohost user permission list wordpress.admin: allowed: - yolo_crew - - john + - alice [...] ``` -Note that, for example, if we want to restrict permission for email so that only Bob, 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 : ```bash $ yunohost user permission update mail --remove all_users --add bob @@ -128,7 +128,7 @@ $ yunohost user permission update mail --remove all_users --add bob ### Notes for apps packagers -By default, installing an app creates the permission `$app.main` with `all_users` allowed by default. +By default, 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`: From 1bf97096af9b66dc7b1f9a887262fbb4ee79497a Mon Sep 17 00:00:00 2001 From: Alexandre Aubin Date: Sat, 26 Oct 2019 17:35:38 +0200 Subject: [PATCH 4/6] Try to clarify what to do for packagers removing the legacy permission stuff --- groups_and_permissions.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/groups_and_permissions.md b/groups_and_permissions.md index 6e1c6c4a..e1ff2932 100644 --- a/groups_and_permissions.md +++ b/groups_and_permissions.md @@ -126,7 +126,8 @@ Note that, for example, if we want to restrict permission for email so that only $ yunohost user permission update mail --remove all_users --add bob ``` -### Notes for apps packagers +Notes for apps packagers +------------------------ By default, installing an app creates the permission `app.main` with `all_users` allowed by default. @@ -143,3 +144,19 @@ ynh_permission_create --permission "admin" --url "/admin" --allowed "$admin_user ``` You don't need to take care of removing permissions or backing up/restoring them as it is handled by the core of YunoHost. + +### 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! + +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 ; +- if relevant, create and initialize any other specific permission (e.g. to some admin interface) in the install script (and *maybe* in some migration happening in the upgrade script). + +Applications scripts should absolutely **NOT** mess up with any already-existing app accesses (including `unprotected`/`skipped_uris` settings) during any other case, as *it would reset any admin-defined access rule*! + +When migrating away from the legacy permission, you should: +- remove any management of `$is_public`-like or `$admin_user`-like setting, except for any manifest question meant to either *initialize* the app as public/private or specific permissions ; +- remove any management of `skipped_`, `unprotected_` and `protected_uris` (and `_regex`) settings that are now considered obsolete and deprecated. (N.B.: you should **explicitly delete them in the upgrade script**). Instead, you should now rely on the new `ynh_permission_*` helpers instead. If you do feel like you still need to use them, please contact the core team to provide your feedback and we'll figure out something ; +- remove any call to `yunohost app addaccess` and similar actions that are now obsolete and deprecated. + From 0a2ce43992a5a6f18c0a5056205ca883cb81e50c Mon Sep 17 00:00:00 2001 From: Alexandre Aubin Date: Fri, 29 Nov 2019 17:23:02 +0100 Subject: [PATCH 5/6] Propagate https://github.com/YunoHost/yunohost/pull/855 --- groups_and_permissions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/groups_and_permissions.md b/groups_and_permissions.md index e1ff2932..443d977c 100644 --- a/groups_and_permissions.md +++ b/groups_and_permissions.md @@ -134,7 +134,7 @@ By default, installing an app creates the permission `app.main` with `all_users` 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`: ```bash -ynh_permission_update --permission "main" --remove "all_users" --add "visitors" +ynh_permission_update --permission "main" --add "visitors" ``` If you wish to create a custom permission for your app (e.g. to restrict access to an admin interface) you may use the following helpers: From cbb6920c8ce7ee7d4bdeecb8991ec2247f9e8e28 Mon Sep 17 00:00:00 2001 From: Kay0u Date: Tue, 10 Mar 2020 23:41:04 +0100 Subject: [PATCH 6/6] adding more information for migration --- groups_and_permissions.md | 123 +++++++++++++++++++++++++++++++++++++- 1 file changed, 121 insertions(+), 2 deletions(-) diff --git a/groups_and_permissions.md b/groups_and_permissions.md index 443d977c..4b28d3ee 100644 --- a/groups_and_permissions.md +++ b/groups_and_permissions.md @@ -129,7 +129,7 @@ $ yunohost user permission update mail --remove all_users --add bob Notes for apps packagers ------------------------ -By default, installing an app creates the permission `app.main` with `all_users` allowed by default. +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`: @@ -158,5 +158,124 @@ Applications scripts should absolutely **NOT** mess up with any already-existing When migrating away from the legacy permission, you should: - remove any management of `$is_public`-like or `$admin_user`-like setting, except for any manifest question meant to either *initialize* the app as public/private or specific permissions ; - remove any management of `skipped_`, `unprotected_` and `protected_uris` (and `_regex`) settings that are now considered obsolete and deprecated. (N.B.: you should **explicitly delete them in the upgrade script**). Instead, you should now rely on the new `ynh_permission_*` helpers instead. If you do feel like you still need to use them, please contact the core team to provide your feedback and we'll figure out something ; -- remove any call to `yunohost app addaccess` and similar actions that are now obsolete and deprecated. +For example, in the upgrade script if you used the `protected_uris` key before, you may use this code in the `DOWNWARD COMPATIBILITY` section: +```bash +protected_uris=$(ynh_app_setting_get --app=$app --key=protected_uris) +# Unused with the permission system +if [ ! -z "$protected_uris" ]; then + ynh_app_setting_delete --app=$app --key=protected_uris +fi +``` + +- remove any call to `yunohost app addaccess` and similar actions that are now obsolete and deprecated. +- if your app use LDAP and support filter, use the filter `'(&(objectClass=posixAccount)(permission=cn=YOUR_APP.main,ou=permission,dc=yunohost,dc=org))'` to allow users who have this permission. (A complete documentation of LDAP [here](https://moulinette.readthedocs.io/en/latest/ldap.html) if you want to undestand how it works with YunoHost) + +Here an example of how to migrate the code from legacy to new permission system: [example](https://github.com/YunoHost/example_ynh/pull/111/files) + +#### Specific case: regex protection + +If you still need to use regex to protect or unprotect urls, you can't use the new permission system (for now). + +But you can create a fake permission and use hooks to handle if there is a change in this faked permission. + +In the install script, create the fake permission (with no url): + +`ynh_permission_create --permission="create poll" --allowed="visitors"` + +Then use the legacy protection: + +```bash +# Make app public if necessary +if [ $is_public -eq 1 ] +then + if [ "$path_url" == "/" ]; then + # If the path is /, clear it to prevent any error with the regex. + path_url="" + fi + # Modify the domain to be used in a regex + domain_regex=$(echo "$domain" | sed 's@-@.@g') + ynh_app_setting_set --app=$app --key=unprotected_regex --value="$domain_regex$path_url/create_poll.php?.*$","$domain_regex$path_url/adminstuds.php?.*" +else + ynh_permission_update --permission="create poll" --remove="visitors" +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: + +`post_app_addaccess`: + +```bash +#!/bin/bash + +# Source app helpers +source /usr/share/yunohost/helpers + +app=$1 +added_users=$2 +permission=$3 +added_groups=$4 + +if [ "$app" == __APP__ ]; then + if [ "$permission" = "create poll" ]; then # The fake permission "create poll" is modifed. + if [ "$added_groups" = "visitors" ]; then # As is it a fake permission we can only grant/remove the "visitors" group. + domain=$(ynh_app_setting_get --app=$app --key=domain) + path_url=$(ynh_app_setting_get --app=$app --key=path) + + if [ "$path_url" == "/" ]; then + # If the path is /, clear it to prevent any error with the regex. + path_url="" + fi + # Modify the domain to be used in a regex + domain_regex=$(echo "$domain" | sed 's@-@.@g') + ynh_app_setting_set --app=$app --key=unprotected_regex --value="$domain_regex$path_url/create_poll.php?.*$","$domain_regex$path_url/adminstuds.php?.*" + + # Sync the is_public variable according to the permission + ynh_app_setting_set --app=$app --key=is_public --value=1 + + yunohost app ssowatconf + else + ynh_print_warn --message="This app doesn't support this authorisation, you can only add or remove visitors group." + fi + fi +fi +``` + +`post_app_removeaccess` + +```bash +#!/bin/bash + +# Source app helpers +source /usr/share/yunohost/helpers + +app=$1 +removed_users=$2 +permission=$3 +removed_groups=$4 + +if [ "$app" == __APP__ ]; then + if [ "$permission" = "create poll" ]; then # The fake permission "create poll" is modifed. + if [ "$removed_groups" = "visitors" ]; then # As is it a fake permission we can only grant/remove the "visitors" group. + + # We remove the regex, no more protection is needed. + ynh_app_setting_delete --app=$app --key=unprotected_regex + + # Sync the is_public variable according to the permission + ynh_app_setting_set --app=$app --key=is_public --value=0 + + yunohost app ssowatconf + else + ynh_print_warn --message="This app doesn't support this authorisation, you can only add or remove visitors group." + fi + fi +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) + +If you have any questions, please contact someone from the apps-group. \ No newline at end of file