README
1Apache Notes
2============
3This package allows you to create a complex site authorization system where
4specific actions on resources are given custom rules. It extends
5Apache::AuthCookie to track sessions. It has been tested with Apache 1 and 2,
6and seems to work well. There are sample sites in the samples directory. The
7differences in the two apache environments require slightly different setups,
8so be sure to use the proper sample for your configuration.
9
10Use Apache2::SiteControl for apache 2.x.
11
12Description
13===========
14
15There are two levels of control in Apache::SiteControl.
16
17The first is managed by Apache::SiteControl, and determines if a valid user
18has logged in. If so, it makes a user object available to the request
19processor. This is done using Apache::SiteControl::UserFactory (a good base
20implementation is already written). The underlying code associates this user
21with a session, and manages the browser interaction.
22
23The second level of control is supplied by an application level
24PermissionManager. The user objects are passed to this object, along
25with the requested action and an opaque resource (of any type). Rules are
26installed in the PM that determine if a specific action is allowed for a given
27user and resource.
28
29 if($manager->can($currentUser, "change", $dnsrecord)) {
30 ...
31 }
32
33where the PM applies the various installed rules (user-defined) and returns
34true if the action is allowed, false otherwise. In this example, one of the
35rules might detect that the resource (dnsrecord) is a row from a DNS tracking
36table. It might then check to see if the currentUser is associated with
37DNS management and return true if they are, false otherwise. The top level
38application could then use this in a pretty abstract way. For example, if there
39is a generic section of code that allows users to modify a row from a table,
40the same code could be used:
41
42 if($manager->can($currentUser, "change", $thisRecord)) {
43 ...
44 }
45
46The application doesn't have to figure out what thisRecord is...the rules can
47sense them. This allows the top-level application to be written in very
48generic terms, and rules to be written based on the actual logic involved.
49
50A rule might include code like this:
51
52 sub grants
53 {
54 $this = shift;
55 $user = shift;
56 $action = shift;
57 $resource = shift;
58
59 if($action eq "change") {
60 if($resource->isa("DNS::Record"))
61 {
62 if($resource->getContactEMail() eq $user->getAttribute("email"))
63 {
64 return "permission granted by DNSRule";
65 }
66 }
67 }
68 return 0;
69 }
70
71which would detect the proper types that it knows how to handle, and do a check
72that would indicate if permission is to be granted.
73
74Comments on Rules
75
76How would you make a system that allows everything, unless something is
77specifically denied?
78 Have a GrantAll rule that always grants permission.
79 Add rules that never grant, but deny on specific cases.
80
81How to make a system that denies everything except things that have been
82checked out:
83 Write rules that grant on your specific cases. The default is to deny
84 permission if no rules have anything else to say about the request.
85
86A rule can take several approaches:
87
88Relative rule: It grants but never denies. Or it denies, but never grants.
89
90Absolute rule: If it grants, then it does not deny. If it does not grant, then
91it denies.
92
93Read the manual pages for more information.
94
README.UPGRADING_TO_1.0
1Version 1.0 has a significant change from previous versions. AccessController
2is dropped in favor of a module actually called SiteControl. This makes the
3whole system work better in the Perl sense, and make version checking and
4installation smoother with CPAN.
5
6To upgrade:
7
81) Edit all of your modules that depend on
9 Apache2::SiteControl::AccessController, and change them to use
10 Apache2::SiteControl.
112) Make the same change in all of your pages. i.e.:
12
13 $user = Apache2::SiteControl::AccessController->getPermissionManager($r)
14
15 becomes:
16
17 $user = Apache2::SiteControl->getPermissionManager($r)
18
19 i.e.
20
21 perl -pi'.bak' 's/SiteControl::AccessController/SiteControl/' *.html
22