SimpleAuth

With SimpleAuth you can add a customizable and ready-to-use login form in CodeIgniter.

SimpleAuth consists of a controller (SimpleAuthController) a middleware (SimpleAuthMiddleware) and a library (Simple_auth) all built with the Luthier CI Authentication Framework.

SimpleAuth installation

The installation is done through the make command of the Luthier CI Built-in CLI Tools. It is necessary to configure a connection to a database (in application/config/database.php) and activate the migrations (in application/config/migration.php) before proceeding with the installation.

Step 1: Copy the necessary files

Open a terminal and execute the following command in the root folder of your application:

php index.php luthier make auth

Step 2: Install the database

To install the database, run the following from the command line:

php index.php luthier migrate

Step 3: Define the routes

In your web.php route file, add the following line:

Route::auth();

The Route::auth() method is a shortcut to create all the necessary routes:

Route::match(['get', 'post'], 'login', 'SimpleAuthController@login')->name('login');
Route::post('logout', 'SimpleAuthController@logout')->name('logout');
Route::get('email_verification/{token}', 'SimpleAuthController@emailVerification')->name('email_verification');
Route::match(['get', 'post'], 'signup', 'SimpleAuthController@signup')->name('signup');
Route::match(['get', 'post'], 'confirm_password', 'SimpleAuthController@confirmPassword')->name('confirm_password');
Route::group('password-reset', function(){
    Route::match(['get','post'], '/', 'SimpleAuthController@passwordReset')->name('password_reset');
    Route::match(['get','post'], '{token}', 'SimpleAuthController@passwordResetForm')->name('password_reset_form');
});

When visiting the /login URL of your application you should see your new login screen.

SimpleAuth controller

El controlador de SimpleAuth (SimpleAuthController) contiene la lógica de cara al usuario para las operaciones de autenticación, tales como el inicio de sesión, el registro de usuario y el restablecimiento de contraseña. Un controlador de SimpleAuth recién creado se ve parecido a esto:

The SimpleAuth controller (SimpleAuthController) contains the user-facing logic for authentication operations, such as login, registration and password reset. A SimpleAuth controller looks like this:

<?php
# application/controllers/SimpleAuthController.php

defined('BASEPATH') OR exit('No direct script access allowed');

/* (...) */

class SimpleAuthController extends Luthier\Auth\SimpleAuth\Controller
{

    /**
     * (...)
     */
    public function getSignupFields()
    {
        return [ ... ];
    }

    /**
     * (...)
     */
    public function getUserFields()
    {
        return [ ... ];
    }
}

The extended Luthier\Auth\SimpleAuth\Controller class already provides all the necessary logic so, unless you want to create something custom, it is not necessary to modify much here.

Customize the user registration form

You can change the fields of the registration form by modifying the returned array of the getSignupFields() method. This is an example of the structure of the array:

public function getSignupFields()
{
    return [
        'Field name 1' => [
            'Field type',
            'Field label',
            [ /* HTML5 attributes array */ ],
            [ /* CI Validation rules array */ ] ,
            [ /* CI Validation error essages array (Optional) */ ]
        ],
        'Field name 2' => [
            'Field type',
            'Field label',
            [ /* ... */ ],
            [ /* ... */ ] ,
        ],

        // ( ... )

        'Field name N' => [
            'Field type',
            'Field label',
            [ /* ... */ ],
            [ /* ... */ ] ,
        ]
    ];
}

The getUserFields() method returns an array with the columns of the database table where users are stored. Each element of the array must match the user registration form field names:

public function getUserFields()
{
    return [
        'first_name',
        'last_name',
        'username',
        'gender',
        'email',
        'password',
        'role',
    ];
}

SimpleAuth Middleware

The SimpleAuth Middleware (SimpleAuthMiddleware) protects those routes where the user authentication is required. This Middleware automatically verifies the current status of the user:

• If the user is authenticated, the request continues normally.
• If the user is not authenticated, it will try to restore the session using the Remember Me feature.
• If it is not possible to restore any previous session, the user will be redirected to the login screen.

You can use the SimpleAuth Middleware in your routes and route groups like any other Middleware, and even combine it with your own Middleware to add additional security layers:

<?php
# application/routes/web.php

Route::auth();
Route::get('/', 'FrontendController@homepage')->name('homepage');
Route::group('dashboard', ['middleware' => ['SimpleAuthMiddleware']], function(){
    Route::get('/', 'UserArea@dashboard');
});

SimpleAuth library

The SimpleAuth library contains methods to perform operations that involve users. To use the SimpleAuth library you must first load it:

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

Get the current user

To get the current authenticated user, use the user() method. This method returns a user instance if the user is authenticated, or NULL otherwise:

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

You can access the user data as properties of the returned object:

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

$firstName = $user->first_name;
$lastName = $user->last_name;

Check if user is guest (anonymous)

The isGuest() method returns TRUE if the user is anonymous (not logged in) or FALSE otherwise:

$this->simple_auth->isGuest();

Check user roles

To verify if a user has a specific role, use the isRole($role) method, which returns TRUE if the user owns the $role role, or FALSE otherwise:

