# BackendPro User Guide Version 0.3.1

Search User Guide

# User Authentication

BackendPro has built in user authentication from the start. If you have used systems like FreakAuth before then you will be at home with BackendPro, but it offers even more. Unless you want to change the way people log in or the logic behind user authentication I would just quickly skim this page to get the basics.

Note: This class is initialized automatically by the system so there is no need to do it manually.

Features:

- Basic user authentication from the start
- Customizable user groups
- Multiple user activation methods and settings (Please see the preference page for possible settings)
- Custom user profiles

Important: The user authentication class stores passwords using an additional salt (More infomation here). The salt used is that of the encryption_key defined in the file system/application/config/config.php. Changing the key after user accounts have been created will corupt their passwords requiring the user to request a new password.

## Configuration Settings

All configuration settings for the Userlib Class can be found in modules/auth/config/userlib.php

Preference | Default Value | Options | Description
--- | --- | --- | ---
userlib_action_login | NULL | None | The CodeIgniter URI string to redirect the user to upon login
userlib_action_logout | NULL | None | The CodeIgniter URI string to redirect the user to upon logout
userlib_action_register | NULL | None | The CodeIgniter URI string to redirect the user to upon registration
userlib_action_activation | NULL | None | The CodeIgniter URI string to redirect the user to upon activation
userlib_action_forgotten_password | auth/login | None | The CodeIgniter URI string to redirect the user to upon completion of a forgotten password form
userlib_action_admin_login | admin | None | The CodeIgniter URI string to redirect the user to upon login IF they have access to the control panel resource
userlib_action_admin_logout | NULL | None | The CodeIgniter URI string to redirect the user to upon logout IF they had access to the control panel resource
userlib_profile_fields |  | None | An associative array of custom user profile field columns to their matching full names
userlib_profile_rules |  | None | An associative array of custom user profile field columns to their matching validation rules

## Custom User Profiles

BackendPro comes with the ability to create extra user profile fields for registered users. I will say now that unlike other systems, mine dosn't hold your hand along the way to implement extra profile fields. If you want the functionallity you have to provide it. The reason for going along this kind of path is I decided a system which assumes to much is too restrictive. Its fine for a CMS but not for developers. I will explain what you need to change to implement a basic user field, I'm not that cruel.

1. Update the database
   This is the first step you must take, locate the table `be_user_profiles` (unless you have changed the table prefix value in the backendpro config file). Create your new column with its required settings. For this example I will create a column called gender.
2. Update the Userlib config file
   Locate the file modules/auth/config/userlib.php and scroll down to the bottom. There you will find two arrays, `userlib_profile_fields` and `userlib_profile_rules`. Here you want to update them to suit your new field. `$config['userlib_profile_fields'] = array('gender' => 'Gender');
   $config['userlib_profile_rules'] = array('gender' => 'required|alpha');`
3. Allow User Profiles
   Log into the control panel and go to the Settings -> Member Settings page. On there make sure the setting `Allow User Profiles` is set to yes. If you do not do this all it means is the administrators will not be able to change a users profile values.
4. Update the Member area in the Control Panel
   We want to allow administrators to now manage this new field for all users. Locate the file modules/auth/controllers/admin/members.php, this file contains all the logic to manage a users account. There are several functions we must update so the form knows how to handle our new field.
   _set_profile_defaults() : This method is used when a new user is being created. In here you want to specify what value your custom fields should be set to by default. So for our example I will make set gender to female. `$this->validation->set_default_value('gender','female');`
   _get_profile_details() : This method is used to extract the data submitted from a form and prepare it to be submiited to the database. There is an example in the method of what is expected.
   The last thing we must do is update the form which data can be entered into, locate and open the file modules/auth/views/admin/members/form_member.php, scroll to the bottom and you will find an area for your custom profile fields (The format the form is layed out in is disscused here). For our example I will add a simple radio button,`<li>
   <?=form_label('Gender','gender')?>
   Male <?=form_radio('gender','male',$this->validation->set_radio('gender','male'))?>
   Female <?=form_radio('gender','female',$this->validation->set_radio('gender','female'))?>
   </li>`
5. Optional: Update the registration form
   For this you must extend the User Authentication library, please see the next section how to do this.

## Extending the User Authentication System

As said above if you want to add/change the way authentication is performed, maybe collect extra information from the user on registration then you must extend the current userlib.php class file.

This is rather simple, just create a new file called MY_Userlib.php in the modules/auth/libraries directory. Then you can overwrite any methods to achive the desired effect.

Method | Description
--- | ---
login_form() | This method is called to create and display the login form, no login logic should be included in here.
_login() | This method provides all login logic and checks once the login form has been submitted.
register_form() | This method is called to create and display the registration form, no registration logic should be included in here.
_register() | This method provides all registration logic and checks once the registration form has been submitted.

Please if possible extend base libraries since this will mean your changes will not be overwritten if you apply an update.

## Userlib Library

The Userlib.php library is found in the modules\auth\libraries directory. Here is a list of the available functions.

- Function: is_user
  Parameters: None
  Returns: boolean
  Notes: Checks to see if a user is logged in by checking the session data.
- Function: check
  Parameters: 3 - resource, action , redirect
  - resource - string - A string containing the name of the resource to check permissions for.
  - action - string - A string containing the name of the action to check permissions for. Optional, defaults to NULL.
  - redirect - boolean - If TRUE, then redirect to login page, otherwise return boolean. Optional, defaults to TRUE.
  Returns: boolean
  Notes: Checks to see if a user has permission to a resource and (optionally) action. If the user does not have access, then the user is either redirected to the login page (if redirect is TRUE), or a boolean is returned (if redirect is FALSE).
- Function: login_form
  Parameters: 1 - container
  - container - string - view file container.
  Returns: void
  Notes: Display a login form for the user. If the user logs in and has access to the control panel, they are redirected to the location in the config item "userlib_action_admin_login". If the user does not have access to the control panel, they are redirected to the location in the config item "userlib_action_login".
- Function: logout
  Parameters: None
  Returns: void
  Notes: Log the user out from the system. The user is redirected to the location in the config item "userlib_action_logout".
- Function: forgotten_password_form
  Parameters: 1 - container
  - container - string - view file container.
  Returns: void
  Notes: Display the form for the forgetten password page and send them an email with their new password.
- Function: register_form
  Parameters: 1 - container
  - container - string - view file container.
  Returns: void
  Notes: Display the register form if user registration is allowed and then process the user's registration.
- Function: activate
  Parameters: none
  Returns: void
  Notes: Activate the user's account. If the activation was successfull, redirect the user to the location in the config item "userlib_action_activation" otherwise redirect the user to the login page.
- Function: encode_password
  Parameters: 1 - password
  - password - string - The password string to encode. If the password is NULL, a NULL is returned.
  Returns: string
  Notes: Encode the user's password using a set method. This uses SHA-1 and a salt appended to the password.

## Custom Notes

When a user logs in all their details are stored in a session cookie, to to get their user_id it should be something along the lines of `$this->session->userdata('id');`