117 lines
6.2 KiB
Markdown
117 lines
6.2 KiB
Markdown
# 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 | | export your own timesheet in the timesheet panel |
|
||
| 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 | | - |
|
||
| export_other_timesheet | TIMESHEET | | export timesheet in the timesheet admin panel |
|
||
| 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 | | grants access to edit the own profile |
|
||
| delete_own_profile | PROFILE | | grants access to delete the own profile |
|
||
| password_own_profile | PROFILE | | grants access to change the own password |
|
||
| roles_own_profile | PROFILE | | SECURITY ALERT: grants access to the own roles |
|
||
| preferences_own_profile | PROFILE | | grants access to the own preferences |
|
||
| api-token_own_profile | PROFILE | | grants access to change the own API token |
|
||
| 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 | | SECURITY ALERT: 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.
|