Wiki Navigation

back to main page

Documentation (draft and notes)

Features

The FreakAuth_light© (read it Freak OUT!) package includes:

a library to secure your application that performs
- user login/logout
- user registration
- reset password if forgotten
- change password
- website reserved areas locking
a backend administration application to
- manage users
- manage administrators

Requirements

CodeIgniter 1.5.X
MySQL 4.0 or higher

Upgrade

see FAL_Upgrade

Installation

on a fresh install of Code Igniter

uncompress the release files in a temp folder
directly rename _demo.php files (remove the _demo suffix)
copy the files and directories, each one at the right place
please remember to set your $config['base_url'] to 'http://your_server/your_ci_folder/' to catch the public files (css, js...)
create a database, and set your database configuration correctly (see CI's user guide)
import the FreakAuth_DB.sql script in it

on an existing Code Igniter installation

uncompress the release files in a temp folder
copy the files and directories, each one at the right place (you can forget about the _demo.php files)

add some items to your autoload arrays (see CI's user guide)

$autoload['libraries'] = array('database', 'Freakauth_light');
$autoload['helper'] = array('url', 'form', 'array', 'freakauth_light', 'html');
$autoload['config'] = array('freakauth_light');

check the sessions config (our piece of advice):

$config['sess_cookie_name']        = 'FreakAuth';
$config['sess_expiration']         = 7200;
$config['sess_encrypt_cookie']     = TRUE;
$config['sess_use_database']       = TRUE;
$config['sess_table_name']         = 'ci_sessions';
$config['sess_match_ip']           = FALSE;
$config['sess_match_useragent']    = FALSE;

import the FreakAuth_DB.sql script in your database

in any case

set your encryption key ($config['encryption_key'] = "whatever2007"; in CI's main config file: see CI's user guide)

change those two settings in FreakAuth config file:

$config['FAL_website_name'] = "YOUR_DOMAIN.com";
$config['FAL_user_support'] = 'you@your-email.com';

In order to make CAPTCHA functionality to work properly make your /tmp folder writable (chmod /path/to/tmp 777).

when done with files and config stuff

Point a browser to reach our installer (maybe http://your_server/your_ci_folder/index.php/installer), you'll be given an installation check and, if everything is ok, a form for the first user (will be a superadmin).

Understanding the roles and their hierarchy

FreakAuth_light is based on 4 main default roles:

superadmin	has permissions on everything and can also create other admin
admin	you can choose what to let him manage
user	it is a registered user, and you can decide to give it rights to access some specific areas (controllers) of your application
guest	basically a visitor (not registered to the website)

You can add your custom roles in application/config/freakauth_light.php. Look for this variable: $config['FAL_roles'].

Default configuration:

$config['FAL_roles'] = array(
//don't change the two following lines//
'superadmin' => 1,
'admin' => 2,
//end don't change

//add your custom roles here
//'editor' => 3,
//'gallery_manager' => 4
//--------------------------

//don't change the following line
'user' => 100,
);

Roles work by inheritance.

This means that the lower the value of the role, the higher in the hierarchy

superadmin (value 1) has more rights than admin (value 2)
editor (value 3) has more rights than user (value 100).

You can also set usergroups with the same hierarchy:

...
'editor' => 4,
'gallery_manager' => 4
...

WARNING: do not set custom groups with value 1 or 2 !!!

Securing your application

You will use the check(...)} function in your controllers.

This function is used to restrict access to controllers or methods of controllers to the specified category of users.

It has 2 optional parameters.

the first parameter specifies the user group i.e. ('admin')
the second parameter specifies whether the area is reserved ONLY to that group (true) or if it is accessible by groups higher in the hierarchy (false: default)

example usage in a controller:

//this restricts acess to registered users and user-groups higher in the hierarchy (i.e. admin, superadmin)
$this->freakauth_light->check();

//this restricts acess to 'admin' and user-groups higher in the hierarchy (i.e. superadmin)
$this->freakauth_light->check('admin');

//this restricts access to 'admin' ONLY
$this->freakauth_light->check('admin', true);

You can use the check() function both in the Class contructor or in the single methods of your class.

It depends on you. If you wanna protect an entire class put it in the constructor, otherwise in the single methods that you want to protect

CASE 1: lock an entire area of the website to users (you baically secure a frontend controller )

For this purpose have a look at the file application/controllers/example.php:

<?php
class Example extends Controller {

    function Example()
    {
        parent::Controller();

        //thanks to this line of code you can protect this controller
        //and reserve access to logged in users
        $this->freakauth_light->check();
    }
       
    function index()
    {
        echo '<h1>You can view this message because you logged in and are at least a user!</h1>';
    }
}
?>

CASE 2: just lock a particular controller method

<?php
class Example extends Controller {

    function Example()
    {
        parent::Controller();

        //thanks to this line of code you can protect this controller
        //and reserve access to logged in users
        $this->freakauth_light->check();
    }
       
    function index()
    {
        echo '<h1>You can view this message because you logged in and are at least a user!</h1>';
    }
  
    function test()
    {
        //thanks to this line of code you can protect this controller
        //and reserve access to logged in users
        $this->freakauth_light->check();
        echo '<h1>You can view this message because you logged in and are at least a user!</h1>';
    }
}
?>

Structuring Controllers and Views logic depending on roles

There are 4 methods in the FreakAuth_light library to perform this operation.

Each method as a helper counterpart.

The methods are:

isValidUser()
isAdmin()
isSuperAdmin()
belongsToGroup()

The first 3 of these methods are specific, while the forth is more general:

$this->freakauth_light->isValidUser()	Checks if a user is logged in, returns false if FreakAuth system is not activated, returns true if a valid user is logged, false otherwise.
$this->freakauth_light->isAdmin()	Checks if a user is an administrator, returns false if FreakAuth system is not activated, returns true if admin or superadmin, false otherwise.
$this->freakauth_light->isSuperAdmin()	Checks if an administrator has superadmin credentials, returns false if FreakAuth system is not activated, returns true if superadmin, false otherwise.
$this->freakauth_light->belongsToGroup()	Method used to check if a logged in member belongs to the custom role (group).

Let's detail the last one.

It requires 2 optional parameters.

The first parameter specifies the user groups as a comma separated string.
The second parameter specifies whether we want to check to the specified groups ONLY or for AT LEAST those group membership in the hierarchy (returns true also if the logged user belongs to a group higher in the hierarchy).

Example usage in a controller:

$this->freakauth_light->belongsToGroup()
//returns true if the visitor is logged in and he is AT LEAST an user

$this->freakauth_light->belongsToGroup('user,editor')
//returns true if the visitor is logged in and he is AT LEAST an user or an editor
//(therefore it returns true also if he belongs to user-groups higher in the hierarchy (i.e. superadmin)

$this->freakauth_light->belongsToGroup('admin', true)
//returns true if the visitor is logged in and is an 'admin' ONLY

change to belongsToGroup() if you use the helper

Customise views and emails

You can create another template directory and tell FAL to use it. For this you just need to change this line in the config file.

$config['FAL_template_dir'] = 'the_name_of_your_template_dir_in_the_views_dir/';

Please add the trailing slash.

The trick is to copy the original one, and then change what doesn't suit your needs.

Internationalisation

The language file is freakauth_lang.php.

Please check on the LanguageFiles page if someone ever produced one for you.

As usual in Code Ingiter, you can easily create a file for your language (see the user guide). Then please update the LanguageFiles page.

CAPTCHAs

In order to make CAPTCHA functionality work properly, you must make your folders www.YOUR_WEBSITE.com/tmp writable (chmod 777).

Have a look at the file system/application/config/freakauth_light.php

In this file you can choose whether to use CAPTCHA for:

login
registration
change password

You can even decide whether to use upper case letters, letters & numbers, or letters & numbers & special characters in the generated image.

CAPTCHA images are stored in root_directory/tmp .

A CAPTCHA image is deleted every time a new CAPTCHA is displayed and if the CAPTCHA image is older than 10 minutes.

Tip & Tricks

How to get users data

Each of these functions has also an helper counterpart. They are used in the example controller.

the user who is connected

It is possible to get the following data from the user session with the following methods.

username: getUserName()
other info: getUserProperty($prop) where $prop can be one of those: 'id', 'user_name', 'country_id', 'email', 'role', 'last_visit', 'created', 'modified' (see the login() function in the lib where the session data is set).

other users

You can also get some data in the database, using getUserPropertyFromId($id, $prop), where $id is the id of the concerned user.