1Catalyst::ActionRole::AUCsLe(r3)Contributed Perl DocumenCtaattailoynst::ActionRole::ACL(3)
2
3
4

NAME

6       Catalyst::ActionRole::ACL - User role-based authorization action class
7

SYNOPSIS

9        package MyApp::Controller::Foo;
10        use Moose;
11        use namespace::autoclean;
12
13        BEGIN { extends 'Catalyst::Controller' }
14
15        sub foo
16        :Local
17        :Does(ACL)
18        :RequiresRole(admin)
19        :ACLDetachTo(denied)
20        {
21            my ($self, $c) = @_;
22            ...
23        }
24
25        sub denied :Private {
26            my ($self, $c) = @_;
27
28            $c->res->status('403');
29            $c->res->body('Denied!');
30        }
31

DESCRIPTION

33       Provides a reusable action role for user role-based authorization.
34       ACLs are applied via the assignment of attributes to application action
35       subroutines.
36

REQUIRED ATTRIBUTES

38       Failure to include the following required attributes will result in an
39       exception when the ACL::Role action's constructor is called.
40
41   ACLDetachTo
42       The name of an action to which the request should be detached if it is
43       determined that ACLs are not satisfied for this user and the resource
44       he is attempting to access.
45
46   RequiresRole and AllowedRole
47       The action must include at least one of these attributes, otherwise the
48       Role::ACL constructor will throw an exception.
49

Processing of ACLs

51       One or more roles may be associated with an action.
52
53       User roles are fetched via the invocation of the context "user"
54       object's "roles" method.
55
56       Roles specified with the RequiresRole attribute are checked before
57       roles specified with the AllowedRole attribute.
58
59       The mandatory ACLDetachTo attribute specifies the name of the action to
60       which execution will detach on access violation.
61
62       ACLs may be applied to chained actions so that different roles are
63       required or allowed for each link in the chain (or no roles at all).
64
65       ACLDetachTo allows us to short-circuit traversal of an action chain as
66       soon as access is denied to one of the actions in the chain by its ACL.
67
68   Examples
69        # this is an invalid action
70        sub broken
71        :Local
72        :Does(ACL)
73        {
74            my ($self, $c) = @_;
75            ...
76        }
77
78        This action will cause an exception because it's missing the ACLDetachTo attribute
79        and has neither a RequiresRole nor an AllowedRole attribute. A Role::ACL action
80        must include at least one RequiresRole or AllowedRole attribute.
81
82        sub foo
83        :Local
84        :Does(ACL)
85        :RequiresRole(admin)
86        :ACLDetachTo(denied)
87        {
88            my ($self, $c) = @_;
89            ...
90        }
91
92       This action may only be executed by users with the 'admin' role.
93
94        sub bar :Local
95        :Does(ACL)
96        :RequiresRole(admin)
97        :AllowedRole(editor)
98        :AllowedRole(writer)
99        :ACLDetachTo(denied)
100        {
101            my ($self, $c) = @_;
102            ...
103        }
104
105       This action requires that the user has the 'admin' role and either the
106       'editor' or 'writer' role (or both).
107
108        sub easy :Local
109        :Does(ACL)
110        :AllowedRole(admin)
111        :AllowedRole(user)
112        :ACLDetachTo(denied)
113        {
114            my ($self, $c) = @_;
115            ...
116        }
117
118       Any user with either the 'admin' or 'user' role may execute this
119       action.
120

WRAPPED METHODS

122   BUILD( $args )
123       Throws an exception if parameters are missing or invalid.
124
125   "execute( $controller, $c )"
126       Overrides &Catalyst::Action::execute.
127
128       In order for delegation to occur, the context 'user' object must exist
129       (authenticated user) and the "can_visit" method must return a true
130       value.
131
132       See Catalyst::Action
133
134   can_visit( $c )
135       Return true if the authenticated user can visit this action.
136
137       This method is useful for determining in advance if a user can execute
138       a given action.
139

AUTHOR

141       David P.C. Wollmann <converter42@gmail.com>
142

CONTRIBUTORS

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

BUGS

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

150       Copyright 2009 by David P.C. Wollmann
151
152       This program is free software; you can redistribute it and/or modify it
153       under the same terms as Perl itself.
154
155
156
157perl v5.38.0                      2023-07-20      Catalyst::ActionRole::ACL(3)
Impressum