Below you will find an overview of how to install and use the class and example GUI. In most cases, you wil not need to create your own GUI.

INSTALLATION

Download and decompress the Metabase (http://koivi.users.phpclasses.org/metabase) database abstraction layer.
Download the XML Parser (http://koivi.users.phpclasses.org/xmlparser and put it in the metabase directory
Uncompress the phpSecurityAdm package.
Edit the config.php file found in the include directory according to the comments found there.*
Edit the database name in psa.schema.xml if necessary
Run the install_db.php script to initiate your database tables. (Like all database schema installs, it is recommended that you run this script from a command prompt rather than a browser.)

* It is best not to store the database connection details in the config.php file. To achieve a higher level of security, set up the SQL_* variables to be passed by the web server. [SetEnvIf Host domain\.com SQL_x=value inside the virtual host directives of apache for example.]

REQUIREMENTS

This system was initially developed using the apache 1.3.20 web server, mysql 3.23.40 database server, and PHP-4.1.1 compiled as a DSO module all running on a linux server. Version 3.0 development was done mostly on Apache 1.3.26, mysql 3.23.51, and PHP 4.2.2 on various Windows 98/ME/2000/XP machines as well as linux. For best results, you should have at least the above setup. You will need to have session support, gettext support, and trans-sid enabled as well.

I have limited resources when it comes to testing other platforms, web servers, database servers, etc. If you would like to contribute the development and/or testing of this project, post a message at http://sourceforge.net/forum/?group_id=67410

GETTING STARTED

To use the phpSecurityAdm package, you will need to decide what pages you would like to restrict access to. At the top of each of these pages (which will need to parse PHP code), add the line:

<?php require_once "/path/to/phpSecurityAdm/_restrict.php"; ?>

Once you have the pages you want to restrict, you will need to add in the location of each page into the database. To do this, you will need to log in to the system by browsing to http://www.domain.com/path/to/phpSecurityAdm/index.php with a web browser. The default password for the user "admin" is "secure" (you will want to change this before going live).

Once you are logged in, go to the "Site Structure" section and add in each of the pages you are restricting access to. The "Page Name" is something to identify each page to you, the admin. This can be any string that you want. The "Location" is the path that is requested to reach the page. For instance, if your page is accessed by http://www.domain.com/page.php, you would enter /page.php. If it was http://www.domain.com/folder/page.php, you would enter /folder/page.php.

As of version 3.0b2, you can now also use wildcard url matching. For instance, if you want to give access to everything in a certain directory, instead of adding a "page" for each file, you can simply use: "/directory/*". This will allow access under the profile for any url starting with "/directory/".

You will now need to give access to these pages to users. The "admin" user does not have access to restricted pages by default. To grant access to pages:

Go into the "Users" section and edit the user you wish to grant access to.
Click "Edit rights to pages."
Select the profiles that this user should have access to and submit the form.

USERS

To create a user, simply go to the "Users" section and click "Create New User." Fill out the presented form, and click submit. By default, a user is active when created.

EDIT CONTACT DETAILS

You can change the contact details of a user at any time by editing that user and selecting "Edit contact details."

EDIT CONNECTIONS

You can change the user's active status, password, or where they are allowed to log into the system from by selecting "Edit connections" from the edit user page. The "Allowed Connections" field works the same way as the one in the "Configuration" section. This allows the admin not only to restrict where connections can be initiated for the system, but also further restrict where each user can connect from.

EDIT USER ACCESS RIGHTS

As of version 2.0, all user rights are handled through the use of the system-defined profiles.

PROFILES

Think of profiles as being similar to groups. You can easily give groups of users the same (or similar) access rights by creating profiles. All you need to do is create a profile by giving it a name to identify it and selecting which pages to allow access to.

You can then apply these profiles to users either during creation or by editing their access rights. During editing, applying a profile is as simple as choosing the name from the drop-down list and submitting the form.

As of version 2.4.0, users can now belong to more than one profile. This would allow you (the administrator) to create profiles that can be used to give users rights to different sections without having to define a separate profile for each possible combination.

For instance, if I have a protected section called "Book Reviews" and one called "Movie Reviews", I would create 2 profiles: "books" and "Movies." Then if I want a user to access "Books," I'd assign them that profile. If the user should access only "Movies," then I'd use that profile. If I want this particular user to access both, I could simply assign both profiles. In previous versions, you would have needed to create a "Books and Movies" profile to accommodate.

SITE STRUCTURE

This section is a list of all the pages that the system sees as being restricted. In order for these to work that way, you do have to add the line of code mentioned in the GETTING STARTED section to the top of the restricted page.

Adding pages to the database is also necessary to do in order to successfully restrict access to them. To do this, simply click on the "Add Page" link above the table listing all the existing pages. The GETTING STARTED section of this document gives you instructions about the form.

CONFIGURATION

The fields in this section are quite self-explanatory with the exception of "Allowed Connections." To only allow connections from certain computers, see the examples below:

To allow only from one address, enter the IP (only works with static IPs).

192.168.1.201

To allow from all machines with an address that starts with a sequence:

192.168.1.
or
192.168.

You can also use multiple entries by separating with a comma:

192.168.1.161, 192.168.2., 10.10.220.

The last example allows connections from only machine 161 from the 192.168.1.* network, and all computers of the 192.168.2.* and 10.10.220.* networks.

CLASS OUTPUT

For the regular user, the output of the example GUI is normal. That is, it sends headers and a complete HTML page. However, for those that would like to have a cutom GUI, there is an option for you as well.

In the config file for the class, there is a flag set as: $PSA_DISPLAY_OUTPUT=TRUE; If you set this flag to FALSE, the example GUI will not output any headers or HTML, but will store the "content" in a table inside the $PSA_OUTPUT variable.

Using this option, you can have your login forms appear anywhere you want in your design, or even make a custom GUI without having to worry about all the coding that goes into displaying the data.

CLASS API (Starting with version 3.0)

Most functions now return boolean TRUE or FALSE as a value and set the new ERROR string in the class. The class constructor now takes arrays as arguments rather than a long list of single variables. Detailed information on specific function APIs can be found in the comments for each function is class.phpSecurityadmin.php. This should be the standardized API for the class. There may be some exceptions to the new API (like the getProfiles function) which return specific values.

GETTING HELP

See the forums for phpSecurityAdm located at http://sourceforge.net/forum/?group_id=67410 to request help, request features, report bugs, or just leave general comments on the class.

TODO List

Ability for User to request a new password for one that is lost/forgotten.
Add functionality to set read, write, or no access to pages.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. (Found in the LICENSE file.)

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA