-
Notifications
You must be signed in to change notification settings - Fork 181
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
216 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,216 @@ | ||
--- | ||
title: "Settings" | ||
date: 2020-02-27T20:35:00+01:00 | ||
weight: 45 | ||
geekdocRepo: https://github.com/owncloud/ocis | ||
geekdocEditPath: edit/master/docs | ||
geekdocFilePath: settings.md | ||
--- | ||
|
||
|
||
|
||
## The Settings service | ||
|
||
Extensions can register a settings bundle with the settings service. | ||
|
||
### Settings bundle definition | ||
A bundle has several properties: | ||
- a name that uniquely identifies the bundle | ||
- a display name that is shown to administrators | ||
- the service the bundle belongs to | ||
- a set of settings (see below) | ||
|
||
Each setting is specified as follows: | ||
- a name that uniquely identifies the setting within the settings bundle | ||
- a display name that is shown to users | ||
- a description (optional) | ||
- a set of values (form definition): | ||
- a default value or function constructing the default value | ||
- type (required) | ||
- string | ||
- integer | ||
- boolean | ||
- list | ||
- set of validation rules | ||
- password | ||
- required | ||
- min | ||
- max | ||
- stepping | ||
- placeholder | ||
- options | ||
|
||
### Example: `User Profile` | ||
The following JSON defines a Settings Bundle `User Profile` with two settings `Email Address` and `Timezone`. | ||
|
||
```json | ||
{ | ||
"name": "user-profile", | ||
"displayName": "User Profile", | ||
"extension": "account", | ||
"settings": [ | ||
{ | ||
"name": "email", | ||
"displayName": "Email Address", | ||
"description": null, | ||
"values": [ | ||
{ | ||
"type": "string", | ||
"default": null, | ||
"validation": ["email", "required"], | ||
"placeholder": "Provide an email address" | ||
} | ||
] | ||
}, | ||
{ | ||
"name": "timezone", | ||
"displayName": "Timezone", | ||
"description": null, | ||
"values": [ | ||
{ | ||
"type": "list", | ||
"validation": ["required"], | ||
"options": [ | ||
{"value": 0, "label": "unknown"}, | ||
{"value": 1, "label": "Europe/Berlin", "default": true}, | ||
{"value": 2, "label": "Europe/Amsterdam"} | ||
] | ||
} | ||
] | ||
} | ||
] | ||
} | ||
``` | ||
|
||
### Registering Settings Bundles | ||
|
||
When registering a setting with the settings service, every single setting automatically creates three permissions: | ||
- `read` to allow reading the setting value from the settings service | ||
- `write` to allow writing the setting value to the settings service | ||
- `display` to allow seeing or listing a settings value in the settings ui | ||
|
||
A user that has the `read` permission, the `display` permission but no `write` permission could see his timezone in the | ||
settings ui but not change it. | ||
|
||
A user that has the `read` permission but no `display` permission should not even see his timezone in the settings ui. | ||
|
||
Referencing a specific permission when querying the settings service works by concatenating the extension, | ||
settings bundle, setting and permission, e.g. `account:user-profile:email:read`. When performing an operation against the | ||
settings service, the permission can be omitted, as it is implicitly clear from the operation. | ||
|
||
## Roles | ||
|
||
- Every user has roles that are tied to his account. | ||
- Every role has a set of permissions. | ||
- Every permission evaluates to a boolean for a certain scope. | ||
|
||
The two roles `user` and `admin` get created on first start of the settings service with the characteristics that the | ||
names imply. | ||
|
||
```json | ||
{ | ||
"roles": [ | ||
{ | ||
"name": "admin", | ||
"displayName": "Admin", | ||
"permissions": [ | ||
{"name": "account:user-profile:email:read", "scope": {"type": "user", "value": ["all"]}}, | ||
{"name": "account:user-profile:email:write", "scope":{"type": "user", "value": ["all"]}} | ||
] | ||
}, | ||
{ | ||
"name": "site-admin", | ||
"displayName": "Site Admin", | ||
"permissions": [ | ||
{"name":"account:user-profile:email:read", "scope": {"type": "group", "value": ["group-uid-1", "group-uid-2"]}}, | ||
{"name":"account:user-profile:email:write", "scope": {"type": "group", "value": ["group-uid-1", "group-uid-2"]}}, | ||
{"name":"account:user-profile:email:read", "scope": {"type": "user", "value": ["me"]}}, | ||
{"name":"account:user-profile:email:write", "scope": {"type": "user", "value": ["me"]}} | ||
] | ||
}, | ||
{ | ||
"name": "user", | ||
"displayName": "User", | ||
"permissions": [ | ||
{"name":"account:user-profile:email:read", "scope": {"type": "user", "value": ["me"]}}, | ||
{"name":"account:user-profile:email:write", "scope": {"type": "user", "value": ["me"]}} | ||
] | ||
} | ||
] | ||
} | ||
|
||
``` | ||
|
||
## Workflow of the settings service | ||
On first start, the settings service creates the roles `admin` and `user` as archetypes. Those two roles | ||
cannot be removed. Every settings bundle that is subsequently registered assigns permissions to these two roles in a way | ||
that they evaluate to `true` for all users for the admin role and evaluate to `true` only for `me` for the user role | ||
unless defined otherwise in the `userPermissions` map of the setting definition. | ||
|
||
TODO: the service owner probably has to decide about initial permissions for existing roles when a new service registers | ||
settings bundles. We need a clever way to not let this turn into a configuration mess. Probably a good idea to define | ||
archetype permission mappings in settings. | ||
|
||
TODO: passwords | ||
- sometimes we need to store them but only certain extensions should be allowed to read them, eg. the wnd app | ||
- they should be encrypted anyway | ||
- but the settings bundle should have a list of extensions that are allowed to read the setting to narrow down who can access | ||
- a permission to only allow the owner access? | ||
|
||
TODO: we should have a json-schema for settings bundle validation | ||
|
||
## TODO: Data model for saved values in the settings service | ||
The settings service has to be able to save multiple instances of a setting, coming from different roles or services, | ||
allowing to save a value and a default for each. This way we can override values and provide defaults in a hierarchy. | ||
This also means that the roles need to have a hierarchy (probably a tree). | ||
The language of a user for example could come as a default from the browser or IDP, can be set by the user and could be | ||
overwritten by an admin. There could also be a default defined by the admin, that is only used if the user didn't define | ||
a language on their own. Defaults should not override other defaults - only if a default is missing but needed, we look | ||
in the next higher role for a default. Values on the other hand should override. If a higher role sets a value for a | ||
certain user it must have precedence to the value set by the user. | ||
|
||
### Examples | ||
|
||
### Timezone | ||
Idea: User should not be able to mess with his timezone | ||
|
||
1. Admin | ||
- has the "Edit Timezone" permission | ||
|
||
2. Site Admin | ||
- has the "Edit Timezone" permission | ||
|
||
3. User | ||
- does NOT have the "Edit Timezone" permission | ||
|
||
#### Quota | ||
Idea: user should not be able to change his quota. | ||
|
||
1. Admin | ||
- has permission to change default quota value | ||
- has permission to change any users quota value | ||
|
||
2. Site Admin | ||
|
||
## Glossary | ||
|
||
**Configuration** | ||
|
||
- System configuration | ||
- e.g. service host names and ports | ||
- Changes need to be propagated to other services | ||
- Typically modified on the CLI | ||
|
||
**Settings** | ||
|
||
- Application level settings | ||
- e.g. default language | ||
- Can be modified at runtime without restarting the service | ||
- Typically modified in the UI | ||
|
||
**Preferences** | ||
|
||
- User settings | ||
- Subset of "Settings" | ||
- Preferred language |