Contents:
  What is an Access Control List
  Checking a users status in the ACL
  The PHP Generic Access Control List
  Installing the PHP Generic Access Control List
  Installing the phpGACL PlugIn Example and Client Class
  Installing the Access Control List Database and Interface
  Administrating the Access Control List
  Appendix A: Resources

An Access Control List (ACL) is a system that can be used to control access to specified resources. In this context we are mainly concerned with resources such as Web pages, application classes and sections, for example administrators or members sections of a Web application.

An overview of the ACL structure used in this example can be seen in the diagram below.


Figure 1 The KB site ACL Tree

An Access Control List is comprised of elements that define who can access what on a particular system. For example:

This ACL says that the resource "Members Pages" is in a resources category called "KB Site".

The "KB Member" is a "thing" or "actor" that can define a person, or a role played by a person such as a member of a forum. This actor (KB Member) is defined in a "things" category called "KB Site Actors".

The ACL now says that this actor has a particular permission for this resource. In this case our "KB Member" actor is ALLOWed to access this "Members Pages" resource. If we specify the access as "DENY", the "KB Member" actor would not be allowed access to this resource.

Initially we could require a user to authenticate (logon) with our application. During the logon process we could retrieve the users name, role (role in the ACL system), etc. A sample SQL query might look something like:

   $q = 'Select name, role From users Where name='.$username.' And password = '.$pword.';
   $row = $db->getRow($q);
   $username = $row['name'];
   $userRole = $row['role']; // E.g. 'kb_member'

Then at the top of a restricted method or section in our application we can test the users credentials against the ACL system:

   // Members Pages
   if ( $gacl->acl_check('kb_site', 'member_pages', 'kb_site_actors', $userRole) ) {
      // OK to access member resources
      $memberMsg = "$username ($roles[$userRole]) has been GRANTED access to Members Pages";
   } else {
      // Not authorised to access member resources
      $myForwardConfig  = $mapping->findForwardConfig('acl_fail');
      $memberMsg = "$username ($roles[$userRole]) has been DENIED access to Members Pages";
   }

If our user logon returned a role, say 'kb_member' and this role was defined in the ACL as a 'kb_site_actors'>'kb_member', the acl_check(...) method will return True, otherwise it will return False. Based on the acl_check(...) return value, we can allow or deny access to this restricted section.

This ACL implementation uses the PHP Generic Access Control List (phpGACL) package. Generic Access Control List was written by Mike Benoit and is available on SourceForge: phpgacl.sourceforge.net

Mike has developers a quite comprehensive administrative Web interface for phpGACL. This interface makes the setup and management of the Access Control List and its components very much easier than it otherwise would be. The package also contains a user manual in several formats.

The PHP Generic Access Control List (phpGACL) can be grouped into two basic categories of usage:

The first part is the small and fast gacl client class that simply queries the ACL database. This is the class we load as a PlugIn and call within our restricted methods.

The second part is the administration classes and Web interface that allow the setup and maintenance of the ACL system and its database. This section would probably be best installed outside of the php.MVC framework for security reasons. The phpGACL system could also be used by other applications apart from the php.MVC framework.

For information on how PlugIn's work in the php.MVC framework see The PlugIn Dynamic Module Loader Guide

An example module demonstrating the use of the PHP Access Control List application in the php.MVC framework is available for download here: phpgacl-plugin

Unpack the archive to a directory within your Web server root directory, inside or outside the of php.MVC library directory. Perhaps something like: C:/WWW/phpmvc-test/phpGACL

Edit Main.php and set the paths to the php.MVC core library directory and the example directory, as usual.

Edit the phpmvc-config.xml file and set the element attributes to match your ACL database settings as specified above.

Review the WEB-INF/classes/CLTestAction.php file for an example of how to use the ACL within php.MVC classes.

