NAME Abilities - Simple, hierarchical user authorization for web applications, with optional support for plan-based paid services. VERSION version 0.1 SYNOPSIS package User; use Moose; 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(', ', $user->abilities); } DESCRIPTION Abilities is a simple yet powerful mechanism for authorizing users of web applications to perform certain actions in the app's code. This is an extension of the familiar role-based access control that is common in various systems and frameworks like Catalyst (See Catalyst::Plugin::Authorization::Roles for the role-based implementation and Catalyst::Plugin::Authorization::Abilities for the ability-based implementation that inspired this module). As opposed to the 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 in the program's code - 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 be assigned other roles; for example, roles 'mods' and 'editors' can be assigned _inside_ role 'mega_mods'. Users of the 'mega_mods' role will assume all actions owned by the 'mods' and 'editors' roles. A commonly known use-case for this type of access control is message boards, where the administrator might wish to create roles with certain actions and associate users with the roles (more commonly called 'user groups'); for example, the admin can create an 'editor' role, giving users of this role the ability to edit and delete posts, but not any other administrative action. So in essence, this type of access control relieves the developer from deciding who gets to do what and passes these decisions to the end-user, which might be necessary in certain situations. The Abilities module is implemented as a Moose role. In order to be able to use this mechanism, web applications must implement a user management system that will consume this role. More specifically, a user class and a role class must be implemented, consuming this role. Entities is a reference implementation that can be used by web applications, or just as an example of an ability-based authorization system. Entities::User and Entities::Role are the user and role classes that consume the Abilities role in the Entities distribution. PAID, SUBSCRIPTION-BASED WEB SERVICES Apart from the scenario described above, this module also provides optional support for subscription-based web services, such as those where customers subscribe to a certain paid (or free, doesn't matter) plan from a list of available plans (GitHub is an example of such a service). This functionality is also implemented as a role, in the Abilities::Features module provided with this distribution. Read its documentation for detailed information. REQUIRED METHODS Classes that consume this role are required to implement the following methods: roles() Returns a list of all roles that a user object belongs to, or a role object inherits from. The list must contain references to the role objects, not just their names. actions() Returns a list of all actions that a user object has been explicitely granted, or that a role object has been granted. The list must contain references to the action objects, not just their names. is_super() This is a boolean attribute that both user and role objects should have. If a user/role object has a true value for this attribute, then they will be able to perform any action, even if it wasn't granted to them. METHODS Classes that consume this role will have the following methods available for them: can_perform( $action_name | @action_names ) Receives the name of an action (or names of actions), and returns a true value if the user/role can perform the provided action(s). If more than one actions are passed, a true value will be returned only if the user/role can perform ALL of these actions. belongs_to( $role_name | @role_names ) takes_from( $role_name | @role_names ) The above two methods are actually the same. The names are meant to differentiate between user objects (first case) and role objects (second case). These methods receive a role name (or names). In case of a user object, the method will return a true value if the user is a direct member of the provided role. In case multiple role names were provided, a true value will be returned only if the user is a member of ALL of these roles. Only direct association is checked, so the user must be specifically assigned to the provided role, and not to a role that inherits from that role (see "inherits_from_role()" instead. In case of a role object, this method will return a true value if the role directly consumes the abilities of the provided role. In case multiple role names were provided, a true value will be returned only if the role directly consumes ALL of these roles. Like in case of a user, only direct association is checked, so inheritance doesn't count. inherits_from_role( $role_name | @role_names ) Receives the name of a role (or names of roles), and returns a true value if the user/role inherits the abilities of the provided role. If more than one roles are passed, a true value will be returned only if the user/role inherits from ALL of these roles. This method takes inheritance into account, so if a user was directly assigned to the 'admins' role, and the 'admins' role inherits from the 'devs' role, then inherits_from_role('devs') will return true for that user. all_abilities() Returns a list of all actions that a user/role can perform, either due to direct association or due to inheritance. INTERNAL METHODS These methods are only to be used internally. _all_abilities() TODO * Create tests Create tests for these roles. Right now the only way this is actually tested is through the Entities distribution tests. * Catalyst::Plugin::Authorization::Abilities Find a way to make Catalyst::Plugin::Authorization::Abilities use this role. AUTHOR Ido Perlmuter, "" BUGS Please report any bugs or feature requests to "bug-abilities at rt.cpan.org", or through the web interface at . I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. SUPPORT You can find documentation for this module with the perldoc command. perldoc Abilities You can also look for information at: * RT: CPAN's request tracker * AnnoCPAN: Annotated CPAN documentation * CPAN Ratings * Search CPAN LICENSE AND COPYRIGHT Copyright 2010 Ido Perlmuter. This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License. See http://dev.perl.org/licenses/ for more information.