NAME Entities - User management and authorization for web applications and subscription-based services. VERSION version 0.2 SYNOPSIS use Entities; # create a new Entities object, with a MongoDB backend my $ent = Entities->new(backend => 'MongoDB'); # create a new role my $role = $ent->new_role(name => 'members'); $role->grant_action('make_mess') ->inherit_from('limited_members'); # create a new user my $user = $ent->new_user(username => 'someone'); $user->add_email('someone@someplace.com') ->add_to_role('members'); ->grant_action('stuff'); # check user can do stuff if ($user->can_perform('stuff')) { &do_stuff(); } else { croak "Listen, you just can't do that. C'mon."; } DESCRIPTION Entities is a complete system of user management and authorization for web applications and subscription-based web services, implementing what I call 'ability-based authorization', as defined by Abilities and Abilities::Features. This is a reference implementation, meant to be both extensive enough to be used by web applications, and to serve as an example of how to use and create ability-based authorization systems. ENTITIES? Ability-based authorization deals with six types of "entities": * Customers (represented by Entities::Customer A customer is an abstract entity that merely serves to unify the people who are actually using your app (see "users"). It can either be a person, a company, an organization or whatever. Basically, the customer is the "body" that signed up for your service and possibly is paying for it. A customer can have 1 or more users. * Users (represented by Entities::User A user is a person that belongs to a certain company and has received access to your app. They are the actual entities that are interacting with your application, not their parent entities (i.e. customers). Users have the ability to perform actions (see later), probably only within their parent entity's scope (see "SCOPING") and maybe to a certain limit (see "LIMITING"). * Plans (represented by Entities::Plan) A plan is a group of features (see "features"), with certain limits and scoping restrictions, that customers subscribe to. You are probably familiar with this concept from web services you use (like GitHub, Google Apps, etc.). A customer can subscribe to one or more plans (plans do not have to be related in any way), so that users of that customer can use the features provided with those plans. * Features (represented by Entities::Feature) A feature is also an abstract entity used to define "something" that customers can use on your web service. Perhaps "SSL Encryption" is a feature provided with some (but not all) of your plans. Or maybe "Opening Blogs" is a feature of all your plans, with different limits set on this feature for every plan. In other words, features are as they're named: the features of your app. It's your decision who gets to use them. * Actions (represented by Entities::Action) Actions are the core of 'ability-based authorization'. They define the actual activities that users can perform inside your app. For example, 'creating a new blog post' is an action that a user can perform. Another example would be 'approving comments'. Maybe even 'creating new users'. Actions, therefore, are units of "work" you define in your code. Users will be able to perform such unit of work only if they are granted with the 'ability' to perform the action the defines it, and only if this action is within the defined 'scope' and 'limit' of the parent customer. A certain ability can be bestowed upon a user either explicitly, or via roles (see below). * Roles (represented by Entities::Role) Roles might be familiar to you from 'role-based authorization'. Figuratively speaking, they are 'masks' that users can wear. A role is nothing but a group of actions. When a user is assigned a certain role, they consume all the actions defined in that role, and therefore the user is able to perform it. You will most likely find yourself creating roles such as 'admins', 'members', 'guests', etc. Roles are self-inheriting, i.e. a role can inherit the actions of another role. SCOPING AND LIMITING Scoping is the process of asserting that customers and their users are only allowed to perform actions in their own scope. For example, let's say your web service is a hosted blogging platform. Customers of your service are allowed to create blogs (i.e. they have the 'blogs' feature), and their users are allowed to post to these blogs, edit the posts and remove them (i.e. they have the 'create_post', 'edit_post' and 'delete_post' actions). Scoping means ensuring users can only create, edit and delete posts in their parent customer's blogs only. Limiting is the process of, well, limiting the amount of times a customer can use a certain feature. Returning to our hosted blog example, the customer's plan might limit the number of blogs the customer can own to a certain number, let's say six. When a user of that customer attempts to create a new blog, a check must be made that the customer has yet to reach the maximum amount of blogs. Users, in themselves, are common features in many plan-based web services. A customer might be able to create, for example, up to five users in a certain plan. Limiting is, therefore, an important part of plan-based web services. Obviously, the Entities system cannot do scoping and limiting for you, so you have to do this yourself. However, I do have plans to provide some simple features in upcoming releases to make these processes easier. METHODS new( backend => $backend ) Creates a new instance of the Entities module. Requires a backend object to be used for storage (see Entities::Backend for more information and a list of currently available backends). new_role( name => 'somerole', [ description => 'Just some role', is_super => 0, roles => [], actions => [], created => $dt_obj, modified => $other_dt_obj, parent => $entities_obj, id => 123 ] ) Creates a new Entities::Role object, stores it in the backend and returns it. new_user( username => 'someguy', passphrase => 's3cr3t', [ realname => 'Some Guy', is_super => 0, roles => [], actions => [], customer => $customer_obj, id => 123, emails => [], created => $dt_obj, modified => $other_dt_obj, parent => $entities_obj ] ) Creates a new Entities::User object, stores it in the backend and returns it. new_action( name => 'someaction', [ description => 'Just some action', parent => $entities_obj, id => 123 ] ) Creates a new Entities::Action object, stores it in the backend and returns it. new_plan( name => 'someplan', [ description => 'Just some plan', features => [], plans => [], created => $dt_obj, modified => $other_dt_obj, parent => $entities_obj, id => 123 ] ) Creates a new Entities::Plan object, stores it in the backend and returns it. new_feature( name => 'somefeature', [ description => 'Just some feature', parent => $entities_obj, id => 123 ] ) Creates a new Entities::Feature object, stores it in the backend and returns it. new_customer( name => 'somecustomer', email_address => 'customer@customer.com', [ features => [], plans => [], created => $dt_obj, modified => $other_dt_obj, parent => $entities_obj, id => 123 ] ) Creates a new Entities::Customer object, stores it in the backend and returns it. METHOD MODIFIERS The following list documents any method modifications performed through the magic of Moose. around qr/^new_.+$/ This method modifier is used when any of the above "new_something" methods are invoked. It is used to automatically pass the Entities object to the newly created object (as the 'parent' attribute), and to automatically save the object in the backend. SEE ALSO Abilities, Abilities::Features, Catalyst::Authentication::Abilities. AUTHOR Ido Perlmuter, "" BUGS Please report any bugs or feature requests to "bug-entities 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 Entities 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.