ion auth docs.pdf

Author:Ben Edmunds

Ion Auth › Documentation

Ben EdmundsHOMECODEPOSTSABOUT

Documentation

Ion Auth

Ion Auth is a simple and lightweight authentication library for the CodeIgniterframework

Want to learn more? Or just support my work?

If you're reading this then you'll probably want to know that I'm writing a book onBuilding Secure PHP Apps. It's now available for early access on Leanpub:

Learn More / Buy

License

http://benedmunds.com/

http://benedmunds.com/ion_auth

http://buildsecurephpapps.com/



http://benedmunds.com/code.html

http://benedmunds.com/posts.html

http://benedmunds.com/about.html

Ion Auth is released under the Apache License v2.0. You can read the license here:http://www.apache.org/licenses/LICENSE-2.0

Installation

1. Download the latest version: http://github.com/benedmunds/CodeIgniter-Ion-Auth/zipball/2

2. Copy the files from this package to the correspoding folder in your applicationfolder. For example, copy Ion_auth/config/ion_auth.php tosystem/application/config/ion_auth.php.

3. Run the appropriate SQL file from the /sql directory.

The default login is:

Email: [email protected]

Password: password

Loading Ion Auth

You load Ion Auth just link any other library:

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

You can also autoload the library.

Configuration Options

Ion Auth is extremely configurable. The following configuration options areavailable:

$config['tables']['groups']

http://www.apache.org/licenses/LICENSE-2.0

http://github.com/benedmunds/CodeIgniter-Ion-Auth/zipball/2

$config['tables']['users']

$config['tables']['users_groups']

$config['tables']['login_attempts']

$config['site_title']

$config['admin_email']

$config['default_group']

$config['admin_group']

$config['join']['users']

$config['join']['groups']

$config['identity']

$config['min_password_length']

$config['max_password_length']

$config['email_activation']

$config['remember_users']

$config['user_expire']

$config['user_extend_on_login']

$config['email_type']

$config['email_templates']

$config['email_activate']

$config['email_forgot_password']

$config['email_forgot_password_complete']

$config['salt_length']

$config['store_salt']

$config['forgot_password_expiration']

$config['track_login_attempts']

$config['maximum_login_attempts']

$config['message_start_delimiter']

$config['message_end_delimiter']

$config['error_start_delimiter']

$config['error_end_delimiter']

Using Config File

To change configuration options simply edit the config/ion_auth.php file.

Config

Edit the ion_auth $config array as needed:

'tables['groups']' - The table name to use for the groups table. DEFAULT is'groups'.

'tables['users']' - The table name to use for the users table. DEFAULT is 'users'.

'tables['users_groups']' - The table name to use for the users groups table.DEFAULT is 'users_groups'.

'tables['login_attempts']' - The table name to use for the login attempts table.DEFAULT is 'login_attempts'.

'site_title' - The title of your site, used for email.

'admin_email' - Your administrator email address. DEFAULT is'[email protected]'.

'default_group' - Name of the default user group. DEFAULT is 'members'.

'admin_group' - Name of the admin group. DEFAULT is 'admin'.

'join['users'] ' - Users table column you want to join WITH. DEFAULT is 'user_id'.

'join['groups'] ' - Group table column you want to join WITH. DEFAULT is'group_id'.

'identity' - Column to use for uniquely identifing user/logging in/etc. Usualchoices are 'email' OR 'username'. You should add an index in the users table for

whatever you set this option to. DEFAULT is 'email'.

'min_password_length' - Minimum length of passwords. DEFAULT is '8'.

'max_password_length' - Maximum length of passwords. DEFAULT is '20'.

'email_activation' - TRUE or FALSE. Sets whether to require email activation ornot. DEFAULT is 'false'.

'remember_users' - TRUE or FALSE. Sets whether to enable 'remember me'functionality or not. DEFAULT is 'true'.

'user_expire' - Sets how long to remember the user for in seconds. Set to zero forno expiration. DEFAULT is '86500'.

'user_extend_on_login' - TRUE or FALSE. Extend the users session expiration onlogin. DEFAULT is 'false'.

'email_type' - Email content type. DEFAULT us 'html'.

'email_templates' - Folder where the email view templates are stored. DEFAULTis 'auth/email/'.

'email_activate' - Filname of the email activation view template. DEFAULT is'activate.tpl.php'.

'email_forgot_password' - Filname of the forgot password email view template.DEFAULT is 'forgot_password.tpl.php'.

