added configurable permission system (#424)
This commit is contained in:
Kevin Papst
@@ -14,7 +14,8 @@ For the most parts Kimai usage should be self-explanatory, so we will only cover
|
||||
- [Configurations](configurations.md) - intro into the global application configs
|
||||
- [Calendar](calendar.md) - the Timesheet calendar view
|
||||
- [Dashboard & widgets](dashboard.md) - how to configure widgets and dashboard sections
|
||||
- [Emails](emails.md) - transport configuration and handling of emails
|
||||
- [Emails](emails.md) - transport configuration and handling of emails
|
||||
- [Permissions](permissions.md) - flexible and configurable ROLE based permission system
|
||||
- [Developer](developers.md) - docs about extending Kimai's feature set
|
||||
- [API](developers_api.md) - how to use the JSON API
|
||||
- [Theme settings](theme.md) - theme related settings
|
||||
|
||||
115
var/docs/permissions.md
Normal file
115
var/docs/permissions.md
Normal file
@@ -0,0 +1,115 @@
|
||||
# Permissions
|
||||
|
||||
Kimai 2 provides a flexible permissions system, which can be adapted though your [local.yaml](configurations.md) config
|
||||
file and that is based on [user roles](users.md).
|
||||
|
||||
## Understanding permission structure
|
||||
|
||||
Before you learn to configure the permission system, you have to understand the three involved config types:
|
||||
|
||||
1. `Permission sets` define a re-usable name for a list of "permission names"
|
||||
2. `Permission maps` will apply a list of "permission sets" to a "user role"
|
||||
3. `Permissions` apply a list of "permission names" to a "user role"
|
||||
|
||||
An example and its explanation:
|
||||
|
||||
```yaml
|
||||
permissions:
|
||||
sets:
|
||||
ACTIVITY: [view_activity,create_activity]
|
||||
TIMESHEET: [view_own_timesheet,start_own_timesheet]
|
||||
maps:
|
||||
ROLE_USER: [TIMESHEET]
|
||||
ROLE_ADMIN: [TIMESHEET,ACTIVITY]
|
||||
roles:
|
||||
ROLE_USER: [my_profile]
|
||||
ROLE_ADMIN: [my_profile,start_other_timesheet]
|
||||
```
|
||||
|
||||
In `sets` we define the two `permissions sets` names "ACTIVITY" and "TIMESHEET". In `maps` we apply the `permissions set` to the
|
||||
called "TIMESHEET" to the user-role "ROLE_USER" and the two `permissions set` called "TIMESHEET" and "ACTIVITY" to the user-role "ROLE_ADMIN".
|
||||
|
||||
At this step the role have the following permissions:
|
||||
|
||||
- `ROLE_USER`: view_own_timesheet,start_own_timesheet
|
||||
- `ROLE_ADMIN`: view_own_timesheet,start_own_timesheet,view_activity,create_activity
|
||||
|
||||
As last step, the list of `permission names` will be added to the list of calculated permissions.
|
||||
So we add the permission "my_profile" to the user-role "ROLE_USER" and the two permissions "my_profile" and "start_other_timesheet" to the user-role "ROLE_ADMIN".
|
||||
|
||||
At the end the system calculated the final list of permissions:
|
||||
|
||||
- `ROLE_USER`: view_own_timesheet,start_own_timesheet,my_profile
|
||||
- `ROLE_ADMIN`: view_own_timesheet,start_own_timesheet,view_activity,create_activity,my_profile,start_other_timesheet
|
||||
|
||||
## Existing permissions
|
||||
|
||||
The permission-names were chosen to be self-explanatory. In the hope that it worked, here is the full list of existing permissions:
|
||||
|
||||
| Permission name | Set name | API use | Description |
|
||||
|---|---|---|---|
|
||||
| view_activity | ACTIVITIES | | allows access to the activity administration |
|
||||
| create_activity | ACTIVITIES | | - |
|
||||
| edit_activity | ACTIVITIES | | - |
|
||||
| delete_activity | ACTIVITIES | | - |
|
||||
| view_project | PROJECTS | | allows access to the project administration |
|
||||
| create_project | PROJECTS | | - |
|
||||
| edit_project | PROJECTS | | - |
|
||||
| delete_project | PROJECTS | | - |
|
||||
| view_customer | CUSTOMERS | | allows access to the customer administration |
|
||||
| create_customer | CUSTOMERS | | - |
|
||||
| edit_customer | CUSTOMERS | | - |
|
||||
| delete_customer | CUSTOMERS | | - |
|
||||
| view_invoice | INVOICE | | allows access to the invoice section |
|
||||
| create_invoice | INVOICE | | - |
|
||||
| view_invoice_template | INVOICE_TEMPLATE | | allows access to the invoice and invoice template section |
|
||||
| create_invoice_template | INVOICE_TEMPLATE | | - |
|
||||
| edit_invoice_template | INVOICE_TEMPLATE | | - |
|
||||
| delete_invoice_template | INVOICE_TEMPLATE | | - |
|
||||
| view_own_timesheet | TIMESHEET | X | - |
|
||||
| start_own_timesheet | TIMESHEET | | - |
|
||||
| stop_own_timesheet | TIMESHEET | | - |
|
||||
| create_own_timesheet | TIMESHEET | X | - |
|
||||
| edit_own_timesheet | TIMESHEET | | - |
|
||||
| export_own_timesheet | TIMESHEET | | - |
|
||||
| delete_own_timesheet | TIMESHEET | | - |
|
||||
| view_other_timesheet | TIMESHEET_OTHER | | allows access to the complete timesheet view |
|
||||
| start_other_timesheet | TIMESHEET_OTHER | | - |
|
||||
| stop_other_timesheet | TIMESHEET_OTHER | | - |
|
||||
| create_other_timesheet | TIMESHEET_OTHER | | - |
|
||||
| edit_other_timesheet | TIMESHEET_OTHER | | - |
|
||||
| delete_other_timesheet | TIMESHEET_OTHER | | - |
|
||||
| view_rate_own_timesheet | RATE | | - |
|
||||
| edit_rate_own_timesheet | RATE | | - |
|
||||
| view_rate_other_timesheet | RATE_OTHER | | - |
|
||||
| edit_rate_other_timesheet | RATE_OTHER | | - |
|
||||
| view_own_profile | PROFILE | | Allows access to the own profile view. Without this permission, users cannot access any of their profile settings or passwords ... |
|
||||
| edit_own_profile | PROFILE | | - |
|
||||
| delete_own_profile | PROFILE | | - |
|
||||
| password_own_profile | PROFILE | | - |
|
||||
| roles_own_profile | PROFILE | | - |
|
||||
| preferences_own_profile | PROFILE | | - |
|
||||
| api-token_own_profile | PROFILE | | - |
|
||||
| view_other_profile | PROFILE_OTHER | | - |
|
||||
| edit_other_profile | PROFILE_OTHER | | - |
|
||||
| delete_other_profile | PROFILE_OTHER | | - |
|
||||
| password_other_profile | PROFILE_OTHER | | allows to change the password for another user |
|
||||
| roles_other_profile | PROFILE_OTHER | | allows to change roles for other users |
|
||||
| preferences_other_profile | PROFILE_OTHER | | allows to change the preferences for another user |
|
||||
| api-token_other_profile | PROFILE_OTHER | | allows to set the API login token for other users |
|
||||
| hourly-rate_own_profile | - | | allows to edit the own user specific hourly rate |
|
||||
| hourly-rate_other_profile | - | | allows to edit other users specific hourly rate |
|
||||
| view_user | USER | X | allows to access the User administration and see the list of all users |
|
||||
| create_user | USER | | allows to create new users |
|
||||
| delete_user | USER | | allows to delete existing users |
|
||||
|
||||
## Configure permissions
|
||||
|
||||
Knowing that many companies need a different combination of allowed permissions than the default ones, you might also
|
||||
want to change the pre-configured permission.
|
||||
|
||||
You can do that in your [local.yaml](configurations.md). Define the permissions like we did in the above mentioned example,
|
||||
you might start by copying the default permissions from `kimai.yaml`.
|
||||
|
||||
Be aware: if you configure your own permission definition, you have to overwrite the complete
|
||||
node (`sets`, `maps` or`roles`) that you edited and define all SETS and/or ROLES.
|
||||
@@ -1,16 +1,20 @@
|
||||
# Users
|
||||
|
||||
## Roles & Permissions
|
||||
## Roles
|
||||
|
||||
There are multiple pre-defined roles in Kimai, which define the ACLs. A user can only inherit one role, where the roles extend each user.
|
||||
There are multiple pre-defined roles in Kimai, which define the ACLs/permissions.
|
||||
|
||||
| Role name | extends | Gives permission for |
|
||||
| Role name | extends | Description |
|
||||
|---|---|---|
|
||||
| ROLE_CUSTOMER | - | Currently has no permissions, but was reserved for future functionality |
|
||||
| ROLE_USER | ROLE_CUSTOMER | Time-tracking |
|
||||
| ROLE_TEAMLEAD | ROLE_USER | All of the above, plus: editing other users timesheets |
|
||||
| ROLE_ADMIN | ROLE_TEAMLEAD | All of the above, plus: editing customers, editing projects, editing activities |
|
||||
| ROLE_SUPER_ADMIN | ROLE_ADMIN | All of the above, plus: editing users |
|
||||
| ROLE_CUSTOMER | - | Currently not used, reserved for future features |
|
||||
| ROLE_USER | ROLE_CUSTOMER | Normal user that wants to track working times |
|
||||
| ROLE_TEAMLEAD | ROLE_USER | This role manages teams of ROLE_USER (this feature is not yet implemented, but planned for the future) and has further permissions on invoices |
|
||||
| ROLE_ADMIN | ROLE_TEAMLEAD | Admins can do almost everything in Kimai, except some user specific tasks |
|
||||
| ROLE_SUPER_ADMIN | ROLE_ADMIN | Evey Super-Admin can do anything Kimai |
|
||||
|
||||
### Permissions
|
||||
|
||||
The permission system is configurable through a configuration file. You can find further information in the [permissions](permissions.md) chapter.
|
||||
|
||||
## Login
|
||||
|
||||
|
||||
Reference in New Issue
Block a user