Auth Class

MeNeedz's robust Auth Class supports the following features:

Authentication of a user
Does not require certain database layout or a database at all
Supports salting
Choose the encryption
Use what ever identifier you want, not restricted to username only
Restrict access to a certain user group

Setup

Database

If you want to use the database for authorization, then you need to set up the tables using this or a similar script:

--
-- Table `group`
--

CREATE TABLE IF NOT EXISTS `group` (
  `group_id` varchar(20) NOT NULL,
  `group_level` tinyint(4) NOT NULL,
  PRIMARY KEY  (`group_id`)
) ENGINE=MyISAM DEFAULT CHARSET=utf8;

-- --------------------------------------------------------

--
-- Table `member`
--

CREATE TABLE IF NOT EXISTS `member` (
  `member_id` smallint(6) NOT NULL auto_increment,
  `group_id` varchar(20) NOT NULL,
  `user_id` smallint(6) NOT NULL,
  PRIMARY KEY  (`member_id`)
) ENGINE=MyISAM DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;

-- --------------------------------------------------------

--
-- Table `right`
--

CREATE TABLE IF NOT EXISTS `right` (
  `right_id` smallint(6) NOT NULL auto_increment,
  `group_id` varchar(20) NOT NULL,
  `controller` varchar(50) NOT NULL,
  `function` varchar(50) NOT NULL,
  `access_right` varchar(10) NOT NULL,
  PRIMARY KEY  (`right_id`)
) ENGINE=MyISAM DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;

-- --------------------------------------------------------

--
-- Table `user`
--

CREATE TABLE IF NOT EXISTS `user` (
  `user_id` smallint(6) NOT NULL auto_increment,
  `user_name` varchar(30) NOT NULL,
  `user_password` varchar(40) NOT NULL,
  `user_salt` varchar(40) NOT NULL,
  `group_id` varchar(20) NOT NULL,
  `user_email` varchar(100) NOT NULL,
  PRIMARY KEY  (`user_id`)
) ENGINE=MyISAM DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;

Session

In order to use this library you need to load the session library and have it properly set up. You can either do this by adding the session library to your autoload config or by adding this to your controller:


$this->load->library('session');

Authenticate User

Authenticating a user is pretty simple and requires only a little amount of code.

Here is a basic example demonstrating how you might create a simple login.

Controller

<?php

class Welcome extends Controller {

	function Welcome()
	{
		parent::Controller();
		$this->load->helper('url');
	}

	function index()
	{
		$this->login();
	}

	function login()
	{
		if($this->auth->is_logged_in())
		{
			echo "logged in";
		}
		else
		{
			$login = $this->auth->login();
			if($login)
			{
				redirect('welcome/login');
			}
			else
			{
				$this->load->view('login');
			}
		}
	}

	function logout()
	{
		$this->auth->logout();
		redirect('welcome/login');
	}

	function access_test()
	{
		if($this->auth->has_access('user'))
		{
			echo "ok";
		}
		else
		{
			echo "not ok";
		}
	}
}

/* End of file welcome.php */
/* Location: ./system/application/controllers/welcome.php */

The Form

Using a text editor, create a form called login.php. In it, place this code and save it to your applications/views/ folder:

<html>
<head>
<title>Welcome to CodeIgniter</title>

<body>
<?
	echo form_open('welcome/login');
	$data = array(
	              'name'        => 'user_name',
	              'id'          => 'user_name',
	              'maxlength'   => '50',
	              'size'        => '50'
	            );
	echo form_input($data);
?>
<br/>
<?
	$data = array(
	              'name'        => 'user_password',
	              'id'          => 'user_password',
	              'maxlength'   => '50',
	              'size'        => '50'
	            );
	echo form_password($data);
?>
<br/>
<?
	echo form_submit('mysubmit', 'Submit Post!');
	echo form_close();
?>
</body>
</html>

By accessing 'welcome/login' you can login using the given form. By accessing 'welcome/logout' you can logout and return to the login form. By accessing 'welcome/access_test' you can check if your user's group level is higher/equals the level of the group 'user'.

Note:: This example requires a properly set up auth library with database access. See below on how to do so. Additionally to that the session library has to be loaded.

Registering User

Registering a user is pretty simple and requires only a little amount of code.

Here is a basic example demonstrating how you might create a simple registration form.

