MeNeedz Auth User Guide Version 1.7


Auth Class

MeNeedz's robust Auth Class supports the following features:

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:

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

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:

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

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:

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:

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_databaseTRUETRUE or FALSE (boolean)Use a database for authentication or not.
database_configSee belowArray settings for database usageAn array with all settings that are needed to use the database to auth a user.
non_database_user_identifierNo DefaultNoneThe identifier that will be used if you don't use a database for authentication.
non_database_user_passwordNo DefaultNoneThe password that will be used if you don't use a database for authentication.
use_encryptionTRUETRUE or FALSE (boolean)Use encryption for authentication or not.
encryption_methodmd5md5 or sha/sha1The 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_meFALSETRUE or FALSE (boolean)Use 'remember me' function or not (changes expiration time of session)
use_emailFALSETRUE or FALSE (boolean)Use email when registering user (should be used if email is not the identifier)
user_standard_groupusername of an existing groupThe standard group that should be set for new users
input_configSee belowArray settings for input usageAn array with all settings for inputs needed to auth a user.
use_database_user_groupsTRUETRUE or FALSE (boolean)Get groups from database or from config.
use_database_rightsTRUETRUE or FALSE (boolean)Get rights from database or from config.
password_length6Numeric valueThe list of the generated passwords.
non_database_user_groupsarray('user' => '1', 'moderator' => '10', 'admin' => '100')Array of rightsA list of all access rights.
non_database_user_group_rightsarray('access_rights' => 'r', 'admin' => array('access_rights' => 'rwd'), 'moderator' => array('access_rights' => 'rw'))Array of rights and their levelA 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

input_config

A more detailed explanation on the input preferences needed

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. 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. 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.