mimmi20/mezzio-generic-authorization

Provides a Authorization middleware for Mezzio and PSR-7 applications.

3.0.7 2024-09-16 04:39 UTC

README

Latest Stable Version Latest Unstable Version License

Code Status

codecov Test Coverage Average time to resolve an issue Percentage of issues still open Mutation testing badge Maintainability

Installation

You can install the mezzio-generic-authorization library with Composer:

composer require mimmi20/mezzio-generic-authorization

Introduction

This component provides middleware for Mezzio and PSR-7 applications for authorizing specific routes based on ACL or RBAC systems.

Unlike in mezzio-authorization this library does not require the ServerRequestInterface by default. This makes it possible to use this component in combination with mezzio-navigation.

If you are using the provided midleware, the route name is used as the resource.

An authorization system first needs authentication: to verify that an identity has access to something (i.e., is authorized) we first need the identity, which is provided during authentication.

Authentication is provided via the package mezzio-authentication. That library provides an AuthenticationMiddleware class that verify credentials using the HTTP request, and stores the identity via a PSR-7 request attribute.

The identity generated by mezzio-authentication is stored as the request attribute Mezzio\Authentication\UserInterface as a UserInterface implementation. That interface looks like the following:

namespace Mezzio\Authentication;

interface UserInterface
{
    /**
     * Get the unique user identity (id, username, email address or ...)
     */
    public function getIdentity() : string;

    /**
     * Get all user roles
     *
     * @return Iterable
     */
    public function getRoles() : iterable;

    /**
     * Get a detail $name if present, $default otherwise
     */
    public function getDetail(string $name, $default = null);

    /**
     * Get all the details, if any
     */
    public function getDetails() : array;
}

mezzio-generic-authorization consumes this identity attribute. It checks if a user's role (as retrieved from the UserInterface object) is authorized (granted) to the perform the current HTTP request.

Authorization is performed using the isGranted() method of the AuthorizationInterface

public function isGranted(?string $role = null, ?string $resource = null, ?string $privilege = null, ?\Psr\Http\Message\ServerRequestInterface\ServerRequestInterface $request = null): bool;

Two adapters are available:

If you want to know more about authentication using middleware in PHP, we suggest reading the blog post "Authorize users using Middleware".

Authorization adapters

You can configure the authorization adapter to use via your service container configuration. Specifically, you can either map the service name Mimmi20\Mezzio\GenericAuthorization\AuthorizationInterface to a factory, or alias it to the appropriate service.

For instance, using Mezzio container configuration, you could select the mezzio-authorization-acl adapter in either of the following ways:

  • Using an alias:

    use Mimmi20\Mezzio\GenericAuthorization\AuthorizationInterface;
    use Mimmi20\Mezzio\GenericAuthorization\Acl\LaminasAcl;
    
    return [
        'dependencies' => [
            // Using an alias:
            'aliases' => [
                AuthorizationInterface::class => LaminasAcl::class,
            ],
        ],
    ];
  • Mapping to a factory:

    use Mimmi20\Mezzio\GenericAuthorization\AuthorizationInterface;
    use Mimmi20\Mezzio\GenericAuthorization\Acl\LaminasAclFactory;
    
    return [
        'dependencies' => [
            // Using a factory:
            'factories' => [
                AuthorizationInterface::class => LaminasAclFactory::class,
            ],
        ],
    ];

We provide two different adapters.

Each adapter is installable via Composer:

composer require mimmi20/mezzio-generic-authorization-rbac
# or
composer require mimmi20/mezzio-generic-authorization-acl

License

This package is licensed using the MIT License.

Please have a look at LICENSE.md.