srigi / ipub-security
ACL permissions setter & checker for Nette Framework
Installs: 1 621
Dependents: 0
Suggesters: 0
Security: 0
Stars: 2
Watchers: 1
Forks: 2
Open Issues: 3
Requires
- php: >=5.4
- latte/latte: ~2.2
- nette/application: ~2.2
- nette/bootstrap: ~2.2
- nette/di: ~2.2
- nette/security: ~2.2
- nette/utils: ~2.2
Requires (Dev)
- nette/tester: ~1.6
- tracy/tracy: ~2.2
README
ACL permissions setter & checker for Nette Framework.
srigi/ipub-security
is a library that allows easy configuration of Nette Framework ACL system. It supports roles & resources inheritance and also permission assertions are supported.
Installation
The best way to install srigi/ipub-security
is by using Composer. To get the latest version of the library run this command at the root of your project:
$ composer require srigi/ipub-security
Or you can specify dependency by hand:
{ "require": { "srigi/ipub-security": "^1.3.0" } }
Setup
After installation you need to register the DI extension. If your'e using Nette 2.3, you can do that by configuration:
extensions: permission: IPub\Security\DI\SecurityExtension
I case of Nette 2.2 register extension in your bootstrap.php
:
$configurator = new Nette\Configurator; // ...some other code IPub\Security\DI\SecurityExtension::register($configurator);
The ACL system 101
Nette ACL system brings some terminology you should know befor continuing. First there are resources that one (a role) wants to access (privilege). This forms a permission. Example is the best teacher:
resources - intranet
, salesModule
, serversDashboard
, databaseServersDashboard
roles - admininstrator
, guest
, authenticated
, employee
, sales
, engineer
privileges - access
, powerOn
, powerOff
, reboot
permission - this is just abstract concept when you combine above three entities:
authenticated
canaccess
theintranet
engineer
canreboot
theserversDashboard
administrator
can doALL
onALL
resources and roles can inherit from each other and create hierarchies:
intranet
├ salesModule
└ serversDashboard
└ databaseServersDashboard
administrator
guest
└ authenticated
└ employee
├ sales
└ engineer
└ backend-engineer
If there is a permission (combination of resource
, role
and privilege
) registered, this inherits down. In our little example engineer
can access
the intranet
because is inheriting this permission from authenticated
.
More on this can be found in access control chapter of Nette Framework documentation.
Creating permissions
Permission is represented by instance of IPub\Security\Entities\IPermission
. Such instance is providing a IPub\Security\Entities\IResource
resource instance, a privilege (defined as string) and assertion (defined as callable). All three components of the permission are optional.
Permissions definitions must be provided by service implementing IPub\Security\Providers\IPermissionsProvider
. Library srigi/ipub-security have example implementation of such provider you can use in your project. Or you can write your own.
Defining set of permissions with our PermissionsProvider
is very easy:
class MyPermissionsProvider extends IPub\Security\Providers\PermissionsProvider { public function __construct() { $intranet = $this->addResource('intranet'); $this->addPermission($intranet, Nette\Security\IAuthorizator::ALL); $this->addPermission($intranet, 'access'); $this->addPermission($intranet, 'update'); $salesModule = $this->addResource('salesModule', $this->getResource('intranet')); $this->addPermission($salesModule, 'access'); $this->addPermission($salesModule, 'edit', function($acl, $role, $resource, $privilege) { // ...code of permission assertion }); // ... more permissions definitions } }
Now just register your permission provider:
services: - MyPermissionsProvider
Creating roles & assigning permissions
Similarly as permission also roles have its own interface and needs a provider service. This provider should also assign permissions to the role:
class MyRolesProvider extends IPub\Security\Providers\RolesProvider { /** * @param MyPermissionsProvider $permissionsProvider */ public function __construct(MyPermissionsProvider $permissionsProvider) { $permissions = $permissionsProvider->getPermissions(); $this->addRole(Entities\IRole::ROLE_ADMINISTRATOR); $this->addRole(Entities\IRole::ROLE_ANONYMOUS); $this->addRole(Entities\IRole::ROLE_AUTHENTICATED, $this->getRole(Entities\IRole::ROLE_ANONYMOUS), $permissions['intranet:access']); $this->addRole('employee', $this->getRole(Entities\IRole::ROLE_AUTHENTICATED)); $this->addRole('sales', $this->getRole('employee'), [ $permissions['salesModule:'], ]); $this->addRole('engineer', $this->getRole('employee'), [ $permissions['servers:access'], ]); // ...more roles & permissions assignments }
Don't forget to register your roles provider:
services: - MyRolesProvider
Now your'e set!
Checking permissions
Library provide a PHP trait, which enables pleasant quering Nette ACL system we've just configured. Please note that traits are available from PHP 5.4, for older versions of PHP you must copy/paste trait contents. This trait is effective only in presenter(s).
class BasePresenter extends Nette\Application\UI\Presenter { use IPub\Security\TPermission; }
Using annotations
You can fine-tune checking logic by this set of annotations:
/** * @Secured * @Secured\User(loggedIn) * @Secured\Resource(RESOURCE_NAME) * @Secured\Privilege(PRIVILEGE_NAME) * @Secured\Permission(RESOURCE_NAME: PRIVILEGE_NAME) * @Secured\Role(ROLE_NAME) */ class IntranetPresenter extends BasePresenter { /** * @Secured * @Secured\Permission(RESOURCE_NAME: PRIVILEGE_NAME) */ public function renderDefault() { } }
@Secured
This annotation instruct security system that presenter is subject to the permissions check. Without it permission checking will be skipped completely!
@Secured\User
This annotation accept value loggedIn
or guest
. Access to any resource
and any privilege
is controled only by login state of the current user.
Next annotations are working over Nette\Security\User
roles assigned during login process.
@Secured\Resource
Access is granted only if role is allowed to access specified resource
.
@Secured\Privilege
This grand access only if role is allowed to access specified privilege
.
@Secured\Permission
Combination of above two - access is granted only if role have resource: privilege
permission.
@Secured\Role
Grand access only to specified role
.
On every place where *_NAME
applies, you can specify multiple names separated by comma.
Using in presenters, components, models, etc.
Permission check can be performed also manually. You just need Nette\Security\User
instance on which you call:
$user->isAllowed('resource', 'privilege');
TRUE
of FALSE
is returned respecively.
Using in Latte
In latte you can use two special macros.
<p>This text is for everyone...</p> {ifAllowed resource => 'intranet', privilege => 'access'} <p>But this one is only for special persons...</p> {/ifAllowed}
Macro ifAllowed
is very similar to annotations definitions. You can use here one or all of available parameters: user, resource, privilege, permission or role.
This macro can be also used as n: macro:
<p>This text is for everyone...</p> <p n:ifAllowed resource => 'intranet', privilege => 'access'> But this one is only for special persons...</p>
And second special macro is for links:
<a n:allowedHref="Intranet:">Link to Intranet...</a>
Macro n:allowedHref is expecting only valid link and in case user doesn't have permission to that resource, link isn't displayed.
Redirect to login page
If user is not logged-in and tries to access secured resource a default action is throwing the Nette\Application\ForbiddenRequestException
. However if you configure so called redirectUrl
, request will be redirected to this url (login page) when this situation occurs.
Also all parameters of the original request will be stored. That way you are able to restore original request and be redirected to secured resource after successful login. To configure redirectUrl
add this to your configuration:
permission:
redirectUrl: 'Login:default'
To restore the original request prepare persistent param backlink
in the presenter and use it in login procedure (callback)
class LoginPresenter { /** @persistent */ public $backlink; public function processLoginForm($form) { // try $this->getUser()->login($form->getValues()); $this->restoreRequest($this->backlink); $this->redirect('Admin:default'); // catch } }
TODO
- check
IPub\Security\Entities\Permission
constructor types - make documentation examples to be in sync w/ tests
- tests for
IPub\Security\Providers\*
- latte macros tests
- check annotations test logic
- permissions-assertions tests/doc
RolesProvider::allow
,RolesProvider::deny
methods
History
- 1.3.4 Add
redirectUrl
functionality - 1.3.0 Rename
RolesModel
andIPub\Security\Models
toRolesProvider
andIPub\Security\Providers
- 1.2.0 Rewrite
Security\Permission
to support resource inheritance & permissions assertions - 1.1.0 Cloned library into
srigi/ipub-permissions
- 1.0.1 Added roles inheritance
License
New BSD License or the GNU General Public License (GPL) version 2 or 3, see license.md.