Introduction

This user guide is still in a developement phase. Be patient and you will get out more!
In the meanwhile check out the forum!

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

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

Installation

Requirements:

• CodeIgniter 1.5.X
• MySQL 4.0 or higher

Follow these steps to install the FreakAuth_light library:

1. download FreakAuth_light
2. unzip FreakAuth.zip in a local folder
3. copy the files INSIDE the folder FreakAuth_light_1.0.X in your CodeIgniter installation directory
4. check out the config_demo.php, autoload_demo.php, routes_demo.php in your in your system/application/config folder. Backup your
   - system/application/config.php
   - system/application/autoload.php
   - system/application/routes.php
   
   Rename the _demo.php files to config.php, autoload.php and routes.php and you are done!
   
   
5. create the necessary tables in the database: import FreakAuth_DB.sql
6. try to access http://www.YOUR_WEBSITE.com/index.php/installer
   
   In this page you wil check if you installed the DB tables properly and if you
   set all necessary configurations.
   
   You will also be able to insert the system superadmin.
7. add your encryption key in your system/application/config/config.php
   (read "Setting Your Key" at http://www.codeigniter.com/user_guide/libraries/encryption.html)
8. In order to make CAPTCHA functionality to work properly make your folders www.YOUR_WEBSITE.com/tmp
   writable (chmod (777)).

If you see a strange output, make sure you have :
- configured your php.ini file with short_open_tag = On. This is needed because in the templates we have used short tags for echo like <?=
- set the base_url properly in application/config/config.php

 

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
i.e superadmin (value 1) has more rights than admin (value 2)
i.e editor (value 3) has more rights than user (value 100)

You can also set usergroups with the same hierarchy
i.e.
...
'editor' => 4,
'gallery_manager' => 4
...


WARNING do not set custom groups with value 1 or 2

Securing your application

Use this in your controllers

//--------------------------------
$this->freakauth_light->check();
//--------------------------------

Method used to restrict acess to controllers or methods of controllers to the specified category of users
it requires 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

example usage in a controller

$this->freakauth_light->check() //this restricts acess to registered users and user-groups higher in the hierarchy (i.e. admin, superadmin) $this->freakauth_light->check('admin') //this restricts acess to 'admin' and user-groups higher in the hierarchy (i.e. superadmin) $this->freakauth_light->check('admin', true) //this restricts acess to 'admin' ONLY
You can use the method check() 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

If you are to lazy to look at that file create a controller as follows:

<?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();
       }
       
       ##### index #####
  function index()
  {
 
  echo '<h1>You can view this message because you logged in and are at least an user!</h1>';
  }
   
}
?>

CASE 2: just lock a particular controller method

<?php
class Example extends Controller  {

       function Example()
       {
            parent::Controller();
                         
       }
       
       ##### index #####
  function index()
   {
 
  echo '<h1>You can view this message because it\'s free for everybody!</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 an user!</h1>';
  }
   
}
?>

 

Structuring Controllers (Views) logic depending on role (user group)

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

Each method as a helper counterpart.

The methods are:

1. isValidUser()
2. isAdmin()
3. isSuperAdmin()
4. belongsToGroup()

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

• $this->freakauth_light->isValidUser()

Checksif 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, otherwise false

• $this->freakauth_light->isSuperAdmin()

Checks if an administrator has superadmin credentials, returns false if FreakAuth system is not activated, returns true if superadmin, otherwise false

• $this->freakauth_light->belongsToGroup()

Method used to check if a logged in member belongs to the custom role (group)

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

In the above examples change $this->freakauth_light->belongsToGroup() to belongsToGroup() if you prefer to use the corresponding helper function

Views: how to customise them

Coming soon...

e-mail content: customisation

Have a look at the files in the application/views/FreakAuth_light/email and change them as you like.

 

Internationalisation

The language file is in:

system/languages/english/freakauth_lang.php

Read here for further infos: Creating Language Files

Advanced features: CAPTCHA

If you don't see the CAPTCHA images it is because in order to make CAPTCHA functionality to work properly you must make your folders www.YOUR_WEBSITE.com/tmp
writable (chmod (777)). Do the same with www.YOUR_WEBSITE.com/public and subfolders

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 decide wheter to use upper case letters, letters&numbers, or letters&numbers&special characters in the generated image.

CAPTCHA images are stored in root_directory/tmp .

CAPTCHA images get deleted every time a new captcha get displayed if the CAPTCHA images are older than 10 minutes.

Advanced features: ASSETS MANAGEMENT

Read this tutorial:

• FreakAuth_light 1.1 new assets management

Advanced features: EXTENDING CORE CLASSES

Read this tutorial:

• Extending FreakAuth

Tip & Tricks

How to get logged in users data

It is possible to get the following data from the user session with the following methos:

• user id: $this->db_session->userdata('id');
• username: $this->db_session->userdata('user_name');
• user role: $this->db_session->userdata('role');

Custom UserProfile and building a user account controller

• Tutorial => FreakAuth_light: custom userprofile - PART 1
• Tutorial => FreakAuth_light: custom userprofile - PART 2

How to re-route the auth controller or split it into multiple controllers

• Tutorial => I don't like that "auth.php" controller!

Using jQuery along with other Javascript frameworks

jQuery is needed by FreakAuth in order to fade out the flash messages. If you are using other Javascript frameworks (Prototype, Script.aculo.us, Mootools) along with jQuery, you might experience some conflicts.

To avoid these conflicts try this:

• open public/js/flash.js
• substitute its content with the following

jQuery.noConflict();
jQuery(document).ready(function($) {
    $("#flashMessage").show("normal",
        function()
        {
            $("#flashMessage").fadeOut(10000);
        }
        );
});

For further documentation about this issue have a look at:

• Using jQuery with Other Libraries

How to use FreakAuth_light with mod_rewrite

1. create a file called .htaccess with the following content
<IfModule mod_rewrite.c>
RewriteEngine on
RewriteCond $1 !^(index\.php|public|tmp|robots\.txt)
RewriteRule ^(.*)$ index.php/$1 [L]
</IfModule>

2. drop the .htaccess file in your root directory
3. open your system/application/config.php and make sure that $config['index_page']
   looks like:
$config['index_page'] = "";