Acl and Phpgacl

ACL

What is an Access Control List:

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.

ACL Overview

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 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.

PhpGALC

The PHP Generic Access Control List:

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.
Installing the PHP Generic Access Control List:
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

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
The SQL dump file will create a database named “gacl_mvc”. Be careful not to overwrite any existing database you have with the same name. There is also an XML file dump of the ACL database that may be useful to users of other DBMS systems.
Browse to the “Main.php” file in the phpGACL example directory, with the action path as shown:
www.myhost.com/phpGACL/Main.php?do=testACL
Select a user role in the form and observe the access levels reported for this user role.

Installing the Access Control List Database and Interface:

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:

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.

Administrating the Access Control List:

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.

Administrating the Access Control List

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”.

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”.

ARO resources

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:

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:

Access Request Object Groups

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.

Assign ARO

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:

ACL List