'email_forgot_password_complete' - Filname of the forgot password completeemail view template. DEFAULT is 'new_password.tpl.php'.

'salt_length' - Length of the encryption salt. DEFAULT is '10'.

'store_salt' - TRUE or FALSE. Store the salt in a separate database column ornot. This can be useful for integrating with existing apps. DEFAULT is 'false'.

'forgot_password_expiration' - Number of seconds before a forgot passwordrequest expires. If set to 0, requests will not expire. DEFAULT is 0.

'track_login_attempts' - Track the number of failed login attempts for each useror ip. DEFAULT is 'false'.

'maximum_login_attempts' - Set the maximum number of failed login attempts.This maximum is not enforced by the library, but is used by $this->ion_auth-

>is_max_login_attempts_exceeded(). The controller should check this functionand act appropriately. If set to 0, there is no maximum. DEFAULT is 3.

'message_start_delimiter' - Starting delimiter for messages. DEFAULT is ''.

'message_end_delimiter' - Ending delimiter for messages. DEFAULT is ''.

'error_start_delimiter' - Starting delimiter for errors. DEFAULT is ''.

'error_end_delimiter' - Ending delimiter for errors. DEFAULT is ''.

Class Function Reference

NOTE: Methods available in the model are called through the controller usingPHP5 magic. You should never use ion_auth_model->method() in yourapplications.

login()

Logs the user into the system.

Parameters

1. 'Username' - string REQUIRED. Usually username or email but depends on yourconfig.

2. 'Password' - string REQUIRED.

3. 'Remember' - boolean OPTIONAL. TRUE sets the user to be remembered ifenabled in the config

Return

boolean. TRUE if the user was successfully logged in FALSE if the user was notlogged in.

Usage

logout()

Logs the user out of the system.

Usage

$this->ion_auth->logout();

register()

Register (create) a new user.

Parameters

1. 'Username' - string REQUIRED.

2. 'Password' - string REQUIRED.

3. 'Email' - string REQUIRED.

4. 'Additional Data' - multidimensional array REQUIRED.

5. 'Group' - array OPTIONAL. If not passed the default group name set in the configwill be used.

$identity = '[email protected]';

$password = '12345678';

$remember = TRUE; // remember the user

$this->ion_auth->login($identity, $password, $remember);

Return

mixed. The ID of the user if the user was successfully created, FALSE if the userwas not created.

Usage

update()

Update a user.

Parameters

1. 'Id' - integer REQUIRED.

2. 'Data' - multidimensional array REQUIRED.

Return

boolean. TRUE if the user was successfully updated FALSE if the user was notupdated.

Usage

$username = 'benedmunds';

$password = '12345678';

$email = '[email protected]';

$additional_data = array(

'first_name' => 'Ben',

'last_name' => 'Edmunds',

);

$group = array('1'); // Sets user to admin. No need for array('1', '2') as user is always set to member by default

$this->ion_auth->register($username, $password, $email, $additional_data, $group)

delete_user()

Delete a user.

Parameters


Return

boolean. TRUE if the user was successfully deleted FALSE if the user was notdeleted.

Usage

$id = 12;

$this->ion_auth->delete_user($id)

forgotten_password()

$id = 12;

$data = array(



'password' => '123456789',

);

$this->ion_auth->update($id, $data)

Resets a users password by emailing the user a reset code.

Parameters

1. 'Identity' - string REQUIRED. (as defined in config/ion_auth.php)

Return

boolean. TRUE if the users password was successfully reset FALSE if the userspassword was not reset.

Usage

- this example assumes you have 'email' selected as the identity inconfig/ion_auth.php

//Working code for this example is in the example Auth controller in the github repo

function forgot_password()

{

$this->form_validation->set_rules('email', 'Email Address', 'required');

if ($this->form_validation->run() == false) {

//setup the input

$this->data['email'] = array('name' => 'email',

'id' => 'email',

);

//set any errors and display the form

$this->data['message'] = (validation_errors()) ? validation_errors() : $this->session->flashdata('message');

$this->load->view('auth/forgot_password', $this->data);

}

else {

//run the forgotten password method to email an activation code to the user

$forgotten = $this->ion_auth->forgotten_password($this->input->post('email'));

if ($forgotten) { //if there were no errors

$this->session->set_flashdata('message', $this->ion_auth->messages());

redirect("auth/login", 'refresh'); //we should display a confirmation page here instead of the login page

}

forgotten_password_complete()

Final step of resetting a users password. The user comes to this page from theiremail.

Parameters

1. 'Code' - string REQUIRED.

Return

string. The users new password.

Usage

else {

$this->session->set_flashdata('message', $this->ion_auth->errors());

redirect("auth/forgot_password", 'refresh');

}

}

}

