README

The package provides Yii 3 authorization middleware that uses Yii RBAC. It is intended for use with web applications. For authorization of a RESTful web service, use the YII3-KEYCLOAK-AUTHZ package instead.

Requirement

• PHP 8.1 or higher.

Installation

composer require klsoft/yii3-authz

How to use

1. Configure Authentication

Example:

use Yiisoft\Session\Session;
use Yiisoft\Session\SessionInterface;
use Yiisoft\Auth\IdentityRepositoryInterface;
use Yiisoft\Definitions\Reference;
use Yiisoft\Auth\AuthenticationMethodInterface;
use Yiisoft\User\Method\WebAuth;

return [
 // ...
 SessionInterface::class => [
 'class' => Session::class,
 '__construct()' => [
 $params['session']['options'] ?? [],
 $params['session']['handler'] ?? null,
 ],
 ],
 IdentityRepositoryInterface::class => IdentityRepository::class,
 CurrentUser::class => [
 'withSession()' => [Reference::to(SessionInterface::class)]
 ],
 AuthenticationMethodInterface::class => WebAuth::class,
];

2. Configure RBAC

3. Add the forbidden URL to param.php

Example:

return [
 'forbiddenUrl' => '/forbidden',
];

4. Configure Authorization

Example:

use Klsoft\Yii3Authz\Middleware\Authorization;

return [
 // ...
 Authorization::class => [
 'class' => Authorization::class,
 '__construct()' => [
 'forbiddenUrl' => $params['forbiddenUrl']
 ],
 ],
];

5. Apply permissions.

5.1. To an action.

First, add Authorization to a route:

use Yiisoft\Auth\Middleware\Authentication;
use Klsoft\Yii3Authz\Middleware\Authorization;

Route::post('/post/create')
 ->middleware(Authentication::class)
 ->middleware(Authorization::class)
 ->action([PostController::class, 'create'])
 ->name('post/create')

Or to a group of routes:

use Yiisoft\Auth\Middleware\Authentication;
use Klsoft\Yii3Authz\Middleware\Authorization;

Group::create()
 ->middleware(Authentication::class)
 ->middleware(Authorization::class)
 ->routes(
 Route::post('/post/create')
 ->action([PostController::class, 'create'])
 ->name('post/create'),
 Route::put('/post/update/{id}')
 ->action([PostController::class, 'update'])
 ->name('post/update')
 )

Then, apply permissions to an action:

use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Message\ResponseInterface;
use Klsoft\Yii3Authz\Permission;

final class PostController
{
 public function __construct(private PostPresenterInterface $postPresenter)
 {
 }

 #[Permission('createPost')]
 public function create(ServerRequestInterface $request): ResponseInterface
 {
 return $this->postPresenter->createPost($request);
 }
}

Example of an OR permission:

#[Permission('createPost|updatePost')]
public function edit(#[RouteArgument('id')] ?int $id = null, ServerRequestInterface $request): ResponseInterface

Example of a permission with an executing parameter value that would be passed to the rules associated with the roles:

#[Permission( 
 'updatePost', 
 ['post' => [ 
 '__container_entry_identifier', 
 PostPresenterInterface::class, 
 'getPost', 
 ['__request']] 
 ] 
)]
public function update(#[RouteArgument('id')] int $id, ServerRequestInterface $request): ResponseInterface

5.2. To a route.

First, define the set of permissions:

use Psr\Container\ContainerInterface;
use Klsoft\Yii3Authz\Middleware\Authorization;
use Klsoft\Yii3Authz\Permission;

'CreatePostPermission' => static function (ContainerInterface $container) {
 return $container
 ->get(Authorization::class)
 ->withPermissions([
 new Permission('createPost'])
 ]);
 }

Then, you can apply this set to a route:

use Yiisoft\Auth\Middleware\Authentication;

Route::post('/post/create')
 ->middleware(Authentication::class)
 ->middleware('CreatePostPermission')
 ->action([PostController::class, 'create'])
 ->name('post/create')