Authorization Guards

Summary

This page explains how Dotkernel Frontend restricts access: roles and their permissions are defined in authorization.global.php, and authorization-guards.global.php requires those permissions for specific routes and controller actions.

Details

The packages responsible for restricting access to certain parts of the application are dot-rbac-guard and dot-rbac. These packages work together to create an infrastructure that is customizable and diversified to manage user access to the platform by specifying the type of role the user has.

The authorization.global.php file provides multiple configurations specifying multiple roles as well as the types of permissions to which these roles have access.

// config/autoload/authorization.global.php - flat RBAC model shipped with Frontend
'dot_authorization' => [
    'guest_role'    => 'guest',
    'role_provider' => [
        'type'    => 'InMemory',
        'options' => [
            'roles' => [
                'user'  => [
                    'permissions' => [
                        'authenticated',
                        'premium',
                    ],
                ],
                'guest' => [
                    'permissions' => [
                        'unauthenticated',
                    ],
                ],
            ],
        ],
    ],
],

The authorization-guards.global.php file provides configuration to restrict access to certain actions based on the permissions defined in authorization.global.php so basically we have to add the permissions in the dot-rbac configuration file first to specify the action restriction permissions.

// config/autoload/authorization-guards.global.php - ControllerPermission guard shipped with Frontend
'type'    => 'ControllerPermission',
'options' => [
    'rules' => [
        [
            'route'       => 'account',
            'actions'     => [ // list of actions to apply, or empty array for all actions
                'avatar',
                'details',
                'changePassword',
                'deleteAccount',
            ],
            'permissions' => ['authenticated'],
        ],
        [
            'route'       => 'page',
            'actions'     => [
                'premium-content',
            ],
            'permissions' => ['premium'], // list of permissions required
        ],
    ],
],

The default protection_policy is GuardInterface::POLICY_ALLOW: routes and actions without a rule are accessible to everyone.

FAQ

Q: What happens to routes and actions that have no rule?

A: They are open to everyone. The shipped protection_policy is GuardInterface::POLICY_ALLOW.

Q: Which role does a visitor who is not logged in have?

A: guest, as set by guest_role in authorization.global.php. It has only the unauthenticated permission.

Q: How do I protect every action of a route?

A: Add a rule for the route with an empty actions array.

Q: What is the premium permission for?

A: It protects the premium-content action of the page route (/page/premium-content). The shipped user role has it, so any logged-in user can open the page.

Q: Where are a user's roles stored?

A: In the user_role table, linked to users through user_roles. The default roles are created by the RoleLoader fixture.