NAME

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

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(Gantry::Plugins::Uaf::AuthorizeFactory);

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 = $gobj->uaf_authz;

if ($manager->can($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 of rules for your system that are subclasses of Gantry::Plugins::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 Gantry::Plugins::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:

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.

2. Create an Authorize object for your application.

3. Surround sensitive sections of code with something like:

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

    # show salary fields

} else {

    # hide salary fields

}

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 Gantry::Plugins::Uaf::User;
use base qw(Gantry::Plugins::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("Gantry::Plugin::Uaf::User") ||
                 !$self->isa("Gantry::Plugin::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. It takes the Gantry object as a parameter.

can(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->can($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

Gantry::Plugins::Uaf::Rule

AUTHOR

Kevin L. Esteb <kesteb@wsipc.org>

COPYRIGHT AND LICENSE

Copyright (C) 2007 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.