atelierdisko / li3_access
A simple library for user access control.
Installs: 2 094
Dependents: 5
Suggesters: 0
Security: 0
Stars: 2
Watchers: 2
Forks: 20
Open Issues: 0
Type:lithium-library
Requires
- php: ^5.4 || ^7
- composer/installers: ^1
- unionofrad/lithium: ^1.1
This package is auto-updated.
Last update: 2020-11-22 20:42:53 UTC
README
Installation
The preferred installation method is via composer. You can add the library as a dependency via:
composer require atelierdisko/li3_access
li₃ plugins must be registered within your application bootstrap phase as they use a different (faster) autoloader.
Libraries::add('li3_access')
The official manual has more information on how to register the plugin with the app or use alternative installation methods (i.e. via GIT).
Checking
You must configure the adapter you wish to use first, but once you have it configured it's fairly simple to use.
if (Access::check('default', Auth::check('default'), $this->request)) {
// Access granted :)
} else {
// Access denied :(
}
If the check failed then any error information generated during the check can be retrieved as follows:
Access::errors('default')
Configuration
In this repository there are 3 adapters. All 3 work in a slightly different way.
Rules Adapter
This adapter effectively allows you to tell it how it should work. It comes with a few preconfigured rules by default but it's very simple to add your own.
All rules must return true
in order to make the access check succeed.
Simple Usage with Builtin Rules
The simplest way to use li3_access and the rules adapter is by granting any authenticated user access and deny access to users not authenticated.
For this we pick just the 'allowAnyUser'
rule from the builtin rules.
Access::config(
'default' => array(
'adapter' => 'Rules',
'rules' => array(
Rules::builtin()['allowAnyUser']
)
)
);
And that's it!
All builtin rules can be used in a similar fashion. There are four built in rules; allowAll, denyAll, allowAnyUser and allowIp, for more information see the adapter itself. However, this adapter is at its most useful when you add your own rules.
Access::config(
'default' => array(
'adapter' => 'Rules',
'rules' => Rules::builtin()
)
);
Advanced Usage with Custom Rules
We start with an empty slate and no rules configured.
Access::config(
'default' => array(
'adapter' => 'Rules'
)
);
Custom rules can be added via via the add
method.
Access::add('default', 'myCustomRule', function($user, $request, $options) {
// Your logic here. Just make sure it strictly returns `true` if the
// rule succeeded and `false` otherwise.
});
The following is similar but also defines a message and redirect which can later
be retrieved via errors()
:
Access::add('default', 'myCustomRule', array(
'message' => 'This did not go well.',
'redirect' => '/',
'rule' => function($user, $params, $options) {
// ...
}
));
Two more to go!
Resources Adapter
This adapter builts upon the Rules
adapter, but uses the 'resource'
as a pre-condition
before executing the rule check. This allows to restrict access to certain resources by
custom rules.
Access::add('default', 'panel', array(
'resource' => array('admin' => true),
'rule' => function($user, $params, $options) {
return $user->role === 'admin';
}
));
Matching Resources
Rules are evaluated top to bottom until the current request can be matched against a resource condition. If the current request cannot be matched the access check fails. Rules without a resource will never match.
Resource defintions can be either:
- an array of param keys
- a route shorthand string (with or without wildcards)
- a regular expression which is matched against the URL
- a string which is strictly compared against the URL
- a closure which receives the current params array.
- an array of 2, 3, 4 or 5 (conditions are OR'ed together)
'resource' => array('controller' => 'Users')
// ... or ...
'resource' => 'Users::*'
// ... or ...
'resource' => '*'
// ... or ...
'resource' => '#^/users/.*#'
// ... or ...
'resource' => function($params) {
return $params['controller'] === 'Users';
}
// ... or ...
'resource' => array(
'Users::*',
'Pages::*'
)
Authed Resource Adapter
This adapter builts upon the Resources
adapter, but instead of relying on custom rule checks,
rules are checked against auth. It's used to control access to resources by checking, if the
user has been authenticated by a certain (set of) auth configurations.
So lets look at an example configuration to try and achieve some clarity:
Auth::config(array(
'admin' => array(
'adapter' => 'Form',
'model' => 'User',
'fields' => array('email' => 'email', 'password' => 'password'),
'scope' => array('active' => true, 'role' => 'admin')
),
'api' => array(
'adapter' => 'Token'
'scope' => array('active' => true)
)
));
Access::config(array(
'default' => array(
'adapter' => 'AuthedResources',
'rules' => array(
array(
'resource' => array('admin' => true),
'auth' => 'admin',
'message' => 'You must login before using the admin panel!11!1!',
'redirect' => array(
'library' => 'admin',
'controller' => 'Users', 'action' => 'login'
)
),
array(
'resource' => array(
'admin' => true,
'controller' => 'Users', 'action' => 'logout'
),
'auth' => '*'
),
array(
'resource' => array(
'api' => true,
'controller' => 'Events', 'action' => 'index'
),
'auth' => array('admin', 'api')
),
array(
'resource' => '*',
'auth' => '*'
)
)
)
));
Require Authentication
'auth'
can be string or an array of auth configuration keys that this rule requires. The string *
denotes everyone, even those who are not authenticated. A string of admin
will validate
anyone who can be authenticated against the user defined admin
Auth configuration. An array
of configuration keys does the same but you can apply it to multiple Auth configurations in one
go.
Assuming we have an Auth configuration like so:
Auth::config(array(
'user' => array(
'adapter' => 'Form',
'model' => 'Customer',
'fields' => array('email' => 'email', 'password' => 'password'),
'scope' => array('active' => true)
),
'editor' => array(
// ...
'scope' => array('active' => true, 'role' => 'editor')
),
'customer' => array(
// ...
'scope' => array('active' => true, 'role' => 'customer')
)
));
Setting 'auth' => array('user', 'customer')
would only apply the rule to anyone that
could authenticate as a user or customer. Setting 'auth' => '*'
would mean that all of
these auth configurations and people that are not authenticated would have this rule applied to
them.
Filters
The Access::check() method is filterable. You can apply filters like so:
Access::applyFilter('check', function($self, $params, $chain) {
// Filter logic goes here
return $chain->next($self, $params, $chain);
});
History
Tom Maiaroto originally authored this plugin. Marc Schwering wrote the original authed resources adapter. rich97 modified the original authed resources adapter and the documentation.
Copyright & License
Copyright 2010 Union of RAD. All rights reserved. This library is distributed under the terms of the BSD 3-Clause License. The full license text can be found in the LICENSE.txt file.