diff --git a/docs/book/v1/basic-usage.md b/docs/book/v1/basic-usage.md new file mode 100644 index 0000000..968b732 --- /dev/null +++ b/docs/book/v1/basic-usage.md @@ -0,0 +1,60 @@ +# Basic Usage + +## Configure an RBAC system + +You can configure your RBAC using a configuration file, as follows: + +```php +// 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`). + +## Custom Authorization Logic + +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: + +```php +isGranted(string $role, ServerRequestInterface $request): bool; +``` + +where `$role` is the role and `$request` is the PSR-7 HTTP request to authorize. diff --git a/docs/book/v1/dynamic-assertion.md b/docs/book/v1/dynamic-assertion.md index 118af5b..dda823c 100644 --- a/docs/book/v1/dynamic-assertion.md +++ b/docs/book/v1/dynamic-assertion.md @@ -9,6 +9,8 @@ These types of authorization are called [dynamic assertions](https://docs.lamina and are implemented via the `Laminas\Permissions\Rbac\AssertionInterface` of [laminas-permissions-rbac](https://github.com/laminas/laminas-permissions-rbac). +## Interfaces + In order to use it, this package provides `LaminasRbacAssertionInterface`, which extends `Laminas\Permissions\Rbac\AssertionInterface`: @@ -35,6 +37,8 @@ interface AssertionInterface } ``` +## Example + Going back to our use case, we can build a class to manage the "editor" authorization requirements, as follows: diff --git a/docs/book/v1/installation.md b/docs/book/v1/installation.md new file mode 100644 index 0000000..be1198c --- /dev/null +++ b/docs/book/v1/installation.md @@ -0,0 +1,5 @@ +# This Is Only a Placeholder + +The content of this page can be found under: + +https://github.com/laminas/documentation-theme/blob/master/theme/pages/installation.html diff --git a/docs/book/v1/intro.md b/docs/book/v1/intro.md index ce7e7da..7a8f8ee 100644 --- a/docs/book/v1/intro.md +++ b/docs/book/v1/intro.md @@ -4,6 +4,8 @@ This component provides [Role-Based Access Control](https://en.wikipedia.org/wik (RBAC) authorization abstraction for the [mezzio-authorization](https://github.com/mezzio/mezzio-authorization) library. +## Roles, Identities, Permissions + 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 @@ -12,8 +14,8 @@ calls). In a typical RBAC system: -- An **identity** has one or more roles. - A **role** requests access to a permission. +- An **identity** has one or more roles. - A **permission** is given to a role. Thus, RBAC has the following model: @@ -29,64 +31,8 @@ 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: - -```php -// 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: - -```php -isGranted(string $role, ServerRequestInterface $request) : bool -``` - -where `$role` is the role and `$request` is the PSR-7 HTTP request to authorize. - +> ### laminas-permissions-rbac +> > This library uses the [laminas/laminas-permissions-rbac](https://docs.laminas.dev/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](https://framework.zend.com/blog/2017-04-27-zend-permissions-rbac.html). +> of this library, read the blog post [Manage permissions with laminas-permissions-rbac](https://framework.zend.com/blog/2017-04-27-zend-permissions-rbac.html). diff --git a/mkdocs.yml b/mkdocs.yml index 3e3c9a0..1095fcb 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -3,10 +3,13 @@ site_dir: docs/html nav: - Home: index.md - Introduction: v1/intro.md - - Reference: - - 'Dynamic Assertion': v1/dynamic-assertion.md + - Installation: v1/installation.md + - Basic Usage: v1/basic-usage.md + - 'Dynamic Assertion': v1/dynamic-assertion.md site_name: mezzio-authorization-rbac site_description: 'RBAC permission adapter for mezzio-authorization.' repo_url: 'https://github.com/mezzio/mezzio-authorization-rbac' extra: project: Mezzio + installation: + config_provider_class: 'Mezzio\Authorization\Rbac\ConfigProvider'