//Working code for this example is in the example Auth controller in the github repo

public function reset_password($code)

{

$reset = $this->ion_auth->forgotten_password_complete($code);

if ($reset) { //if the reset worked then send them to the login page

$this->session->set_flashdata('message', $this->ion_auth->messages());

redirect("auth/login", 'refresh');

}

else { //if the reset didnt work then send them back to the forgot password page

$this->session->set_flashdata('message', $this->ion_auth->errors());

logged_in()

Check to see if a user is logged in.

Return

boolean. TRUE if the user is logged in FALSE if the user is not logged in.

Usage

if (!$this->ion_auth->logged_in())

{

redirect('auth/login');

}

is_admin()

Check to see if the currently logged in user is an admin.

Parameters

1. 'id' - integer OPTIONAL. If a user id is not passed the id of the currently logged inuser will be used.

Return

redirect("auth/forgot_password", 'refresh');

}

}

boolean. TRUE if the user is an admin FALSE if the user is not an admin.

Usage

in_group()

Check to see if the currently logged in user is in the passed in group.

Parameters

1. 'Group ID or Name' - string, integer or array of strings and integers REQUIRED.

2. 'User ID' - integer OPTIONAL. If a user id is not passed the id of the currentlylogged in user will be used.

Return

boolean. TRUE if the user is in any of the given groups, FALSE otherwise.

Usage

if (!$this->ion_auth->is_admin())

{

$this->session->set_flashdata('message', 'You must be an admin to view this page');

redirect('welcome/index');

}

# single group (by name)

$group = 'gangstas';

if (!$this->ion_auth->in_group($group))

{

$this->session->set_flashdata('message', 'You must be a gangsta to view this page');


}

# single group (by id)

$group = 1;


{

$this->session->set_flashdata('message', 'You must be part of the group 1 to view this page');


}

# multiple groups (by name)

$group = array('gangstas', 'hoodrats');


$this->session->set_flashdata('message', 'You must be a gangsta OR a hoodrat to view this page');


}

# multiple groups (by id)

$group = array(1, 2);


$this->session->set_flashdata('message', 'You must be a part of group 1 or 2 to view this page');


}

# multiple groups (by id and name)

$group = array('gangstas', 2);


$this->session->set_flashdata('message', 'You must be a part of the gangstas or group 2');


}

username_check()

Check to see if the username is already registered.

Parameters

1. 'Username' - string REQUIRED.

Return

boolean. TRUE if the user is registered FALSE if the user is not registered.

Usage

email_check()

Check to see if the email is already registered.

//This is a lame example but it works. Usually you would use this method with form_validation.

$username = $this->input->post('username');

$password = $this->input->post('password');

$email = $this->input->post('email');


'first_name' => $this->input->post('first_name'),

'last_name' => $this->input->post('last_name'),

);

if (!$this->ion_auth->username_check($username))

{

$group_name = 'users';

$this->ion_auth->register($username, $password, $email, $additional_data, $group_name)

}

Parameters

1. 'Email' - string REQUIRED.

Return


Usage

identity_check()

Check to see if the identity is already registered.

Parameters

1. 'Identity' - string REQUIRED.

Return

//This is a lame example but it works. Usually you would use this method with form_validation.

$username = $this->input->post('username');

$password = $this->input->post('password');

$email = $this->input->post('email');




);

if (!$this->ion_auth->email_check($email))

{

$group_name = 'users';

$this->ion_auth->register($username, $password, $email, $additional_data, $group_name)

}


Usage

is_max_login_attempts_exceeded()

If login attempt tracking is enabled, checks to see if the number of failed loginattempts for this identity or ip address has been exceeded. The controller must callthis method and take any necessary actions. Login attempt limits are not enforcedin the library.

Parameters


Return

boolean. TRUE if maximum_login_attempts is exceeded FALSE if not or if loginattempts not tracked.

Usage

//This is a lame example but it works.

$user = $this->ion_auth->user();

$data = array(

'identity' => $this->input->post('identity'),



);

if ($data['identity'] === $user->username || $data['identity'] === $user->email || $this->ion_auth->identity_check($data['identity']) === FALSE)

{

$this->ion_auth->update_user($user->id, $data)

}

get_attempts_num()

Returns the number of failed login attempts for this identity or ip address.

Parameters


Return

int. The number of failed login attempts for this identity or ip address.

Usage

