Permissions
Defining permissions
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
Role based permissions in user blueprints
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 /site/blueprints/users/editor.yml
).
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:
The user
permission only applies to the user itself, while the users
permissions sets these permissions for all users.
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 true
or 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.
The *
wildcard
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:
Visitors without Panel access
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 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.
Specific permissions in page, file, user or site options
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.
Page options
Since 3.2.0
You can control each option for pages, files and users in blueprints with fine-grained permissions based on user role:
You can also use a wildcard to change the default for all roles and then assign exceptions to individual roles:
Controlling permissions with hooks
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.
Authenticate or impersonate
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.
Authentication
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().
Impersonate
One way to go without authentication is to impersonate an existing user or the special kirby
super user, which has full permissions:
The impersonation will be active for all code that runs in the current request after the call to $kirby->impersonate()
. If you want to limit the impact to a single operation, call the method with a callback (see below).
Since 3.4.0
Impersonate with callback
If you only want a single operation to run with different privileges, use a callback:
The impersonation automatically gets reset to the previous value after the callback returns.
Since 3.5.0
Disable all permissions
It is also possible to disable all permissions, even if a user is currently logged in. This is useful for operations where you want to ensure that no changes are made to the site (read-only access):