Controller

<?php

class Welcome extends Controller {

	function Welcome()
	{
		parent::Controller();
	}

	function index()
	{
		$this->register();
	}

	function register()
    {
        if($this->auth->is_logged_in())
        {
            echo "logged in";
        }
        else
        {
            $register = $this->auth->register();
            if($register)
            {
                redirect('welcome/register');
            }
            else
            {
                $this->load->view('register');
            }
        }
    }
}

/* End of file welcome.php */
/* Location: ./system/application/controllers/welcome.php */

The Form

Using a text editor, create a form called register.php. In it, place this code and save it to your applications/views/ folder:

<html>
<head>
<title>Welcome to CodeIgniter</title>

<body>
<?
	echo form_open('welcome/register');
	$data = array(
	              'name'        => 'user_name',
	              'id'          => 'user_name',
	              'maxlength'   => '50',
	              'size'        => '50'
	            );
	echo "name: ".form_input($data);
?>
<br/>
<?
	$data = array(
	              'name'        => 'user_password',
	              'id'          => 'user_password',
	              'maxlength'   => '50',
	              'size'        => '50'
	            );
	echo "pass: ".form_password($data);
?>
<br/>
<?
	$data = array(
	              'name'        => 'user_email',
	              'id'          => 'user_email',
	              'maxlength'   => '50',
	              'size'        => '50'
	            );
	echo "email: ".form_input($data);
?>
<br/>
<?

	echo form_hidden('user_id', 123345);
	echo form_submit('mysubmit', 'Submit Post!');
	echo form_close();
?>
</body>
</html>

By accessing 'welcome/register' you can register a new user using the given form.

Note:: This example requires a properly set up auth library with database access. See below on how to do so. Additionally to that the session library has to be loaded.

Setting Auth Preferences

There are 14 different preferences available to tailor how your authentication should work. You can either set them manually as described here, or automatically via preferences stored in your config file, described below:

Preferences are set by passing an array of preference values to the auth initialize function. Here is an example of how you might set some preferences:

	$config['input_config'] = array(
		'login' => 	array(
				'identifier' => 'user_name', //name of the input that holds the identifier used for login
				'password' => 'user_password', //name of the input that holds the password used for login
				'remember' => 'remember_me' //name of the checkbox that says wether to remember the user or not
			),
		'register' => 	array(
				'identifier' => 'user_name', //name of the input that holds the identifier used for registration
				'password' => 'user_password', //name of the input that holds the password used for registration
				'email' => 'user_email' //name of the input that holds the email used for registration (only needed if use_email is set to TRUE)
				'primary_key' => 'user_id' //name of the primary key field in the user table
			)
	);
	$config['use_database'] = TRUE;
	$this->auth->initialize($config);

Note: All preferences have default values that will be used if you do not set them.

Setting Auth Preferences in a Config File

If you prefer not to set preferences using the above method, you can instead put them into a config file. Simply create a new file called the auth.php, add the $config array in that file. Then save the file at in your application/config folder and it will be used automatically. You will NOT need to use the $this->auth->initialize() function if you save your preferences in a config file.

Auth Preferences

The following is a list of all the preferences that can be set when using authentication.

Preference	Default Value	Options	Description
use_database	TRUE	TRUE or FALSE (boolean)	Use a database for authentication or not.
database_config	See below	Array settings for database usage	An array with all settings that are needed to use the database to auth a user.
non_database_user_identifier	No Default	None	The identifier that will be used if you don't use a database for authentication.
non_database_user_password	No Default	None	The password that will be used if you don't use a database for authentication.
use_encryption	TRUE	TRUE or FALSE (boolean)	Use encryption for authentication or not.
encryption_method	md5	md5 or sha/sha1	The encryption method that will be used for authentication.
encryption_order	%salt%.%password%	%salt%, %password% combined by '.'	The way the password is encrypted with salting.
use_remember_me	FALSE	TRUE or FALSE (boolean)	Use 'remember me' function or not (changes expiration time of session)
use_email	FALSE	TRUE or FALSE (boolean)	Use email when registering user (should be used if email is not the identifier)
user_standard_group	user	name of an existing group	The standard group that should be set for new users
input_config	See below	Array settings for input usage	An array with all settings for inputs needed to auth a user.
use_database_user_groups	TRUE	TRUE or FALSE (boolean)	Get groups from database or from config.
use_database_rights	TRUE	TRUE or FALSE (boolean)	Get rights from database or from config.
password_length	6	Numeric value	The list of the generated passwords.
non_database_user_groups	array('user' => '1', 'moderator' => '10', 'admin' => '100')	Array of rights	A list of all access rights.
non_database_user_group_rights	array('access_rights' => 'r', 'admin' => array('access_rights' => 'rwd'), 'moderator' => array('access_rights' => 'rw'))	Array of rights and their level	A list of all groups a user can be part of and their access level.

