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.

atelierdisko / li3_access

Maintainers

Details