Kimai 2 provides a flexible permissions system, which is based on user roles.
This permission system limits access to the functionality of Kimai. If you are looking for a way to limit access to
timesheets, activities, projects and customers read the Team permission documentation.
Your user needs the
role_permissions to use it, this feature is available since Kimai 1.6.
You find it by looking out for the button in the users page.
This is the full list of existing permissions with short descriptions:
|view_activity||Allows access to the activity administration|
|create_activity||Create a new activity|
|edit_activity||Edit existing activities|
|view_project||Allows access to the project administration|
|create_project||Create a new project|
|edit_project||Edit existing projects|
|delete_project||Delete existing projects|
|view_customer||Allows access to the customer administration|
|create_customer||Create new customers|
|edit_customer||Edit existing customers|
|delete_customer||Delete existing customers|
|view_invoice||Allows access to the invoice section|
|create_invoice||Create a new invoice|
|manage_invoice_template||Administrate invoice templates|
|view_own_timesheet||Allows access to the own timesheet views|
|start_own_timesheet||Create a running timesheet record (restart and create)|
|stop_own_timesheet||Stop the own running timesheets records|
|create_own_timesheet||Create a new timesheet record with the dialog|
|edit_own_timesheet||Edit own timesheet records|
|export_own_timesheet||Export your own timesheet in the timesheet panel|
|delete_own_timesheet||Delete own timesheet records|
|view_other_timesheet||Allows access to the timesheet admin panel, listing records for all users|
|start_other_timesheet||Start running timesheet records for other users|
|stop_other_timesheet||Stop running timesheet records of other users|
|create_other_timesheet||Create a new timesheet record in the name of another user|
|edit_other_timesheet||Edit existing records of other users|
|export_other_timesheet||Export timesheet in the timesheet admin panel|
|delete_other_timesheet||Delete timesheets of other users|
|view_rate_own_timesheet||View the rates for own timesheet records (fixed, hourly and total)|
|edit_rate_own_timesheet||Edit the rates for own timesheet records (fixed, hourly and total)|
|view_rate_other_timesheet||View the rates for other users timesheet records (fixed, hourly and total)|
|edit_rate_other_timesheet||Edit the rates for other users timesheet records (fixed, hourly and total)|
|view_export||Allows access to the export module|
|create_export||Create an export from the selected timesheet data|
|edit_export_own_timesheet||Set the export state of your own timesheet record|
|edit_export_other_timesheet||Set the export state of for other users timesheet records|
|view_own_profile||View own user profile and statistics|
|edit_own_profile||Edit own user profile/account|
|preferences_own_profile||Allows a user to edit the own preferences|
|password_own_profile||Change own password (should be deactivated when LDAP is used)|
|roles_own_profile||SECURITY ALERT: change the own user roles|
|api-token_own_profile||Change the own API token|
|view_other_profile||View other user profiles|
|edit_other_profile||SECURITY ALERT: edit the profile for another user|
|password_other_profile||Change the password for another user|
|roles_other_profile||SECURITY ALERT: change roles for other users|
|preferences_other_profile||Change the preferences for another user|
|api-token_other_profile||Change the API token for other users|
|hourly-rate_own_profile||Edit the own (user specific) hourly rate|
|hourly-rate_other_profile||Edit other (users specific) hourly rate|
|teams_own_profile||Edit team assignments in own user profile (since 1.2)|
|teams_other_profile||Edit team assignments in other user profile (since 1.2)|
|view_user||Access the User administration and see the list of all users|
|create_user||Create new users|
|delete_user||SECURITY ALERT: Delete existing users|
|system_information||Enter the system-information (about) screen|
|system_configuration||Configure global Kimai settings|
|plugins||Access the plugin administration|
|view_tag||Access the tag administration|
|manage_tag||Edit existing and create new tags in the administration|
|delete_tag||Delete existing tags|
|edit_exported_timesheet||Edit and delete timesheet records which were exported|
|role_permissions||SECURITY ALERT: view and change permissions for user roles, create and delete user roles|
|edit_teamlead_activity||Allows teamleads to edit activities for assigned projects/customers (since 1.2)|
|budget_teamlead_activity||Allows teamleads to see the budget reports for activities of assigned projects/customers (since 1.2)|
|delete_teamlead_activity||Allows teamleads to delete activities of assigned projects/customers (since 1.2)|
|edit_team_activity||Allows team-members to edit activities of assigned projects/customers (since 1.2)|
|budget_team_activity||Allows team-members to see the budget reports for activities of assigned projects/customers (since 1.2)|
|delete_team_activity||Allows team-members to delete activities of assigned projects/customers (since 1.2)|
|edit_teamlead_project||Allows teamleads to edit assigned projects or projects for assigned customers (since 1.2)|
|budget_teamlead_project||Allows teamleads to see the budget reports for assigned projects or projects of assigned customers (since 1.2)|
|permissions_teamlead_project||Allows teamleads to edit the teams for assigned projects or projects of assigned customers (since 1.2)|
|delete_teamlead_project||Allows teamleads to delete assigned projects or projects for assigned customers (since 1.2)|
|edit_team_project||Allows team-members to edit assigned projects or projects for assigned customers (since 1.2)|
|budget_team_project||Allows team-members to see the budget reports for assigned projects or projects of assigned customers (since 1.2)|
|permissions_team_project||Allows team-members to edit the teams for assigned projects or projects of assigned customers (since 1.2)|
|delete_team_project||Allows team-members to delete assigned projects or projects for assigned customers (since 1.2)|
|edit_teamlead_customer||Allows teamleads to edit assigned customers (since 1.2)|
|budget_teamlead_customer||Allows teamleads to see the budget reports for assigned customers (since 1.2)|
|permissions_teamlead_customer||Allows teamleads to edit the teams for assigned customers (since 1.2)|
|delete_teamlead_customer||Allows teamleads to delete assigned customers (since 1.2)|
|edit_team_customer||Allows team-members to edit assigned customers (since 1.2)|
|budget_team_customer||Allows team-members to see the budget reports for assigned customers (since 1.2)|
|permissions_team_customer||Allows team-members to edit the teams for assigned customers (since 1.2)|
|delete_team_customer||Allows team-members to delete assigned customers (since 1.2)|
|view_team||See team management (since 1.2)|
|edit_team||Edit team assignments (since 1.2)|
|create_team||Create new teams (since 1.2)|
|delete_team||Delete existing teams (since 1.2)|
|view_team_member||View the teamlead and members for the teams of the current user (since 1.4)|
|details_customer||View customer details (account number, vat, rates, meta-fields, assigned teams & users) (since 1.7)|
|comments_customer||Show posted comments for customers. For adding/changing comments you need the
|details_project||View project details (Order number & date, start and end date, rates, assigned teams & users) (since 1.7)|
|comments_project||Show posted comments for projects. For adding/changing comments you need the
|lockdown_grace_timesheet||All records in the last lockdown period can be edited, even after the grace period ended (since 1.10)|
|lockdown_override_timesheet||None of the lockdown rules apply (since 1.10)|
There are other business rules which might limit access to certain functions, so these permissions are not the only checks in place.
For example timesheet records which were exported cannot be edited any longer, even if a user has the
Developer can add/change permissions through plugins, see Developers documentation.
Since Kimai 1.6 there is generally no reason for changing the default permission through the local.yaml. It can be considered bad practice, as it could lead to problems with future updates.
Before you learn to configure the permission system, you have to understand the three involved config types:
Permission sets- a re-usable mapping of a free choosable name (e.g.
TEST) to a list of:
!to negate a permission, e.g.
Permission maps- a mapping of a role name to a list of “permission sets” (no
@required here, e.g.
Permissions- a mapping of a role name to a list of:
An example and its explanation:
permissions: sets: ACTIVITY: ['view_activity', 'create_activity'] TIMESHEET: ['view_own_timesheet', 'start_own_timesheet'] PROFILE: ['my_profile', 'show_roles', 'other_profiles'] EXAMPLE: ['@PROFILE', '@ACTIVITY'] EXAMPLE_USER: ['@PROFILE', '!show_roles'] maps: ROLE_USER: ['TIMESHEET', 'EXAMPLE_USER'] ROLE_ADMIN: ['TIMESHEET', 'EXAMPLE'] roles: ROLE_USER: ['!other_profiles'] ROLE_ADMIN: ['delete_activity']
setswe define the
permissions setsnames “ACTIVITY”, “TIMESHEET”, “PROFILE” and “EXAMPLE”.
setcalled “EXAMPLE” inherits the other
setscalled “PROFILE” and “ACTIVITY”, so its contains the permissions: my_profile, show_roles, other_profiles, view_activity , create_activity.
setcalled “EXAMPLE_USER” inherits the
setcalled “PROFILE” and removes the permission “show_roles”, so its contains the permissions: my_profile, other_profiles.
maps we now apply the
permission set called “TIMESHEET” and “EXAMPLE_USER” to the user-role “ROLE_USER”
and the two
permission sets called “TIMESHEET” and “EXAMPLE” to the user-role “ROLE_ADMIN”.
At this step the roles have the following permissions:
ROLE_USER- view_own_timesheet, start_own_timesheet, my_profile, other_profiles
ROLE_ADMIN- view_own_timesheet, start_own_timesheet, my_profile, show_roles, other_profiles, view_activity, create_activity
As last step, the list of
permission names will be merged with the list of previously calculated permissions.
We removed the permission “other_profiles” from the user-role “ROLE_USER” and added the permission “delete_activity” 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, my_profile, show_roles, other_profiles, view_activity, create_activity, delete_activity
Yes, that could have been easier ;-) but I wanted to demonstrate all possibilities!
In most cases you just want to adjust single permissions, like remove from or add single permissions to a user role. This can be done by adding something like this to your local.yaml:
kimai: permissions: roles: ROLE_TEAMLEAD: ['!edit_invoice_template', 'delete_invoice_template']
This example removes
edit_invoice_template and adds
delete_invoice_template for the user role
If you want to go further and want to re-adjust which
sets are applied to a user role, you have to overwrite the
complete map for that role. Lets assume you want to redefine user permissions and allow full access to tags,
then you edit your
local.yaml like this:
kimai: permissions: maps: ROLE_USER: ['ROLE_USER', 'TAGS']
As you overwrite the default map
ROLE_USER by defining it, you have to apply the default set
ROLE_USER and append the set
TAGS (see below in “Existing maps”).
Customizing sets is generally not recommended, as you should be able to achieve everything with
See below in “Existing sets”.
Existing sets can be seen in
kimai.yaml. I will not go into details here, as their customization
is generally not necessary.
You cannot extend existing sets, if you define them, they will be overwritten with your config.
Therefor it is not recommended to overwrite any existing
set but create new ones.
Please start their name with a prefix like ‘CUSTOM_’:
kimai: permissions: sets: CUSTOM_ROLE_USER: ['@ROLE_USER', '@TAGS'] maps: ROLE_USER: ['CUSTOM_ROLE_USER']
By default each role owns only one set, which is called like the user role itself:
kimai: permissions: maps: ROLE_USER: ['ROLE_USER'] ROLE_TEAMLEAD: ['ROLE_TEAMLEAD'] ROLE_ADMIN: ['ROLE_ADMIN'] ROLE_SUPER_ADMIN: ['ROLE_SUPER_ADMIN']