02. Quick Start.md

Quick Start

In this section, you will learn:

• How to set up the module
• How to specify an identity provider
• How to add a simple role provider

Before starting the quick start, make sure you have properly installed the module by following the instructions in the README file.

Specifying an identity provider

By default, ZfcRbac internally uses the Zend\Authentication\AuthenticationService service key to retrieve the user (logged or not). Therefore, you must implement and register this service in your application by adding these lines in your module.config.php file:

return [
    'service_manager' => [
        'factories' => [
	        'Zend\Authentication\AuthenticationService' => function($sm) {
	            // Create your authentication service!
	        }
	    ]
    ]
];

The identity given by Zend\Authentication\AuthenticationService must implement ZfcRbac\Identity\IdentityInterface. Note that the default identity provided with ZF2 does not implement this interface, neither does the ZfcUser suite.

ZfcRbac is flexible enough to use something other than the built-in AuthenticationService, by specifying custom identity providers. For more information, refer to this section.

Adding a guard

A guard allows your application to block access to routes and/or controllers using a simple syntax. For instance, this configuration grants access to any route that begins with admin (or is exactly admin) to the admin role only:

return [
    'zfc_rbac' => [
        'guards' => [
	        'ZfcRbac\Guard\RouteGuard' => [
                'admin*' => ['admin']
	        ]
        ]
    ]
];

ZfcRbac has several built-in guards, and you can also register your own guards. For more information, refer to this section.

Adding a role provider

RBAC model is based on roles. Therefore, for ZfcRbac to work properly, it must be aware of all the roles that are used inside your application.

This configuration creates an admin role that has a child role called member. The admin role automatically inherits the member permissions.

return [
    'zfc_rbac' => [
        'role_provider' => [
	        'ZfcRbac\Role\InMemoryRoleProvider' => [
	            'admin' => [
	                'children'    => ['member'],
	                'permissions' => ['delete']
	            ],
		        'member' => [
		            'permissions' => ['edit']
		        ]
	        ]
	    ]
    ]
];

In this example, the admin role has two permissions: delete and edit (because it inherits the permissions from its child), while the member role only has the edit permission.

ZfcRbac has several built-in role providers, and you can also register your own role providers. For more information, refer to this section.

Registering a strategy

When a guard blocks access to a route/controller, or if you throw the ZfcRbac\Exception\UnauthorizedException exception in your service, ZfcRbac automatically performs some logic for you depending on the view strategy used.

For instance, if you want ZfcRbac to automatically redirect all unauthorized requests to the "login" route, add the following code in the onBootstrap method of your Module.php class:

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

By default, RedirectStrategy redirects all unauthorized requests to a route named "login" when the user is not connected and to a route named "home" when the user is connected. This is, of course, entirely configurable.

For flexibility purposes, ZfcRbac does not register any strategy for you by default!

For more information about built-in strategies, refer to this section.

Using the authorization service

Now that ZfcRbac is properly configured, you can inject the authorization service into any class and use it to check if the current identity is granted to do something.

The authorization service is registered inside the service manager using the following key: ZfcRbac\Service\AuthorizationService. Once injected, you can use it as follow:

use ZfcRbac\Exception\UnauthorizedException;

public function delete()
{
    if (!$this->authorizationService->isGranted('delete')) {
        throw new UnauthorizedException();
    }

    // Delete the post
}

Navigation

• Continue to the Role providers
• Back to the Introduction
• Back to the Index