/ 
Entities-0.4
River stage zero No dependents
/ Entities

NAME

Entities - User management and authorization for web applications and subscription-based services.

VERSION

version 0.4

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 customer and has received access to your app. They are the actual entities that are interacting with your application, not their parent customer entities. Users have the ability to perform actions (see later), probably only within their parent entity's scope and maybe to a certain limit (see "SCOPING AND LIMITING").

  • Plans (represented by Entities::Plan)

    A plan is a group of features (see below), 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 a 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 them. 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.

ATTRIBUTES

backend

Holds the storage backend object. This will be an object that does the role Entities::Backend.

CONSTRUCTOR

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).

OBJECT METHODS

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.

SEE ALSO

Abilities, Abilities::Features, Catalyst::Authentication::Abilities.

AUTHOR

Ido Perlmuter, <ido at ido50 dot net>

BUGS

Please report any bugs or feature requests to bug-entities at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Entities. 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:

LICENSE AND COPYRIGHT

Copyright 2010-2013 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.