increase_login_attempts()

If login attempt tracking is enabled, records another failed login attempt for thisidentity or ip address. This method is automatically called during the login()


if ($this->ion_auth->is_max_login_attempts_exceeded($identity))

{

$this->session->set_flashdata('message', 'You have too many login attempts');


}


$num_attempts = $this->ion_auth->get_attempts_num($identity);

method if the login failed.

Parameters


Usage

clear_login_attempts()

Clears all failed login attempt records for this identity or this ip address. Thismethod is automatically called during the login() method if the login succeded.

Parameters


Usage


$password = '12345678';

if ($this->ion_auth->login($identity, $password) == FALSE) {

$this->ion_auth->increase_login_attempts($identity)

}


$password = '12345678';

if ($this->ion_auth->login($identity, $password) == TRUE) {

$this->ion_auth->clear_login_attempts($identity)

}

user()

Get a user.

Parameters

1. 'Id' - integer OPTIONAL. If a user id is not passed the id of the currently logged inuser will be used.

Return

Usage

$user = $this->ion_auth->user()->row();

echo $user->email;

stdClass Object (

[id] => 1

[ip_address] => 127.0.0.1

[username] => administrator

[password] => 59beecdf7fc966e2f17fd8f65a4a9aeb09d4a3d4

[salt] => 9462e8eee0

[email] => [email protected]

[activation_code] => 19e181f2ccc2a7ea58a2c0aa2b69f4355e636ef4

[forgotten_password_code] => 81dce1d0bc2c10fbdec7a87f1ff299ed7e4c9e4a

[remember_code] => 9d029802e28cd9c768e8e62277c0df49ec65c48c

[created_on] => 1268889823

[last_login] => 1279464628

[active] => 0

[first_name] => Admin

[last_name] => Account

[company] => Some Corporation

[phone] => (123)456-7890

)

users()

Get the users.

Parameters

1. 'Group IDs' - array OPTIONAL. If an array of group ids are passed (or a singlegroup id) this will return the users in those groups.

Return

array of objects

Usage

$users = $this->ion_auth->users()->result();

group()

Get a group.

Parameters


Return

object

Usage

$group_id = 2;

$group = $this->ion_auth->group($group_id);

groups()

Get the groups.

Return

array of objects

Usage

$groups = $this->ion_auth->groups()->result();

messages()

Get messages.

Return

string

Usage

$id = 12;

$data = array(



messages_array()

Get messages as an array.

Return

array

Parameters

1. 'Langify' - boolean OPTIONAL. TRUE means that the messages will be langified.

Usage

);

if ($this->ion_auth->update_user($id, $data))

{

$messages = $this->ion_auth->messages();

echo $messages;

}

else

{

$errors = $this->ion_auth->errors();

echo $errors;

}

$id = 12;

$data = array(



);


{

get_users_groups()

Get all groups a user is part of.

Parameters

1. 'Id' - integer OPTIONAL. If a user id is not passed the id of the currently logged inuser will be used.

Return

$messages = $this->ion_auth->messages_array();

foreach ($messages as $message)

{

echo $message;

}

}

else

{

$errors = $this->ion_auth->errors_array();

foreach ($errors as $error)

{

echo $error;

}

}

stdClass Object (

[id] => 1

[name] => admins

[description] => Administrator

)

Usage

remove_from_group()

Remove user from group(s)

Parameters

1. 'User_id' - integer REQUIRED.

Return

boolean. TRUE if the user was removed from group(s) FALSE if the user is notremoved from group(s).

Usage

$user_groups = $this->ion_auth->get_users_groups($user->id)->result();

// pass an array of group ID's and user ID

$this->ion_auth->remove_from_group(array('1', '3', '6'), $user_id);

// pass a single ID and user ID

$this->ion_auth->remove_from_group(1, $user_id);

// pass NULL to remove user from all groups

$this->ion_auth->remove_from_group(NULL, $user_id);

create_group()

Create a group

Parameters

1. 'group_name' - string REQUIRED.

2. 'group_description' - string.

Return

brand new group_id if the group was created, FALSE if the group creation failed.

Usage

update_group()

Update details of a group

// pass the right arguments and it's done

$group = $this->ion_auth->create_group('new_test_group', 'This is a test description');

if(!$group)

{

$view_errors = $this->ion_auth->messages();

}

else

{

$new_group_id = $group;

// do more cool stuff

}

Parameters

1. 'group_id' - int REQUIRED.

2. 'group_name' - string REQUIRED.

3. 'group_description' - string.

