Authorization.pm

filter: Statementstmt 96.7% 180 / 186 Branchbran 92.2% 83 / 90 Conditioncond 92.3% 24 / 26 MC/DCmcdc 78.5% 11 / 14 Subroutinesub 96.4% 27 / 28 Podpod 100% 15 / 15 totaltotal 94.7% 340 / 359 CC 61 SCAR 19.1
CC
61
Cov
95%
config
17.0
is_authz_runmode
9.3
instance
6.0
CRAP 6.8
« Authorization/Driver/DBI.pm ↑ Summary Authorization/Driver/SimpleGroup.pm »
1 package CGI::Application::Plugin::Authorization;
2  
3 11 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 11 ▶use vars qw($VERSION);
Subroutine BEGIN: called CC=1 SCAR=0.0
5 11 $VERSION = '0.07';
6  
7 11 our %__CONFIG;
8  
9 11 ▶use UNIVERSAL::require;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 11 ▶use Scalar::Util;
Subroutine BEGIN: called CC=1 SCAR=0.0
11 11 ▶use List::Util qw(first);
Subroutine BEGIN: called CC=1 SCAR=0.0
12 11 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
13  
14 15 ▶sub import {
Subroutine import: called CC=3 SCAR=11.0
15 15 my $pkg = shift;
16 15 my $callpkg = caller;
17 {
18 11 ▶ no strict qw(refs);
Subroutine BEGIN: called CC=1 SCAR=0.0
19 15 *{ $callpkg . '::authz' }
20 = \&CGI::Application::Plugin::_::Authorization::authz;
21 15 *{ $callpkg . '::authorization' }
22 = \&CGI::Application::Plugin::_::Authorization::authz;
23 }
24 15 ▶ if ( !UNIVERSAL::isa( $callpkg, 'CGI::Application' ) ) {
Branch: 2 branches
BranchTrueFalseTotal
if (not UNIVERSAL::isa($callpkg, 'CGI::Application')) { } 1 14 15
elsif (not UNIVERSAL::can($callpkg, 'add_callback')) { } 0 14 14
25 1 warn
26 "Calling package is not a CGI::Application module so not setting up the prerun hook. If you are using \@ISA instead of 'use base', make sure it is in a BEGIN { } block, and make sure these statements appear before the plugin is loaded";
27 }
28 elsif ( !UNIVERSAL::can( $callpkg, 'add_callback' ) ) {
29 0 warn
30 "You are using an older version of CGI::Application that does not support callbacks, so the prerun method can not be registered automatically (Lookup 'CGI::Application CALLBACKS' in the docs for more info)";
31 }
32 else {
33 14 $callpkg->add_callback( prerun => \&prerun_callback );
34 }
35 }
36  
37 =head1 NAME
38  
39 CGI::Application::Plugin::Authorization - Authorization framework for
40 CGI::Application
41  
42  
43 =head1 SYNOPSIS
44  
45 use base qw(CGI::Application);
46 use CGI::Application::Plugin::Authentication;
47 use CGI::Application::Plugin::Authorization;
48  
49 # default config for runmode authorization
50 __PACKAGE__->authz->config(
51 DRIVER => [ 'HTGroup', FILE => 'htgroup' ],
52 );
53  
54 # Using a named configuration to distinguish it from
55 # the above configuration
56 __PACKAGE__->authz('dbaccess')->config(
57 DRIVER => [ 'DBI',
58 DBH => $self->dbh,
59 TABLES => ['user', 'access'],
60 JOIN_ON => 'user.id = access.user_id',
61 CONSTRAINTS => {
62 'user.name' => '__USERNAME__',
63 'access.table' => '__PARAM_1__',
64 'access.item_id' => '__PARAM_2__'
65 }
66 ],
67 );
68  
69 sub admin_runmode {
70 my $self = shift;
71  
72 # User must be in the admin group to have access to this runmode
73 return $self->authz->forbidden unless $self->authz->authorize('admin');
74  
75 # rest of the runmode
76 ...
77 }
78  
79 sub update_widget {
80 my $self = shift;
81 my $widget = $self->query->param('widget_id');
82  
83 # Can this user edit this widget in the widgets table?
84 return $self->authz->forbidden unless $self->authz('dbaccess')->authorize(widgets => $widget);
85  
86 # save changes to the widget
87 ...
88 }
89  
90 =head1 DESCRIPTION
91  
92 CGI::Application::Plugin::Authorization adds the ability to authorize users for
93 specific tasks. Once a user has been authenticated and you know who you are
94 dealing with, you can then use this plugin to control what that user has access
95 to. It imports two methods (C<authz> and C<authorization>) into your
96 L<CGI::Application> module. Both of these methods are interchangeable, so you
97 should choose one and use it consistently throughout your code. Through the
98 authz method you can call all the methods of the
99 CGI::Application::Plugin::Authorization plugin.
100  
101 =head2 Named Configurations
102  
103 There could be multiple ways that you may want to authorize actions in
104 different parts of your code. These differences may conflict with each other.
105 For example you may have runmode level authorization that requires that the
106 user belongs to a certain group. But secondly, you may have row level database
107 authorization that requires that the username column of the table contains the
108 name of the current user. These configurations would conflict with each other
109 since they are authorizing using different information. To solve this you can
110 create multiple named configurations, by specifying a unique name to the
111 c<authz> method.
112  
113 __PACKAGE__->authz('dbaccess')->config(
114 DRIVER => [ 'DBI', ... ],
115 );
116 # later
117 $self->authz('dbaccess')->authorize(widgets => $widget_id);
118  
119  
120  
121 =head1 EXPORTED METHODS
122  
123 =head2 authz -and- authorization
124  
125 These methods are interchangeable and provided for users that either prefer
126 brevity, or clarity. Everything is controlled through this method call, which
127 will return a CGI::Application::Plugin::Authorization object, or just the class
128 name if called as a class method. When using the plugin, you will always first
129 call $self->authz or __PACKAGE__->authz and then the method you wish to invoke.
130 You can create multiple named authorization modules by providing a unique name
131 to the call to authz. This will allow you to handle different types of
132 authorization in your modules. For example, you could use the main
133 configuration to do runmode level authorization, and use a named configuration
134 to manage database row level authorization.
135  
136  
137 =cut
138  
139 {
140 package # Hide from PAUSE
141 CGI::Application::Plugin::_::Authorization;
142  
143 ##############################################
144 ###
145 ### authorization
146 ###
147 ##############################################
148 #
149 # Return an authorization object that can be used
150 # for managing authorization.
151 #
152 # This will return a class name if called
153 # as a class, and a singleton object
154 # if called as an object method
155 #
156 142 ▶ sub authz {
Subroutine authz: called CC=3 SCAR=11.0
157 142 my $cgiapp = shift;
158 142 ▶ my $name = shift || '__default__';
Condition100%2/2
shift() || '__default__'
l!l
3139
MC/DC100%1/1
shift() || '__default__'
shift()
Truth table100%2/2
A
A= shift()
Aresult
11
00
159  
160 142 ▶ if ( ref($cgiapp) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $cgiapp) { } 121 21 142
161 121 return CGI::Application::Plugin::Authorization->instance(
162 ref($cgiapp) . '-' . $name, $cgiapp );
163 }
164 else {
165 21 return CGI::Application::Plugin::Authorization->instance(
166 $cgiapp . '-' . $name, $cgiapp );
167 }
168 }
169  
170 }
171  
172 11 package CGI::Application::Plugin::Authorization;
173  
174 =head1 METHODS
175  
176 =head2 config
177  
178 This method is used to configure the CGI::Application::Plugin::Authorization
179 module. It can be called as an object method, or as a class method.
180  
181 The following parameters are accepted:
182  
183 =over 4
184  
185 =item DRIVER
186  
187 Here you can choose which authorization module(s) you want to use to perform
188 the authorization. For simplicity, you can leave off the
189 CGI::Application::Plugin::Authorization::Driver:: part when specifying the
190 DRIVER parameter. If this module requires extra parameters, you can pass an
191 array reference that contains as the first parameter the name of the module,
192 and the required parameters as the rest of the array. You can provide multiple
193 drivers which will be used, in order, to check the permissions until a valid
194 response is received.
195  
196 DRIVER => [ 'DBI', dbh => $self->dbh ],
197  
198 - or -
199  
200 DRIVER => [
201 [ 'HTGroup', file => '.htgroup' ],
202 [ 'LDAP', binddn => '...', host => 'localhost', ... ]
203 ],
204  
205  
206 =item FORBIDDEN_RUNMODE
207  
208 Here you can specify a runmode that the user will be redirected to if they fail
209 the authorization checks.
210  
211 FORBIDDEN_RUNMODE => 'forbidden'
212  
213 =item FORBIDDEN_URL
214  
215 If your forbidden page is external to this module, then you can use this option
216 to specify a URL that the user will be redirected to when they fail the
217 authorization checks. If both FORBIDDEN_URL and FORBIDDEN_RUNMODE are
218 specified, then the latter will take precedence.
219  
220 FORBIDDEN_URL => 'http://example.com/forbidden.html'
221  
222 =item GET_USERNAME
223  
224 This option allows you to provide a method that should return us the username
225 of the currently logged in user. It will be passed the current authz objects
226 as the only parameter. This is not a required option, and can be omitted if
227 you use the Authentication plugin, or if your authentication system sets
228 $ENV{REMOTE_USER}.
229  
230 GET_USERNAME => sub { my $authz = shift; return $authz->cgiapp->my_username }
231  
232  
233 =back
234  
235 =cut
236  
237 47 ▶sub config {
Subroutine config: called CC=17 SCAR=28.3
Pod documented
238 47 my $self = shift;
239 47 my $class = ref $self;
240  
241 die
242 "Calling config after the Authorization object has already been created"
243 47 ▶ if $self->{loaded};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"loaded"} 1 46 47
244 46 my $config = $self->_config;
245  
246 46 ▶ if (@_) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 45 1 46
247 45 my $props;
248 45 ▶ if ( ref( $_[0] ) eq 'HASH' ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $_[0] eq 'HASH') { } 2 43 45
249 2 my $rthash = %{ $_[0] };
250 2 $props = CGI::Application->_cap_hash( $_[0] );
251 }
252 else {
253 43 $props = CGI::Application->_cap_hash( {@_} );
254 }
255  
256 # Check for DRIVER
257 45 ▶ if ( defined $props->{DRIVER} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $props->{"DRIVER"}) 36 9 45
258 croak
259 "authz config error: parameter DRIVER is not a string or arrayref"
260 if ref $props->{DRIVER}
261 36 ▶ && Scalar::Util::reftype( $props->{DRIVER} ) ne 'ARRAY';
Branch: 1 branch
BranchTrueFalseTotal
if ref $props->{"DRIVER"} and builtin::reftype($props->{"DRIVER"}) ne "ARRAY" 1 35 36
Condition100%3/3
ref $props->{"DRIVER"} and builtin::reftype($props->{"DRIVER"}) ne "ARRAY"
!ll&&!rl&&r
2331
MC/DC100%2/2
ref $props->{"DRIVER"} and builtin::reftype($props->{"DRIVER"}) ne "ARRAY"
ref $props->{"DRIVER"} builtin::reftype($props->{"DRIVER"}) ne "ARRAY"
Truth table100%3/3
A and B
A= ref $props->{"DRIVER"}B= builtin::reftype($props->{"DRIVER"}) ne "ARRAY"
ABresult
0X0
100
111
262 35 $config->{DRIVER} = delete $props->{DRIVER};
263 # We will accept a string, or an arrayref of options, but what we
264 # really want is an array of arrayrefs of options, so that we can
265 # support multiple drivers each with their own custom options
266 11 ▶ no warnings qw(uninitialized);
Subroutine BEGIN: called CC=1 SCAR=0.0
267 $config->{DRIVER} = [ $config->{DRIVER} ]
268 35 ▶ if Scalar::Util::reftype( $config->{DRIVER} ) ne 'ARRAY';
Branch: 1 branch
BranchTrueFalseTotal
if builtin::reftype($config->{"DRIVER"}) ne "ARRAY" 2 33 35
269 $config->{DRIVER} = [ $config->{DRIVER} ]
270 35 ▶ if Scalar::Util::reftype( $config->{DRIVER}->[0] ) ne 'ARRAY';
Branch: 1 branch
BranchTrueFalseTotal
if builtin::reftype($config->{"DRIVER"}[0]) ne "ARRAY" 31 4 35
271 }
272  
273 # Check for FORBIDDEN_RUNMODE
274 44 ▶ if ( defined $props->{FORBIDDEN_RUNMODE} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $props->{"FORBIDDEN_RUNMODE"}) 4 40 44
275 croak
276 "authz config error: parameter FORBIDDEN_RUNMODE is not a string"
277 4 ▶ if ref $props->{FORBIDDEN_RUNMODE};
Branch: 1 branch
BranchTrueFalseTotal
if ref $props->{"FORBIDDEN_RUNMODE"} 1 3 4
278 3 $config->{FORBIDDEN_RUNMODE} = delete $props->{FORBIDDEN_RUNMODE};
279 }
280  
281 # Check for FORBIDDEN_URL
282 43 ▶ if ( defined $props->{FORBIDDEN_URL} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $props->{"FORBIDDEN_URL"}) 7 36 43
283 carp
284 "authz config warning: parameter FORBIDDEN_URL ignored since we already have FORBIDDEN_RUNMODE"
285 7 ▶ if $config->{FORBIDDEN_RUNMODE};
Branch: 1 branch
BranchTrueFalseTotal
if $config->{"FORBIDDEN_RUNMODE"} 0 7 7
286 croak
287 "authz config error: parameter FORBIDDEN_URL is not a string"
288 7 ▶ if ref $props->{FORBIDDEN_URL};
Branch: 1 branch
BranchTrueFalseTotal
if ref $props->{"FORBIDDEN_URL"} 1 6 7
289 6 $config->{FORBIDDEN_URL} = delete $props->{FORBIDDEN_URL};
290 }
291  
292 # Check for GET_USERNAME
293 42 ▶ if ( defined $props->{GET_USERNAME} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $props->{"GET_USERNAME"}) 10 32 42
294 croak
295 "authz config error: parameter GET_USERNAME is not a CODE reference"
296 10 ▶ if ref $props->{GET_USERNAME} ne 'CODE';
Branch: 1 branch
BranchTrueFalseTotal
if ref $props->{"GET_USERNAME"} ne "CODE" 1 9 10
297 9 $config->{GET_USERNAME} = delete $props->{GET_USERNAME};
298 }
299  
300 # If there are still entries left in $props then they are invalid
301 41 ▶ croak "Invalid option(s) ("
Branch: 1 branch
BranchTrueFalseTotal
if %$props 1 40 41
302 . join( ', ', keys %$props )
303 . ") passed to config"
304 if %$props;
305 }
306 }
307  
308 =head2 authz_runmodes
309  
310 This method takes a list of runmodes that are to be authorized, and
311 the authorization rules for said runmodes. If a user tries to access
312 one of these runmodes, then they will be redirected to the forbidden
313 page unless authorization is granted.
314  
315 The runmode names can be simple strings, regular expressions, coderefs
316 (which are passed the name of the runmode as their only parameter), or
317 special directives that start with a colon.
318  
319 The authorization rules can be simple strings representing the name of
320 the group that the user must be a member of, as a list-ref of group
321 names (of which the user only has to be a member of B<any one of the
322 groups>, or as a code-ref that will be called (with I<no> parameters).
323  
324 This method is cumulative, so if it is called multiple times, the new
325 values are appended to the list of existing entries. It returns a list
326 containing all of the entries that have been configured thus far.
327  
328 B<NOTE:> compatibility with the interface as was defined in 0.06 B<is>
329 preserved. 0.06 allowed for runmodes to be passed in as a list-ref of
330 two-element lists to specify authorization rules. Although this
331 interface is supported, the extra list-refs aren't necessary.
332  
333 =over 4
334  
335 =item :all - All runmodes in this module will require authorization
336  
337 =back
338  
339 # match all runmodes
340 __PACKAGE__->authz->authz_runmodes(
341 ':all' => 'admin',
342 );
343  
344 # only protect runmodes one and two
345 __PACKAGE__->authz->authz_runmodes(
346 one => 'admin',
347 two => 'admin',
348 );
349  
350 # protect only runmodes that start with auth_
351 __PACKAGE__->authz->authz_runmodes(
352 qr/^authz_/ => 'admin',
353 );
354  
355 # protect all runmodes that *do not* start with public_
356 __PACKAGE__->authz->authz_runmodes(
357 qr/^(?!public_)/ => 'admin',
358 );
359  
360 # preserve the interface from 0.06:
361 __PACKAGE__->authz->authz_runmodes(
362 [':all' => 'admin'],
363 );
364  
365 =cut
366  
367 34 ▶sub authz_runmodes {
Subroutine authz_runmodes: called CC=4 SCAR=13.9
Pod documented
368 34 my $self = shift;
369 34 my $config = $self->_config;
370  
371 34 ▶ $config->{AUTHZ_RUNMODES} ||= [];
Condition100%2/2
$config->{"AUTHZ_RUNMODES"} ||= []
l!l
1618
MC/DC100%1/1
$config->{"AUTHZ_RUNMODES"} ||= []
$config->{"AUTHZ_RUNMODES"}
Truth table100%2/2
A
A= $config->{"AUTHZ_RUNMODES"}
Aresult
11
00
372  
373 34 ▶ while (@_) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 33 34 67
374 33 my ($rm, $group);
375  
376 # extract next runmode/authz rule from args
377 33 ▶ if (ref($_[0]) eq 'ARRAY') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $_[0] eq 'ARRAY') { } 3 30 33
378 # 0.06 interface; list-ref
379 3 my $rule = shift @_;
380 3 ($rm, $group) = @{$rule};
381 }
382 else {
383 # new interface; list
384 30 $rm = shift @_;
385 30 $group = shift @_;
386 }
387  
388 # add authz rule to our config
389 33 push( @{$config->{AUTHZ_RUNMODES}}, [$rm, $group] );
390 }
391  
392 34 return @{$config->{AUTHZ_RUNMODES}};
393 }
394  
395 =head2 is_authz_runmode
396  
397 This method accepts the name of a runmode, and if that runmode requires
398 authorization (ie the user needs to be a member of a particular group
399 or has to satisfy some other authorization rule) then this method
400 returns the corresponding authorization rule which must be satisfied
401 (which could be either a scalar, a list-ref, or a code-ref, depending
402 on how the rules were defined).
403  
404 =cut
405  
406 17 ▶sub is_authz_runmode {
Subroutine is_authz_runmode: called CC=9 SCAR=22.3
Pod documented
407 17 my $self = shift;
408 17 my $runmode = shift;
409  
410 17 foreach my $runmode_info ($self->authz_runmodes) {
411 14 my ($runmode_test, $rule) = @$runmode_info;
412 14 ▶ if (overload::StrVal($runmode_test) =~ /^Regexp=/) {
Branch: 3 branches
BranchTrueFalseTotal
if (overload::StrVal($runmode_test) =~ /^Regexp=/) { } 2 12 14
elsif (ref $runmode_test and ref $runmode_test eq 'CODE') { } 2 10 12
elsif ($runmode_test eq ':all') { } 2 8 10
413 # We were passed a regular expression
414 2 ▶ return $rule if $runmode =~ $runmode_test;
Branch: 1 branch
BranchTrueFalseTotal
if $runmode =~ /$runmode_test/ 2 0 2
415 ▶ } elsif (ref $runmode_test && ref $runmode_test eq 'CODE') {
Condition66%2/3
ref $runmode_test and ref $runmode_test eq "CODE"
!ll&&!rl&&r
1002
MC/DC50%1/2
ref $runmode_test and ref $runmode_test eq "CODE"
ref $runmode_test ref $runmode_test eq "CODE"
Truth table66%2/3
A and B
A= ref $runmode_testB= ref $runmode_test eq "CODE"
ABresult
0X0
100
111
416 # We were passed a code reference
417 2 ▶ return $rule if $runmode_test->($runmode);
Branch: 1 branch
BranchTrueFalseTotal
if &$runmode_test($runmode) 2 0 2
418 } elsif ($runmode_test eq ':all') {
419 # all runmodes are protected
420 2 return $rule;
421 } else {
422 # assume we were passed a string
423 8 ▶ return $rule if $runmode eq $runmode_test;
Branch: 1 branch
BranchTrueFalseTotal
if $runmode eq $runmode_test 8 0 8
424 }
425 }
426  
427 3 return undef;
428 }
429  
430 =head2 new
431  
432 This method creates a new L<CGI::Application::Plugin::Authorization> object.
433 It requires as it's only parameter a L<CGI::Application> object. This method
434 should never be called directly, since the C<authz> method that is imported
435 into the L<CGI::Application> module will take care of creating the
436 L<CGI::Application::Plugin::Authorization> object when it is required.
437  
438 =cut
439  
440 68 ▶sub new {
Subroutine new: called CC=2 SCAR=6.9
Pod documented
441 68 my $class = shift;
442 68 my $name = shift;
443 68 my $cgiapp = shift;
444 68 my $self = {};
445  
446 68 bless $self, $class;
447 68 $self->{name} = $name;
448 68 $self->{cgiapp} = $cgiapp;
449 Scalar::Util::weaken( $self->{cgiapp} )
450 68 ▶ if ref $self->{cgiapp}; # weaken circular reference
Branch: 1 branch
BranchTrueFalseTotal
if ref $self->{"cgiapp"} 47 21 68
451  
452 68 return $self;
453 }
454  
455 =head2 instance
456  
457 This method works the same way as C<new>, except that it returns the same
458 Authorization object for the duration of the request. This method should never
459 be called directly, since the C<authz> method that is imported into the
460 L<CGI::Application> module will take care of creating the
461 L<CGI::Application::Plugin::Authorization> object when it is required.
462  
463 =cut
464  
465 143 ▶sub instance {
Subroutine instance: called CC=6 SCAR=17.9
Pod documented
466 143 my $class = shift;
467 143 ▶ my $name = shift ||'';
Condition100%2/2
shift() || ''
l!l
1421
MC/DC100%1/1
shift() || ''
shift()
Truth table100%2/2
A
A= shift()
Aresult
11
00
468 143 my $cgiapp = shift;
469 143 ▶ die
Branch: 1 branch
BranchTrueFalseTotal
unless defined $cgiapp and UNIVERSAL::isa($cgiapp, "CGI::Application") 2 141 143
Condition100%3/3
defined $cgiapp and UNIVERSAL::isa($cgiapp, "CGI::Application")
!ll&&!rl&&r
11141
MC/DC100%2/2
defined $cgiapp and UNIVERSAL::isa($cgiapp, "CGI::Application")
defined $cgiapp UNIVERSAL::isa($cgiapp, "CGI::Application")
Truth table100%3/3
A and B
A= defined $cgiappB= UNIVERSAL::isa($cgiapp, "CGI::Application")
ABresult
0X0
100
111
470 "CGI::Application::Plugin::Authorization->instance must be called with a CGI::Application object or class name"
471 unless defined $cgiapp
472 && UNIVERSAL::isa( $cgiapp, 'CGI::Application' );
473  
474 141 ▶ if ( ref $cgiapp ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $cgiapp) { } 120 21 141
475 # being called from a CGI::Application object
476 $cgiapp->{__CAP_AUTHORIZATION_INSTANCE}->{$name}
477 = $class->new( $name, $cgiapp )
478 120 ▶ unless defined $cgiapp->{__CAP_AUTHORIZATION_INSTANCE}->{$name};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $cgiapp->{"__CAP_AUTHORIZATION_INSTANCE"}{$name} 47 73 120
479 120 return $cgiapp->{__CAP_AUTHORIZATION_INSTANCE}->{$name};
480 }
481 else {
482 # being called from a CGI::Application class
483 21 return $class->new( $name, $cgiapp );
484 }
485 }
486  
487 =head2 authorize
488  
489 This method will test to see if the current user has access to the given
490 resource. It will take the given parameters and test them against the DRIVER
491 classes that have been configured. A true return value means the user should
492 have access to the given resource.
493  
494 # is the current user in the admin group
495 if ($self->authz->authorize('admingroup')) {
496 # perform an admin action
497 }
498  
499 =cut
500  
501 38 ▶sub authorize {
Subroutine authorize: called CC=3 SCAR=11.0
Pod documented
502 38 my $self = shift;
503 38 my @params = @_;
504  
505 38 foreach my $driver ( $self->drivers ) {
506 36 ▶ return 1 if $driver->authorize(@params);
Branch: 1 branch
BranchTrueFalseTotal
if $driver->authorize(@params) 14 19 33
507 }
508 19 return 0;
509 }
510  
511 =head2 username
512  
513 This method will return the name of the currently logged in user. It uses
514 three different methods to figure out the username:
515  
516 =over 4
517  
518 =item GET_USERNAME option
519  
520 Use the subroutine provided by the GET_USERNAME option to figure out the
521 current username
522  
523 =item CGI::Application::Plugin::Authentication
524  
525 See if the L<CGI::Application::Plugin::Authentication> plugin is being used,
526 and retrieve the username through this plugin
527  
528 =item REMOTE_USER
529  
530 See if the REMOTE_USER environment variable is set and use that value
531  
532 =back
533  
534 =cut
535  
536 39 ▶sub username {
Subroutine username: called CC=3 SCAR=11.0
Pod documented
537 39 my $self = shift;
538 39 my $config = $self->_config;
539  
540 39 ▶ if ( $config->{GET_USERNAME} ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($config->{'GET_USERNAME'}) { } 17 22 39
elsif ($self->cgiapp->can('authen')) { } 1 21 22
541 17 return $config->{GET_USERNAME}->($self);
542 }
543 elsif ( $self->cgiapp->can('authen') ) {
544 1 return $self->cgiapp->authen->username;
545 }
546 else {
547 21 return $ENV{REMOTE_USER};
548 }
549 }
550  
551 =head2 drivers
552  
553 This method will return a list of driver objects that are used for
554 this authorization instance.
555  
556 =cut
557  
558 42 ▶sub drivers {
Subroutine drivers: called CC=6 SCAR=17.9
Pod documented
559 42 my $self = shift;
560  
561 42 ▶ if ( !$self->{drivers} ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->{"drivers"}) 27 15 42
562 27 my $config = $self->_config;
563  
564 # Fetch the configuration parameters for the driver(s)
565 my $driver_configs
566 27 ▶ = defined $config->{DRIVER} ? $config->{DRIVER} : [ ['Dummy'] ];
Branch: 1 branch
BranchTrueFalseTotal
defined $config->{'DRIVER'} ? : 26 1 27
567  
568 27 foreach my $driver_config (@$driver_configs) {
569 28 my ( $drivername, @params ) = @$driver_config;
570 # Load the the class for this driver
571 28 ▶ my $driver_class = _find_delegate_class(
Condition100%2/2
_find_delegate_class('CGI::Application::Plugin::Authorization::Driver::' . $drivername, $drivername) || die('Driver ' . $drivername . ' can not be found')
l!l
271
MC/DC100%1/1
_find_delegate_class('CGI::Application::Plugin::Authorization::Driver::' . $drivername, $drivername) || die('Driver ' . $drivername . ' can not be found')
_find_delegate_class('CGI::Application::Plugin::Authorization::Driver::' . $drivername, $drivername)
Truth table100%2/2
A
A= _find_delegate_class('CGI::Application::Plugin::Authorization::Driver::' . $drivername, $drivername)
Aresult
11
00
572 'CGI::Application::Plugin::Authorization::Driver::'
573 . $drivername, $drivername
574 )
575 || die "Driver " . $drivername . " can not be found";
576  
577 # Create the driver object
578 27 ▶ my $driver = $driver_class->new( $self, @params )
Condition100%2/2
$driver_class->new($self, @params) || die("Could not create new $driver_class object")
l!l
261
MC/DC100%1/1
$driver_class->new($self, @params) || die("Could not create new $driver_class object")
$driver_class->new($self, @params)
Truth table100%2/2
A
A= $driver_class->new($self, @params)
Aresult
11
00
579 || die "Could not create new $driver_class object";
580 26 push @{ $self->{drivers} }, $driver;
581 }
582 25 $self->{loaded} = 1;
583 }
584  
585 40 my $drivers = $self->{drivers};
586 40 return @$drivers[ 0 .. $#$drivers ];
587 }
588  
589 =head2 cgiapp
590  
591 This will return the underlying CGI::Application object.
592  
593 =cut
594  
595 228 ▶sub cgiapp {
Subroutine cgiapp: called CC=1 SCAR=0.0
Pod documented
596 228 return $_[0]->{cgiapp};
597 }
598  
599  
600 =head2 setup_runmodes
601  
602 This method is called during the prerun stage to register some custom
603 runmodes that the Authentication plugin requires in order to function.
604  
605 =cut
606  
607 17 ▶sub setup_runmodes {
Subroutine setup_runmodes: called CC=1 SCAR=0.0
Pod documented
608 17 my $self = shift;
609 17 $self->cgiapp->run_modes( authz_dummy_redirect => \&authz_dummy_redirect );
610 17 $self->cgiapp->run_modes( authz_forbidden => \&authz_forbidden );
611 17 return;
612 }
613  
614 =head1 CGI::Application CALLBACKS
615  
616 We'll automatically add the C<authz_forbidden> run mode if you are using
617 CGI::Application 4.0 or greater.
618  
619 If you are using an older version of CGI::Application you will need to add it yourself.
620  
621 sub cgiapp_prerun {
622 my $self = shift;
623  
624 $self->run_modes( authz_forbidden => \&CGI::Application::Plugin::Authorization::authz_forbidden, );
625 }
626  
627 =cut
628  
629 =head2 prerun_callback
630  
631 This method is a CGI::Application prerun callback that will be
632 automatically registered for you if you are using CGI::Application
633 4.0 or greater. If you are using an older version of CGI::Application
634 you will have to create your own cgiapp_prerun method and make sure you
635 call this method from there.
636  
637 sub cgiapp_prerun {
638 my $self = shift;
639  
640 $self->CGI::Application::Plugin::Authorization::prerun_callback();
641 }
642  
643 =cut
644  
645 17 ▶sub prerun_callback {
Subroutine prerun_callback: called CC=5 SCAR=16.1
Pod documented
646 17 my $self = shift;
647 17 my $authz = $self->authz;
648 17 my $rule = undef;
649  
650 # setup the default login and logout runmodes
651 17 $authz->setup_runmodes;
652  
653 17 ▶ if ($rule = $authz->is_authz_runmode($self->get_current_runmode)) {
Branch: 1 branch
BranchTrueFalseTotal
if ($rule = $authz->is_authz_runmode($self->get_current_runmode)) 14 3 17
654 # This runmode requires authorization
655 my $authz_ok = ref($rule) eq 'CODE' ? $rule->()
656 14 ▶ : ref($rule) eq 'ARRAY' ? first { $self->authz->authorize($_) } @{$rule}
Subroutine __ANON__: called CC=1 SCAR=0.0
Branch: 2 branches
BranchTrueFalseTotal
ref $rule eq 'CODE' ? : 2 12 14
ref $rule eq 'ARRAY' ? : 2 10 12
657 : $self->authz->authorize($rule);
658 14 ▶ return $self->authz->redirect_to_forbidden
Branch: 1 branch
BranchTrueFalseTotal
unless $authz_ok 7 7 14
659 unless ($authz_ok);
660 }
661 }
662  
663 =head2 redirect_to_forbidden
664  
665 This method is be called during the prerun stage if
666 the current user is not authorized, and they are trying to
667 access an authz runmode. It will redirect to the page
668 that has been configured as the forbidden page, based on the value
669 of FORBIDDEN_RUNMODE or FORBIDDEN_URL If nothing is configured
670 then the default forbidden page will be used.
671  
672 =cut
673  
674 7 ▶sub redirect_to_forbidden {
Subroutine redirect_to_forbidden: called CC=3 SCAR=13.6
Pod documented
675 7 my $self = shift;
676 7 my $cgiapp = $self->cgiapp;
677 7 my $config = $self->_config;
678  
679 7 ▶ if ($config->{FORBIDDEN_RUNMODE}) {
Branch: 2 branches
BranchTrueFalseTotal
if ($config->{'FORBIDDEN_RUNMODE'}) { } 0 7 7
elsif ($config->{'FORBIDDEN_URL'}) { } 0 7 7
680 0 $cgiapp->prerun_mode($config->{FORBIDDEN_RUNMODE});
681 } elsif ($config->{FORBIDDEN_URL}) {
682 0 $cgiapp->header_add(-location => $config->{FORBIDDEN_URL});
683 0 $cgiapp->header_type('redirect');
684 0 $cgiapp->prerun_mode('authz_dummy_redirect');
685 } else {
686 7 $cgiapp->prerun_mode('authz_forbidden');
687 }
688 }
689  
690 =head2 forbidden
691  
692 This will return a forbidden page. It checks the configuration to see if there
693 is a custom runmode or URL to redirect to, otherwise it calls the builtin
694 authz_forbidden runmode.
695  
696 =cut
697  
698 3 ▶sub forbidden {
Subroutine forbidden: called CC=3 SCAR=11.0
Pod documented
699 3 my $self = shift;
700 3 my $cgiapp = $self->cgiapp;
701 3 my $config = $self->_config;
702  
703 3 ▶ if ( $config->{FORBIDDEN_RUNMODE} ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($config->{'FORBIDDEN_RUNMODE'}) { } 1 2 3
elsif ($config->{'FORBIDDEN_URL'}) { } 1 1 2
704 1 my $runmode = $config->{FORBIDDEN_RUNMODE};
705 1 return $cgiapp->$runmode();
706 }
707 elsif ( $config->{FORBIDDEN_URL} ) {
708 1 $cgiapp->header_add( -location => $config->{FORBIDDEN_URL} );
709 1 $cgiapp->header_type('redirect');
710 1 return;
711 }
712 else {
713 1 return authz_forbidden( $self->cgiapp );
714 }
715 }
716  
717 =head1 CGI::Application RUNMODES
718  
719 =head2 authz_forbidden
720  
721 This runmode is provided if you do not want to create your own forbidden
722 runmode. It will display a simple error page to the user.
723  
724 =cut
725  
726 8 ▶sub authz_forbidden {
Subroutine authz_forbidden: called CC=1 SCAR=0.0
Pod documented
727 8 my $self = shift;
728 8 my $q = $self->query;
729  
730 8 my $html = join(
731 "\n",
732 CGI::start_html(
733 -title => 'Forbidden',
734 #-style => { -code => $self->auth->styles },
735 ),
736 CGI::h2('Forbidden'),
737 CGI::p('You do not have permission to perform that action'),
738 CGI::end_html(),
739 );
740  
741 8 return $html;
742 }
743  
744 =head2 authz_dummy_redirect
745  
746 This runmode is provided for convenience when an external redirect needs
747 to be done. It just returns an empty string.
748  
749 =cut
750  
751 0 ▶sub authz_dummy_redirect {
Subroutine authz_dummy_redirect: not called CC=1 SCAR=6.9
Pod documented
752 0 return '';
753 }
754  
755 ###
756 ### Helper methods
757 ###
758  
759 28 ▶sub _find_delegate_class {
Subroutine _find_delegate_class: called CC=3 SCAR=11.0
760 28 foreach my $class (@_) {
761 30 ▶ $class->require && return $class;
Branch: 1 branch
BranchTrueFalseTotal
$class->require and return $class 27 3 30
762 }
763 1 return;
764 }
765  
766 156 ▶sub _config {
Subroutine _config: called CC=5 SCAR=16.1
767 156 my $self = shift;
768 156 my $name = $self->{name};
769 156 my $config;
770 156 ▶ if ( ref $self->cgiapp ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $self->cgiapp) { } 136 20 156
771 136 ▶ $config = $self->{__CAP_AUTHORIZATION_CONFIG} ||= $__CONFIG{$name}
Condition80%4/5
$self->{"__CAP_AUTHORIZATION_CONFIG"} ||= $CGI::Application::Plugin::Authorization::__CONFIG{$name} || {}
l!l&&r!l&&!r
91450
$CGI::Application::Plugin::Authorization::__CONFIG{$name} || {}
l!l
1332
MC/DC0%0/2
$self->{"__CAP_AUTHORIZATION_CONFIG"} ||= $CGI::Application::Plugin::Authorization::__CONFIG{$name} || {}
$self->{"__CAP_AUTHORIZATION_CONFIG"} $CGI::Application::Plugin::Authorization::__CONFIG{$name}
Truth table66%2/3
A ||= B
A= $self->{"__CAP_AUTHORIZATION_CONFIG"}B= $CGI::Application::Plugin::Authorization::__CONFIG{$name}
ABresult
1X1
011
000
772 || {};
773 }
774 else {
775 20 ▶ $__CONFIG{$name} ||= {};
Condition100%2/2
$CGI::Application::Plugin::Authorization::__CONFIG{$name} ||= {}
l!l
812
MC/DC100%1/1
$CGI::Application::Plugin::Authorization::__CONFIG{$name} ||= {}
$CGI::Application::Plugin::Authorization::__CONFIG{$name}
Truth table100%2/2
A
A= $CGI::Application::Plugin::Authorization::__CONFIG{$name}
Aresult
11
00
776 20 $config = $__CONFIG{$name};
777 }
778 156 return $config;
779 }
780  
781 =head1 EXAMPLE
782  
783 In a CGI::Application module:
784  
785 package MyCGIApp;
786  
787 use base qw(CGI::Application);
788 use CGI::Application::Plugin::AutoRunmode;
789 use CGI::Application::Plugin::Authentication;
790 use CGI::Application::Plugin::Authorization;
791
792 # Configure Authentication
793 MyCGIApp->authen->config(
794 DRIVER => 'Dummy',
795 );
796 MyCGIApp->authen->protected_runmodes(qr/^admin_/);
797  
798 # Configure Authorization (manages runmode authorization)
799 MyCGIApp->authz->config(
800 DRIVER => [ 'DBI',
801 DBH => $self->dbh,
802 TABLES => ['user', 'usergroup', 'group'],
803 JOIN_ON => 'user.id = usergroup.user_id AND usergroup.group_id = group.id',
804 CONSTRAINTS => {
805 'user.name' => '__USERNAME__',
806 'group.name' => '__GROUP__',
807 }
808 ],
809 );
810 MyCGIApp->authz->authz_runmodes(
811 [a_runmode => 'a_group'],
812 [qr/^admin_/ => 'admin'],
813 [':all' => 'all_group'],
814 [sub {my $rm = shift; return ($rm eq "dangerous_rm")} => 'super_group'],
815 );
816  
817 # Configure second Authorization module using a named configuration
818 __PACKAGE__->authz('dbaccess')->config(
819 DRIVER => [ 'DBI',
820 DBH => $self->dbh,
821 TABLES => ['user', 'access'],
822 JOIN_ON => 'user.id = access.user_id',
823 CONSTRAINTS => {
824 'user.name' => '__USERNAME__',
825 'access.table' => '__PARAM_1__',
826 'access.item_id' => '__PARAM_2__'
827 }
828 ],
829 );
830  
831 sub start : Runmode {
832 my $self = shift;
833  
834 }
835  
836 sub admin_one : Runmode {
837 my $self = shift;
838 # The user will only get here if they are logged in and
839 # belong to the admin group
840  
841 }
842  
843 sub admin_widgets : Runmode {
844 my $self = shift;
845 # The user will only get here if they are logged in and
846 # belong to the admin group
847  
848 # Can this user edit this widget in the widgets table?
849 my $widget_id = $self->query->param('widget_id');
850 return $self->authz->forbidden unless $self->authz('dbaccess')->authorize(widgets => $widget_id);
851
852 }
853  
854  
855 =head1 TODO
856  
857 The module is definately in a usable state, but there are still some parts
858 missing that I would like to add in:
859  
860 =over 4
861  
862 =item provide easy methods for authorizing runmode access automatically
863  
864 =item allow subroutine attributes to configure authorization for a runmode
865  
866 =item write a tutorial/cookbook to include with the docs
867  
868 =back
869  
870  
871 =head1 BUGS
872  
873 This is alpha software and as such, the features and interface are subject to
874 change. So please check the Changes file when upgrading.
875  
876  
877 =head1 SEE ALSO
878  
879 L<CGI::Application::Plugin::Authentication>, L<CGI::Application>, perl(1)
880  
881  
882 =head1 AUTHOR
883  
884 Cees Hek <ceeshek@gmail.com>
885  
886 =head1 CREDITS
887  
888 Thanks to SiteSuite (http://www.sitesuite.com.au) for funding the development
889 of this plugin and for releasing it to the world.
890  
891  
892 =head1 LICENCE AND COPYRIGHT
893  
894 Copyright (c) 2005, SiteSuite. All rights reserved.
895  
896 This module is free software; you can redistribute it and/or modify it under
897 the same terms as Perl itself.
898  
899 =head1 DISCLAIMER OF WARRANTY
900  
901 BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE
902 SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE
903 STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE
904 SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
905 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
906 FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
907 PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE,
908 YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
909  
910 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY
911 COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE
912 SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES,
913 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING
914 OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO
915 LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR
916 THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE),
917 EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
918 DAMAGES.
919  
920 =cut
921  
922 11 1;
« Authorization/Driver/DBI.pm ↑ Summary Authorization/Driver/SimpleGroup.pm »