allow_access_if

Check the rule condition and allow access to the actions under $path if the rule returns true.

This is normally useful to allow acces only to a specific part of a tree whose parent has a "deny_access_unless" clause attached to it.

If the rule test returns false access is not denied or allowed. Instead the next rule in the chain will be checked - in this sense the combinatory behavior of these rules is like logical OR.

allow_access_if_any

Same as above for any role in the list.

deny_access_unless

Check the rule condition and disallow access if the rule returns false.

This is normally useful to restrict access to any portion of the application unless a certain condition can be met.

If the rule test returns true access is not allowed or denied. Instead the next rule in the chain will be checked - in this sense the combinatory behavior of these rules is like logical AND.

deny_access_unless_any

Same as above for any role in the list.

allow_access

deny_access

Unconditionally allow or deny access to a path.

acl_add_rule

Manually add a rule to all the actions under $path using the more flexible (but more verbose) method:

    __PACKAGE__->acl_add_rule(
        "/foo",
        sub { ... }, # see FLEXIBLE RULES below
        sub {
            my $action = shift;
            # return a true value if you want to apply the rule to this action
            # called for all the actions under "/foo"
        }
    };

In this case the rule must be a sub reference (or method name) to be invoked on $c.

The default filter will skip all actions starting with an underscore, namely "_DISPATCH", "_AUTO", etc (but not "auto", "begin", et al).

acl_access_denied

acl_access_allowed

The default event handlers for access denied or allowed conditions. See below on handling access violations.

acl_allow_root_internals

execute

setup_actions

Easy Rules

The easy rules are all predicate list oriented. "allow_access_if" will explicitly allow access if the predicate is true, and "deny_access_unless" will explicitly disallow if the predicate is false.

Role Lists

  __PACAKGE__->deny_access_unless_any( "/foo/bar", [qw/admin moose_trainer/] );
    

When the role is evaluated the Catalyst::Plugin::Authorization::Roles will be used to check whether the currently logged in user has the specified roles.

If "allow_access_if_any" is used, the presence of any of the roles in the list will immediately permit access, and if "deny_access_unless_any" is used, the lack of all of the roles will immediately deny access.

Similarly, if "allow_access_if" is used, the presence of all the roles will immediately permit access, and if "deny_access_unless" is used, the lack of any of the roles will immediately deny access.

When specifying a role list without the Catalyst::Plugin::Authorization::Roles plugin loaded the ACL engine will throw an error.

Predicate Code Reference / Method Name

The code reference or method is invoked with the context and the action objects. The boolean return value will determine the behavior of the rule.

    __PACKAGE__->allow_access_if( "/gorch", sub { ... } );
    __PACKAGE__->deny_access_unless( "/moose", "method_name" );
    

When specifying a method name the rule engine ensures that it can be invoked using "can" in UNIVERSAL.

Constant

You can use "undef", 0 and '' to use as a constant false predicate, or 1 to use as a constant true predicate.

Flexible Rules

All access control is performed using exceptions - $Catalyst::Plugin::Authorization::ACL::Engine::DENIED, and $Catalyst::Plugin::Authorization::ACL::Engine::ALLOWED (these can be imported from the engine module).

If no rule decides to explicitly allow or deny access, access will be permitted.

Here is a rule that will always break out of rule processing by either explicitly allowing or denying access based on how much mojo the current user has:

    __PACKAGE__->acl_add_rule(
        "/foo",
        sub {
            my ( $c, $action ) = @_;

            if ( $c->user->mojo > 50 ) {
                die $ALLOWED;
            } else {
                die $DENIED;
            }
        }
    );

Provide an "access_denied" action

    package MyApp::Controller::Foo;

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

        ...
        $c->forcibly_allow_access
            if $you->mean_it eq "really";
    }

If you call "forcibly_allow_access" then the blocked action will be immediately unblocked. Otherwise the execution of the action will cease, and return to it's caller or end.

Cleanup in "end"

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

        if ( $c->error and $c->error->[-1] eq "access denied" ) {
            $c->error(0); # clear the error

            # access denied
        } else {
            # normal end
        }
    }

Override the plugin event handler methods

    package MyApp;

    sub acl_access_allowed {
        my ( $c, $class, $action ) = @_;
        ...
    }

    sub acl_access_denied {
        my ( $c, $class, $action, $err ) = @_;
        ...
    }

$class is the controller class the $action object was going to be executed in, and $err is the exception cought during rule evaluation, if any (access is denied if a rule raises an exception).