File: HowToInstall.txt

 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 test@localhost 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 claudius.iacob@gmail.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 claudius.iacob@gmail.com, thank you.