view release on metacpan or  search on metacpan

lib/Catalyst/Plugin/Authorization/ACL.pm  view on Meta::CPAN

    __PACKAGE__->deny_access_unless( "/moose", "method_name" );

When specifying a method name the rule engine ensures that it can be invoked
using L<UNIVERSAL/can>.

=item Constant

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

=back

=head2 Flexible Rules

These rules are the most annoying to write but provide the most flexibility.

All access control is performed using exceptions -
C<$Catalyst::Plugin::Authorization::ACL::Engine::DENIED>, and
C<$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;
            }
        }
    );

=head1 HANDLING DENIAL

There are two plugin methods that can be called when a rule makes a decision
about an action:

=over 4

=item acl_access_allowed

A no-op

=item acl_access_denied

Looks for a private action named C<access_denied> from the denied action's
controller and outwards (much like C<auto>), and if none is found throws an
access denied exception.

=item forcibly_allow_access

Within an C<access_denied> action this will immediately cause the blocked
action to be executed anyway.

=back

This means that you have several alternatives:

=head2 Provide an C<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 C<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.

=head2 Cleanup in C<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
        }
    }

=head2 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 ) = @_;
        ...
    }

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

=head1 SEE ALSO

L<Catalyst::Plugin::Authentication>, L<Catalyst::Plugin::Authorization::Roles>,
L<http://catalyst.perl.org/calendar/2005/24>

=head1 AUTHOR

Yuval Kogman E<lt>nothingmuch@woobling.orgE<gt>

=head1 CONTRIBUTORS

castaway: Jess Robinson

caelum: Rafael Kitover E<lt>rkitover@cpan.orgE<gt>

=head1 COPYRIGHT & LICENSE

Copyright (c) 2005 - 2009
the Catalyst::Plugin::Authorization::ACL L</AUTHOR> and L</CONTRIBUTORS>
as listed above.

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

=cut