codeigniter-aauth documentation - read the docs · codeigniter-aauth documentation, release 2.2.0...
TRANSCRIPT
CodeIgniter-Aauth DocumentationRelease 2.2.0
Emre Akay (emreakay)
October 18, 2015
Contents
1 Introduction 31.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 What is new in Version 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3 Migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.4 Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2 Config File 72.1 Redirects/Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.2 Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.3 Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.4 User and Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.5 Secutiry Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3 Downloads 11
4 Migration 134.1 6 easy steps to upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134.2 Changed functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134.3 New features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
5 User Functions 155.1 Using the User Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
6 Group Functions 216.1 Method Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
7 Permissions and Access Control 257.1 Method Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
8 User and System Variables 298.1 Method Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
9 Private Messages 319.1 Method Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
10 Error and Info Messages 3310.1 Lifespan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3310.2 Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3310.3 Info Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
i
10.4 Method Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
11 enhanced Securtiy Features 3911.1 reCAPTCHA v2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3911.2 TOTP (Time-based One-time Password Algorithm) . . . . . . . . . . . . . . . . . . . . . . . . . . . 3911.3 Method Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
ii
CodeIgniter-Aauth Documentation, Release 2.2.0
Aauth is a User Authorization Library for CodeIgniter 2.x, which aims to make easy some essential jobs such as login,permissions and access operations. Despite its ease of use, it has also very advanced features like private messages,groupping, access management, and public access.
Contents 1
CodeIgniter-Aauth Documentation, Release 2.2.0
2 Contents
CHAPTER 1
Introduction
Aauth is a User Authorization Library for CodeIgniter 2.x, which aims to make easy some essential jobs such as login,permissions and access operations. Despite its ease of use, it has also very advanced features like private messages,groupping, access management, and public access.
This is the Introduction page. You can also take a look at the detailed Documentation to learn about othergreat Features.
1.1 Features
• User Management and Operations (login, logout, register, verification via e-mail, forgotten password, user ban,login DDoS protection)
• Group Operations (creating/deleting groups, membership management)
• Admin and Public Group support (Public permissions)
• Permission Management (creating/deleting permissions, allow/deny groups, public permissions, permissionchecking)
• Group Permissions
• User Permissions
• User and System Variables
• Login DDoS Protection
• Private Messages (between users)
• Error Messages and Validations
• Langugage and config file support
• Flexible implementation
1.2 What is new in Version 2
• User Permissions
• User and System Variables
• Login DDoS Protection
3
CodeIgniter-Aauth Documentation, Release 2.2.0
• Updated functions (check documentation for details)
• Bugs fixes
1.3 Migration
If you are currently using Version 1, take a look at the v1 to v2 migration page.
1.4 Quick Start
1.4.1 Loading Library
Let’s get started :) First, we will load the Aauth Library into the system
$this->load->library("Aauth");
That was easy!
1.4.2 Create Users
Now let’s create two new users, Frodo and Legolas.
$this->aauth->create_user('[email protected]','frodopass','Frodo Baggins');$this->aauth->create_user('[email protected]','legolaspass','Legolas');
We now we have two users.
1.4.3 Create Groups
OK, now we can create two groups, hobbits and elves.
$this->aauth->create_group('hobbits');$this->aauth->create_group('elves');
Now, let’s create a user with power, Gandalf (for our example, let’s assume he was given the id of 12).
$this->aauth->create_user('[email protected]', 'gandalfpass', 'Gandalf the Gray');
OK, now we have two groups and three users.
1.4.4 Create Permissions
Let’s create two permissions walk_unseen and immortality
$this->aauth->create_perm('walk_unseen');$this->aauth->create_perm('immortality');
4 Chapter 1. Introduction
CodeIgniter-Aauth Documentation, Release 2.2.0
1.4.5 Grant/Revoke Groups Permissions
Ok, now let’s give accesses to our groups. The Hobbits seem to have ability to walk unseen, so we will assign thatprivilage to them. The Elves have imortality, so we will assign that privilage to them. We will assign access withallow_group() function.
$this->aauth->allow_group('hobbits','walk_unseen');$this->aauth->allow_group('elves','immortality');
$this->aauth->allow_group('hobbits','immortality');
Wait a minute! Hobbits should not have immortality. We need to fix this, we can use deny() to remove thepermission.
$this->aauth->deny('hobbits','immortality');
1.4.6 Grant User Permissions
Gandalf can also live forever.
$this->aauth->allow_user(12,'immortality');
1.4.7 Permission Check Users/Groups
Ok now let’s check if Hobbits have immortality.
if($this->aauth->is_group_allowed('hobbits','immortality')){echo "Hobbits are immortal";
} else {echo "Hobbits are NOT immortal";
}
Results:
Hobbits are NOT immortal
Does Gandalf have the ability to live forever?
if($this->aauth->is_allowed(12,'immortality')){echo "Gandalf is immortal";
} else {echo "Gandalf is NOT immortal";
}
Results:
Gandalf is immortal
Since we don’t accually live in Middle Earth, we are not aware of actual immortality. Alas, we must delete thepermission.
$this->aauth->delete_perm('immortality');
It is gone.
1.4. Quick Start 5
CodeIgniter-Aauth Documentation, Release 2.2.0
1.4.8 Un-authenticated Users
So, how about un-authenticated users? In Aauth they are part of the public group. Let’s give them permissions totravel. We will assume we already have a permission set up named travel.
$this->aauth->allow_group('public','travel');
1.4.9 Admin Users
What about the Admin users? The Admin user and any member of the Admin group is a superuser who had accesseverthing, There is no need to grant additional permissions.
1.4.10 User Parameters/Variables
For each user, variables can be defined as individual key/value pairs.
$this->aauth->set_user_var("key","value");
For example, if you want to store a user’s phone number.
$this->aauth->set_user_var("phone","1-507-555-1234");
To retreive value you will use get_user_var():
$this->aauth->get_user_var("key");
Aauth also permits you to define System Variables. These can be which can be accesed by all users in the system.
$this->aauth->set_system_var("key","value");$this->aauth->get_system_var("key");
1.4.11 Private Messages
OK, let’s look at private messages. Frodo (id = 3) will send a PM to Legolas (id = 4);
$this->aauth->send_pm(3,4,'New cloaks','These new cloaks are fantastic!')
1.4.12 Banning users
Frodo has broke the rules and will not need to be banned from the system.
$this->aauth->ban_user(3);
You have reached the end of the Quick Start Guide, but please take a look at the detailed Documentationfor additional information.
Don’t forget to keep and eye on Aauth, we are constantly improving the system. You can also contribute and help meout. :)
6 Chapter 1. Introduction
CHAPTER 2
Config File
2.1 Redirects/Links
No Permission redirect, if user don’t have permisssion to see the page he will be redirected the page spesificed belowIf its FALSE redirection is disabled, used by control.
$config['aauth']['no_permission'] = FALSE;
Verfication Link, without site_url or base_url.
$config['aauth']['verification_link'] = '/account/verification/';
Reset Password Link, without site_url or base_url.
$config['aauth']['reset_password_link'] = '/account/reset_password/';
2.2 Groups
Admin Group, used by is_admin and is_group_allowed
$config['aauth']['admin_group'] = 'admin';
Default Group, the new user is added in it
$config['aauth']['default_group'] = 'default';
Public Group, people who not logged in
$config['aauth']['public_group'] = 'public';
2.3 Databases
Users
$config['aauth']['users'] = 'aauth_users';
Groups
7
CodeIgniter-Aauth Documentation, Release 2.2.0
$config['aauth']['groups'] = 'aauth_groups';
User to Groups
$config['aauth']['user_to_group'] = 'aauth_user_to_group';
Permissions
$config['aauth']['perms'] = 'aauth_perms';
Permissions to Group
$config['aauth']['perm_to_group'] = 'aauth_perm_to_group';
Permissions to User
$config['aauth']['perm_to_user'] = 'aauth_perm_to_user';
Private Messages
$config['aauth']['pms'] = 'aauth_pms';
System Variables
$config['aauth']['system_variables'] = 'aauth_system_variables';
User Variables
$config['aauth']['user_variables'] = 'aauth_user_variables';
2.4 User and Login
Remember time, sets the cookie lifetime.
$config['aauth']['remember'] = ' +3 days';
Pasword maximum character lenght (min is 4).
$config['aauth']['max'] = 24;
Additional valid characters that are allowed in a name.
$config['aauth']['valid_chars'] = array();
Maximum login attempts, if its reached user cant login.
$config['aauth']['max_login_attempt'] = 10;
User Verification, if its TRUE it sends a verification email on user creation.
$config['aauth']['verification'] = false;
Login Indetificator, if its TRUE username needed to login else email address.
$config['aauth']['login_with_name'] = false;
Email Address, used by remind_password, send_verification and reset_password.
8 Chapter 2. Config File
CodeIgniter-Aauth Documentation, Release 2.2.0
$config['aauth']['email'] = '[email protected]';
Name from Email address.
$config['aauth']['name'] = 'Emre Akay';
2.5 Secutiry Features
DDoS Protection, if it is true, the user will be banned temporary when he exceed the login ‘try’.
$config['aauth']['ddos_protection'] = true;
reCAPTCHA enabler, enables Google’s reCAPTCHA v2:
$config['aauth']['recaptcha_active'] = false;
reCAPTCHA Login Attempts, if users login_attempts is reached reCAPTCHA appears troughgenerate_recaptcha_field.
$config['aauth']['recaptcha_login_attempts'] = 4;
reCAPTCHA siteKey and secret, available on reCAPTCHA site registration.
$config['aauth']['recaptcha_siteKey'] = '';$config['aauth']['recaptcha_secret'] = '';
TOTP enabler, enables Time-based One-time Password Algorithm.
$config['aauth']['totp_active'] = false;
TOTP only on IP Change, if TRUE TOTP Code is only needed if IP of user changed.
$config['aauth']['totp_only_on_ip_change'] = false;
TOTP reset over reste Password, if TRUE on reset password removes users TOTP security key.
$config['aauth']['totp_reset_over_reset_password'] = false;
2.5. Secutiry Features 9
CodeIgniter-Aauth Documentation, Release 2.2.0
10 Chapter 2. Config File
CHAPTER 3
Downloads
Release .zip .tar.gzCodeIgniter-Aauth 2.2.0 CodeIgniter-Aauth-2.2.0.zip CodeIgniter-Aauth-2.2.0.tar.gzCodeIgniter-Aauth 2.1.0 CodeIgniter-Aauth-2.1.0.zip CodeIgniter-Aauth-2.1.0.tar.gzCodeIgniter-Aauth 2.0.5 CodeIgniter-Aauth-2.0.5.zip CodeIgniter-Aauth-2.0.5.tar.gzCodeIgniter-Aauth 2.0.4 CodeIgniter-Aauth-2.0.4.zip CodeIgniter-Aauth-2.0.4.tar.gzCodeIgniter-Aauth 2.0.3 CodeIgniter-Aauth-2.0.3.zip CodeIgniter-Aauth-2.0.3.tar.gzCodeIgniter-Aauth 2.0.2 CodeIgniter-Aauth-2.0.2.zip CodeIgniter-Aauth-2.0.2.tar.gzCodeIgniter-Aauth 2.0.1 CodeIgniter-Aauth-2.0.1.zip CodeIgniter-Aauth-2.0.1.tar.gzCodeIgniter-Aauth 2.0-beta CodeIgniter-Aauth-2.0-beta.zip CodeIgniter-Aauth-2.0-beta.tar.gz
11
CodeIgniter-Aauth Documentation, Release 2.2.0
12 Chapter 3. Downloads
CHAPTER 4
Migration
4.1 6 easy steps to upgrade
1. Copy and paste the new files.
2. Back up your database data. (only data not structure)
3. Create new Database
4. Execute Aauth_v2_sql
5. Copy your backed up data to new database
6. Change the deprecated functions below
4.2 Changed functions
• unlock_user() changed to unban_user()
• fire_member() changed to remove_member()
• allow() changed to allow_group()
• deny() changed to deny_group()
• get_errors() changed to print_errors()
• get_infos() changed to print_infos()
4.3 New features
• new parameter added to is_member()
• allow_user() added
• deny_user() added
• keep_infos() added
• kepp_errors() added
• User and Aauth System Variables added
• set_user_var() added
13
CodeIgniter-Aauth Documentation, Release 2.2.0
• unset_user_var() added
• get_user_var() added
• set_system_var() added
• unset_system_var() added
• get_system_var() added
New Columns added to Database schema.
14 Chapter 4. Migration
CHAPTER 5
User Functions
5.1 Using the User Functions
Log in User
Examples with remember
$this->aauth->login(’[email protected]’, ’password’, true)
without remember
$this->aauth->login(’[email protected]’, ’password’)
without remember but with TOTP code
$this->aauth->login(’[email protected]’, ’password’, false, ’156124’)
Log out User
Example
$this->aauth->logout()
Create User
Example
$this->aauth->create_user(’[email protected]’, ’example_pass’, ’Optional Name’)
List User
Examples To list all unbanned user in the system
$this->aauth->list_users()
To list any user that grants ‘Admin’ group
$this->aauth->list_users(’Admin’)
To list the first 25 users in the system
$this->aauth->list_users(FALSE, 25)
To list the first 25 users with a offset of 50 in the system
$this->aauth->list_users(FALSE, 25, 50)
To list all user incl. banned users in the system
$this->aauth->list_users(FALSE, FALSE, FALSE, TRUE)
15
CodeIgniter-Aauth Documentation, Release 2.2.0
5.1.1 To list the user
Method Reference
login($identifier, $pass, $remember = FALSE, $totp_code = NULL)
Parameters
• $identifier (string) – Email address or Username.
• $pass (string) – Password.
• $remember (int) – Whether to remember for next visits.
• $totp_code (int) – TOTP Code.
Returns TRUE on success, FALSE on failure.
Return type bool
Logs user into system.
logout()
Return type
void
Clears all sessions of current user.
list_users($group_par = NULL, $limit = NULL, $offset = NULL, $include_banneds = NULL)
Parameters
• $group_par (int|string) – ID or Name of Group.
• $limit (int) – Sets the limit of rows.
• $offset (int) – Sets the offset for rows.
• $include_banneds (bool) – Whether to displays banned users too.
Returns List of Users
Return type object
Lists users.
is_loggedin()
Returns TRUE if user is logged in, FALSE if user isn’t logged in
Return type bool
checks if user is logged in
create_user($email, $pass, $name = ‘’)
Parameters
• $email (string) – Email address.
• $pass (string) – Password.
• $name (string) – Name.
Returns User ID of created user, FALSE if users cant create
Return type mixed
16 Chapter 5. User Functions
CodeIgniter-Aauth Documentation, Release 2.2.0
Creates a user.
update_user($user_id, $email = FALSE, $pass = FALSE, $name = FALSE)
Parameters
• $email (string) – Email address.
• $pass (string) – Password.
• $name (string) – Name.
Returns TRUE if user was updated, FALSE if wasn’t updated
Return type
bool
Updates user by using user_id
verify_user($user_id, $ver_code)
Parameters
• $user_id (int) – User ID.
• $ver_code (sting) – Verification Code.
Returns TRUE if user is verified, FALSE if user isn’t verified
Return type bool
verifies user
ban_user($user_id)
Parameters
• $user_id (int) – User ID.
Returns TRUE if user was banned, FALSE if user wasn’t banned
Return type bool
bans a user
unban_user($user_id)
Parameters
• $user_id (int) – User ID.
Returns TRUE if user is unbanned, FALSE if user isn’t unbanned
Return type bool
unban a banned user
is_banned($user_id)
Parameters
• $user_id (int) – User ID.
Returns TRUE if user is already banned, FALSE if user isn’t banned
Return type bool
checks if user is banned
delete_user($user_id)
5.1. Using the User Functions 17
CodeIgniter-Aauth Documentation, Release 2.2.0
Parameters
• $user_id (int) – User ID.
Returns TRUE if user was deleted, FALSE if user wasn’t deleted
Return type bool
deletes user. I recommend to use ban_user function.
remind_password($email)
Parameters
• $email (string) – Email address.
Returns TRUE on success, FALSE on failure
Return type bool
send a vertification code to given email if user exists
reset_password($user_id, $ver_code)
Parameters
• $user_id (int) – User ID.
• $ver_code (sting) – Verification Code.
Returns TRUE if email was send, FALSE if email wasn’t send
Return type bool
resets password and sends a random password user’s email
get_user($user_id = FALSE)
Parameters
• $user_id (int) – User ID.
Returns User information if user exists, FALSE if user not exists and a error message
Return type object
get_user_id($email = FALSE)
Parameters
• $email (string) – Email address.
Returns User ID, if email parameter not given, it will return current logged in user’s id.
Return type int
get_user_groups($user_id = FALSE)
Parameters
• $user_id (int) – User ID.
Returns Joined groups of given user
Return type object
You should also check Group Operations.
user_exist_by_name($name)
Parameters
18 Chapter 5. User Functions
CodeIgniter-Aauth Documentation, Release 2.2.0
• $name (sting) – Username.
Returns TRUE if user exist, FALSE if user not exist.
Return type bool
Check if user exist by name
user_exist_by_email($user_email)
Parameters
• $user_email (sting) – Email address.
Returns TRUE if user exist, FALSE if user not exist.
Return type bool
Check if user exist by email
update_activity($user_id = FALSE)
Parameters
• $user_id (int) – User ID.
Returns TRUE if user activity updated , FALSE if user not exists
Return type bool
Updates the user’s last activity time. Remember! control function also do this job.
reset_login_attempts($user_id)
Parameters
• $user_id (int) – User ID.
Returns TRUE if attempts is reseted, FALSE if attempts isn’t reseted
Return type bool
Resets the login attempts of a user.
Limits login attempt. People can do 10 login attempts per minute by default. It can changed from config file bychanging ’try’ => 10, line.
You can also deactivate this by changing that line to true ’dos_protection’ => true,.
send_verification($user_id)
Parameters
• $user_id (int) – User ID.
Return type void
Sends a verification mail to the user’s email, create_user also sends verification using this function.
update_last_login($user_id = FALSE)
Parameters
• $user_id (int) – User ID.
Returns TRUE if user last login updated , FALSE if user not exists
Return type bool
Updates last login time. Remember! login function use this.
5.1. Using the User Functions 19
CodeIgniter-Aauth Documentation, Release 2.2.0
update_remember($user_id, $expression = NULL, $expire = NULL)
Parameters
• $user_id (int) – User ID.
Returns TRUE if users last login updated , FALSE if users last login failed
Return type bool
Updates the remember time for a user, login function use this.
login_fast($user_id)
Parameters
• $user_id (int) – User ID.
Returns TRUE on success, FALSE on failure.
Return type bool
Login by using only user_id
hash_password($pass, $user_id)
Parameters
• $pass (int) – Password.
• $user_id (int) – User ID.
Returns Hashed password
Return type string
Hash the password for storage in the database.
20 Chapter 5. User Functions
CHAPTER 6
Group Functions
6.1 Method Reference
Groups are most important part of Aauth First you must know groups settings can be changed from Aauth config file(we recomend not to change) ’admin_group’ => ’Admin’ is group name of admin ’default_group’ =>’Default’ is for new users ’public_group’ => ’Public’ for whom not logged in
In Aauth, Users can have more than one group. Admin has all rights
lets look at functions
create_group($group_name, $definition)
Creates a group.
param string $group_name Name.
param string $definition Defintion.
Returns Group ID of created group, FALSE if group cant create
Return type mixed
update_group($group_par, $group_name=FALSE, $definition=FALSE)Updates group using group_id
Parameters
• $group_par (int|string) – ID or name of group.
• $group_name (string) – Name.
• $definition (string) – Defintion.
Returns TRUE if group was updated, FALSE if group couldn’t updated
Return type bool
delete_group($group_par)Deletes a group
Parameters
• $group_par (int|string) – ID or name of group.
Returns TRUE if group was deleted, FALSE if group couldn’t deleted
Return type bool
21
CodeIgniter-Aauth Documentation, Release 2.2.0
add_member($user_id, $group_par)Adds member to a group.
Parameters
• $user_id (int|string) – User ID.
• $group_par (int|string) – ID or name of group.
Returns TRUE if user was added to group, FALSE if user couldn’t add to group
Return type bool
remove_member($user_id, $group_par)Removes member from a group.
Parameters
• $user_id (int|string) – User ID.
• $group_par (int|string) – ID or name of group.
Returns TRUE if user was removed from group, FALSE if user couldn’t removed from group
Return type bool
is_member($group_par, $user_id = FALSE)Check if user is a member of a group
Parameters
• $group_par (int|string) – ID or name of group.
• $user_id (int|string) – User ID, if not given current user.
Returns TRUE if current user is member of given group, FALSE if not
Return type bool
is_admin()It is a special function which control if a current user is an admin Remember! you can change admin’s groupfrom Aauth config file
Returns TRUE if current user is admin, FALSE if current user isn’t admin
Return type bool
list_groups()List all groups
Returns List of all groups
Return type object
get_group_name($group_id)
Parameters
• $group_id (int) – Group ID.
Returns Name of a group.
Return type string
get_group_id($group_par)
Parameters
• $group_par (int|string) – ID or name of group.
22 Chapter 6. Group Functions
CodeIgniter-Aauth Documentation, Release 2.2.0
Returns Group ID
Return type int
6.1. Method Reference 23
CodeIgniter-Aauth Documentation, Release 2.2.0
24 Chapter 6. Group Functions
CHAPTER 7
Permissions and Access Control
Permissions is the most important part of Aauth. In Aauth you can set permissions of a group or a specified user.
7.1 Method Reference
create_perm($perm_name, $definition=’‘)creates new permission rule
Parameters
• $perm_name (string) – Name.
• $definition (string) – Defintion.
Returns Perm ID of created perm, FALSE if perm cant create
Return type mixed
update_perm($perm_par, $perm_name, $definition=false)updates permission
Parameters
• $perm_par (int|string) – ID or name of permission.
• $perm_name (string) – Name.
• $definition (string) – Defintion.
Returns TRUE if permission was updated, FALSE if permission couldn’t updated
Return type bool
delete_perm($perm_par)removes a permission. Be careful.
Parameters
• $perm_par (int|string) – ID or name of permission.
Returns TRUE if permission was deleted, FALSE if permission couldn’t deleted
Return type bool
list_perms()
Returns List of permissions
Return type object
25
CodeIgniter-Aauth Documentation, Release 2.2.0
get_perm_id($perm_par)
Parameters
• $perm_par (int|string) – ID or name of permission.
Returns Permission ID
Return type int
control($perm_par = NULL)It is a special function which control if a current user has permission.
It updates user’s last activity date-time.
I recommend you to use this function inside every conrtollers’ constructer.
to control access of a user for permission rule with id 5
$this->aauth->control(5)
to control the bla permission
$this->aauth->control(’bla’)
Parameters
• $perm_par (int|string) – ID or name of permission, If empty checks if logged in or not.
Returns TRUE if user has permission, If user hasn’t permission it stops the execution and shows amessage (can be changed from language file)
Return type bool
is_allowed($perm_par, $user_id=false)Check if user allowed to do specified action, admin always allowed.
First checks user permissions then check group permissions
Example to check a user with id 33 has permission to print_report or not
$this->aauth->is_allowed(33,"print_report")
Parameters
• $perm_par (int|string) – ID or name of permission.
• $user_id (int) – User ID, if not given current user.
Returns TRUE if user has permission, If user hasn’t permission it stops the execution and shows amessage (can be changed from language file)
Return type bool
is_group_allowed($perm_par, $group_par=false)Checks if a group has permissions for given permition rule
To check if current user has permission for ‘new_message’.
This will checks all groups of current user and if at least one of group has permission, it will return true.
$this->aauth->is_group_allowed(’new_message’)
to check if ‘mod’ has permission for ‘new_message’
$this->aauth->is_group_allowed(’new_message’, ’mod’)
to check if not logged users has permissions for rule with id=4
$this->aauth->is_group_allowed(4, ’public’)
26 Chapter 7. Permissions and Access Control
CodeIgniter-Aauth Documentation, Release 2.2.0
to check if group with id=3 has permissions for rule with id=2
$this->aauth->is_group_allowed(2,3)
Parameters
• $perm_par (int|string) – ID or name of permission.
• $group_par (int|string) – ID or name of group, if empty it checks all groups of currentuser.
Returns TRUE if group has permission, FALSE if group hasn’t permission
Return type bool
Note: The admin group is authorized for anything.
allow_user($user_id, $perm_par)allow just a user to access given permission rule. perm_par can be id or permission name.
to give permission to user with id 33 for ‘comment’
$this->aauth->allow_user(33, ’public’)
or with permission id (23)
$this->aauth->allow_user(33, 23)
Parameters
• $user_id (int) – User ID.
• $perm_par (int|string) – ID or name of permission.
Returns TRUE if user was denied from permission, FALSE if user couldn’t denied from permission
Return type bool
deny_user($user_id, $perm_par)Remove user from permission
Parameters
• $user_id (int) – User ID.
• $perm_par (int|string) – ID or name of permission.
Returns TRUE if user was denied from permission, FALSE if user couldn’t denied from permission
Return type bool
allow_group($group_par, $perm_par)Allow a group (members of a group) to access given permission rule.
to give permission to public for ‘comment’
$this->aauth->allow_group(’comment’, ’public’)
to give mods the permsiison with id=3
$this->aauth->allow_group(3, ’mod’)
Parameters
• $group_par (int|string) – ID or name of group.
• $perm_par (int|string) – ID or name of permission.
7.1. Method Reference 27
CodeIgniter-Aauth Documentation, Release 2.2.0
Returns TRUE if group was allowed for permission, FALSE if group couldn’t allowed for permis-sion
Return type bool
deny_group($group_par, $perm_par)Denying in Aauth means not having permissions. Users are denied as long as permission is not given
to take back permission (to deny) from public for ‘comment’
$this->aauth->deny_group(’comment’, ’public’)
Parameters
• $group_par (int|string) – ID or name of group.
• $perm_par (int|string) – ID or name of permission.
Returns TRUE if group was denied from permission, FALSE if group couldn’t denied from permis-sion
Return type bool
28 Chapter 7. Permissions and Access Control
CHAPTER 8
User and System Variables
with Aauth v2 you can define user specified variables or sytem variables for all users.
8.1 Method Reference
set_user_var($key, $value, $user_id = false)Set Aauth User Variable as key & value.
If variable not set before, it will ve set. If its already set, it overwrites the value.
$this->aauth->set_user_var("address","Kardesler Building, Cakmaklar StreetNo:34 Sutluce / Istanbul")
Parameters
• $key (string) – Key.
• $value (string) – Value.
• $user_id (int) – User ID, if not given current user.
Returns TRUE if variable was setted, FALSE if variable couldn’t setted
Return type bool
unset_user_var($key, $user_id = false)Unset User Variable
$this->aauth->unset_user_var("phone")
Parameters
• $key (string) – Key.
• $user_id (int) – User ID, if not given current user.
Returns TRUE if the variable was deleted, FALSE if the variable couldn’t deleted
Return type bool
get_user_var($key, $user_id = false)Get User Variable by key Return string of variable value or false when not found.
$this->aauth->get_user_var("phone")
Parameters
• $key (string) – Key.
29
CodeIgniter-Aauth Documentation, Release 2.2.0
• $user_id (int) – User ID, if not given current user.
Returns The variable’s value if its setted, FALSE if its not setted.
Return type mixed
list_user_var_keys($user_id = FALSE)Lists all variables from user
Parameters
• $user_id (int) – User ID, if not given current user.
Returns All users variables from given user
Return type object
set_system_var($key, $value)Set Aauth System Variable as key & value.
If variable not set before, it will ve set. If its already set, it overwrites the value.
Parameters
• $key (string) – Key.
• $value (string) – Value.
Returns TRUE if variable was setted, FALSE if variable couldn’t setted
Return type bool
unset_system_var($key)Unset System Variable
$this->aauth->unset_system_var("site_name")
Parameters
• $key (string) – Key.
Returns TRUE if the variable was deleted, FALSE if the variable couldn’t deleted
Return type bool
get_system_var($key)Get System Variable by key
Parameters
• $key (string) – Key.
Returns The variable’s value if its setted, FALSE if its not setted.
Return type mixed
list_system_var_keys()Lists all system variables
Returns All system variables
Return type object
30 Chapter 8. User and System Variables
CHAPTER 9
Private Messages
With Aauth, users can send pms to each others.
9.1 Method Reference
send_pm($sender_id, $receiver_id, $title, $message)Simply sends pm.
to send pm from user with id=2 to id=3
$this->aauth->send_pm(2, 3, ’Message subject’, ’Msg body’)
Parameters
• $sender_id (int) – User ID from sender.
• $receiver_id (int) – User ID from receiver.
• $title (string) – Title.
• $message (string) – Message.
Returns TRUE if PM sended, FALSE if error and error messages
Return type bool
list_pms($limit=5, $offset=0, $receiver_id=false, $sender_id=false)You can limit pms by giving limit and offset.
if you want to list pms from specified sender or reciever, you have to give reciever_id or sender_id or both.
to list 50 pm
$this->aauth->list_pms(50)
to list 50 coming pms for speceified user (id=13)
$this->aauth->list_pms(50,0,13)
to list 50 sent pms for speceified user (id=13)
$this->aauth->list_pms(50,0,false,13)
to list 50 pms from id=3 to id=5
$this->aauth->list_pms(50,0,5,3)
Parameters
31
CodeIgniter-Aauth Documentation, Release 2.2.0
• $limit (int) – Sets the limit of rows.
• $offset (int) – Sets the offset for rows.
• $receiver_id (int) – User ID from receiver.
• $sender_id (int) – User ID from sender.
Returns the requested Private Messages.
Return type object
get_pm($pm_id, $set_as_read = true)if set_as_true is true, it also checks pm as true.
to get pm with pm_id=53
$this->aauth->get_pm(53)
Parameters
• $pm_id (int) – ID of Private Message
• $set_as_read (bool) – Whether if message set as readed.
Returns the requested Private Message
Return type object
delete_pm($pm_id)Deletes pm
Parameters
• $pm_id (int) – ID of Private Message
Returns TRUE if PM was deleted, FALSE if PM wasn’t deleted
Return type bool
count_unread_pms($receiver_id=false)if reciever_id not specified, returns current user’s unread pm number
Parameters
• $receiver_id (int) – User ID from receiver.
Returns unread pms as an integer.
Return type int
set_as_read_pm($pm_id)Sets a pm as read
Remember! you can also do it with get_pm() function
Parameters
• $pm_id (int) – ID of Private Message
Return type void
32 Chapter 9. Private Messages
CHAPTER 10
Error and Info Messages
Error messages are used to warn the user when something went wrong. Info messages are used to inform the userwhen something has changed or was updated.
Aauth supports both built-in error and info messages, and user-defined errors.
For example, if you are trying to send a private message to yourself, you will get an error.Another example: if you try to create a group that already exists, you will get a “Group Exists” error.
Note: However, errors are not fatal and do not stop execution of the code.
Aauth system error messages can be customized in the Aauth Language file.
The most useful case is logging in and registering. If user has entered wrong information – such as a password that istoo short, an invalid email, or an invalid character – you will get an array of any, and all, errors.
10.1 Lifespan
Error and info messages are temporary and last only for the duration of the current request. Optionally, messages canbe added as flash data (see Codeigniter session documentation) which will make them available only on the next serverrequest.
10.2 Error Messages
10.2.1 $this->aauth->error()
Adds an error message to the error message stack
$this->aauth->error('Please fill in all required fields on the form');// Adds a single error message to the stack
Optionally you can set a flag to make the error message available only on the next request.
$this->aauth->error('You have been logged out due to inactivity', TRUE);// Adds a single error message to the flash data error stack available on the next request.// this is useful if using http redirects in your code
33
CodeIgniter-Aauth Documentation, Release 2.2.0
10.2.2 $this->aauth->keep_errors()
Keeps the flashdata errors for one more page refresh. Optionally adds the default errors into the flashdata list. Thisshould be called last in your controller; and with care, as it could continue to revive all errors and not let them expireas intended.
This is beneficial when using Ajax Requests.
$this->aauth->keep_errors();// resets the current flashdata errors
If you pass a boolean value of TRUE into the function it will also change all current errors to flashdata errors.
$this->aauth->keep_errors(TRUE);// resets the current flashdata errors, and moves all current "standard" errors into flashdata errors.
10.2.3 $this->aauth->get_errors_array()
Returns all errors as an array of strings.
$this->aauth->get_errors_array();
10.2.4 $this->aauth->print_errors()
Prints error messages to string separated with a customizable divider. Default divider = <br />.
$this->aauth->print_errors(' -|- ');// Produces the error string with the divider of " -|- " instead of the default
10.2.5 $this->aauth->clear_errors()
Removes all errors from error message stack and clears all associated flashdata error messages
$this->aauth->clear_errors();// eliminates all current error message
10.3 Info Messages
Info messages are identical to error message, the difference lies in how they are used. Info message are intended fortrivial warnings and notices.
For example: when a new user is successfully created, an info message is triggered notifying the user ofthat fact.
10.3.1 $this->aauth->info()
Adds an info message to the info message stack
$this->aauth->info('The form has successfully been submitted');// Adds a single info message to the stack
34 Chapter 10. Error and Info Messages
CodeIgniter-Aauth Documentation, Release 2.2.0
Optionally you can set a flag to make the info message available only on the next request.
$this->aauth->info('Your account has successfully been created, and you are now logged in.', TRUE);// Adds a single info message to the flashdata info stack available on the next request.// this is useful if using http redirects in your code
10.3.2 $this->aauth->keep_infos()
Keeps the flashdata info messages for one more page refresh. Optionally adds the default info messages into theflashdata list. This should be called last in your controller; and with care, as it could continue to revive all infomessages and not let them expire as intended.
This is beneficial when using Ajax Requests.
$this->aauth->keep_infos();// resets the current flashdata info messages
If you pass a boolean value of TRUE into the function it will also change all current info messages to flashdata infomessages.
$this->aauth->keep_infos(TRUE);// resets the current flashdata info messages, and moves all current "standard" info messages into flashdata errors.
10.3.3 $this->aauth->get_infos_array()
Returns all info messages as an array of strings.
$this->aauth->get_infos_array();
10.3.4 $this->aauth->print_infos()
Prints info messages to string separated with a customizable divider. Default divider = <br />.
$this->aauth->print_infos(' -|- ');// Prints the info message string with the divider of " -|- " instead of the default
10.3.5 $this->aauth->clear_infos()
Removes all info messages from info message stack and clears all associated flashdata info messages
$this->aauth->clear_infos();// eliminates all current info message
10.4 Method Reference
error($message = ‘’, $flashdata = FALSE)Add message to error array and set flash data
$this->aauth->error(’Please fill the form’)
Parameters
10.4. Method Reference 35
CodeIgniter-Aauth Documentation, Release 2.2.0
• $message (string) – Message to add to array.
• $flashdata (bool) – if TRUE add $message to CI flashdata
Return type void
keep_errors($include_non_flash = FALSE)Keeps the flashdata errors for one more page refresh. Optionally adds the default errors into the flashdata list.This should be called last in your controller, and with care as it could continue to revive all errors and not letthem expire as intended.
Benefitial when using Ajax Requests
Parameters
• $include_non_flash (bool) – TRUE if it should stow basic errors as flashdata.
Return type void
get_errors_array()Get Errors Array
Returns Array of messages, empty array if no errors
Return type array
print_errors($divider = ‘<br />’)Prints string of errors separated by delimiter
it prints the string which error messages divided with a divider ( default divider is new line char )
infos are same with errors, but it is user for trivial warnigns for instance, in check_email() function if email istaken, it will create an info.
Parameters
• $divider (string) – Separator for errors
clear_errors()Removes errors from error list and clears all associated flashdata
Return type void
info($message = ‘’, $flashdata = FALSE)Add message to info array and set flash data.
Parameters
• $message (string) – Message to add to infos array.
• $flashdata (bool) – if TRUE add $message to CI flashdata.
Return type void
keep_infos($include_non_flash = FALSE)Keeps the flashdata infos for one more page refresh. Optionally adds the default infos into the flashdata list.This should be called last in your controller, and with care as it could continue to revive all infos and not letthem expire as intended.
Benefitial by using Ajax Requests
Parameters
• $include_non_flash (bool) – TRUE if it should stow basic infos as flashdata.
Return type void
36 Chapter 10. Error and Info Messages
CodeIgniter-Aauth Documentation, Release 2.2.0
get_infos_array()Return array of infos
Returns Array of messages, empty array if no infos
Return type array
print_infos($divider = ‘<br />’)Print string of info separated by delimiter
Parameters
• $divider (string) – Separator for info.
Returns all infos
Return type string
clear_infos()Removes info messages from info list and clears all associated flashdata
Return type void
10.4. Method Reference 37
CodeIgniter-Aauth Documentation, Release 2.2.0
38 Chapter 10. Error and Info Messages
CHAPTER 11
enhanced Securtiy Features
11.1 reCAPTCHA v2
to use reCAPTCHA with aauth
Setup the ‘application/config/aauth.php’,
1. turn recaptcha_active from false to true
2. register your website on https://www.google.com/recaptcha/admin
3. insert the reCAPTCHA siteKey and secret that you got from the registration
4. (optional) set ‘recaptcha_login_attempts’
Place the captcha field in layout, its simply you need only to place echo$this->aauth->generate_recaptcha_field(); in your layout
11.2 TOTP (Time-based One-time Password Algorithm)
Setup the ‘application/config/aauth.php’,
1. change totp_active from FALSE to TRUE
2. (optional) change totp_only_on_ip_change to TRUE
3. (optional) change totp_reset_over_reset_password to TRUE
Generate a TOTP secret and QR Code.
$secret = $this->aauth->generate_unique_totp_secret();echo $secret;$qr_code = $this->aauth->generate_totp_qrcode($secret);echo '<img src="'.$qr_code.'" width="200" height="200" />';
Last but not least Update Users TOTP secret
$this->aauth->update_user_totp_secret(FALSE, $secret);
11.3 Method Reference
generate_recaptcha_field()
39
CodeIgniter-Aauth Documentation, Release 2.2.0
Returns the HTML for the reCAPTCHA field.
Return type string
update_user_totp_secret($user_id = FALSE, $secret)Updates users TOTP secret.
Parameters
• $user_id (int) – User ID.
• $secret (string) – TOTP Secret
Returns TRUE if updated, FALSE if not updated
Return type bool
generate_unique_totp_secret()Generates a unique TOTP secret.
Returns TOTP secret
Return type int
generate_totp_qrcode($secret)Generates a QR Code URL by TOTP secret.
Parameters
• $secret (string) – TOTP secret.
Returns URL of QR Code
Return type string
40 Chapter 11. enhanced Securtiy Features
Index
Aadd_member() (global function), 21allow_group() (global function), 27allow_user() (global function), 27
Bban_user() (global function), 17
Cclear_errors() (global function), 36clear_infos() (global function), 37control() (global function), 26count_unread_pms() (global function), 32create_group() (global function), 21create_perm() (global function), 25create_user() (global function), 16
Ddelete_group() (global function), 21delete_perm() (global function), 25delete_pm() (global function), 32delete_user() (global function), 17deny_group() (global function), 28deny_user() (global function), 27
Eerror() (global function), 35
Ggenerate_recaptcha_field() (global function), 39generate_totp_qrcode() (global function), 40generate_unique_totp_secret() (global function), 40get_errors_array() (global function), 36get_group_id() (global function), 22get_group_name() (global function), 22get_infos_array() (global function), 36get_perm_id() (global function), 26get_pm() (global function), 32get_system_var() (global function), 30get_user() (global function), 18
get_user_groups() (global function), 18get_user_id() (global function), 18get_user_var() (global function), 29
Hhash_password() (global function), 20
Iinfo() (global function), 36is_admin() (global function), 22is_allowed() (global function), 26is_banned() (global function), 17is_group_allowed() (global function), 26is_loggedin() (global function), 16is_member() (global function), 22
Kkeep_errors() (global function), 36keep_infos() (global function), 36
Llist_groups() (global function), 22list_perms() (global function), 25list_pms() (global function), 31list_system_var_keys() (global function), 30list_user_var_keys() (global function), 30list_users() (global function), 16login() (global function), 16login_fast() (global function), 20logout() (global function), 16
Pprint_errors() (global function), 36print_infos() (global function), 37
Rremind_password() (global function), 18remove_member() (global function), 22reset_login_attempts() (global function), 19reset_password() (global function), 18
41
CodeIgniter-Aauth Documentation, Release 2.2.0
Ssend_pm() (global function), 31send_verification() (global function), 19set_as_read_pm() (global function), 32set_system_var() (global function), 30set_user_var() (global function), 29
Uunban_user() (global function), 17unset_system_var() (global function), 30unset_user_var() (global function), 29update_activity() (global function), 19update_group() (global function), 21update_last_login() (global function), 19update_perm() (global function), 25update_remember() (global function), 19update_user() (global function), 17update_user_totp_secret() (global function), 40user_exist_by_email() (global function), 19user_exist_by_name() (global function), 18
Vverify_user() (global function), 17
42 Index