Return

boolean. TRUE if the group was updated, FALSE if the update failed.

Usage

delete_group()

// source these things from anywhere you like (eg., a form)

$group_id = 2;

$group_name = 'test_group_changed_name';

$group_description = 'I changed the name yay';


$group_update = $this->ion_auth->update_group($group_id, $group_name, $group_description);

if(!$group_update)

{


}

else

{


}

Remove a group. Removes the group details from the configured 'groups' table.Users belonging to the group are stripped of this status (references to this groupare removed from users_groups), but user data itself remains untouched.

Parameters

1. 'group_id' - int REQUIRED.

Return

boolean. TRUE if the group was deleted, FALSE if the delete failed.

Usage

set_message_delimiters()

Set the message delimiters.

// source this from anywhere you like (eg., a form)

$group_id = 2;


$group_delete = $this->ion_auth->delete_group($group_id);

if(!$group_delete)

{


}

else

{


}

Parameters

1. 'Start Delimiter' - string REQUIRED.

2. 'End Delimiter' - string REQUIRED.

Usage

errors()

Get the errors.

Return

string

$id = 12;

$data = array(



);


{

$this->ion_auth->set_message_delimiters('','');


echo $messages;

}

else

{

$this->ion_auth->set_error_delimiters('','');


echo $errors;

}

Usage

errors_array()

Get error messages as an array.

Return

array

Parameters

1. 'Langify' - boolean OPTIONAL. TRUE means that the error messages will belangified.

Usage

$id = 12;

$data = array(



);


{


echo $messages;

}

else

{


echo $errors;

}

set_error_delimiters()

Set the error delimiters.

Parameters

1. 'Start Delimiter' - string REQUIRED.

2. 'End Delimiter' - string REQUIRED.

$id = 12;

$data = array(



);


{

$messages = $this->ion_auth->messages_array();

foreach ($messages as $message)

{

echo $message;

}

}

else

{

$errors = $this->ion_auth->errors_array();

foreach ($errors as $error)

{

echo $error;

}

}

Usage

set_hook()

Set a single or multiple functions to be called when trigged by trigger_events(). Seean example here: http://gist.github.com/657de89b26decda2b2fa

Parameters

1. 'Event' - string REQUIRED.

2. 'Name' - string REQUIRED.

3. 'Class' - string REQUIRED.

4. 'Method' - string REQUIRED.

$id = 12;

$data = array(



);


{

$this->ion_auth->set_message_delimiters('','');


echo $messages;

}

else

{

$this->ion_auth->set_error_delimiters('','');


echo $errors;

}

http://gist.github.com/657de89b26decda2b2fa

5. 'Arguments' - Array OPTIONAL.

Usage

class Accounts extends CI_Controller {

public function __construct()

{

parent::__construct();

/*

make sure we loaded ion_auth2

The following does not need to go in __construct() it just needs to be set before

you trigger_events().

*/

$event = 'socialpush';

$class = 'Accounts';

$args = array('this is the content of the message', 'billy');

$name = 'activate_sendmail';

$method = 'email';

$this->ion_auth->set_hook($event, $name, $class, $method, $args);

$name = 'call_Twitter';

$method = 'twitter';


$name = 'call_MailChimp_API';

$method = 'mailchimp';


$name = 'call_Facebook_API';

$method = 'facebook';


$name = 'call_gPlus_API';

$method = 'gplus';


}

trigger_events()

Call Additional functions to run that were registered with set_hook().

public function Post_Message($one)

{

$this->ion_auth->trigger_events('socialpush');

}

public function email($content, $who)

{

return true;

}

public function twitter($content, $who)

{

return true;

}

public function mailchimp($content, $who)

{

return true;

}

public function facebook($content, $who)

{

return true;

}

public function gplus($content, $who)

{

return true;

}

}

Parameters

1. 'Name' - String or Array REQUIRED.

Usage

$this->ion_auth->trigger_events('socialpush');

Top of Page

CodeIgniter · Copyright © 2010 Ben Edmunds · Ellislab, Inc.

Architecting awesome softwareby day, hacking on interestingideas by night. PHP Town Hallpodcast co-host. PDX PHP co-

http://codeigniter.com/

http://ellislab.com/

organizer. Conference speaker.Open source advocate.

http://github.com/benedmunds

http://twitter.com/#!/benedmunds

http://www.linkedin.com/in/benedmunds

ion auth docs.pdf

Documents

default login

default isgroups

users groups table

default user group

users table forwhatever

login attempts table

joinusers users table

users true