NAME

Scaffold::Uaf::Authorize - An abstract base class to use as a pattern for your AuthorizeFactory.

SYNOPSIS

This package is a simple abstract base class. Use it as the base for creating your instance of an Authorize object.

package MyAuthorize;

use strict;
use warnings;

use XYZRule;
use SomeOtherRule;
use base qw(Scaffold::Uaf::Authorize);

sub rules {
   my $self = shift;

   $self->add_rule(XYZRule->new());
   $self->add_rule(SomeOtherRule->new());

}

1;

Then later in the main line code.

my $manager = $self->scaffold->authz;

if ($manager->xcan($user, "read", "/etc/shadow")) {
   open DATA, "</etc/shadow";
    ...
}

DESCRIPTION

This module implements an authorization scheme. The basic idea is that you have a set of users and a set of objects that can be accessed within a system. In the code of the system itself, you want to surround sensitive operations with code that determines if the current user is allowed to do that operation.

This module attempts to make such a system possible. The module requires that you write implementations rules for your system that are subclasses of Scaffold::Uaf::Rule. The rules can be written to use any data types, which are abstractly known as "users", "actions", and "resources."

A user is generally a Scaffold::Uaf::User object that your applications has identify as the entity operating the application.

An action can be any data type (i.e. simply a string). It is really up to the rule to determine what is valid. But, you have the latitude to define anything as a action.

A resource can be any data type (i.e simply a string). But, it is really up to the rule to determine what a resource is. Again, you have the latitude to define anything as a resource.

These are the steps needed to create an Authorize object:

Step 1

Decide what sections of your code will need to be protected, and decide what to do if the user doesn't have access. For example if a screen should just hide fields, then the application code needs to reflect that.

Step 2

Create an Authorize object for your application.

Step 3

Surround sensitive sections of code with something like:

if ($manager->can($user, "view salary", $payrollRecord)) {

    # show salary fields

} else {

    # hide salary fields

}

Step 4

Create rules that spell out the behavior you want and add them to your application's Authorization object. The basic idea is that a rule can grant permission, or deny it. If it neither grants or denies, then the object will take the safe route and say that the action cannot be taken. Part of the code for the rule for protecting salaries might look like:

package SalaryViewRule;

use Scaffold::Uaf::User;
use base qw(Scaffold::Uaf::Rule);

sub grants {

    $self = shift;
    $user = shift;
    $action = shift;
    $resource = shift;

    # Do not grant on requests we don't understand.

    return 0 if (!$user->isa("Scaffold::Uaf::User") ||
                 !$self->isa("Scaffold::Uaf::Rule"));

    if (($action eq "view salary") && 
        ($resource->isa("Payroll::Record"))) {

       if ($user->username() eq $resource->getEmployeeName()) {

          return "user can view their own salary";

       }

    }

    return 0;

}

Then in your subclass of AuthorizeFactory:

use SalaryViewRule;

  ...

$viewRule = new SalaryViewRule;
$manager->add_rule($viewRule);

METHODS

new()

This method intializes the object.

xcan(user, action, resource)

This is the primary method of the Authorization object. It asks if the specified user can do the specified action on the specified resource.

Example:

$manager->xcan($user, "eat", "cake");

This would return true if the user is allowed to eat cake.

add_rule(rule)

This method will add an new rule to the object.

Example:

$authz->add_rule(MyRule->new());

rules()

This method should be overridden and your rules applied to the object. See the above examples for usage.

SEE ALSO

Scaffold
Scaffold::Base
Scaffold::Cache
Scaffold::Cache::FastMmap
Scaffold::Cache::Manager
Scaffold::Cache::Memcached
Scaffold::Class
Scaffold::Constants
Scaffold::Engine
Scaffold::Handler
Scaffold::Handler::Default
Scaffold::Handler::Favicon
Scaffold::Handler::Robots
Scaffold::Handler::Static
Scaffold::Lockmgr
Scaffold::Lockmgr::KeyedMutex
Scaffold::Lockmgr::UnixMutex
Scaffold::Plugins
Scaffold::Render
Scaffold::Render::Default
Scaffold::Render::TT
Scaffold::Routes
Scaffold::Server
Scaffold::Session::Manager
Scaffold::Stash
Scaffold::Stash::Controller
Scaffold::Stash::Cookie
Scaffold::Stash::Manager
Scaffold::Stash::View
Scaffold::Uaf::Authenticate
Scaffold::Uaf::AuthorizeFactory
Scaffold::Uaf::Authorize
Scaffold::Uaf::GrantAllRule
Scaffold::Uaf::Login
Scaffold::Uaf::Logout
Scaffold::Uaf::Manager
Scaffold::Uaf::Rule
Scaffold::Uaf::User
Scaffold::Utils

AUTHOR

Kevin L. Esteb <kevin@kesteb.us>

COPYRIGHT AND LICENSE

Copyright (C) 2009 Kevin L. Esteb

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.