HOW TO INSTALL Authenticator DEMO ------------------------------- Contents: 1. What is Authenticator 2. What the demo does 3. Installing the demo 4. License 5. Author 6. Version 1. Authenticator is a PHP class that provides low-level API for users registration, login and credentials management. Most typically, you will integrate registration in admin control panels, credentials management in users profile pages and login functionality in all protected areas across your web application. 2. This demo provides two sample PHP classes, ./AuthenticatorDemo.php and ./ProtectedContent.php. Together, they mimic an actual web application containing two sections. One administrative section, that provides authentication, password recovery and user registration functionality; and one content section, that only grants access for authenticated users. These two classes do not showcase the full set of features the Authenticator class provides; for instance, no super-user tasks are performed. Consult the ./Authenticator.html file for the full documentation on these and other features. 3. a) E-mail server setup It is essential that a working Mail Transport Agent is available to PHP for sending e-mails. This demo will need to send confirmation keys to you by e-mail. Please ensure that you have a working e-mail server on the machine you run this demo on, before proceeding. Installing an SMTP server is beyond the scope of this tutorial, but these links could come in handy: - http://www.pmail.com/overviews/ovw_mercwin.htm (for installing Mercury under Windows); - http://www.postfix.org/ (for installing Postfix under Unix). b) ParamsProxy setup If you have already setup ParamsProxy on this machine, you may skip this step, in whole or in part. The Authenticator class makes use of ParamsProxy in order to read its parameters from a configuration file. Before being able to use Authenticator, you must setup a configuration folder. All configuration files will live in here, each placed under a sub-folder with the same name as the name of the class to be configured. Under Unix, create this folder: /home/MyConfig Under Windows, create this folder: C:\MyConfig Open the file ./ParamsProxy_config.xml and fill in the path of the folder just created, e.g.: <value>/home/MyConfig/</value> c) Database access file The Authenticator class makes use of DbProxy in order to execute queries on your database. You'll need to place its database access file in the proper location before Authenticator can communicate with the database. i. change into /home/MyConfig (on Unix) or C:\MyConfig (on Windows); ii. create sub-folder Authenticator iii. change into just created sub-folder iv. copy provided file ./dbAccess.xml as /home/MyConfig/Authenticator/dbAccess.xml (on Unix) or as C:\MyConfig\Authenticator\dbAccess.xml (on Windows) d) Database setup You need to provide a database to host the tables needed by this demo. The mysql session transcript below shows you how to create a database called "AuthenticatorDemo", having a user named "test", authenticated by password "1234". You may, of course, use a visual tool, such as PHPMyAdmin instead of the mysql terminal; or you could use an already existing database althogether. If you do use an existing database, you must update its connection data inside your database access file. mysql> mysql -u root -p Enter password: **** Welcome to the MySQL monitor. Commands end with ; or \g. Your MySQL connection id is 2 Server version: 5.1.33-community MySQL Community Server (GPL) Type 'help;' or '\h' for help. Type '\c' to clear the buffer. mysql> create database AuthenticatorDemo; Query OK, 1 row affected (0.02 sec) mysql> grant all on AuthenticatorDemo.* to firstname.lastname@example.org identified by '1234'; Query OK, 0 rows affected (0.03 sec) mysql> quit; Bye e) Configuration file You'll also need to place Authenticator's configuration file in the proper location: copy provided file ./config.xml as /home/MyConfig/Authenticator/config.xml (on Unix) or as C:\MyConfig\Authenticator\config.xml (on Windows). f) Cookies setup Cookies must be on in your browser, or you won't be able to sign in. g) Completing installation Point your browser to the AuthenticatorDemo.php file. If you have correctly installed Authenticator, you should see the Login Page. You may now sign up for an account and then sign in. You'll want to carefully observe the source code of both ./AuthenticatorDemo.php and ./ProtectedContent.php files, as they provide comprehensive comments. 4. Both this demo and the Authenticator class are licensed under the Creative Commons Attribution Share Alike license. You should have received a full copy of this license as ./Creative Commons Attribution Share Alike.txt. The full license body is also available online, at http://creativecommons.org/licenses/by-sa/3.0/legalcode. 5. The Authenticator class has been written and is being maintained by Claudius Tiberiu Iacob. You can reach me at email@example.com 6. You're holding version 1.5a (alpha) of Authenticator. Please note that API and functionality are subject to change in future versions. Send all bugs to firstname.lastname@example.org, thank you.