YunoHost/doc
1
0
Fork 0
mirror of https://github.com/YunoHost/doc.git synced 2024-09-03 20:06:26 +02:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request #1263 from YunoHost/extends_premission_feature

Browse source 
Update doc for extended permission feature
This commit is contained in:
Alexandre Aubin 2021-01-06 19:41:20 +01:00 committed by GitHub
commit f20fd85741
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 100 additions and 309 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

19
contributordoc.md
View file

@ -1,26 +1,27 @@
# Contributor documentation
* [General ways of contributing to YunoHost](/contribute)
* [Chat rooms](/chat_rooms)
* [Writing documentation](/write_documentation)
* [Documentation writing guide](/doc_writing_guide)
* [Markdown guide](/doc_markdown_guide)
* [Power your code using Git & GitHub](/doc_use_git)
* [Chat rooms](/chat_rooms)
* Application packaging
* [Apps wishlist](/apps_wishlist)
* [General introduction to app packaging](/packaging_apps_start)
* [Technical introduction to app packaging](/packaging_apps)
* [How to use Git to package apps](/packaging_apps_git)
* [Setting up a dev environment with VirtualBox](/packaging_apps_virtualbox)
* [Manifest](packaging_apps_manifest)
* [Scripts](packaging_apps_scripts)
* [Arguments management](packaging_apps_arguments_management)
* [Arguments format](packaging_apps_arguments_format)
* [NGINX configuration](packaging_apps_nginx_conf)
* [Manifest](/packaging_apps_manifest)
* [Scripts](/packaging_apps_scripts)
* [Arguments management](/packaging_apps_arguments_management)
* [Arguments format](/packaging_apps_arguments_format)
* [NGINX configuration](/packaging_apps_nginx_conf)
* [User groups and permissions](/groups_and_permissions)
* [Multi-instance](packaging_apps_multiinstance)
* [Helpers](packaging_apps_helpers)
* [Multi-instance](/packaging_apps_multiinstance)
* [Helpers](/packaging_apps_helpers)
* [Trap usage](/packaging_apps_trap)
* [App permissions](/packaging_apps_permissions)
* [Adding your app to the apps list](https://github.com/YunoHost/Apps/#contributing)
* [Advanced packaging features](/packaging_apps_advanced)
* [Application actions](/packaging_apps_actions)
@ -41,4 +42,4 @@
* [Raspberry Pi images](https://github.com/YunoHost/rpi-image)
* [Other ARM board images](https://github.com/YunoHost/arm-images)
* [Using the YunoHost API outside of the webadmin](/admin_api)
* [A discussion about shell variable scope](shell_variables_scope)
* [A discussion about shell variable scope](/shell_variables_scope)

5
contributordoc_fr.md
View file

@ -1,11 +1,11 @@
# Guide du contributeur
* [Liste des façons de contribuer à YunoHost](/contribute)
* [Salons de discussion](/chat_rooms)
* [Écrire de la documentation](/write_documentation)
* [Guide de redaction de la documentation](/doc_writing_guide)
* [Guide Markdown](/doc_markdown_guide)
* [Propulser son code avec Git & GitHub](/doc_use_git)
* [Salons de discussion](/chat_rooms)
* Packaging d'application
* [Liste d'applications souhaitées par la communauté](/apps_wishlist)
* [Introduction générale au packaging d'apps](/packaging_apps_start)
@ -21,6 +21,7 @@
* [Multi-instance](/packaging_apps_multiinstance)
* [Fonctions utiles](/packaging_apps_helpers)
* [Utilisation de 'trap'](/packaging_apps_trap)
* [App permissions](/packaging_apps_permissions)
* [Ajouter son application à la liste des apps](https://github.com/YunoHost/Apps/#contributing)
* [Feature de packaging avancées](/packaging_apps_advanced)
* [Actions pour une application](/packaging_apps_actions)
@ -42,4 +43,4 @@
* [Images Raspberry Pi](https://github.com/YunoHost/rpi-image)
* [Autres images pour cartes ARM](https://github.com/YunoHost/arm-images)
* [Utiliser l'API YunoHost en dehors de la webadmin](/admin_api)
* [Une discussion sur la portée des variables en bash](shell_variables_scope)
* [Une discussion sur la portée des variables en bash](/shell_variables_scope)

154
groups_and_permissions.md
View file

@ -167,160 +167,18 @@ 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
```
Note that some permissions may be "protected", meaning that you won't be able to add/remove the visitor group to this permission. Generally, this is because it would make no sense (or is a security risk) to do so.
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
### Hide/display specific tiles in the user portal
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 group `visitors`:
Since yunohost 4.1, you can choose to hide/display specific tiles in the SSO. In the webadmin, you can do so by going in the corresponding app view, go in "Manage label and tiles" and check/uncheck the option "Display the tile in the user portal" for the corresponding permission. In command line, this may be done with :
```shell
ynh_permission_update --permission "main" --add visitors
# Enable the tile for the wordpress admin interface
$ yunohost user permission update wordpress.admin --show_tile True
```
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:
```shell
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 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 ;
- 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 ;
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" "all_users"`
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 added or removed 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 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 question, please contact someone from the apps-group.

156
groups_and_permissions_fr.md
View file

@ -164,161 +164,17 @@ de la permission, en la supprimant du panneau de groupe `all_users`, ou en CLI :
$ yunohost user permission update mail --remove all_users --add bob
```
Notez que certaines permissions peuvent être "protégées", ce qui signifie que vous ne pourrez pas l'ajouter/enlever du groupe visiteur. Ce mécanisme est généralement là car ajouter/enlever la permission au groupe utilisateur n'a pas de sens (ou est un risque de sécurité).
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)
### Montrer/cacher les tuiles dans le portail utilisateur
## Notes aux packageurs d'applications
L'installation d'une application crée l'autorisation `app.main` avec `all_users` autorisée par défaut.
Si vous souhaitez rendre l'application accessible au public, au lieu de l'ancien mécanisme `unprotected_urls`, vous devez donner accès au groupe spécial `visitors` :
Depuis Yunohost 4.1, il est possible de montrer/cacher certaines tuiles dans le portail. Depuis la webadmin, vous pouvez changer cela en allant dans la vue de l'application à manipuler, puis dans "Gérer les tuiles et les labels", et cocher/décocher l'option "Montrer cette tuile dans le portail utilisateur" pour la permissison correspondante. En ligne de commande, le même genre de chose peut être fait avec :
```shell
ynh_permission_update --permission "main" --add visitors
# Activer la tuile pour l'interface d'admin de wordpress
$ yunohost user permission update wordpress.admin --show_tile True
```
Si vous souhaitez créer une autorisation personnalisée pour votre application (par exemple pour restreindre l'accès à une interface d'administration), vous pouvez utiliser les helpers suivants :
```shell
ynh_permission_create --permission "admin" --url "/admin" --allowed "$admin_user"
```
Vous n'avez pas besoin de supprimer les autorisations ou de les sauvegarder / restaurer car elles sont gérées par le core de YunoHost.
### Migration hors de la gestion des autorisations héritées
Lors de la migration / correction d'une application utilisant toujours le système d'autorisations hérité, il faut comprendre que les accès doivent maintenant être gérés par des fonctionnalités du core, en dehors des scripts d'application !
Les scripts d'application devraient seulement :
- le cas échéant, pendant le script d'installation, initialiser l'autorisation principale de l'application en tant que public (`visitors`) ou privé (`all_users`) ou uniquement accessible à des groupes / utilisateurs spécifiques ;
- le cas échéant, créer et initialiser toute autre autorisation spécifique (par exemple, sur une interface d'administration) dans le script d'installation (et *sans doute* dans certaines migrations se produisant dans le script de mise à niveau).
Les scripts d'applications ne devraient absolument **PAS** altérer les accès aux applications déjà existantes (y compris les paramètres `unprotected` / `skipped_uris`), car cela réinitialiserait toutes les règles d'accès définies par l'administrateur !
Lors de la migration hors de l'autorisation héritée, vous devez :
- supprimer toute gestion du paramètre de type `$is_public` ou `$admin_user`, sauf pour toute question manifeste destinée à *initialiser* l'application avec des autorisations publiques / privées ou spécifiques ;
- supprimer toute gestion des paramètres `skipped_`, `unprotected_` et `protected_uris` (et `_regex`) qui sont désormais considérés comme obsolètes et dépréciés. (NB : vous devez **les supprimer explicitement dans le script upgrade**). Au lieu de cela, vous devriez désormais vous fier aux nouveaux helpers `ynh_permission_ *`. Si vous sentez que vous avez encore besoin de les utiliser, veuillez contacter l'équipe core pour pouvoir être assisté ;
Par exemple, dans le script *upgrade*, si vous avez utilisé la clé `protected_uris` auparavant, vous pouvez utiliser ce code dans la section `DOWNWARD COMPATIBILITY` :
```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
```
- Supprimez tout appel à `yunohost app addaccess` et aux actions similaires qui sont désormais obsolètes et dépréciés.
- Si votre application utilise LDAP et prend en charge le filtre, utilisez le filtre `(&(objectClass=posixAccount)(permission=cn=YOUR_APP.main,ou=permission,dc=yunohost,dc=org))'` pour autoriser les utilisateurs ayant cette permission. (On trouvera une documentation sur LDAP [ici](https://moulinette.readthedocs.io/en/latest/ldap.html))
Voici un exemple de migration de code vers le nouveau système d'autorisation : [exemple](https://github.com/YunoHost/example_ynh/pull/111/files)
#### Cas spécifique : protection regex
Si vous devez toujours utiliser regex pour protéger ou déprotéger les URL, vous ne pouvez pas utiliser le nouveau système d'autorisation (pour l'instant).
Mais vous pouvez créer une fausse autorisation et utiliser des crochets pour gérer s'il y a un changement dans cette fausse autorisation.
Dans le script d'installation, créez la fausse autorisation (sans URL) :
`ynh_permission_create --permission="create poll" --allowed "visitors" "all_users"`
Utilisez ensuite la protection héritée :
```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
```
Dans cet exemple, si l'application est publique, le groupe `visitors` a accès à l'autorisation `create poll`, sinon le groupe est supprimé de cette autorisation.
Créez ensuite deux fichiers dans le répertoire `hooks` à la racine du dépôt Git de l'application : `post_app_addaccess` et `post_app_removeaccess`. Dans ces hooks, vous supprimerez ou rajouterez la protection contre les regex si le groupe `visitors` est ajouté ou supprimé de cette autorisation :
`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
```
N'oubliez pas de remplacer `__APP__` pendant le script *install* / *upgrade*.
Voici quelques applications qui utilisent ce cas spécifique : [Lutim](https://github.com/YunoHost-Apps/lutim_ynh/pull/44/files) et [OpenSondage](https://github.com/YunoHost-Apps/opensondage_ynh/pull/59/files)
Si vous avez des questions, veuillez contacter un des membres du groupe apps.

75
packaging_apps_permissions.md Normal file
View file

@ -0,0 +1,75 @@
# User groups and permissions
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 group `visitors`:
```shell
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:
```shell
ynh_permission_create --permission "admin" --url "/admin" --allowed "$admin_user" --label "Label for your permission"
```
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 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 ;
- 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 the old legacy permissions. Check out the recommended way to proceed in the example_ynh app (in particular [this code snippet](https://github.com/YunoHost/example_ynh/pull/111/files#diff-57aeb84da86cb7420dfedd8e49bc644fb799d5413d01927a0417bde753e8922f))
It should boil down to :
```bash
if ynh_legacy_permissions_exists; then
ynh_legacy_permissions_delete_all
ynh_app_setting_delete --app=$app --key=is_public
# Create the permission using the new framework (if your app has relevant additional permissions)
ynh_permission_create --permission="admin" --url="/admin" --allowed=$admin
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)
#### Additional features from 4.1
- Label customization : this is the name displayed to end users in the user portal. You can provide a default label (for example app.admin maybe be labelled 'Admin interface'). The label may be changed later by the admin after installation.
- Enabling/disabling tile : this toggles wether or not an app is shown in the user portal (if the user has the corresponding permission). The corresponding option is called `show_tile` which may be `True` or `False`. A single app may have multiple tiles in the SSO. The url of each tile corresponds to the `url` parameter of the permission.
- Multiple url support: a permission may have additional urls associated to it. This give the possiblity to protect many url with the same permission - in particular for tricky use case (for example several pieces of admin interfaces spread over different subpaths).
- Protecting permission: As a packager, you may choose to "protect" a permission if you believe that it's not relevant for the admin to add/remove this permission to/from the visitors group. For example, this is the case for the API permission of Nextcloud, which in the vast majority of cases should be kept publicly because mobile client won't go through the SSO. Note that when using the helper `ynh_permission_update`, it's still possible to add/remove the `visitor` group of this permission.
- Disabling auth header: some app authentification mecanism do not appreciate that SSOwat injects the Authorization header (which is an essential mecanism for single sign-on). You can now choose to disable the auth header injection from SSOwat to fix this (instead of the previous hack of using `skipped_uris`)
##### Correspondance between the old and new permission mecanism
| | with auth header | no auth header |
| :---------- | :--------------- | :------------- |
| **public** | unprotected_uris | skipped_uris |
| **private** | protected_uris | N/A |
| | with auth header | no auth header |
| :---------- | :------------------------------------------ | :------------------------------------------- |
| **public** | auth_header=True, visitor group allowed | auth_header=False, visitor group allowed |
| **private** | auth_header=True, visitor group not allowed | auth_header=False, visitor group not allowed |
All of theses feature are managable by theses following helper:
- `ynh_permission_create`
- `ynh_permission_url`
- `ynh_permission_update`
If you have any question, please contact the app team