$this->simple_auth->isRole('ADMIN');

Check user permissions

To verify if a user has a specific permission, use the isGranted($permission) method, which returns TRUE if the user has the $permission permission, or FALSE otherwise:

$this->simple_auth->isGranted('general.read');

To verify if a user belongs to a role that begins with a specific phrase/category, use the character (*):

$this->simple_auth->isGranted('general.*');

Check if user is fully authenticated

The isFullyAuthenticated() method returns TRUE if the user is fully authenticated, or FALSE otherwise:

$this->simple_auth->isFullyAuthenticated();

A fully authenticated user is one who has logged in through the login form and not through the Remember Me feature.

Prompt password

The promptPassword($route) method redirects to $route if the user is not fully authenticated (see isFullyAuthenticated() method).

This is useful for check if a useris authenticated through the Remember Me feature.

Search an user

The searchUser($search) method returns an object with the first user that matches $search, or NULL if no user is found. The search criteria vary depending on the type of supplied $search variable:

• If $search is an integer, the user will be searched by its primary key (ID).
• If $search is a string, the user will be searched by the value that matches the column set for the username (simpleauth_username_col parameter)
• If $search is an array, the search will be performed as the where($search) CodeIgniter QueryBuilder native method.

Example:

$this->simple_auth->searchUser(1);
$this->simple_auth->searchUser('admin@admin.com');
$this->simple_auth->searchUser(['gender' => 'm', 'active' => 1]);

Update a user

The updateUser($search, $values) method updates the first user found by the $search criteria (see searchUser() method) with the new values ​​supplied in $values ​array.

Example:

$this->simple_auth->updateUser(1, ['first_name' => 'John']);
$this->simple_auth->updateUser('admin@admin.com', ['gender' => 'f']);

Create a user

The createUser($user) method creates a user with the data of $data array. Each index corresponds to a column of the user database table.

Example:

$this->simple_auth->createUser(
    [
        'first_name' => 'Admin',
        'last_name'  => 'Admin',
        'username'   => 'admin',
        'email'      => 'admin@admin.com',
        'password'   => 'admin',
        'gender'     => 'm',
        'role'       => 'admin',
        'verified'   => 1
    ]
);

Access Control Lists (ACL)

Access Control Lists provides more control of user permissions. When this feature is used, a userhas one or more permissions assigned. Together, those permissions grant (or deny) the access to certain resources of the application.

Consider the following user_permissions_categories table:

ID      NAME        PARENT_ID
-----------------------------
1       general     [null]
2       read        1
3       write       1
4       delete      1
5       local       4
6       global      4

And the following user_permissions table:

ID      USERNAME    PERMISSION_ID
---------------------------------
1       anderson    2
2       anderson    5
3       julio       3
4       julio       6

When the user anderson logs in, he will have the following permissions:

general.read
general.delete.local

And when the user julio logs in, he will have the following permissions:

general.write
general.delete.global

Check if a permission exists

The permissionsExists($permission) method returns TRUE if the $permission exists in the ACL database table, or FALSE otherwise.

Example:

$this->simple_auth->permissionExists('general.read');

Grant a permission

The grantPermission($permission, $username) method assigns the $permission to the $username user and returns TRUE if the operation was successful, or FALSE otherwise. If $username is omitted, the operation will be performed on the current authenticated user.

Example:

$this->simple_auth->grantPermission('general.read');

Revoke a permission

The revokePermission($permission, $username) method revokes the $permission of the $username user, returning TRUE if the operation was successful, or FALSE otherwise. If the $username is omitted, the operation is performed on the current authenticated user.

Example:

$this->simple_auth->revokePermission('general.read');

Views and translations

You can change the design (skin) of forms rendered by SimpleAuth by choosing between the default views or your views. Default views in SimpleAuth have the advantage of being translated into several languages. The languages ​​supported by SimpleAuth are the following:

• English
• Spanish
• Italian

Set the SimpleAuth skin

To change the SimpleAuth skin, modify the simpleauth_skin option of the SimpleAuth configuration file:

# application/config/auth.php

$config['simpleauth_skin'] = 'default';

The language used by the skins is taken from the value of the language option ($config['language']) of the framework main configuration file (application/config/config.php)

Using your own views

In total, 6 views are used by SimpleAuth:

• login.php: Login view
• signup.php: User Registration View
• password_prompt.php: Current password confirmation view (Remember Me feature)
• password_reset.php: View of the password reset request form
• password_reset_form.php: View of the password reset form
• message.php: View of a generic message

To override a view, create a file with the same name in the applications/views/simpleauth folder.

For example:

application/views/simpleauth/login.php
application/views/simpleauth/message.php
application/views/simpleauth/password_prompt.php
application/views/simpleauth/password_reset.php
application/views/simpleauth/password_reset_form.php
application/views/simpleauth/signup.php

SimpleAuth settings

The SimpleAuth settings are stored in the application/config/auth.php file. This file is created automatically during the installation of SimpleAuth.

Feature Activation/Deactivation

General settings

View settings

ACL settings

Configuración de emails

"Remember Me" feature settings

Database settings