NAME
    Catalyst::ActionRole::ACL - User role-based authorization action class

SYNOPSIS
     package MyApp::Controller::Foo;
     use Moose;
     use namespace::autoclean;

     BEGIN { extends 'Catalyst::Controller::ActionRole' }

     sub foo
     :Local
     :Does(ACL)
     :RequiresRole(admin)
     :ACLDetachTo(denied)
     {
         my ($self, $c) = @_;
         ...
     }

     sub denied :Private {
         my ($self, $c) = @_;

         $c->res->status('403');
         $c->res->body('Denied!');
     }

DESCRIPTION
    Provides a Catalyst reusable action role for user role-based
    authorization. ACLs are applied via the assignment of attributes to
    application action subroutines.

REQUIRED ATTRIBUTES
    Failure to include the following required attributes will result in an
    exception when the ACL::Role action's constructor is called.

  ACLDetachTo
    The name of an action to which the request should be detached if it is
    determined that ACLs are not satisfied for this user and the resource he
    is attempting to access.

  RequiresRole, AllowedRole or AuthzValidateMethod
    The action must include at least one of these attributes, otherwise the
    Role::ACL constructor will throw an exception.

Processing of ACLs
    One or more roles may be associated with an action.

    User roles are fetched, if necessary, via the invocation of the context
    "user" object's "roles" method.

    Roles specified with the RequiresRole attribute are checked before roles
    specified with the AllowedRole attribute.

    The mandatory ACLDetachTo attribute specifies the name of the action to
    which execution will detach on access violation.

    ACLs may be applied to chained actions so that different roles are
    required or allowed for each link in the chain (or no roles at all).

    ACLDetachTo allows us to short-circuit traversal of an action chain as
    soon as access is denied to one of the actions in the chain by its ACL.

  Examples
     # this is an invalid action
     sub broken
     :Local
     :Does(ACL)
     {
         my ($self, $c) = @_;
         ...
     }

     This action will cause an exception because it's missing the ACLDetachTo attribute
     and has none of the RequiresRole, AllowedRole, nor AuthzValidateMethod attributes. A Role::ACL action
     must include at least one RequiresRole, AllowedRole or AuthzValidateMethod attribute.

     sub foo
     :Local
     :Does(ACL)
     :RequiresRole(admin)
     :ACLDetachTo(denied)
     {
         my ($self, $c) = @_;
         ...
     }

    This action may only be executed by users with the 'admin' role.

     sub bar :Local
     :Does(ACL)
     :RequiresRole(admin)
     :AllowedRole(editor)
     :AllowedRole(writer)
     :ACLDetachTo(denied)
     {
         my ($self, $c) = @_;
         ...
     }

    This action requires that the user has the 'admin' role and either the
    'editor' or 'writer' role (or both).

     sub easy :Local
     :Does(ACL)
     :AllowedRole(admin)
     :AllowedRole(user)
     :ACLDetachTo(denied)
     {
         my ($self, $c) = @_;
         ...
     }

    Any user with either the 'admin' or 'user' role may execute this action.

     sub complex :Local
     :Does(ACL)
     :AuthzValidateMethod(complexValidate(hello,there))
     :ACLDetachTo(denied)
     {
         my ($self, $c) = @_;
         ...
     }
 
     sub complexValidate :Private
     {
         my ($self, $user, $c, $arg) = @_;
         my @actualArgs = split /,/, $arg;
         return userHasPaidDuesAndIsGenerallyTrustworthyThisTimeOfDay($user, @actualArgs);
     }

    This setup demonstrates how the "complex" action is only executed if the
    arbitrary "complexValidate" criterion is met. Note that the User
    implementation need not support the "roles" feature if they are not
    used. In addition, an arbitrary string may be passed between parens
    after the method name.

     sub complex2 :Local
     :Does(ACL)
     :AuthzValidateMethod(complexValidate)
     :AllowedRole(admin)
     :ACLDetachTo(denied)
     {
         my ($self, $c) = @_;
         ...
     }
 
     sub complexValidate :Private
     {
         my ($self, $user, $c) = @_;
         return userHasPaidDuesAndIsGenerallyTrustworthyThisTimeOfDay($user);
     }

    Here, complex2 is only executed if complexValidate returns true, AND the
    user has the 'admin' role.

WRAPPED METHODS
  "BUILD( $args )"
    Throws an exception if parameters are missing or invalid.

  "execute( $controller, $c )"
    Overrides &Catalyst::Action::execute.

    In order for delegation to occur, the context 'user' object must exist
    (authenticated user) and the "can_visit" method must return a true
    value.

    See Catalyst::Action

  "can_visit( $c, $controller )"
    Return true if the authenticated user can visit this action.

    This method is useful for determining in advance if a user can execute a
    given action.

AUTHOR
    David P.C. Wollmann <[email protected]>

CONTRIBUTORS
    Converted from an action class to an action role by Tomas Doran (t0m)

BUGS
    This is new code. Find the bugs and report them, please.

COPYRIGHT & LICENSE
    Copyright 2009 by David P.C. Wollmann

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