Roles
Kirby's user management is based on a simple role system. By default, Kirby is configured to provide two roles:
- Admin
- Editor
Roles can be assigned to the users in the Users section of the Panel.
The Admin role is mandatory and cannot be removed. Users with that role have all permissions, while editors are by default only allowed to edit their own user profile, but not allowed to create, modify or delete other users.
2.4.0 +
Creating your own roles
You can create your own roles in the site/roles
directory.
Each role gets its own PHP file, like site/roles/editor.php
:
<?php
return [
'name' => 'Editor',
'default' => false,
'permissions' => [
...
]
];
If you want to create roles that are not allowed to access the Panel at all without configuring permissions, use something like this:
<?php
return [
'name' => 'Client',
'default' => false,
'panel' => false
];
name option
The name
option sets the human-readable name of the role. It is displayed in the role select field on the user forms in the Panel.
default option
The default
option determines which role is being selected by default when a new user is being created.
Only one role can be the default.
panel option
The panel
option is a shortcut for the panel.access
permission. If you set it to false
, users won't be able to access the Panel at all. This option is useful for pure frontend roles.
permissions option
The permissions
option allows you to control the permissions (in the Panel or for your own frontend features) of all users with the role. Learn more about permissions.
Defining simple roles
If your roles are simple and don't have complex permission rules, you can define roles with a config option instead.
This is also the feature you need if you are still using an older Kirby version before Kirby 2.4.
Do not use these role definitions when definining role permissions in site/roles
.
c::set('roles', [
[
'id' => 'admin',
'name' => 'Admin',
'default' => true,
'panel' => true
],
[
'id' => 'editor',
'name' => 'Editor',
'panel' => true
],
[
'id' => 'client',
'name' => 'Client',
'panel' => false
]
]);
2.5.6 +
Users with invalid roles
If a user's account file contains an invalid role (a role that doesn't exist), Kirby used to fall back to the default role.
Because of the new permissions system, this might lead to a situation where a user has more permissions than he would have with his intended role.
Since version 2.5.6, Kirby assigns a role called nobody
to users with an invalid role. This role can't be defined by the developer. It is always set to a role without any permissions whatsoever.
The nobody
role can also not be selected in the Panel, it just means that a user has an invalid role. You can't save such a user in the Panel without actively choosing a new role for that user.
Excursion: Creating a role without permissions
If you need a role without permissions yourself, it is easily possible to define a custom role like this:
<?php
return [
'name' => 'Permissionless',
'permissions' => false
];
In fact that's exactly how the nobody
role works. But if you define a custom role like this, make sure not to call it nobody
as that name is reserved by Kirby's internal role (which can't be overwritten and which can't be selected in the Panel).