view release on metacpan or  search on metacpan

lib/CGI/Application/Plugin/Authorization.pm  view on Meta::CPAN

        *{ $callpkg . '::authz' }
            = \&CGI::Application::Plugin::_::Authorization::authz;
        *{ $callpkg . '::authorization' }
            = \&CGI::Application::Plugin::_::Authorization::authz;
    }
    if ( !UNIVERSAL::isa( $callpkg, 'CGI::Application' ) ) {
        warn
            "Calling package is not a CGI::Application module so not setting up the prerun hook.  If you are using \@ISA instead of 'use base', make sure it is in a BEGIN { } block, and make sure these statements appear before the plugin is loaded";
    }
    elsif ( !UNIVERSAL::can( $callpkg, 'add_callback' ) ) {
        warn
            "You are using an older version of CGI::Application that does not support callbacks, so the prerun method can not be registered automatically (Lookup 'CGI::Application CALLBACKS' in the docs for more info)";
    }
    else {
        $callpkg->add_callback( prerun => \&prerun_callback );
    }
}

=head1 NAME

CGI::Application::Plugin::Authorization - Authorization framework for
CGI::Application


=head1 SYNOPSIS

 use base qw(CGI::Application);
 use CGI::Application::Plugin::Authentication;
 use CGI::Application::Plugin::Authorization;

 # default config for runmode authorization
 __PACKAGE__->authz->config(
     DRIVER => [ 'HTGroup', FILE => 'htgroup' ],
 );

 # Using a named configuration to distinguish it from
 # the above configuration
 __PACKAGE__->authz('dbaccess')->config(
     DRIVER => [ 'DBI',
         DBH   => $self->dbh,
         TABLES      => ['user', 'access'],
         JOIN_ON     => 'user.id = access.user_id',
         CONSTRAINTS => {
             'user.name'      => '__USERNAME__',
             'access.table'   => '__PARAM_1__',
             'access.item_id' => '__PARAM_2__'
         }
     ],
 );

 sub admin_runmode {
    my $self = shift;

    # User must be in the admin group to have access to this runmode
    return $self->authz->forbidden unless $self->authz->authorize('admin');

    # rest of the runmode
    ...
 }

 sub update_widget {
    my $self = shift;
    my $widget = $self->query->param('widget_id');

    # Can this user edit this widget in the widgets table?
    return $self->authz->forbidden unless $self->authz('dbaccess')->authorize(widgets => $widget);

    # save changes to the widget
    ...
 }

=head1 DESCRIPTION

CGI::Application::Plugin::Authorization adds the ability to authorize users for
specific tasks.  Once a user has been authenticated and you know who you are
dealing with, you can then use this plugin to control what that user has access
to.  It imports two methods (C<authz> and C<authorization>) into your
L<CGI::Application> module.  Both of these methods are interchangeable, so you
should choose one and use it consistently throughout your code.  Through the
authz method you can call all the methods of the
CGI::Application::Plugin::Authorization plugin.

=head2 Named Configurations

There could be multiple ways that you may want to authorize actions in
different parts of your code.  These differences may conflict with each other.
For example you may have runmode level authorization that requires that the
user belongs to a certain group.  But secondly, you may have row level database
authorization that requires that the username column of the table contains the
name of the current user.  These configurations would conflict with each other
since they are authorizing using different information.  To solve this you can
create multiple named configurations, by specifying a unique name to the
c<authz> method.

 __PACKAGE__->authz('dbaccess')->config(
     DRIVER => [ 'DBI', ... ],
 );
 # later
 $self->authz('dbaccess')->authorize(widgets => $widget_id);



=head1 EXPORTED METHODS

=head2 authz -and- authorization

These methods are interchangeable and provided for users that either prefer
brevity, or clarity.  Everything is controlled through this method call, which
will return a CGI::Application::Plugin::Authorization object, or just the class
name if called as a class method.  When using the plugin, you will always first
call $self->authz or __PACKAGE__->authz and then the method you wish to invoke.
You can create multiple named authorization modules by providing a unique name
to the call to authz.  This will allow you to handle different types of
authorization in your modules.  For example, you could use the main
configuration to do runmode level authorization, and use a named configuration
to manage database row level authorization.


=cut

{