Load the example ACL SQL data (MySQL):
Some ACL data can be found in the Ext/sql directory for use with the example. If using MySQL you can load the data at the command line, something like:

   $ ./bin/mysql -u userid -puserpword < /tmp/kb_acl.sql

Browse to the "Main.php" file in the phpGACL example directory, with the action path as shown:

	www.myhost.com/phpmvc-test/phpGACL/Main.php?do=testACL

Select a user role in the form and observe the access levels reported for this user role.

The process of setting up and administrating the ACL (phpGACL) can be a little tricky at first. The steps I have taken to install and setup the ACL system are as follows:

Note: See the install section in the phpGACL user manual for more details.

Note for MySQL users: I could not get the phpGACL Web interface to operate successfully using the MySQL DBMS. Mike uses the "sequence list" feature of many DBMS's to obtain table ID's. As far as I know MySQL does not yet support sequence lists. I have modified the file "gacl_api.class.php" to work around this issue. The modified file is included with the phpGACL PlugIn example, in the Ext directory.

Download the phpGACL archive from the authors SourceForge site:

Install phpGACL to a directory outside the php.MVC framework. Perhaps something like /libs/phpgacl/

Open the /admin/gacl_admin.inc.php file and edit the $gacl_options array to specify the Database Management System (DBMS) and host, username and password and the name we want to use for the ACL database. For example:

   'db_type'     => 'mysql'
   'db_host'     => 'localhost'
   'db_user'     => 'myuser'
   'db_password' => 'mypword'
   'db_name'     => 'gacl'

Logon to your DBMS and create the ACL database. Something like:

   >mysql u myuser pmypword
   mysql>Create Database gacl_mvc;

Browse to the phpGACL install directory and open "setup.php". For example: http://www.myhost.com/libs/phpgacl/setup.php . This should install the necessary ACL tables in the database we specified above.

Add a Smarty compile directory to the phpGACL directory as follows: phpgacl/admin/smarty/templates_c. Make this compile directory writable by the Web server.

Secure the phpGACL directory with an .htaccess file (or other suitable means) to control who can access your phpGACL directory.

Browse to the phpGACL administrative page: http://www.myhost.com/libs/phpgacl/admin/acl_admin.php. This will display the ACL interface where you can setup and maintain your Access Control Lists.

If using MySQL and the administrative page does not work as expected see the note for MySQL users above.

Please refer to the phpGACL user manual for a detailed discussion on Access Control List theory.

This figure shows the ACL administrator main page. This is where we can specify Access Control Object (ACO) resources we want to control, and the Access Request Object (ARO) "actors" associated with the ACO, along with the Access status (Allow, Deny). There is also a field at the bottom of the form where a description of this item can be entered. The selections on this form would become an entry in the phpGACL ACL list.


Figure 2 The ACL Administrator Main Page

Another point to note is that the default assess policy for the ACL lists is DENY.

The PHP Generic Access Control List (phpGACL) uses several primary elements: Access Control Objects (ACO), Access Request Objects (ARO), The Access Control List (ACL) and Access Request Object Groups.

Access Control Objects (ACO)
These are the resources that we want to control access to, like Web pages, class methods or sections etc.

All ACO items must be identified with an ACO section. In this example we define a "KB Site" section as the logical container to hold various controlled resources for this site.

We must add a new resource section (ACO) before we can add any actual resource objects. To add or edit a resource section (ACO), use the "Edit" link on the top left of the ACL Administrator Main Page. (See figure 2).

Now we can add actual Access Control Objects (ACOs) using the "Edit" link on the ACL Administrator Main Page, under the "Access Control Objects" heading. Be sure to select a "Sections" item first. For example "KB Site".

This figure shows the "KB Site" section with three ACO resources: "Admin Pages", "Members Pages" and "Public Pages".


Figure 3 The ACO Resources

Access Request Objects (ARO)
These are the "things" or actors that we can allocate permissions to allow access to particular ACO resources. An ARO could be a person, or a role played by a person such as a member of a forum, or represent some other item such as a server.

