Introduction

This component provides Role-Based Access Control (RBAC) authorization abstraction for the mezzio-authorization library.

RBAC is based on the idea of roles. In a web application, users have an identity (e.g. username, email, etc). Each identified user then has one or more roles (e.g. admin, editor, guest). Each role has a permission to perform one or more actions (e.g. access an URL, execute specific web API calls).

In a typical RBAC system:

  • An identity has one or more roles.
  • A role requests access to a permission.
  • A permission is given to a role.

Thus, RBAC has the following model:

  • Many-to-many relationship between identities and roles.
  • Many-to-many relationship between roles and permissions.
  • Roles can have a parent role.

The first requirement for an RBAC system is identities. In our scenario, the users are generated by an authentication system, provided by mezzio-authentication. That library provides a PSR-7 request attribute named Mezzio\Authentication\UserInterface when a user is authenticated. The RBAC system uses this instance to get information about the user's identity.

Configure an RBAC system

You can configure your RBAC using a configuration file, as follows:

// config/autoload/authorization.local.php
return [
    // ...
    'mezzio-authorization-rbac' => [
        'roles' => [
            'administrator' => [],
            'editor'        => ['administrator'],
            'contributor'   => ['editor'],
        ],
        'permissions' => [
            'contributor' => [
                'admin.dashboard',
                'admin.posts',
            ],
            'editor' => [
                'admin.publish',
            ],
            'administrator' => [
                'admin.settings',
            ],
        ],
    ]
];

In the above example, we designed an RBAC system with 3 roles: administator, editor, and contributor. We defined a hierarchy of roles as follows:

  • administrator has no parent role.
  • editor has administrator as a parent. That means administrator inherits the permissions of the editor.
  • contributor has editor as a parent. That means editor inherits the permissions of contributor, and following the chain, administator inherits the permissions of contributor.

For each role, we specified an array of permissions. As you can notice, a permission is just a string; it can represent anything. In our implementation, this string represents a route name. That means the contributor role can access the routes admin.dashboard and admin.posts but cannot access the routes admin.publish (assigned to editor role) and admin.settings (assigned to administrator).

If you want to change the authorization logic for each permission, you can write your own Mezzio\Authorization\AuthorizationInterface implementation. That interface defines the following method:

isGranted(string $role, ServerRequestInterface $request) : bool

where $role is the role and $request is the PSR-7 HTTP request to authorize.

This library uses the laminas/laminas-permissions-rbac library to implement the RBAC system. If you want to know more about the usage of this library, read the blog post Manage permissions with laminas-permissions-rbac.

Found a mistake or want to contribute to the documentation? Edit this page on GitHub!