dotproject 2.1.2

phpGACL Generic Access Control List Mike Benoit <ipso@snappymail.ca> James Russell <james-phpgacl@ps2-pro.com> Karsten Dambekalns <k.dambekalns@fishfarm.de> Copyright � 2002,2003, Mike Benoit Copyright � 2003, James Russell Copyright � 2003, Karsten Dambekalns Document Version: 42 Last Updated: 5/20/03 - 18:55:08 Table of Contents Table of Contents 2 About 5 What is it? 5 Where can I get it? 5 What do I need to run it? 5 Who is responsible for it? 5 Introduction 6 Understanding Access Control 6 Who/Where 6 Who/Where 7 Defining access control with phpGACL 7 Fine-grain access control 8 Multi-level Groups 9 How does phpGACL determine permissions? 9 Adding groups 11 Adding people 11 Resolving conflicts 12 Naming Access Objects 13 Adding Sections 14 Multiple Purposes 15 Access eXtension Objects 15 Installation 18 Basic setup 18 Advanced setup 20 Using phpGACL in your application 21 Basic usage 21 Advanced usage 21 Using the ACL admin utility 22 API Reference 23 ACL 23 add_acl() 23 edit_acl() 23 del_acl() 24 Groups 24 get_group_id() 24 get_group_parent_id() 24 add_group() 24 get_group_objects() 25 add_group_object() 25 del_group_object() 25 edit_group() 26 del_group() 26 Access Objects (ARO/ACO/AXO) 26 get_object() 26 get_object_data() 27 get_object_id() 27 get_object_section_value() 27 add_object() 27 edit_object() 28 del_object() 28 Access Object Sections 29 get_object_section_section_id() 29 add_object_section 29 edit_object_section() 30 del_object_section() 30 FAQ 31 About What is it? phpGACL is an set of functions that allows you to apply access control to arbitrary objects (web pages, databases, etc) by other arbitrary objects (users, remote hosts, etc). It offers fine-grained access control with simple management, and is very fast. It is written in PHP (hence phpGACL), a popular scripting language that is commonly used to dynamically create web pages. The GACL part of phpGACL stands for Generic Access Control List. Where can I get it? phpGACL is hosted by sourceforge.net at http://phpGACL.sourceforge.net/ What do I need to run it? phpGACL requires a relational database to store the access control information. It accesses this database via an abstract wrapper called ADOdb. This is compatible with databases such as PostgreSQL, MySQL and Oracle. phpGACL is written in the PHP scripting language. It requires PHP 4.2 and above. Access Control List administration is performed by a web interface, and therefore it is necessary to have a web server with PHP support, such as Apache . Who is responsible for it? Mike Benoit <ipso@snappymail.ca> is the author and project manager. James Russell <james-phpgacl@ps2-pro.com> and Karsten Dambekalns < k.dambekalns@fishfarm.de> did the documentation. Introduction Understanding Access Control Han is captain of the Millennium Falcon and Chewie is his second officer. They've taken on board some passengers: Luke, Obi-wan, R2D2 and C3PO. Han needs to define access restrictions for various rooms of the ship: The Cockpit, Lounge, Engines and the external Guns. Han says: "Me and Chewie should have access to everywhere, but after a particularly messy hyperdrive repair, I forbid Chewie from going near the Engine Room ever again. Passengers are confined to the Passenger's Lounge." Let's assume from now on that access is Boolean. That is, the result of looking up a person's access to a room is either ALLOW or DENY. There is no middle ground. If we mapped this statement into an access matrix showing who has access to where, it would look something like this (O means ALLOW, X means DENY): +--------------------------------------------------+ | Who/Where | Cockpit | Lounge | Guns | Engines | |------------+----------+--------+------+----------| | Han | O | O | O | O | |------------+----------+--------+------+----------| | Chewie | O | O | O | X | |------------+----------+--------+------+----------| | Obi-wan | X | O | X | X | |------------+----------+--------+------+----------| | Luke | X | O | X | X | |------------+----------+--------+------+----------| | R2-D2 | X | O | X | X | |------------+----------+--------+------+----------| | C3PO | X | O | X | X | +--------------------------------------------------+ The columns list the rooms that Han wants to restrict access to, and the rows list the people that might request access to those rooms. More generally, the "rooms" are "things to control access on". We call these Access Control Objects (ACOs). The "people" are "things requesting access". We call these Access Request Objects (AROs). The people request access to the rooms, or in our terminology, AROs request access to the ACOs. There is a third type of Object, the Access eXtention Object (AXO) that we'll discuss later. These objects share many attributes and are collectively referred to as Access Objects. Managing access using an access matrix like the one above has advantages and disadvantages. Pros: * It's very fine-grained. It's possible to control access for an individual person if necessary. * It's easy to see who has access to what. The answer is stored in the intersection of the person and the room. Cons: * It's difficult to manage on a large scale. 6 passengers and 4 places is fairly simple, but what if there were thousands of passengers and hundreds of places, and you need to restrict access to large groups of them at once, but still retain enough fine-grained control to manage access for an individual? That would mean a lot of fiddly and lengthy adjustment to the matrix, and it's a difficult task to verify that the final matrix is correct. * It's hard to summarize or visualize. The above example is fairly simple to summarize in a few sentences (as Han did above), but what if the matrix looked like this? +--------------------------------------------------+ | Who/Where | Cockpit | Lounge | Guns | Engines | |------------+----------+--------+------+----------| | Han | O | O | O | O | |------------+----------+--------+------+----------| | Chewie | O | X | O | X | |------------+----------+--------+------+----------| | Obi-wan | X | O | X | X | |------------+----------+--------+------+----------| | Luke | O | O | O | X | |------------+----------+--------+------+----------| | R2-D2 | X | O | X | O | |------------+----------+--------+------+----------| | C3PO | O | O | X | O | +--------------------------------------------------+ This matrix is not so obvious to summarize, and it's not clear to the reader why those access decisions might have been made in the first place. Defining access control with phpGACL It seems that for large or complex situations, this 'access matrix' approach is clearly unsuitable. We need a better system that maintains the advantages (fine-grain control and a clear idea of who has access to what) but removes the disadvantages (difficult to summarize, and difficult to manage large groups of people at once). One solution is phpGACL. phpGACL doesn't describe access from the 'bottom-up' like the Access Matrix above. Instead, it describes it 'top-down', like the textual description of Han's access policy. This is a very flexible system that allows you to manage access in large groups, it neatly summarizes the access policy, and it's easy to see who has access to what. An ARO tree defines a hierarchy of Groups and AROs (things that request access). This is very similar to a tree view of folders and fi