Again we must add an ARO section before we can add any ARO "actors". To add or edit an ARO section, use the "Edit" link on the mid left of the ACL Administrator Main Page. (See figure 2).

Now we can add actual Access Resource Objects (ARO) using the "Edit" link on the ACL Administrator Main Page, just below the "Access Request Objects" heading. Be sure to select a "Sections" item first. For example "KB Site Actors".

This figure shows the "KB Site Actors" section with four ARO resources: "KB Admin", KB Members" and "KB Public" and a sudo admin "KB Supervisor".


Figure 4 The ARO Actors

The Access Control List (ACL)
As described above, an Access Control List is comprised of elements that define who can access what on a particular system. For example:

The Resources	The Person or Role	Access
KB Site>Members Pages	KB Site Actors>KB Member	ALLOW

This ACL says that this actor has a particular permission (ALLOW) for this resource. In this case our "KB Member" actor is ALLOWed to access this "Members Pages" resource. If we specify the access as DENY, the "KB Member" actor would not be allowed access to this resource.

To create an ACL entry we use the ACL Administrator form (See figure 2). Select the appropriate resources (ACOs), actors (AROs), set the access permission (ALLOW or DENY) and add a descriptive note (bottom of the admin form). When we hit the "Submit" form button an ACL list entry is created. To view the ACL list use the "ACL List" link at the top of the ACL Administrator form. The ACL list for our example site is shown in figure 5:


Figure 5 The ACL List

Access Request Object Groups
The phpGACL also contains the ability to use Groups to add additional flexibility to the Access Control Lists system.

Using the ACL Groups function we can add users or other actors (AROs) to an ARO Group. This group can then be granted permissions on a particular resource (ACO).

Initially we must create a group section. The Groups form is accessed via the "ACL List -> ARO Group Admin" link. The ARO Group Administrator form should look something like figure 6:


Figure 6 The ARO Group Administrator

From this form we can hit the "Add" button to add groups and child groups. For this example I have created a KB Group item as the parent group for this site, and several sub-groups: KB Admins Group, KB Members Group and KB World Group.

Next we have to assign our site users or actors (AROs) to the groups. So from the ARO Group Administrator page we hit the "Assign ARO" link for the appropriate group. Perhaps we wanted to add a sudo administrator actor to the administrators group, so we could temporarily promote someone to the administrator role. So we hit the "Assign ARO" link in the "KB Admins Group" row on the Group Administrator page, and a form should come up that will allow us to manage the ARO actors we wish to assign to the "KB Admins Group". Figure 7 shows the KB Admins Group form with two ARO actors assigned to this group.


Figure 7 The KB Admins Group Assignments

We can see that the KB Supervisor ARO actor is included in the KB Admins Group. I've also added the KB Admin ARO actor to the KB Admins Group for completeness, although this entry is probably not necessary. The other ARO actors can be assigned to relevant groups in a similar manner.

When all the group entries are complete, we can return to the phpGACL Administrator page (see figure 2). From there we can add one or more groups to an Access Control List entry. For example I have added the KB Admins Group to the KB Admin ARO entry, so any user with KB Supervisor status will have the same access rights as the administrator on the system.

Reviewing and Testing the ACL

To review the Access Control List entries hit the "ACL List" link at the top of the ACL Administrator form (see figure 2). We can now see the groups that have been added to each ACL.

When our Access Control List is complete we can check the entries using the "ACL Test" page link. For the example ACL data, the ACL test page should look something like figure 8 below:


Figure 8 The KB Access Control List Test Page

phpGACL home page and documentation.
phpGACL home page

phpGACL download site
Note: The phpGACL library is included in the php.MVC PlugIn example packege.
phpGACL download site

phpGACL as a php.MVC PlugIn example (phpgacl-plugin.tgz/zip)
phpGACL PlugIn example