database_config

A more detailed explanation on the database preferences needed

	$config['database_config'] = array(
		'user_table' => 	array(
				'name' => 'user', //name of the user table
				'user_primary_key_column' => 'user_id', //name of the column that holds the primary key thats referenced in other tables
				'user_primary_key_column_is_auto_increment' => TRUE, //is the primary key column auto increment or has it to be set manually during registration
				'user_identifier_column' => 'user_name', //column with the identfier used for login, can be the same as primary key
				'user_password_column' => 'user_password', //column with the password used for login
				'user_salt_column' => 'user_salt', //column with the salt used for login
				'group_foreign_key_column' => 'group_id' //column with the group of the user (only used when user can't be member of multiple groups
			),
		'group_table' =>	array(
				'name' => 'group', //name of the group table
				'group_primary_key_column' => 'group_id', //name of the column that holds the primary key thats referenced in other tables
				'group_level_column' => 'group_level' //name of the column with the access level of the group
			),
		'right_table' =>	array(
				'name' => 'right', //name of the right table
				'group_foreign_key_column' => 'group_id', //column with the group
				'controller_column' => 'controller', //column with the controller
				'function_column' => 'function', //column with the function
				'access_right_column' => 'access_right' //column with the granted rights
			),
		'member_table' => 	array(
				'name' => 'member', //name of the table
				'group_foreign_key_column' => 'group_id', //column with the group
				'user_foreign_key_column' => 'user_id' //column with the user
			)
	);

input_config

A more detailed explanation on the input preferences needed

	$config['input_config'] = array(
		'login' => 	array(
				'identifier' => 'user_name', //name of the input that holds the identifier used for login
				'password' => 'user_password', //name of the input that holds the password used for login
				'remember' => 'remember_me' //name of the checkbox that says wether to remember the user or not
			),
		'register' => 	array(
				'identifier' => 'user_name', //name of the input that holds the identifier used for registration
				'password' => 'user_password', //name of the input that holds the password used for registration
				'email' => 'user_email' //name of the input that holds the email used for registration (only needed if use_email is set to TRUE),
				'primary_key' => 'user_id' //value of the primary key column in the user table, only needed if it is not set to auto increment
			)
	);

Auth Function Reference

$this->auth->login()

Trys to login the user using the values of the submitted form:

$this->auth->login(); Returns TRUE on success and FALSE on failure.

$this->auth->logout()

Logout of the currently logged in user:

$this->auth->logout(); Returns TRUE.

$this->auth->is_logged_in()

Checks if the current user is logged in

$this->auth->is_logged_in(); Returns TRUE if logged and FALSE of not.

$this->auth->get_user()

Get the info from the database of the currently logged in user:

$this->auth->get_user(); Returns an array on success and FALSE on failure. If a database is being used it selects all data from the given user table for the current user. If no database is being used it returns and array holding the value of option "non_database_user_identifier".

$this->auth->has_access()

Compares the given group with the group of the logged in user:

$this->auth->has_access('admin'); Returns TRUE if user has access and FALSE if he does not. If no group is given TRUE is returned. If the user is not logged in FALSE is returned. If either the given group or the group of the user is invalid FALSE is returned. The access level of the given group and the group of the user are being compared and if the level of the group of the user is higher/equals the one of the given group than TRUE is returned, else FALSE.

$this->auth->has_right()

Checks if any of the groups the user is member of has the required right:

$this->auth->has_access('r'); Returns TRUE if user has the right and FALSE if he does not. If no right is given TRUE is returned. If the user is not logged in FALSE is returned. Access rights can be configured in general for all groups in all controllers and can further refined per group, per controller and even per function. See below for further details.

$this->auth->register()

