05. Strategies.md

Strategies

In this section, you will learn:

• What strategies are
• How to use built-in strategies
• How to create custom strategies

What are strategies?

A strategy is an object that listens to the MvcEvent::EVENT_DISPATCH_ERROR event. It is used to describe what happens when access to a resource is unauthorized by ZfcRbac.

ZfcRbac strategies all check if an ZfcRbac\Exception\UnauthorizedExceptionInterface has been thrown.

By default, ZfcRbac does not register any strategy for you. The best place to register it is in your onBootstrap method of the Module.php class:

public function onBootstrap(MvcEvent $e)
{
    $app = $e->getApplication();
    $sm = $app->getServiceManager();
    $em = $app->getEventManager();
    
    $listener = $sm->get(\ZfcRbac\View\Strategy\UnauthorizedStrategy::class);
    $listener->attach($em);
}

Built-in strategies

ZfcRbac comes with two built-in strategies: RedirectStrategy and UnauthorizedStrategy.

RedirectStrategy

This strategy allows your application to redirect any unauthorized request to another route by optionally appending the previous URL as a query parameter.

To register it, copy-paste this code into your Module.php class:

public function onBootstrap(MvcEvent $e)
{
    $app = $e->getApplication();
    $sm = $app->getServiceManager();
    $em = $app->getEventManager();
    
    $listener = $sm->get(\ZfcRbac\View\Strategy\RedirectStrategy::class);
    $listener->attach($em);
}

You can configure the strategy using the redirect_strategy subkey:

return [
    'zfc_rbac' => [
        'redirect_strategy' => [
            'redirect_when_connected'        => true,
            'redirect_to_route_connected'    => 'home',
            'redirect_to_route_disconnected' => 'login',
            'append_previous_uri'            => true,
            'previous_uri_query_key'         => 'redirectTo'
        ],
    ]
];

If users try to access an unauthorized resource (eg.: http://www.example.com/delete), they will be redirected to the "login" route if is not connected and to the "home" route otherwise (it must exist in your route configuration of course) with the previous URL appended : http://www.example.com/login?redirectTo=http://www.example.com/delete

You can prevent redirection when a user is connected (i.e. so that the user gets a 403 page) by setting redirect_when_connected to false.

UnauthorizedStrategy

This strategy allows your application to render a template on any unauthorized request.

To register it, copy-paste this code into your Module.php class:

public function onBootstrap(MvcEvent $e)
{
    $app = $e->getApplication();
    $sm = $app->getServiceManager();
    $em = $app->getEventManager();
    
    $listener = $sm->get(\ZfcRbac\View\Strategy\UnauthorizedStrategy::class);
    $listener->attach($em);
}

You can configure the strategy using the unauthorized_strategy subkey:

return [
    'zfc_rbac' => [
        'unauthorized_strategy' => [
            'template' => 'error/custom-403'
        ],
    ]
];

By default, ZfcRbac uses a template called error/403.

Creating custom strategies

Creating a custom strategy is rather easy. Let's say we want to create a strategy that integrates with the ApiProblem Zend Framework 2 module:

namespace Application\View\Strategy;

use Zend\Http\Response as HttpResponse;
use Zend\Mvc\MvcEvent;
use ZF\ApiProblem\ApiProblem;
use ZF\ApiProblem\ApiProblemResponse;
use ZfcRbac\View\Strategy\AbstractStrategy;
use ZfcRbac\Exception\UnauthorizedExceptionInterface;

class ApiProblemStrategy extends AbstractStrategy
{
    public function onError(MvcEvent $event)
    {
        // Do nothing if no error or if response is not HTTP response
        if (!($exception = $event->getParam('exception') instanceof UnauthorizedExceptionInterface)
            || ($result = $event->getResult() instanceof HttpResponse)
            || !($response = $event->getResponse() instanceof HttpResponse)
        ) {
            return;
        }

        return new ApiProblemResponse(new ApiProblem($exception->getMessage()));
    }
}

Register your strategy:

public function onBootstrap(EventInterface $e)
{
    $e->getTarget()
      ->getEventManager()
      ->attach(new ApiProblemStrategy());
}

Navigation

• Continue to the Authorization Service
• Back to the Guards
• Back to the Index