NAME

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

DESCRIPTION

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

EXPORTED METHODS

METHODS

  # match all runmodes
  __PACKAGE__->authz->authz_runmodes(
      ':all' => 'admin',
      );

  # only protect runmodes one and two
  __PACKAGE__->authz->authz_runmodes(
      one => 'admin',
      two => 'admin',
      );

  # protect only runmodes that start with auth_
  __PACKAGE__->authz->authz_runmodes(
      qr/^authz_/ => 'admin',
      );

  # protect all runmodes that *do not* start with public_
  __PACKAGE__->authz->authz_runmodes(
      qr/^(?!public_)/ => 'admin',
      );

  # preserve the interface from 0.06:
  __PACKAGE__->authz->authz_runmodes(
      [':all' => 'admin'],
      );

 # is the current user in the admin group
 if ($self->authz->authorize('admingroup')) {
    # perform an admin action
 }

CGI::Application CALLBACKS

If you are using an older version of CGI::Application you will need to add it yourself.

 sub cgiapp_prerun {
    my $self = shift;

    $self->run_modes( authz_forbidden => \&CGI::Application::Plugin::Authorization::authz_forbidden, );
 }

 sub cgiapp_prerun {
    my $self = shift;

    $self->CGI::Application::Plugin::Authorization::prerun_callback();
 }

CGI::Application RUNMODES

EXAMPLE

  package MyCGIApp;

  use base qw(CGI::Application);
  use CGI::Application::Plugin::AutoRunmode;
  use CGI::Application::Plugin::Authentication;
  use CGI::Application::Plugin::Authorization;
  
  # Configure Authentication
  MyCGIApp->authen->config(
        DRIVER => 'Dummy',
  );
  MyCGIApp->authen->protected_runmodes(qr/^admin_/);

  # Configure Authorization (manages runmode authorization)
  MyCGIApp->authz->config(
      DRIVER => [ 'DBI',
          DBH         => $self->dbh,
          TABLES      => ['user', 'usergroup', 'group'],
          JOIN_ON     => 'user.id = usergroup.user_id AND usergroup.group_id = group.id',
          CONSTRAINTS => {
             'user.name'  => '__USERNAME__',
             'group.name' => '__GROUP__',
          }
      ],
  );
  MyCGIApp->authz->authz_runmodes(
     [a_runmode => 'a_group'],
     [qr/^admin_/ => 'admin'],
     [':all' => 'all_group'],
     [sub {my $rm = shift; return ($rm eq "dangerous_rm")} => 'super_group'],
  );

  # Configure second Authorization module using a named 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 start : Runmode {
    my $self = shift;

  }

  sub admin_one : Runmode {
    my $self = shift;
    # The user will only get here if they are logged in and
    # belong to the admin group

  }

  sub admin_widgets : Runmode {
    my $self = shift;
    # The user will only get here if they are logged in and
    # belong to the admin group

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

TODO

provide easy methods for authorizing runmode access automatically

allow subroutine attributes to configure authorization for a runmode

write a tutorial/cookbook to include with the docs

BUGS

SEE ALSO

AUTHOR

CREDITS

LICENCE AND COPYRIGHT

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

DISCLAIMER OF WARRANTY

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.