laminas-authorization

Out of the box, Laminas's authentication module provides interfaces and services for authenticating users and saving their identities in a session storage. This module provides an authorization service by transparently redirecting unauthorized users accessing a certain resource, with the support of defining multiple authorization links forming an authorization chain. You can configure the list of controller/method authorization statuses (policies) by creating annotations on top of your methods or setting it in the configuration.

Installation

Install using composer, run

$ composer require alichry/laminas-authorization

Add the modules AliChry\Laminas\AccessControl and AliChry\Laminas\Authorization to config/modules.config.php

Prerequisites

This module is not concerned with authenticating users, rather, its only intent is to check the authorization status of the (authenticated) identity. To create an authorization link, we require:

An AuthenticationServiceInterface: You can use doctrine/doctrine-module to configure an authentication service easily.
An AccessControlListInterface: alichry/laminas-accesscontrol provides configurable services. By default, this module configures an IdentityAccessControlList instance using AnnotatedResourceManager as a dependency alongside passed identities implementing IdentityInterface.

Quick start

The fastest path to create a Laminas application with authorization support is through Doctrine ORM integration. If you're unfamiliar with Doctrine ORM, please check the doctrine project website and doctrine/doctrine-orm-module

Let your identity type class implement IdentityInterface. The methods to implement are hasPermission and hasRole, in an ORM environment where the associations are already defined, it is easy to implement such methods.
The authorization service requires an authentication service, configure Doctrine\Authentication to quickly deploy an authentication service based on your identity type.
Configure this module by defining a "global" authorization link:

<?php
# module.config.php

use Laminas\Authentication\AuthenticationService;

return [
    // ...
    'alichry' => [
        'authorization' => [
            'chain' => [
                'global' => [
                    'redirect_route' => 'login',
                    'authentication_service' => AuthenticationService::class,
                    'access_control_list' => 'identity'
                ]
            ]
        ]
    ],
    // ...
];

The authorization service is now configured, you can define annotations on top of your methods to indicate authorization policies.

Defining method policy using annotations

On top of your controller's method or class docblock, you can define @Authorization annotations, indicating:

The target link name.
The policy: Allow, Reject, Authenticate or Authorize.
The permission: if the specified policy is Authorize, permission should also be specified.

You can define multiple annotations, each with a different link name. Additionally, you can omit the link name and it will be treated as the fallback.

Example:

<?php
use AliChry\Laminas\Authorization\Annotation\Authorization;

/**
 * Class-level annotations are treated as a fallback. First method annotations
 * are consulted, if no relevant method annotations were found then
 * class-level annotations are utilized.
 *
 * Default class policy is to reject unspecified links:
 * @Authorization(policy="Reject")
 *
 * Require valid authentication status for "global" link:
 * @Authorization(link="global", policy="Authenticate")
 */
class ApplicationController
{
    /**
     * Allow this resource to be publicly accessible:
     * @Authorization(policy="Allow")
     * The above will override class-level annotations, and since the link
     * property was omitted, it will apply to all links.
     */
    public function indexAction()
    {
    }
        
    /**
     * Allow this resource to be accessible by entities granted the "delete"
     * permission under the "global" link:
     * @Authorization(link="global", policy="Authorize", permission="delete")
     */
    public function deleteAction()
    {
    }

    /**
     * No annotations are defined for this method, the class annotations
     * will be used as a fallback. This method requires the user to be
     * authenticated for the "global" link or the request is rejected for all
     * other links.
     */
    public function profileAction()
    {
    }
}

Authorization Link

An Authorization Link can infer whether an (authenticated) identity is authorized to access a controller or a controller's action.

This is achieved by relying on AuthenticationService (for authentication status) and a AccessControlListInterface from alichry/laminas-accesscontrol that implies the accessibility or authorization level of a controller or a controller's method.

Eventually, an Authorization Link can imply whether an (authenticated) identity is granted access to a certain resource (controller/action) and will return the result.

Authorization Chain

An Authorization Chain is built from one or more Authorization Links which the authorization result is aggregated using a specified binary operator (OR/AND). While most applications generally utilize only one link, this is primarily related to the design.

If you are building an administrative end for your application, you may end up using a different Authentication Service, therefore additional Authorization Link and ACL. Alternatively, you may use the same Authentication Serivce and assign each identity with a user or admin role/permission (or the like...)

Redirection of unauthorized users

We perform authorization during the MVC lifecycle and prior dispatching requests for restful controllers. In Laminas MVC architecture, the target method to call for an action-based controller is retrievable prior dispatch by listening on the MVC dispatch event. For restful controllers, however, the target method cannot be retrieved prior dispatch. We provide EigenRestfulController as an ad-hoc solution. Simply extend your controller from EigenRestfulController instead of AbstractRestfulController.

During authorization, whether on the MVC-level or executed by EigenRestfulController, we redirect unauthorized requests to a configured route.

Configuration

See config.md

How to help ?

It would be nice to star this repository. It would help attract more contributors, and makes me happy to receive a star ! :)

alichry / laminas-authorization Goto Github PK