iCreativa User Authentication Suite.
Installation Guide.

This guide will help you getting Auth Suite up and running in your web server and integrate it with your existing applications.

Integrating Auth in your application.

Auth Suite was designed as a component that you can drop in your application in a matter of minutes, so you can continue working on other things. Following you'll find three diferent ways of integrate Auth Suite with your application depending on your needs.

Simple User Authentication.

By now probably you have defined your own "users" table and probably you already have some users accounts there. No problem, you can customize the way Auth Suite access your database easly. For example, supose you have the folowing users table:

CREATE TABLE accounts (
    account_key INT NOT NULL AUTO_INCREMENT,

    login CHAR(32) NOT NULL,
    pass CHAR(32) NOT NULL,
    email VARCHAR(255) NOT NULL,
    fullname VARCHAR(255) NOT NULL,

    UNIQUE (login),
    UNIQUE (email),
    PRIMARY KEY(account_key)
);

The fields account_key, login and pass are the only requirement for the users table. Since this aren't the default settings for Auth Suite, we need to configure the class to use this table. We can do this creating an array and passing it to the constructor.

$options = array(
    'usersTable' => 'accounts',
    'userIdField' => 'account_key',
    'usernameField' => 'login',
    'passwordField' => 'pass'
);

$auth = new Auth($options);

Protecting a script.

After that, to protect a script you write this code in the first lines:

require_once('adodb.inc.php');
require_once('auth.php');

$auth = new Auth($myAppSettings);
$auth->forceLogin();

That code forces the user to identify him self and check if the user belongs to the "admins" AND the "editors" groups. requireGroups() requires that the user belongs to each group that is passed. If you need to grant access to users that belong to "admins" OR "editors" then use the requireAtLeast() method.

Creating a Login form.

Usualy you don't need to create a login.php script because every protected script presents a login form but if you want to... Create a new script and write this:

require_once('adodb.inc.php');
require_once('auth.php');

$auth = new Auth(array('force_redirect' => true, 'redirect' => 'index.php'));
$auth->forceLogin();

That's all you have to do and, by the way, when the user has authenticated it'll be redirected to index.php. Neat he?

Logout a user.

A logout.php script is as easy as:

require_once('adodb.inc.php');
require_once('auth.php');

$auth = new Auth();
$auth->logout();

Accessing User's preferences.

Now, you don't need to restrict access to your users to use Auth. Have you seen Amazon.com? That site customizes their homepage according user's preferences. You can do that:

require_once('adodb.inc.php');
require_once('auth.php');

$auth = new Auth($myAppSettings);
$auth->startSession();

After those lines, if the user has identified before, you can access his information using the $auth->user property. For example if you have a "theme" field in your users table then with this code your site will have user-defined themes:

$theme = $auth->user['theme'];
include("themes/$theme/header.php");

But, How do I know if a user has been authenticaded? There is a property in the class that you can check:

if($auth->isIdentified) {
    // show customized content here.
} else {
    // default content for all users.
}

This is a read-only property and you shouldn't modify this in any form.

Now you should be wondering: How do I change those horrible login forms. Well if you tell them horrible I wont tell you!. I've spend... well like five minutes designing them. Ok, they are in the "auth.callback.php" file. There you change everything the user sees.

Installing the examples.

Included in the distribution are 3 examples that you can use to learn the concepts used in Auth Suite. In every directory of each example you can find a MySQL.sql file that you can use to recreate the database. You can issue the following command:

mysql --database=test --user=root < MySQL.sql

You will also need to update the file conf.php to update the database connection parameters. Change the following lines to the apropiate values.

$cnf->dbdriver = 'mysql';
$cnf->hostname = 'localhost';
$cnf->username = 'root';
$cnf->password = '';
$cnf->database = 'test';

Don't forguet to install ADOdb some where accessible by the script. Finally point your browser to the directory where you unpack Auth Suite.