עידו פרלמוטר (Ido Perlmuter) > Entities-0.5 > Entities

Download:
Entities-0.5.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.5   Source  

NAME ^

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

VERSION ^

version 0.5

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":

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.

syntax highlighting: