Apache...ontrol(3pm)

💖 Apache2::SiteControl — the manual, but make it cute 💖

okay bestie, so this page is Apache...ontrol(3pm) from the User Contributed Perl Documentation, and it's literally your whole guide to Apache2::SiteControl. grab a boba, we're doing auth 🧋✨

---

🌸 NAME 🌸

Apache2::SiteControl — a whole Perl web site authentication/authorization system, no cap 👑

---

✨ SYNOPSIS ✨

okay so first thing: go look at samples/site for the complete example, it's giving tutorial energy fr. also important — this module is intended for mod_perl. if you want mod_perl2, you want Apache2::SiteControl (which, yes, is the module we're literally talking about, iykyk).

---

🦋 DESCRIPTION 🦋

Apache2::SiteControl is a set of perl object-oriented classes that implement a fine-grained security control system for a web-based application. the whole vibe? clear, easy-to-integrate, and — this is the iconic part — your policies do NOT have to be written into your application components. it separates the concerns of how to show and manipulate data from the concerns of who is allowed to view and manipulate data and why. it's giving separation of concerns, it's giving clean architecture 💅

for example, say your web application is written in HTML::Mason. your individual "screens" are composed of Mason modules, and you would like to keep those as clean as possible, but decisions have to be made about what to allow as the component is processed. SiteControl attempts to make that as easy as possible. obsessed.

🎀 DEVELOPER'S VIEWPOINT - EXAMPLE 🎀

in this document we use HTML::Mason to create examples of how to use the control mechanisms, but any mod_perl based system should be supportable. no gatekeeping here 🫶

a good mason component tries to do most of the perl processing in a separate block, so that simple substitutions can be made in HTML in the rest of the page. this makes it much easier for web developers and perl developers to co-exist on a project. collab era.

the SiteControl system tries to make it possible to continue to follow this model. you obtain a user object and permission manager from the SiteControl system. these are intended to be opaque data types to the page designer, and are defined elsewhere (see USERS). the actual web page component should carry these objects around without implementing anything in the way of policy. main character energy: carry the objects, don't do the policy.

for example, your mason component might look like this:

<HTML>
   <HEAD> ... </HEAD>
% if($manager->can($currentUser, "edit", $table)) {
      <FORM METHOD=POST ACTION="...">
         <P><INPUT TYPE=TEXT NAME="x" VALUE="<% $table->{x} %>">
         ...
      </FORM>
% } else {
      <P>x is <% $table->{x} %>
% }

<%init>
my $currentUser = Apache2::SiteControl->getCurrentUser($r);
my $manager = Apache2::SiteControl->getPermissionManager($r);

... application specific stuff...
i.e.

my $table = ...
</%init>

notice that the component does not bother looking at the user object, and there is no policy code...just a request for permission:

if($manager->can($currentUser, "do something to", $resource))

of course the developer needs to know something about the underlying system. for example, the action string "do something to" is rather arbitrary. these can be anything, and must be specified as rule actions. it is recommended that you use some form of Perl constants for these instead of strings, but that is up to you. your call, bestie 💁‍♀️

the resource is intended to be less opaque. this is likely the object that the page developer wants to muck with, and so probably knows the internals of that object a bit better. this is the crossover point from what SiteControl can figure out on its own to information you have to supply.

⚠️ the default behavior is for the manager to deny any request. in order for a request to be approved, someone has to write a rule that joins together the user, action, and resource and makes a decision about the permissibility of the action. deny by default is the vibe check and it PASSED.

if all you want is login and user tracking (but no permission manager), then it is safe to ignore the permission manager altogether. slay, less work.

---

👑 USERS 👑

Users and Rules are the central components of the SiteControl system. the user object must be Apache2::SiteControl::User (or a subclass). see Apache2::SiteControl::User for a description of what it supports (session storage, logout, etc.). the glue to SiteControl is the UserFactory, which you can define or accept the default of Apache2::SiteControl::UserFactory (recommended). take the default, it's the low-effort high-reward option 💅

whenever a login attempt succeeds, the factory returns an object that represents a valid, logged-in user. see Apache2::SiteControl::UserFactory for more information.

🌈 PERMISSION MANAGER 🌈

each site will have a permission manager. there is usually no need for you to subclass Apache2::SiteControl::PermissionManager, but you do need to create one and populate it with your access rules. you do this by creating a factory class, which looks something like this:

package samples::site::MyPermissionFactory;

use Apache2::SiteControl::PermissionManager;
use Apache2::SiteControl::GrantAllRule;
use samples::site::EditControlRule;

use base qw(Apache2::SiteControl::ManagerFactory);

our $manager;

sub getPermissionManager
{
   return $manager if defined($manager);

   $manager = new Apache2::SiteControl::PermissionManager;
   $manager->addRule(new Apache2::SiteControl::GrantAllRule);
   $manager->addRule(new samples::site::EditControlRule);

   return $manager;
}

1;

the primary goal of your factory is to produce an instance of a permission manager that knows the rules for permitting access to your site. this is an easy process that involves calling the constructor (via new) and then calling addRule one or more times. that's it, that's the whole ritual ✨

💜 RULES 💜

the PermissionManager is the object that the site developers ask about what is allowed and what is not. as you saw in the previous section, you create a manager, and add some rules.

each rule is a custom-written class that implements some aspect of your site's access logic. rules can choose to grant or deny a request. the following is a pretty complex example that demonstrates the features of a rule. it's giving overachiever rule, honestly iconic.

most rules will either specifically grant permission, or deny it. most will not deal with both possibilities. in this example we are assuming that the user is implemented as an object that has attributes which can be retrieved with a getAttribute method (of course, you would have to have implemented that as well). the basic action that this rule handles is called "beat up", so the site makes calls like:

if($referee->can($userA, "beat up", $userB)) { ... }

in terms of English, we would describe the rule "If A is taller than B, then we say that A can beat up B. If A is less skilled than B, then we say that A cannot beat up B". the rule looks like this:

package samples::FightRules;

use strict;
use warnings;
use Carp;
use Apache2::SiteControl::Rule;

use base qw(Apache2::SiteControl::Rule);

sub grants($$$$)
{
   my $this = shift;
   my $user = shift;
   my $action = shift;
   my $resource = shift;

   if($action eq "beat up" && $resource->isa("Apache2::SiteControl::User")) {
      my ($h1, $h2);
      $h1 = $user->getAttribute("height");
      $h2 = $resource->getAttribute("height");
      return 1 if(defined($h1) && defined($h2) && $h1 > $h2);
   }

   return 0;
}

sub denies($$$$)
{
   my $this = shift;
   my $user = shift;
   my $action = shift;
   my $resource = shift;

   if($action eq "beat up" && $resource->isa("Apache2::SiteControl::User")) {
      my ($s1, $s2);
      $s1 = $user->getAttribute("skill");
      $s2 = $resource->getAttribute("skill");
      return 1 if(defined($s1) && defined($s2) && $s1 < $s2);
   }

   return 0;
}

1;

🔥 the PermissionManager will only give permission if at least one rule grants permission, and no rule denies it. that's the whole law. one yes, zero nos.

i think it is clearer to separate rules like the previous one into separate rule classes altogether. a HeightMakesMightRule and a DefenseSkillRule. splitting into two rules makes things clearer, and there is no limit to the number of rules that the PermissionManager can check. stack those rules, queen 👑

it is important that your rules never grant or deny a request they do not understand, so it is a good idea to use type checking to prevent strangeness. assertions should not be used if you expect different rules to accept different resource types or user types, since each rule is used on every access request. fr fr, every single request. be careful.

---

🍓 EXPORT 🍓

none by default. nothing. zero. nada. you get nothing unless you ask 💀 (jk, it's just standard perl behavior bestie)

---

🌟 SEE ALSO 🌟

• Apache2::SiteControl::UserFactory
• Apache::SiteControl::ManagerFactory
• Apache2::SiteControl::PermissionManager
• Apache::SiteControl::Rule

go read them, they're the supporting cast and they ate 💅

---

💖 AUTHOR 💖

this module was written by Tony Kay, <tkay@uoregon.edu>. king behavior honestly 👑

---

🎀 COPYRIGHT AND LICENSE 🎀

this modules is covered by the GNU public license. (yes, the original says "this modules", we're keeping it exactly, no edits 💖)

---

and that's the whole page, bestie! this was Apache...ontrol(3pm) from the User Contributed Perl Documentation, and the footer said perl v5.26.2, dated 2018-08-31. ok bye ily, go write some rules 🫶✨