02. Quick Start.md

Quick Start

In this section, you will learn:

• How to setup the module
• How to specify an identity provider
• How to add 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 to retrieve the user (logged or not). Therefore, you must register this service in your application by adding those 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 like the one provided by Doctrine Module Authentication. Note that the default identity provided with ZF2 does not implement this interface.

ZfcRbac is flexible enough to use something else than the built-in AuthenticationService, by specifying custom identity providers. For more information, refer [to this section](/docs/03. Role providers.md#identity-providers).

Adding a guard

A guard allows 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 have several built-in guards, and you can also register your own guards. For more information, refer [to this section](/docs/04. Guards.md#built-in-guards).

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 children 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 have two permissions: delete and edit (because it inherits the permissions from its child), while the member role only has the permission edit.

ZfcRbac have several built-in role providers, and you can also register your own role providers. For more information, refer [to this section](/docs/03. Role providers.md#built-in-role-providers).

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(EventInterface $e)
{
    $t = $e->getTarget();

    $t->getEventManager()->attach(
        $t->getServiceManager()->get('ZfcRbac\View\Strategy\RedirectStrategy')
    );
}

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

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

For more information about built-in strategies, refer [to this section](/docs/05. Strategies.md#built-in-strategies).

Using the authorization service

Now that ZfcRbac is properly configured, you can inject the authorization service in 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](/docs/03. Role providers.md)
• Back to [the Introduction](/docs/01. Introduction.md)
• Back to the Index