Trys to register a new user using the values of the submitted form:

$this->auth->register(); Returns TRUE on success and FALSE on failure.

$this->auth->change_password()

Changes the password of the given user:

$this->auth->change_password('test', 'test123'); Returns the new password on success and FALSE on failure. The first parameter is the identifier of the user. The second parameter is the new password, if it's left empty a new password will be generated using the password helper that's included in the download file.

How to configure user groups

Without database

Define your groups in the config file similar to the below example.

$config['non_database_user_group_rights'] = array(	'user' => '1',
										'moderator' => '10',
										'admin' => '100');

Using this array your groups would have the following access levels:
Group 'user' has access level 1, group 'moderator' has access level 10 and group 'admin' has access level 100.

Note: A user in a group has access to every page where the access level of the required group is lower/equals the access level of this group. E.g. a user in the 'moderator' group has access to all pages that require 'user' or 'moderator' group, but not those that require 'admin' group, but 'admin' group would have access to every page.

With database

Set up a table according to your settings. In case you use the default values you can use the statement from the setup section:
You have to insert a row in your group table for every group you want to have. Group primary key column holds the identifier of the group and group level column holds the access level of the group. You have to make sure, that whatever group your user is member of exists in the group table.

User is member in only one group

If you set the option 'use_database_multi_user_groups' to FALSE, then the group foreign key column in the user table is used to determine what group the user is in and that value is used for checking the access level.

User is member in multiple group

If you set the option 'use_database_multi_user_groups' to TRUE, then you have to make sure that you have a properly set up member table (e.g. using the statement from the setup section). The library selects all rows in the member table where the user foreign key column in the member table equals the user primary key column in the user table and checks for each row thats found if the group the user is member in has the required access level.

Note: You can either get both infos (membership and groups) from the database or only use the database for membership management and use the non database user groups array for your groups by putting "$config['use_database_user_groups'] = FALSE;" in your config file.

How to configure user rights

Without database

Set your rights in the config file similar to the below example.

$config['non_database_user_group_rights'] = array(	'access_rights' = 'r',
										'admin' = array(	'access_rights' = 'rwd'),
										'moderator' = array(	'access_rights' = 'rw',
														'welcome' => array(	'access_rights' => 'r',
																		'test_function' => 'rwd')));

Using this array your user groups would have the following access rights:
All groups would have right 'r' (in my case that would be 'read') in all controllers and all functions.
Group 'admin' would have right 'rwd' (in my case that would be 'read write delete') in all controllers and all functions.
Group 'moderator' would have right 'rw' (in my case that would be 'read write') in all controllers and all functions but in controller 'welcome' it would only have right 'r' except function 'test_function' where it would have right 'rwd'.

With database

Set up a table according to your settings. In case you use the default values you can use the statement from the setup section:
To configure rights in general for all groups in all controllers and functions insert a row empty group_id, controller and function column and only fill the right column with the right you want to give all groups in general, e.g. 'r'.

To configure rights for a specific group for all controllers and function insert a row with empty controller and function column and only fill the group_id column with the name/id of your group and the right column with the right you wannt to give to this group, e.g. 'admin' and 'rwd'.

To configure rights for a specific group for a specific controller do the same as before and additionally fill the controller column with the name of your controller, e.g. 'admin', 'rwd', 'welcome'.

To configure rights for a specific group for a specific controller and a specific function in that controller do the same as before and additionally fill the function column with the name of the function, e.e. 'admin', 'rwd', 'welcome', 'test_function'.

Note: You can call your rights whatever you want, just make sure they are unique and that word for a right may not be contained in the name for another right. I just figured that 'r' for read, 'w' for write and 'd' for delete would be enough to begin with.

MeNeedz Auth User Guide Version 1.7

Auth Class

Setup

Database

Session

Authenticate User

Controller

The Form

Registering User

Controller

The Form

Setting Auth Preferences

Setting Auth Preferences in a Config File

Auth Preferences

database_config

input_config

Auth Function Reference

$this->auth->login()

$this->auth->logout()

$this->auth->is_logged_in()

$this->auth->get_user()

$this->auth->has_access()

$this->auth->has_right()

$this->auth->register()

$this->auth->change_password()

How to configure user groups

Without database

With database

User is member in only one group

User is member in multiple group

How to configure user rights

Without database

With database