Permissions in Kirby can be defined in two places:
- In a user blueprint for each role
- In the page, file or the site blueprint for more detailed rules
Each role can have its own blueprint with custom fields for users with that role and optional user permissions. User blueprints are stored in
/site/blueprints/users and get the name of each role (i.e
Permissions are only valid for custom roles. The admin role does not obey to those settings and can always do anything.
Here is an overview of all available permissions:
You don't have to set all permissions for each role. Each permission is set to
true by default, if not specified otherwise.
You can also enable or disable entire permission sections by passing
false instead of an array of definitions for each action. A more simple permission setup for an editor, who should not be allowed to edit other users, could look like this:
This would prevent the editor from editing other users (
users: false), from changing their own role, from deleting pages and from updating the site settings.
For permission types with many actions with the same setting, you can use the * wildcard as first argument. Afterwards you can still override specific actions, for example to whitelist actions:
user: *: false changeName: true
Frontend users can also be managed through the Panel, but you most likely don't want them to be able to access the Panel at all. In order to achieve this, set Panel access to
title: Visitor permissions: access: panel: false
If you use any of Kirby's PHP APIs in the frontend to modify pages, files, the site or users, you should set the permissions like above to control what a visitor can do in your frontend. You can also have multiple frontend user roles without access to the Panel but with different access rights to the PHP APIs. Our REST API follows the same rules.
You can keep all permissions in the role files, but you can also overwrite them individually per page, file, user or the site in the corresponding blueprints. Those specific permission settings will always override the role settings.
You can control each option for pages, files and users in blueprints with fine-grained permissions based on user role:
options: delete: admin: true editor: false
You can also use a wildcard to change the default for all roles and then assign exceptions to individual roles:
options: update: *: false editor: true
If the blueprint-based permission settings are too limiting for your project, you can get more flexibility by creating your own permission checks with
before hooks for various actions.
Of course this can be more complex and sophisticated than that, but it's a good first start.
To obtain the required permissions for certain actions, you can authenticate as a user by logging in. If you want to run actions programmatically without logging in, you can also impersonate a user.
Users can log in through the Panel login page or a custom login form. To learn more about how to log in a user programmatically, read the reference for $user->login().
One way to go without authentication is to impersonate an existing user or the special
kirby super user, which has full permissions:
<?php $kirby = kirby(); $kirby->impersonate('kirby'); page('notes/a-great-article')->update([ 'author' => 'Homer Simpson' ]);
The impersonation will only last for the current request.