view release on metacpan or  search on metacpan

lib/Abilities.pm  view on Meta::CPAN

package Abilities;

# ABSTRACT: Simple, hierarchical user authorization for web applications, with optional support for plan-based (paid) services.

use Carp;
use Hash::Merge qw/merge/;
use Moo::Role;
use namespace::autoclean;

our $VERSION = "0.5";
$VERSION = eval $VERSION;

=head1 NAME

Abilities - Simple, hierarchical user authorization for web applications, with optional support for plan-based (paid) services.

=head1 VERSION

version 0.5

=head1 SYNOPSIS

	package User;
	
	use Moose; # or Moo
	with 'Abilities';
	
	# ... define required methods ...
	
	# somewhere else in your code:

	# get a user object that consumed the Abilities role
	my $user = MyApp->get_user('username'); # $user is a User object

	# check if the user is able to do something
	if ($user->can_perform('something')) {
		do_something();
	} else {
		die "Hey you can't do that, you can only do " . join(', ', keys %{$user->abilities});
	}

=head1 DESCRIPTION

Abilities is a simple yet powerful mechanism for authorizing users of web
applications (or any applications) to perform certain actions in the application. This is an
extension of the familiar role-based access control that is common in
various systems and frameworks like L<Catalyst> (See L<Catalyst::Plugin::Authorization::Roles>
for the role-based implementation and L<Catalyst::Plugin::Authorization::Abilities>
for the ability-based implementation that inspired this module).

As opposed to role-based access control - where users are allowed access
to a certain feature (here called 'action') only through their association
to a certain role that is hard-coded into the program - in ability-based
acccess control, a list of actions is assigned to every user, and they are
only allowed to perform these actions. Actions are not assigned by the
developer during development, but rather by the end-user during deployment.
This allows for much more flexibility, and also speeds up development,
as you (the developer) do not need to think about who should be allowed
to perform a certain action, and can easily grant access later-on after
deployment (assuming you're also the end-user).

Abilities to perform certain actions can be given to a user specifically, or
via roles the user can assume (as in role-based access control). For example,
if user 'user01' is a member of role 'admin', and this user wishes to perform
some action, for example 'delete_foo', then they will only be able to do
so if the 'delete_foo' ability was given to either the user itself or the
'admin' role itself. Furthermore, roles can recursively inherit other roles;
for example, the role 'mega_mods' can inherit the roles 'mods' and 'editors'.